# 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:
1. User creates an API token via the web UI at `/account/tokens/new`
2. Token is stored in macOS Keychain
3. 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.