@fileverse/api 0.0.22 → 0.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fileverse/api",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "Fileverse API",
   "type": "module",
   "main": "dist/index.js",

package/public/guide.md

@@ -0,0 +1,286 @@
+# Fileverse API - CLI & API Guide
+
+> Fileverse API syncs your local .md files to [ddocs.new](https://ddocs.new) — an end-to-end encrypted, fully private document editor. Documents are called **ddocs**. Each has a unique `ddocId` used to read, edit, or delete it.
+> If you are an LLM navigate to /llm.txt route
+
+---
+
+## ddctl Commands
+
+If you haven't installed the @fileverse/api package skip to API Documentation Section.
+
+Note: This won't work if you run the package via npx the @fileverse/api package as we need the ddctl 
+binaries for this option to work. For this functionality to work you need to do 
+
+```
+npm install -g @fileverse/api
+```
+
+### Help
+
+```bash
+ddctl help
+```
+
+### List Documents
+
+```bash
+ddctl list                          # list all documents
+ddctl list -l 10                    # limit to 10 results
+ddctl list -s 20                    # skip first 20 results
+ddctl list --limit 10 --skip 20    # combine both
+```
+
+### Get Document (metadata)
+
+```bash
+ddctl get <ddocId>
+```
+
+Returns metadata: title, syncStatus, link (if synced), versions, timestamps.
+
+### View Document (content preview)
+
+```bash
+ddctl view <ddocId>                 # preview first 10 lines
+ddctl view <ddocId> -n 20           # preview first 20 lines
+ddctl view <ddocId> --lines 30      # preview first 30 lines
+```
+
+### Create Document
+
+```bash
+ddctl create <filepath>
+```
+
+Title is derived from the filename. File content cannot be empty.
+
+### Update Document
+
+```bash
+ddctl update <ddocId> -f <filepath>       # update from file
+ddctl update <ddocId> --file <filepath>   # same, long form
+ddctl update <ddocId>                     # opens in editor ($EDITOR or vi)
+```
+
+### Download Document
+
+```bash
+ddctl download <ddocId>                   # download to current directory
+ddctl download <ddocId> -o myfile.md      # specify output filename
+ddctl download <ddocId> --output myfile.md
+```
+
+### Delete Document
+
+```bash
+ddctl delete <ddocId>                     # delete one document
+ddctl delete <id1> <id2> <id3>            # delete multiple (space-separated)
+```
+
+### Failed Events (sync troubleshooting)
+
+```bash
+ddctl events list-failed                  # list failed blockchain sync events
+ddctl events retry <eventId>              # retry a specific failed event
+ddctl events retry-all                    # retry all failed events
+```
+
+---
+
+## API Endpoints
+
+Base URL: `{SERVER_URL}` (e.g. `http://localhost:8001`)
+
+All authenticated endpoints require `apiKey` as a **query parameter**.
+
+### Health Check
+
+```
+GET /ping
+```
+
+No auth required. Returns `{"reply": "pong"}`.
+
+### List Documents
+
+```
+GET /api/ddocs?apiKey={API_KEY}&limit=10&skip=0
+```
+
+Response:
+```json
+{
+  "ddocs": [ ... ],
+  "total": 100,
+  "hasNext": true
+}
+```
+
+### Get Document
+
+```
+GET /api/ddocs/{ddocId}?apiKey={API_KEY}
+```
+
+Response:
+```json
+{
+  "ddocId": "abc123",
+  "title": "My Document",
+  "content": "...",
+  "syncStatus": "pending | synced | failed",
+  "link": "https://...",
+  "localVersion": 2,
+  "onchainVersion": 2,
+  "isDeleted": 0,
+  "createdAt": "...",
+  "updatedAt": "..."
+}
+```
+
+### Create Document (JSON)
+
+```
+POST /api/ddocs?apiKey={API_KEY}
+Content-Type: application/json
+
+{
+  "title": "Document Title",
+  "content": "Document content here..."
+}
+```
+
+Response (201):
+```json
+{
+  "message": "...",
+  "data": {
+    "ddocId": "abc123",
+    "title": "...",
+    "syncStatus": "pending",
+    ...
+  }
+}
+```
+
+Extract `ddocId` from `response.data.ddocId`.
+
+### Create Document (File Upload)
+
+```
+POST /api/ddocs?apiKey={API_KEY}
+Content-Type: multipart/form-data
+
+Field: "file" = <your file>
+```
+
+Title is derived from filename. Max file size: 10MB.
+
+### Update Document (JSON)
+
+```
+PUT /api/ddocs/{ddocId}?apiKey={API_KEY}
+Content-Type: application/json
+
+{
+  "title": "New Title",
+  "content": "Updated content..."
+}
+```
+
+Both fields are optional — send only what you want to change.
+
+### Update Document (File Upload)
+
+```
+PUT /api/ddocs/{ddocId}?apiKey={API_KEY}
+Content-Type: multipart/form-data
+
+Field: "file" = <your updated file>
+```
+
+### Delete Document
+
+```
+DELETE /api/ddocs/{ddocId}?apiKey={API_KEY}
+```
+
+### Search Documents
+
+```
+GET /api/search?apiKey={API_KEY}&q={query}&limit=10&skip=0
+```
+
+Response:
+```json
+{
+  "nodes": [ ... ],
+  "total": 5,
+  "hasNext": false
+}
+```
+
+Note: search returns `nodes`, not `ddocs`.
+
+### OpenAPI Spec
+
+```
+GET {SERVER_URL}/openapi.json
+```
+
+Machine-readable OpenAPI 3.1 specification.
+
+---
+
+## Quick Reference
+
+### API Endpoints
+
+| Method | Path                              | Description              |
+|--------|-----------------------------------|--------------------------|
+| GET    | /ping                             | Health check (no auth)   |
+| GET    | /api/ddocs                        | List documents           |
+| GET    | /api/ddocs/{ddocId}               | Get document             |
+| POST   | /api/ddocs                        | Create document          |
+| PUT    | /api/ddocs/{ddocId}               | Update document          |
+| DELETE | /api/ddocs/{ddocId}               | Delete document          |
+| GET    | /api/search?q={query}             | Search documents         |
+
+### ddctl Commands
+
+| Command                        | Description                        |
+|--------------------------------|------------------------------------|
+| ddctl list                     | List documents                     |
+| ddctl get {ddocId}             | Get document metadata              |
+| ddctl view {ddocId}            | Preview document content           |
+| ddctl create {filepath}        | Create document from file          |
+| ddctl update {ddocId}          | Update document (editor or file)   |
+| ddctl download {ddocId}        | Download document to file          |
+| ddctl delete {ddocId} [...]    | Delete one or more documents       |
+
+---
+
+## Sync Status
+
+After creating or updating a document, it syncs to the blockchain asynchronously:
+
+| Status    | Meaning                                    |
+|-----------|--------------------------------------------|
+| `pending` | Saved locally, blockchain sync in progress |
+| `synced`  | Published on blockchain, `link` available  |
+| `failed`  | Sync failed — use events retry to fix      |
+
+Typical sync time: 5-30 seconds.
+
+---
+
+## Error Codes
+
+| Code | Meaning                                          |
+|------|--------------------------------------------------|
+| 400  | Validation error (missing/invalid body or params)|
+| 401  | Invalid or missing API key                       |
+| 404  | Resource not found                               |
+| 429  | Rate limited — respect Retry-After header        |
+| 500  | Internal server error                            |