mirror of
https://github.com/johannesjo/super-productivity.git
synced 2026-07-21 02:20:12 +00:00
3aa21d751a
* docs(wiki): enhance keyboard shortcuts documentation Added detailed descriptions of functional grouping for keyboard shortcuts, including categories such as Global, Navigation, Task management, and UI panels. Updated the Global Shortcuts section for clarity and included platform-specific differences, configurable vs reserved shortcuts, context-dependent behavior, and storage definitions. This improves user understanding of the shortcut system and its configuration. * docs(wiki): add reference to Web App vs Desktop differences Updated the 3.00-Reference and 3.02-Settings-and-Preferences documentation to include a new section on differences between the Web app and Desktop app, linking to the newly created [[3.05-Web-App-vs-Desktop]] page. This enhances clarity and provides users with a direct reference for understanding the distinctions. * docs(wiki): expand short syntax documentation Enhanced the 3.04-Short-Syntax.md file by detailing the four main short syntax forms for task metadata: tags, projects, time estimates, and due dates. Each syntax form now includes its purpose, grammar, valid and invalid examples, and additional parsing rules. This update improves user understanding of how to effectively utilize short syntax in task management. * docs(wiki): add User Data reference to documentation Included a new reference to [[3.06-User-Data]] in both the 3.00-Reference and _Sidebar.md files. This addition enhances navigation and provides users with direct access to information regarding user data management. * docs(wiki): expand API documentation for Sync Server and Plugin API Added comprehensive details on the Sync Server REST API and Plugin API, including authentication methods, endpoint descriptions, request/response schemas, error codes, rate limits, and data retention policies. This update significantly enhances the documentation, providing users with a clearer understanding of the APIs available for data synchronization and plugin development.
217 lines
11 KiB
Markdown
Executable file
217 lines
11 KiB
Markdown
Executable file
# APIs
|
||
|
||
Super Productivity exposes **two API systems**: the **Sync Server REST API** (for data synchronization) and the **Plugin API** (for extending the app). This reference summarizes both; full request/response schemas and examples live in the repository (Sync Server: `packages/super-sync-server/`; Plugin API: `packages/plugin-api/` and `docs/plugin-development.md`).
|
||
|
||
## 1. Sync Server REST API
|
||
|
||
The Sync Server is a custom, operation-based synchronization service (event-sourcing style). It is **not** WebDAV. It is intended for use with the built-in SuperSync sync provider. See [[2.08-Choose-Sync-Backend]] and [[2.09-Configure-Sync-Backend]] for user-facing sync options.
|
||
|
||
### Authentication and Authorization
|
||
|
||
All sync endpoints require **JWT Bearer** authentication: `Authorization: Bearer <token>`.
|
||
|
||
- **Token expiry:** 7 days.
|
||
- **Environment:** Server requires `JWT_SECRET` (minimum 32 characters).
|
||
- **Token contents:** `userId`, `email`, `tokenVersion` (for invalidation).
|
||
- Invalid or missing token returns 401.
|
||
|
||
### Authentication Endpoints
|
||
|
||
**Traditional:**
|
||
|
||
- `POST /api/register` — User registration (email verification required).
|
||
- `POST /api/login` — Password login.
|
||
- `POST /api/verify-email` — Email verification.
|
||
- `POST /api/replace-token` — Replace compromised JWT (requires current auth).
|
||
|
||
**Passkey (WebAuthn):**
|
||
|
||
- `POST /api/register/passkey/options` — Registration options.
|
||
- `POST /api/register/passkey/verify` — Verify registration.
|
||
- `POST /api/login/passkey/options` — Authentication options.
|
||
- `POST /api/login/passkey/verify` — Verify authentication.
|
||
- `POST /api/recover/passkey` — Request passkey recovery (e.g. magic link).
|
||
- `POST /api/recover/passkey/options` — Recovery registration options.
|
||
- `POST /api/recover/passkey/complete` — Complete recovery.
|
||
|
||
**Magic link:**
|
||
|
||
- `POST /api/login/magic-link` — Request magic link email.
|
||
- `POST /api/login/magic-link/verify` — Verify magic link token.
|
||
|
||
**Account:**
|
||
|
||
- `DELETE /api/account` — Delete user and all data (requires auth).
|
||
|
||
### Synchronization Endpoints
|
||
|
||
All require authentication.
|
||
|
||
**Operations:**
|
||
|
||
- `POST /api/sync/ops` — Upload operations (incremental). Request: `ops[]`, `clientId`, optional `lastKnownServerSeq`, optional `requestId` (deduplication).
|
||
- `GET /api/sync/ops?sinceSeq={seq}&limit={limit}&excludeClient={clientId}` — Download operations. Query: `sinceSeq` (required), `limit` (default 500, max 1000), `excludeClient` (optional).
|
||
|
||
**Snapshots:**
|
||
|
||
- `GET /api/sync/snapshot` — Get full state snapshot.
|
||
- `POST /api/sync/snapshot` — Upload full state (backup/repair/migration). Body limit 30 MB (compressed).
|
||
|
||
**Status and maintenance:**
|
||
|
||
- `GET /api/sync/status` — Sync status and storage info.
|
||
- `DELETE /api/sync/data` — Delete all sync data for the user (e.g. encryption password change).
|
||
- `GET /api/sync/restore-points?limit={limit}` — List restore points (limit 1–100).
|
||
- `GET /api/sync/restore/{serverSeq}` — Get state snapshot at a specific sequence.
|
||
|
||
**Health:**
|
||
|
||
- `GET /health` — Database connectivity check (no auth). Returns 200 with `{ status: 'ok', db: 'connected' }` or 503 on failure.
|
||
|
||
### Request/Response Overview
|
||
|
||
- **Upload ops:** Body is an array of operations; each has `id`, `clientId`, `actionType`, `opType`, `entityType`, `entityId`/`entityIds`, `payload`, `vectorClock`, `timestamp`, `schemaVersion`, optional `isPayloadEncrypted`. Response: `results[]` (per-op accepted/rejected + `serverSeq`), optional `newOps`, `latestSeq`, optional `hasMorePiggyback`, optional `deduplicated`.
|
||
- **Download ops:** Response: `ops`, `hasMore`, `latestSeq`, optional `gapDetected`, optional `latestSnapshotSeq`, optional `snapshotVectorClock`, `serverTime`.
|
||
- **Snapshot:** Response: `state`, `serverSeq`, `generatedAt`. Upload snapshot body: `state`, `clientId`, `reason`, `vectorClock`, `schemaVersion`, optional `isPayloadEncrypted`.
|
||
- **Status:** Response: `latestSeq`, `devicesOnline`, optional `snapshotAge`, `storageUsedBytes`, `storageQuotaBytes`.
|
||
|
||
Exact schemas (Zod on server, TypeScript types in repo) are in `packages/super-sync-server/src/sync/sync.types.ts` and `sync.routes.ts`.
|
||
|
||
### Error Codes
|
||
|
||
Structured error codes (for client handling) include: `VALIDATION_FAILED`, `INVALID_OP_ID`, `INVALID_OP_TYPE`, `INVALID_ENTITY_TYPE`, `INVALID_ENTITY_ID`, `INVALID_PAYLOAD`, `PAYLOAD_TOO_LARGE`, `INVALID_VECTOR_CLOCK`, `INVALID_CLIENT_ID`, `CONFLICT_CONCURRENT`, `CONFLICT_STALE`, `DUPLICATE_OPERATION`, `RATE_LIMITED`, `STORAGE_QUOTA_EXCEEDED`, `ENCRYPTED_OPS_NOT_SUPPORTED`, `SYNC_IMPORT_EXISTS`, `INTERNAL_ERROR`. Defined in `sync.types.ts` (`SYNC_ERROR_CODES`).
|
||
|
||
### Rate Limits (per endpoint)
|
||
|
||
- Email verification: 20 / 15 min.
|
||
- Token replacement: 5 / 15 min.
|
||
- Account deletion: 3 / 15 min.
|
||
- Passkey registration: 10 / 15 min.
|
||
- Passkey login: 20 / 15 min.
|
||
- Passkey recovery (request/options/complete): 5–10 / 15 min.
|
||
- Magic link request: 5 / 15 min; verify: 10 / 15 min.
|
||
- Upload ops: 100 / 1 min.
|
||
- Download ops: 200 / 1 min.
|
||
- Snapshot (GET): 10 / 5 min.
|
||
|
||
### Storage Quotas (Sync Server)
|
||
|
||
- **Per user:** Default 100 MB. Enforced before accepting uploads; automatic cleanup (restore points and old operations) when over quota.
|
||
- **Upload limits:** Max payload 20 MB; max operations per upload 100. Compressed ops body: 10 MB; compressed snapshot: 30 MB; decompressed cap (zip-bomb protection): 100 MB.
|
||
|
||
### Compression
|
||
|
||
- **Request:** Gzip via `Content-Encoding: gzip`. Android can send base64-encoded gzip with `Content-Transfer-Encoding: base64`.
|
||
- **Response:** Server may send compressed responses where configured.
|
||
|
||
### CORS
|
||
|
||
Configurable via environment/config. Typical allowed headers include `Authorization`, `Content-Type`, `Content-Encoding`, `X-Expected-Rev`, `X-Force-Overwrite`, `X-Requested-With`. Credentials supported.
|
||
|
||
### Data Retention
|
||
|
||
Operations, devices, and related validation data are retained for **45 days**. Older data is purged.
|
||
|
||
### Request Deduplication
|
||
|
||
Upload ops accepts optional `requestId`. Repeated requests with the same `requestId` receive cached results (and fresh piggybacked ops if applicable), so clients can retry safely without duplicating operations.
|
||
|
||
### End-to-End Encryption
|
||
|
||
Payloads can be encrypted client-side; server stores them as opaque blobs. Restore-at-sequence is not supported when operations are encrypted (`ENCRYPTED_OPS_NOT_SUPPORTED`).
|
||
|
||
---
|
||
|
||
## 2. Plugin API
|
||
|
||
The Plugin API is exposed to plugins via a global `PluginAPI` object. Plugins run in a sandboxed environment (VM or iframe). See [[3.05-Web-App-vs-Desktop]] for web limitations (e.g. Node-only plugins disabled, iframe API restrictions). Full types and the development guide: `packages/plugin-api/src/types.ts`, `docs/plugin-development.md`.
|
||
|
||
### Plugin API Categories
|
||
|
||
**Data — Tasks:**
|
||
|
||
- `getTasks()`, `getArchivedTasks()`, `getCurrentContextTasks()` — Read tasks.
|
||
- `addTask(taskData)`, `updateTask(taskId, updates)`, `deleteTask(taskId)` — Create/update/delete.
|
||
- `batchUpdateForProject(request)` — Batch create/update/delete/reorder for a project.
|
||
- `reorderTasks(taskIds, contextId, contextType)` — Reorder tasks.
|
||
|
||
**Data — Projects:**
|
||
|
||
- `getAllProjects()`, `addProject(projectData)`, `updateProject(projectId, updates)`.
|
||
|
||
**Data — Tags:**
|
||
|
||
- `getAllTags()`, `addTag(tagData)`, `updateTag(tagId, updates)`.
|
||
|
||
**Data — Simple counters:**
|
||
|
||
- `setCounter(id, value)`, `getCounter(id)`, `incrementCounter(id, incrementBy)`, `decrementCounter(id, decrementBy)`, `deleteCounter(id)`, `getAllCounters()`.
|
||
|
||
**UI:**
|
||
|
||
- `showSnack(snackCfg)`, `notify(notifyCfg)` — Notifications.
|
||
- `openDialog(dialogCfg)`, `showIndexHtmlAsView()` — Dialogs and plugin UI.
|
||
|
||
**Registration (main plugin context only; not in iframe):**
|
||
|
||
- `registerHeaderButton(config)`, `registerMenuEntry(config)`, `registerShortcut(config)`, `registerSidePanelButton(config)`, `registerHook(hook, handler)`.
|
||
|
||
**Persistence:**
|
||
|
||
- `persistDataSynced(dataStr)`, `loadSyncedData()`, `getConfig()` — Plugin-specific storage and config.
|
||
|
||
**Advanced:**
|
||
|
||
- `executeNodeScript(request)` — Run Node.js scripts (Electron only, `nodeExecution` permission and user consent).
|
||
- `dispatchAction(action)` — Dispatch NgRx actions (allowed subset).
|
||
- `downloadFile(filename, data)`, `isWindowFocused()`, `onWindowFocusChange(handler)`.
|
||
|
||
### Hooks (Events)
|
||
|
||
Plugins can register handlers for: `taskCreated`, `taskComplete`, `taskUpdate`, `taskDelete`, `currentTaskChange`, `finishDay`, `languageChange`, `persistedDataUpdate`, `action`, `anyTaskUpdate`, `projectListUpdate`. Payload types are defined in `plugin-api` types (`HookPayloadMap`).
|
||
|
||
### Plugin Data Types
|
||
|
||
Core types (Task, Project, Tag, ProjectFolder, etc.) and batch types (`BatchUpdateRequest`, `BatchUpdateResult`, `BatchOperation`, etc.) are in `packages/plugin-api/src/types.ts`.
|
||
|
||
### Plugin Manifest
|
||
|
||
Plugins require `manifest.json`: `name`, `id`, `manifestVersion`, `version`, `minSupVersion`, optional `description`, `hooks`, `permissions`, optional `iFrame`, `isSkipMenuEntry`, `type`, `assets`, `icon`, `nodeScriptConfig`, `sidePanel`, `jsonSchemaCfg`. See `PluginManifest` in the repo.
|
||
|
||
### Plugin Permissions
|
||
|
||
- **nodeExecution:** Required for `executeNodeScript()` (Electron only; user consent). See [[3.05-Web-App-vs-Desktop]] and [[3.06-User-Data]] for file-system and desktop-only behavior.
|
||
- Other permissions may gate specific API methods; see the plugin development guide.
|
||
|
||
### Iframe Restrictions
|
||
|
||
When a plugin uses an iframe UI, the following are **not** available: `registerHeaderButton`, `registerMenuEntry`, `registerSidePanelButton`, `registerShortcut`, `registerHook`, `execNodeScript`. Iframe content is subject to CSP (e.g. no external scripts; same-origin or inlined only).
|
||
|
||
---
|
||
|
||
## 3. Versioning and Compatibility
|
||
|
||
### Schema Versioning (Sync)
|
||
|
||
- **Current schema version:** 1 (shared schema in `packages/shared-schema`).
|
||
- **Minimum supported:** 1.
|
||
- **Max version skip:** 3 (if remote data is more than 3 versions ahead, client should update).
|
||
- Operations and snapshots carry `schemaVersion`; server validates and may reject unsupported versions.
|
||
|
||
### Vector Clocks
|
||
|
||
Sync uses vector clocks for conflict resolution. Server validates/sanitizes clocks: max 100 entries; keys max 255 chars; values 0–10,000,000. Invalid entries are stripped.
|
||
|
||
### API Validation (Sync Server)
|
||
|
||
- Operation IDs: 1–255 characters. Client IDs: alphanumeric, underscore, hyphen; max 255.
|
||
- Entity types: 1–255 characters. Schema version: 1–100.
|
||
- Payload validation by op type (CRT, UPD, DEL, MOV, BATCH, SYNC_IMPORT, etc.); see `validatePayload` in `sync.types.ts`.
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
- **Sync Server:** Production-oriented (JWT, rate limiting, CORS, Helmet). Multi-instance deployment has limitations (e.g. passkey challenge storage in memory; snapshot generation locks); single-instance is the typical deployment.
|
||
- **Plugin API:** Sandboxed; iframe and Electron have different capabilities. See [[3.05-Web-App-vs-Desktop]] and the repo plugin guide.
|
||
- **Further documentation:** Sync Server README and auth docs in `packages/super-sync-server/`; Plugin API and examples in `packages/plugin-api/`, `docs/plugin-development.md`, and example plugins under `packages/plugin-dev/`.
|