macOS App API Gaps

Missing API Endpoints

1. List Uploaded Attachments

Status: IMPLEMENTED (see apps/server/internal/httpserver/handlers.go handleAttachmentsList)

The app needs a way to show an index of all uploaded files. The current API only allows uploading (POST /api/uploads) and downloading (GET /attachments/{hash}).

Needed:

GET /api/attachments
Response: {
  "attachments": [
    {
      "hash": "sha256",
      "originalName": "filename.pdf",
      "contentType": "application/pdf",
      "sizeBytes": 12345,
      "createdAt": "2024-01-01T00:00:00Z",
      "url": "/attachments/{hash}"
    }
  ]
}

2. Create Document from Content

Status: AVAILABLE BY PATH

The existing POST /api/documents/{path} works but requires knowing the path upfront. For the "new note from clipboard" feature, it would be cleaner to have:

POST /api/documents
Body: {
  "content": "# Note Title\n\nBody...",
  "folder": "inbox" // optional, defaults to root
}
Response: {
  "path": "inbox/note-title.md",
  "title": "Note Title",
  "hash": "sha256"
}

The current workaround is to POST to /api/documents/{path} with the desired path.

3. Inbox/Upload Folder Concept

Status: NOT IMPLEMENTED

The server has no concept of a default upload folder or inbox. All documents live in a flat-ish hierarchy under the content source directory. The macOS app will:

Allow the user to configure a default upload folder (e.g., "inbox/")
Fall back to root if not configured
Document this as a client-side convention

Stub Implementations

The attachment list placeholder has been replaced with a repository-backed implementation. Native sync deltas now apply non-conflicting create/update/delete/rename changes and return newSnapshotId; create/update changes should include inline markdown content or reference a hash already present in the content store.

Authentication

The app uses the existing Bearer token (API key) auth flow:

User creates an API token via the web UI at /account/tokens/new
Token is stored in macOS Keychain
All requests include Authorization: Bearer <token>

Notes

File sync uses the existing /api/sync/* protocol. Clients should persist newSnapshotId after each delta response.
Upload uses POST /api/uploads. Markdown, plain-text, and HTML files are promoted into readable documents; other supported files remain attachments.
Uploaded file listing uses the repository-backed GET /api/attachments endpoint. Its url field points to the rendered page for promoted documents.

2.5 KiB Raw Blame History