diff --git a/docs/api/README.md b/docs/api/README.md index ce02e66..2ee463b 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -249,6 +249,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route | [`routes/pos/pimage.md`](routes/pos/pimage.md) | `GET /v1/pimage` | | [`routes/v1/product.md`](routes/v1/product.md) | `GET /v1/product` | | [`routes/vfs/list.md`](routes/vfs/list.md) | `GET /vfs` | +| [`routes/vfs/drafts/response.md`](routes/vfs/drafts/response.md) | `POST /vfs/drafts/response` | | [`routes/vfs/mkdir.md`](routes/vfs/mkdir.md) | `POST /vfs/mkdir` | | [`routes/vfs/rename.md`](routes/vfs/rename.md) | `POST /vfs/rename` | | [`routes/vfs/upload.md`](routes/vfs/upload.md) | `POST /vfs/upload` | diff --git a/docs/api/routes-all.md b/docs/api/routes-all.md index 7ab46c8..ca29d9f 100644 --- a/docs/api/routes-all.md +++ b/docs/api/routes-all.md @@ -1,6 +1,6 @@ # Dash API Routes Overview (All) -Overview of all 231 API endpoints across all modules. +Overview of all 232 API endpoints across all modules. ### Notation @@ -10,55 +10,60 @@ Params: path values first, then `query:` and `body:` (`body?` = optional body). ### Reusable types - `T1` = `{ order: T2 }` -- `T2` = `{ id: int, number: str, type: str, entityId: int|null, date: str, lines: T25[], createdAt?: str, shipping?: T33|null, shippings?: T33[], payment?: T39|null, payments?: T39[], paid?: bool, shipped?: bool, delivered?: bool, orderTotal?: num, paidTotal?: num, orderedQuantity?: num, shippedQuantity?: num, shipments?: T7[] }` +- `T2` = `{ id: int, number: str, type: str, entityId: int|null, date: str, lines: T28[], createdAt?: str, shipping?: T36|null, shippings?: T36[], payment?: T42|null, payments?: T42[], paid?: bool, shipped?: bool, delivered?: bool, orderTotal?: num, paidTotal?: num, orderedQuantity?: num, shippedQuantity?: num, shipments?: T7[] }` - `T3` = `{ article: T4 }` -- `T4` = `{ id: int, sku: str, name: str, slug: str, desc: str|null, seo: str|null, track_stock: bool, unitamount: num|null, weight: num|null, unit: T36, brand: T34|null, categoryIds: int[], photos: T31[], eans: str[], prices: T42[], suppliers: T14[] }` +- `T4` = `{ id: int, sku: str, name: str, slug: str, desc: str|null, seo: str|null, track_stock: bool, unitamount: num|null, weight: num|null, unit: T39, brand: T37|null, categoryIds: int[], photos: T34[], eans: str[], prices: T46[], suppliers: T16[] }` - `T5` = `{ delivery: T6 }` -- `T6` = `{ id: int, number: str, type: str, supplierId: int|null, date: str, lines: T25[], files: T11[], externalNumber?: str|null, createdAt?: str, ledger?: T46 }` -- `T7` = `{ id: int, number: str, type: str, date: str, lines: T25[], shippings: T33[], entityId?: int|null, externalNumber?: str|null, createdAt?: str|null, lineCount?: int, packageCount?: int }` -- `T8` = `{ labeltemplate: T9 }` -- `T9` = `{ id: int, name: str, width: num, height: num, dpi: int, type: str, content: T21, thumb?: str|null }` -- `T10` = `{ quote: T13 }` -- `T11` = `{ id: int, manifestId: int, fileId: int, sort: int, hash: str, mimetype: str, name: str, size: int, created?: str, modified?: str, thumbavif?: str|null, thumbx?: int|null, thumby?: int|null, meta?: { [k]: str }|null }` -- `T12` = `{ id: int, name: str, pairingpin?: str|null, token?: str|null, pairedAt?: str|null, clientserial?: str|null, rootCategoryId?: int|null, syncRootArticles?: bool, lastseenAt?: str|null, updatedAt?: str|null, categoryIds?: int[] }` -- `T13` = `{ id: int, number: str, type: str, entityId: int|null, date: str, lines: T25[], createdAt?: str }` -- `T14` = `{ id: int, articleId: int, entityId: int, pu: num, sort: int, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T48|null }` -- `T15` = `{ id: int, entityId: int, addressType: str, firstName?: str|null, name?: str|null, street?: str|null, streetNumber?: str|null, zip?: str|null, city?: str|null, county?: str|null }` -- `T16` = `{ ledger: T17[] }` -- `T17` = `{ id: int, manifestarticle_id: int, transaction_type: str, amount: num, transaction_text: str, hash_version: int, prev_hash?: str, sku?: str|null, created_at?: str }` -- `T18` = `{ id: int, name: str, sort: int, exclusive: bool, values: T37[], articleCount?: int }` -- `T19` = `{ id: int, companyuser_id: int, provider: str, model: str, created_at: str, updated_at: str, state: str, started_by?: integer,null, first_message?: string,null }` -- `T20` = `{ id: int, name: str, rootCategoryId: int|null, languageId: int|null, iso639: str|null, taxrate: num, reducedtaxrate: num, taxfreerate: num }` -- `T21` = `{ objects: T26[] }` -- `T22` = `{ objects: T27[] }` -- `T23` = `{ printer: T29 }` -- `T24` = `{ entity: T32 }` -- `T25` = `{ id: int, sku: str|null, name: str|null, pu: num, amount: num, net: num, rebate: num, taxrate: num, comment: str|null }` -- `T26` = `{ id: str, type: str, x: num, y: num, w?: num, h?: num, text?: str, font?: str, fontSize?: num, barcodeFormat?: str }` -- `T27` = `{ id: str, type: str, x: num, y: num, w?: num, h?: num, text?: str, font?: str, fontSize?: num, barcodeFormat?: str }` -- `T28` = `{ shipping: T33 }` -- `T29` = `{ id: int, company_id: int, address: str, type: str, sort: int, model?: str|null, serial?: str|null, desc?: str|null }` -- `T30` = `{ amount: num, net: num, taxrate: num, sku?: str|null, name?: str|null, pu?: num, rebate?: num, comment?: str|null }` -- `T31` = `{ sort: int, fullHash: str, fullW: int, fullH: int, fullSize: int, thumbW: int, thumbH: int, thumbHash: str }` -- `T32` = `{ id: int, customergroupId: int, firstName: str|null, name: str, number: str|null, createdAt: str, updatedAt: str }` -- `T33` = `{ id: int, manifestId: int, number: str, type: str, state: str, trackingCode?: str|null, carrier?: str|null }` -- `T34` = `{ name: str, id?: int|null, fullHash?: str|null, thumbW?: int|null, thumbH?: int|null, thumbHash?: str|null }` -- `T35` = `{ article: T40 }` -- `T36` = `{ si: str, basesi: str, basesifactor: num, symbol?: str|null, name?: str|null }` -- `T37` = `{ id: int, attributeId: int, value: str, sort: int, articleCount?: int }` -- `T38` = `{ id: int, name: str, sort: int, exclusive: bool, articleCount?: int }` -- `T39` = `{ id: int, accountId: int, manifestId: int, type: str, amount: num }` -- `T40` = `{ id: int, categoryId: int, name: str, sku: str, track_stock: bool }` -- `T41` = `{ id: int, email: str, selectedCompanyId: int|null, picture?: str }` -- `T42` = `{ minmultiplier: num, net: num, taxRate: num, customergroupId: int }` -- `T43` = `{ fullHash: str, thumbW: int, thumbH: int, thumbHash: str }` -- `T44` = `{ id: int, entityId: int, contactType: str, contact: str }` -- `T45` = `{ id: int, name: str, createdAt: str, updatedAt: str }` -- `T46` = `{ totalPositions: int, completelyOnLedgerPositions: int }` -- `T47` = `{ warehouse: T49 }` -- `T48` = `{ net: num, taxId: int, taxRate?: num|null }` -- `T49` = `{ id: int, name: str, sort: int }` -- `T50` = `{ id: int, categoryIds: int[] }` +- `T6` = `{ id: int, number: str, type: str, supplierId: int|null, date: str, lines: T28[], files: T13[], externalNumber?: str|null, createdAt?: str, ledger?: T50 }` +- `T7` = `{ id: int, number: str, type: str, date: str, lines: T28[], shippings: T36[], entityId?: int|null, externalNumber?: str|null, createdAt?: str|null, lineCount?: int, packageCount?: int }` +- `T8` = `{ name: str, path: str, totalSizeBytes: int, timestamp: str|null, manifest?: T9|null }` +- `T9` = `{ id: str, timestamp: str, dateKey: str, monthKey: str, dbProvider: str, manual: bool, files: T17, totalSizeBytes: int, durationMs: int }` +- `T10` = `{ labeltemplate: T11 }` +- `T11` = `{ id: int, name: str, width: num, height: num, dpi: int, type: str, content: T24, thumb?: str|null }` +- `T12` = `{ quote: T15 }` +- `T13` = `{ id: int, manifestId: int, fileId: int, sort: int, hash: str, mimetype: str, name: str, size: int, created?: str, modified?: str, thumbavif?: str|null, thumbx?: int|null, thumby?: int|null, meta?: { [k]: str }|null }` +- `T14` = `{ id: int, name: str, pairingpin?: str|null, token?: str|null, pairedAt?: str|null, clientserial?: str|null, rootCategoryId?: int|null, syncRootArticles?: bool, lastseenAt?: str|null, updatedAt?: str|null, categoryIds?: int[] }` +- `T15` = `{ id: int, number: str, type: str, entityId: int|null, date: str, lines: T28[], createdAt?: str }` +- `T16` = `{ id: int, articleId: int, entityId: int, pu: num, sort: int, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T53|null }` +- `T17` = `{ vfs: T51, storage: T51, database: T44 }` +- `T18` = `{ id: int, entityId: int, addressType: str, firstName?: str|null, name?: str|null, street?: str|null, streetNumber?: str|null, zip?: str|null, city?: str|null, county?: str|null }` +- `T19` = `{ ledger: T20[] }` +- `T20` = `{ id: int, manifestarticle_id: int, transaction_type: str, amount: num, transaction_text: str, hash_version: int, prev_hash?: str, sku?: str|null, created_at?: str }` +- `T21` = `{ id: int, name: str, sort: int, exclusive: bool, values: T40[], articleCount?: int }` +- `T22` = `{ id: int, companyuser_id: int, provider: str, model: str, created_at: str, updated_at: str, state: str, started_by?: integer,null, first_message?: string,null }` +- `T23` = `{ id: int, name: str, rootCategoryId: int|null, languageId: int|null, iso639: str|null, taxrate: num, reducedtaxrate: num, taxfreerate: num }` +- `T24` = `{ objects: T29[] }` +- `T25` = `{ objects: T30[] }` +- `T26` = `{ printer: T32 }` +- `T27` = `{ entity: T35 }` +- `T28` = `{ id: int, sku: str|null, name: str|null, pu: num, amount: num, net: num, rebate: num, taxrate: num, comment: str|null }` +- `T29` = `{ id: str, type: str, x: num, y: num, w?: num, h?: num, text?: str, font?: str, fontSize?: num, barcodeFormat?: str }` +- `T30` = `{ id: str, type: str, x: num, y: num, w?: num, h?: num, text?: str, font?: str, fontSize?: num, barcodeFormat?: str }` +- `T31` = `{ shipping: T36 }` +- `T32` = `{ id: int, company_id: int, address: str, type: str, sort: int, model?: str|null, serial?: str|null, desc?: str|null }` +- `T33` = `{ amount: num, net: num, taxrate: num, sku?: str|null, name?: str|null, pu?: num, rebate?: num, comment?: str|null }` +- `T34` = `{ sort: int, fullHash: str, fullW: int, fullH: int, fullSize: int, thumbW: int, thumbH: int, thumbHash: str }` +- `T35` = `{ id: int, customergroupId: int, firstName: str|null, name: str, number: str|null, createdAt: str, updatedAt: str }` +- `T36` = `{ id: int, manifestId: int, number: str, type: str, state: str, trackingCode?: str|null, carrier?: str|null }` +- `T37` = `{ name: str, id?: int|null, fullHash?: str|null, thumbW?: int|null, thumbH?: int|null, thumbHash?: str|null }` +- `T38` = `{ article: T43 }` +- `T39` = `{ si: str, basesi: str, basesifactor: num, symbol?: str|null, name?: str|null }` +- `T40` = `{ id: int, attributeId: int, value: str, sort: int, articleCount?: int }` +- `T41` = `{ id: int, name: str, sort: int, exclusive: bool, articleCount?: int }` +- `T42` = `{ id: int, accountId: int, manifestId: int, type: str, amount: num }` +- `T43` = `{ id: int, categoryId: int, name: str, sku: str, track_stock: bool }` +- `T44` = `{ name: str|null, sizeBytes: int, backedUp: bool, reason?: str|null }` +- `T45` = `{ id: int, email: str, selectedCompanyId: int|null, picture?: str }` +- `T46` = `{ minmultiplier: num, net: num, taxRate: num, customergroupId: int }` +- `T47` = `{ fullHash: str, thumbW: int, thumbH: int, thumbHash: str }` +- `T48` = `{ id: int, entityId: int, contactType: str, contact: str }` +- `T49` = `{ id: int, name: str, createdAt: str, updatedAt: str }` +- `T50` = `{ totalPositions: int, completelyOnLedgerPositions: int }` +- `T51` = `{ name: str, sizeBytes: int, sourceExists: bool }` +- `T52` = `{ warehouse: T54 }` +- `T53` = `{ net: num, taxId: int, taxRate?: num|null }` +- `T54` = `{ id: int, name: str, sort: int }` +- `T55` = `{ id: int, categoryIds: int[] }` ### Routes @@ -88,7 +93,7 @@ _none_ #### Create article in category — `POST /article` - Params: `body: { categoryId: int, name: str, desc?: str, seo?: str, track_stock?: bool }` -- Returns: `201 T35` +- Returns: `201 T38` #### Export articles as ZIP — `GET /article/export.zip` - Params: `query: categoryId?: int` - Returns: `200 zip` @@ -124,10 +129,10 @@ _none_ - Returns: `200 { children: { id: int, sku: str, name: str, parentsort: int, attributeValueId: int, attributeValue: str }[] }` #### Create and attach a new child article to a parent article — `POST /article/{sku}/children` - Params: `sku: str, body: { attributeValueId?: int, value?: str, name?: str }` -- Returns: `201 T35` +- Returns: `201 T38` #### Attach an existing article as a child to a parent article — `PUT /article/{sku}/children` - Params: `sku: str, body: { sku: str, attributeValueId?: int, value?: str, reparent?: bool }` -- Returns: `200 { article: T40, children: { id: int, sku: str, name: str, parentsort: int, attributeValueId: int, attributeValue: str }[] }` +- Returns: `200 { article: T43, children: { id: int, sku: str, name: str, parentsort: int, attributeValueId: int, attributeValue: str }[] }` #### Remove a child article from a parent article — `DELETE /article/{sku}/children/{childSku}` - Params: `sku: str, childSku: str, query: deleteArticle?: bool` - Returns: `200 { success: bool, deleted: bool }` @@ -154,7 +159,7 @@ _none_ - Returns: `200 { options: { id: int, articleId: int, sku: str, name: str, count: int, sort: int, mandated: bool }[] }` #### Toggle parent mode for an article — `POST /article/{sku}/parent` - Params: `sku: str, body: { isParent: bool, attributeNameId?: int }` -- Returns: `200 T35` +- Returns: `200 T38` #### Replace POS prices by SKU (net > gross; price=net, tax=taxRate %) — `PUT /article/{sku}/prices` - Params: `sku: str, body: { prices: { net?: num, gross?: num, price?: num, taxRate?: num, tax?: num, minmultiplier?: num }[] }` - Returns: `200 T3` @@ -172,10 +177,10 @@ _none_ - Returns: `200 { ok: bool }` #### List article suppliers — `GET /article/{sku}/supplier` - Params: `sku: str` -- Returns: `200 { suppliers: T14[] }` +- Returns: `200 { suppliers: T16[] }` #### Assign supplier to article — `POST /article/{sku}/supplier` - Params: `sku: str, body: { entityId: int, sku?: str|null, pu?: num, stock?: num|null, sort?: int|null, netPrice?: num|null, taxId?: int|null, taxRate?: num|null }` -- Returns: `201 { supplier: T14 }` +- Returns: `201 { supplier: T16 }` #### Reorder article suppliers — `PUT /article/{sku}/supplier/order` - Params: `sku: str, body: { ids: int[] }` - Returns: `200 { ids: int[] }` @@ -184,7 +189,7 @@ _none_ - Returns: `204 void` #### Update article supplier assignment — `PATCH /article/{sku}/supplier/{id}` - Params: `sku: str, id: int, body: { sku?: str|null, pu?: num, stock?: num|null, sort?: int, netPrice?: num|null, taxId?: int|null, taxRate?: num|null }` -- Returns: `200 { supplier: T14 }` +- Returns: `200 { supplier: T16 }` #### Set article track_stock flag by SKU — `PUT /article/{sku}/track_stock` - Params: `sku: str, body: { track_stock: bool }` - Returns: `200 T3` @@ -196,19 +201,19 @@ _none_ #### List attribute names — `GET /attributename` _none_ -- Returns: `200 { attributenames: T18[] }` +- Returns: `200 { attributenames: T21[] }` #### Create attribute name — `POST /attributename` - Params: `body: { name: str, sort?: int, exclusive?: bool }` -- Returns: `201 { attributename: T18 }` +- Returns: `201 { attributename: T21 }` #### Reorder attribute names — `PUT /attributename/order` - Params: `body: { attributenameIds: int[] }` - Returns: `200 { ok: bool }` #### List values for an attribute — `GET /attributename/{attributeId}/value` - Params: `attributeId: int` -- Returns: `200 { values: T37[] }` +- Returns: `200 { values: T40[] }` #### Create value for an attribute — `POST /attributename/{attributeId}/value` - Params: `attributeId: int, body: { value: str, sort?: int }` -- Returns: `201 { attributevalue: T37 }` +- Returns: `201 { attributevalue: T40 }` #### Reorder values of an attribute — `PUT /attributename/{attributeId}/value/order` - Params: `attributeId: int, body: { attributevalueIds: int[] }` - Returns: `200 { ok: bool }` @@ -217,7 +222,7 @@ _none_ - Returns: `200 { ok: bool }` #### Update attribute name — `PATCH /attributename/{id}` - Params: `id: int, body: { name?: str, sort?: int, exclusive?: bool }` -- Returns: `200 { attributename: T18 }` +- Returns: `200 { attributename: T21 }` ### Section: /attributevalue @@ -226,37 +231,37 @@ _none_ - Returns: `200 { ok: bool }` #### Update attribute value — `PATCH /attributevalue/{id}` - Params: `id: int, body: { value?: str, sort?: int }` -- Returns: `200 { attributevalue: T37 }` +- Returns: `200 { attributevalue: T40 }` #### Delete attribute value image — `DELETE /attributevalue/{id}/image` - Params: `id: int` -- Returns: `200 { attributevalue: { id: int, thumbW: int|null, thumbH: int|null, thumbHash: str|null, pics: T43[] } }` +- Returns: `200 { attributevalue: { id: int, thumbW: int|null, thumbH: int|null, thumbHash: str|null, pics: T47[] } }` #### Add or replace attribute value image — `POST /attributevalue/{id}/image` - Params: `id: int, image/avif` -- Returns: `201 { attributevalue: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: T43[] } }` +- Returns: `201 { attributevalue: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: T47[] } }` ### Section: /auth #### Login with Google ID token — `POST /auth/login` - Params: `body: { idToken: str }` -- Returns: `200 { message: str, user: T41 }` +- Returns: `200 { message: str, user: T45 }` #### Logout — `POST /auth/logout` _none_ - Returns: `200 { message: str }` #### Current user — `GET /auth/me` _none_ -- Returns: `200 { user: T41, googleClientId: str }` +- Returns: `200 { user: T45, googleClientId: str }` #### Set selected company — `PUT /auth/selected-company` - Params: `body: { companyId: int }` -- Returns: `200 { user: T41 }` +- Returns: `200 { user: T45 }` ### Section: /backup #### List backups and service status — `GET /backup` _none_ -- Returns: `200 { status: {}, backups: {} }` +- Returns: `200 { status: { enabled: bool, isRunning: bool, dbProvider: str, mssqlWarning: bool, backupDir: str, retention: { hourlyMax: int, dailyMax: int, monthly: str }, counts: { hourly: int, daily: int, monthly: int }, latestHourly?: T8|null, latestDaily?: T8|null, latestMonthly?: T8|null }, backups: { counts: { hourly: int, daily: int, monthly: int }, hourly: T8[], daily: T8[], monthly: T8[] } }` #### Trigger manual backup — `POST /backup/run` _none_ -- Returns: `200 {}` +- Returns: `200 { success: bool, id: str, timestamp: str, promotedDaily: bool, promotedMonthly: bool, totalSizeBytes: int, pruneResult: { hourlyPruned: int, dailyPruned: int }, manifest: T9 }` ### Section: /brand @@ -265,7 +270,7 @@ _none_ - Returns: `200 { brands: { id: int, name: str, articleCount: int, pics: { fullHash: str, thumbW: int, thumbH: int, thumbHash: str, smallThumbW?: int|null, smallThumbH?: int|null, smallThumbBinary?: str|null }[], gsprpinfo?: str|null }[], total: int, offset: int, limit: int }` #### Create brand — `POST /brand` - Params: `body: { name: str, gsprpinfo?: str }` -- Returns: `201 { brand: { id: int, name: str, pics: T43[], gsprpinfo?: str|null } }` +- Returns: `201 { brand: { id: int, name: str, pics: T47[], gsprpinfo?: str|null } }` #### Delete brand — `DELETE /brand/{id}` - Params: `id: int` - Returns: `204 void` @@ -274,10 +279,10 @@ _none_ - Returns: `200 { brand: { id: int, name: str, touchedArticleCount: int, gsprpinfo?: str|null } }` #### Delete brand image — `DELETE /brand/{id}/image` - Params: `id: int` -- Returns: `200 { brand: { id: int, thumbW: int|null, thumbH: int|null, thumbHash: str|null, pics: T43[] } }` +- Returns: `200 { brand: { id: int, thumbW: int|null, thumbH: int|null, thumbHash: str|null, pics: T47[] } }` #### Add or replace brand image — `POST /brand/{id}/image` - Params: `id: int, image/avif` -- Returns: `201 { brand: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: T43[] } }` +- Returns: `201 { brand: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: T47[] } }` ### Section: /category @@ -301,7 +306,7 @@ _none_ - Returns: `200 { category: { id: int, name: str, slug: str, parentId: int, sort: int } }` #### Articles in category — `GET /category/{id}/articles` - Params: `id: int` -- Returns: `200 { articles: { id: int, sku: str, name: str, slug: str, track_stock: bool, optionsCount: int, articleListCount: int, childCount: int, net?: num|null, taxRate?: num|null, parentArticleId?: int|null, parentSku?: str|null, fullHash?: str|null, thumbW?: int|null, thumbH?: int|null, thumbHash?: str|null, brand?: T34|null }[] }` +- Returns: `200 { articles: { id: int, sku: str, name: str, slug: str, track_stock: bool, optionsCount: int, articleListCount: int, childCount: int, net?: num|null, taxRate?: num|null, parentArticleId?: int|null, parentSku?: str|null, fullHash?: str|null, thumbW?: int|null, thumbH?: int|null, thumbHash?: str|null, brand?: T37|null }[] }` #### List category attribute values — `GET /category/{id}/attributevalue` - Params: `id: int` - Returns: `200 { attributevalues: { id: int, attributeId: int, attributeName: str, attributeValueId: int, value: str, sort: int, categoryId?: int, exclusive?: bool }[] }` @@ -328,10 +333,10 @@ _none_ #### List companies — `GET /company` _none_ -- Returns: `200 { companies: T20[] }` +- Returns: `200 { companies: T23[] }` #### Create company — `POST /company` - Params: `body: { iso639: str, name: str, taxrate: num, reducedtaxrate: num }` -- Returns: `201 { company: T20, user: T41 }` +- Returns: `201 { company: T23, user: T45 }` #### Get company history — `GET /company/history` - Params: `query: limit?: int` - Returns: `200 { history: { id: int, date: str, text: str, companyuserId?: int|null }[], truncated: bool }` @@ -355,7 +360,7 @@ _none_ - Returns: `204 void` #### Update company — `PUT /company/{id}` - Params: `id: int, body: { iso639: str, name: str, taxrate: num, reducedtaxrate: num }` -- Returns: `200 { company: T20 }` +- Returns: `200 { company: T23 }` ### Section: /customergroup @@ -364,7 +369,7 @@ _none_ - Returns: `200 { customergroups: { id: int, name: str, sort: int, editable: bool }[] }` #### Create customer group — `POST /customergroup` - Params: `body: { name: str }` -- Returns: `201 { customergroup: T49 }` +- Returns: `201 { customergroup: T54 }` #### Reorder customer groups — `PUT /customergroup/order` - Params: `body: { customergroupIds: int[] }` - Returns: `200 { customergroupIds: int[] }` @@ -373,15 +378,15 @@ _none_ - Returns: `204 void` #### Update customer group — `PATCH /customergroup/{id}` - Params: `id: int, body: { name: str }` -- Returns: `200 { customergroup: T49 }` +- Returns: `200 { customergroup: T54 }` ### Section: /delivery #### List deliveries — `GET /delivery` _none_ -- Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T46 }[] }` +- Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T50 }[] }` #### Create delivery — `POST /delivery` -- Params: `body: { externalNumber: str, date: str, lines: T30[], supplierId?: int|null, files?: { mimetype: str, name: str, content: str, sort?: int, size?: int, hash?: str, created?: str, modified?: str, meta?: { [k]: str } }[] }` +- Params: `body: { externalNumber: str, date: str, lines: T33[], supplierId?: int|null, files?: { mimetype: str, name: str, content: str, sort?: int, size?: int, hash?: str, created?: str, modified?: str, meta?: { [k]: str } }[] }` - Returns: `201 T5` #### Parse document (SSE) — `POST /delivery/parse` - Params: `form: { file: str }` @@ -402,7 +407,7 @@ _none_ - Params: `id: int` - Returns: `200 T5` #### Update delivery — `PATCH /delivery/{id}` -- Params: `id: int, body: { externalNumber?: str|null, date?: str, supplierId?: int|null, lines?: T30[], files?: { mimetype: str, name: str, content: str, sort?: int, size?: int, hash?: str, created?: str, modified?: str, meta?: { [k]: str } }[] }` +- Params: `id: int, body: { externalNumber?: str|null, date?: str, supplierId?: int|null, lines?: T33[], files?: { mimetype: str, name: str, content: str, sort?: int, size?: int, hash?: str, created?: str, modified?: str, meta?: { [k]: str } }[] }` - Returns: `200 T5` #### Get delivery attachment file content — `GET /delivery/{id}/file/{fileId}` - Params: `id: int, fileId: int, query: download?: bool` @@ -412,46 +417,46 @@ _none_ #### List entities — `GET /entity` - Params: `query: customergroupId?: int, role?: str` -- Returns: `200 { entities: T32[] }` +- Returns: `200 { entities: T35[] }` #### Create entity — `POST /entity` - Params: `body: { customergroupId: int, name: str, firstName?: str|null, number?: str }` -- Returns: `201 T24` +- Returns: `201 T27` #### Peek next customer number — `GET /entity/next-number` _none_ - Returns: `200 { number: str }` #### List entity addresses — `GET /entity/{entityId}/address` - Params: `entityId: int` -- Returns: `200 { addresses: T15[] }` +- Returns: `200 { addresses: T18[] }` #### Create entity address — `POST /entity/{entityId}/address` - Params: `entityId: int, body: { addressType: str, firstName?: str|null, name?: str|null, street?: str|null, streetNumber?: str|null, zip?: str|null, city?: str|null, county?: str|null }` -- Returns: `201 { address: T15 }` +- Returns: `201 { address: T18 }` #### Delete entity address — `DELETE /entity/{entityId}/address/{id}` - Params: `entityId: int, id: int` - Returns: `204 void` #### Update entity address — `PATCH /entity/{entityId}/address/{id}` - Params: `entityId: int, id: int, body: { addressType?: str, firstName?: str|null, name?: str|null, street?: str|null, streetNumber?: str|null, zip?: str|null, city?: str|null, county?: str|null }` -- Returns: `200 { address: T15 }` +- Returns: `200 { address: T18 }` #### List entity contacts — `GET /entity/{entityId}/contact` - Params: `entityId: int` -- Returns: `200 { contacts: T44[] }` +- Returns: `200 { contacts: T48[] }` #### Create entity contact — `POST /entity/{entityId}/contact` - Params: `entityId: int, body: { contactType: str, contact: str }` -- Returns: `201 { contact: T44 }` +- Returns: `201 { contact: T48 }` #### Delete entity contact — `DELETE /entity/{entityId}/contact/{id}` - Params: `entityId: int, id: int` - Returns: `204 void` #### Update entity contact — `PATCH /entity/{entityId}/contact/{id}` - Params: `entityId: int, id: int, body: { contactType?: str, contact?: str }` -- Returns: `200 { contact: T44 }` +- Returns: `200 { contact: T48 }` #### Delete entity — `DELETE /entity/{id}` - Params: `id: int` - Returns: `204 void` #### Get entity — `GET /entity/{id}` - Params: `id: int` -- Returns: `200 T24` +- Returns: `200 T27` #### Update entity — `PATCH /entity/{id}` - Params: `id: int, body: { name?: str, firstName?: str|null, number?: str|null }` -- Returns: `200 T24` +- Returns: `200 T27` ### Section: /events @@ -474,6 +479,8 @@ _none_ - `modelconversation`: `{}` - `modelconversation-`: `{}` - `brand`: `{ sender, brandId }` + - `draft`: `{ sender, action, name, content }` + - `draft:request`: `{ requestId, action, name, target, sender }` ### Section: /health @@ -493,35 +500,35 @@ _none_ _none_ - Returns: `200 { labeltemplates: { id: int, name: str, width: num, height: num, dpi: int, type: str, thumb?: str|null }[] }` #### Create label template — `POST /labeltemplate` -- Params: `body: { name: str, width: num, height: num, dpi: int, type: str, content: T22 }` -- Returns: `201 T8` +- Params: `body: { name: str, width: num, height: num, dpi: int, type: str, content: T25 }` +- Returns: `201 T10` #### Delete label template — `DELETE /labeltemplate/{id}` - Params: `id: int` - Returns: `204 void` #### Get label template by ID — `GET /labeltemplate/{id}` - Params: `id: int` -- Returns: `200 T8` +- Returns: `200 T10` #### Update label template (partial) — `PATCH /labeltemplate/{id}` -- Params: `id: int, body: { name?: str, width?: num, height?: num, dpi?: int, type?: str, content?: T22 }` -- Returns: `200 T8` +- Params: `id: int, body: { name?: str, width?: num, height?: num, dpi?: int, type?: str, content?: T25 }` +- Returns: `200 T10` #### Update label template — `PUT /labeltemplate/{id}` -- Params: `id: int, body: { name?: str, width?: num, height?: num, dpi?: int, type?: str, content?: T22 }` -- Returns: `200 T8` +- Params: `id: int, body: { name?: str, width?: num, height?: num, dpi?: int, type?: str, content?: T25 }` +- Returns: `200 T10` ### Section: /ledger #### Query ledger by manifest article ID or SKU — `GET /ledger` - Params: `query: manifestarticle_id?: int, sku?: str, transaction_type?: str` -- Returns: `200 T16` +- Returns: `200 T19` #### Add ledger entry — `POST /ledger` - Params: `body: { manifestarticle_id: int, transaction_type: str, amount: num, transaction_text: str }` -- Returns: `201 { ledger: T17 }` +- Returns: `201 { ledger: T20 }` #### Query ledger by manifest article ID — `GET /ledger/manifestarticle/{manifestarticleId}` - Params: `manifestarticleId: int, query: transaction_type?: str` -- Returns: `200 T16` +- Returns: `200 T19` #### Query ledger by article SKU — `GET /ledger/sku/{sku}` - Params: `sku: str, query: transaction_type?: str` -- Returns: `200 T16` +- Returns: `200 T19` ### Section: /mcp @@ -551,16 +558,16 @@ _none_ #### List conversations — `GET /modelconversation` _none_ -- Returns: `200 { conversations: T19[] }` +- Returns: `200 { conversations: T22[] }` #### Create conversation — `POST /modelconversation` - Params: `body: { provider: str, model: str }` -- Returns: `201 { conversation: T19 }` +- Returns: `201 { conversation: T22 }` #### Delete conversation — `DELETE /modelconversation/{id}` - Params: `id: int` - Returns: `204 void` #### Get conversation — `GET /modelconversation/{id}` - Params: `id: int` -- Returns: `200 { conversation: T19 }` +- Returns: `200 { conversation: T22 }` #### List conversation messages — `GET /modelconversation/{id}/message` - Params: `id: int` - Returns: `200 { messages: { id: int, conversation_id: int, created_at: str, role: str, message: str }[] }` @@ -601,7 +608,7 @@ _none_ - Params: `query: offset?: int, limit?: int, search?: str, onlyUnpaid?: bool, onlyUndelivered?: bool, seekMonths?: int` - Returns: `200 { orders: T2[], total: int, unfilteredTotal: int, offset: int, limit: int }` #### Create order — `POST /order` -- Params: `body: { number: str, date: str, lines: T30[], entityId?: int|null }` +- Params: `body: { number: str, date: str, lines: T33[], entityId?: int|null }` - Returns: `201 T1` #### Delete order — `DELETE /order/{id}` - Params: `id: int` @@ -610,14 +617,14 @@ _none_ - Params: `id: int` - Returns: `200 T1` #### Update order — `PATCH /order/{id}` -- Params: `id: int, body: { number?: str, date?: str, entityId?: int|null, lines?: T30[] }` +- Params: `id: int, body: { number?: str, date?: str, entityId?: int|null, lines?: T33[] }` - Returns: `200 T1` #### List payments of an order — `GET /order/{id}/payment` - Params: `id: int` -- Returns: `200 { payments: T39[] }` +- Returns: `200 { payments: T42[] }` #### Add payment to an order — `POST /order/{id}/payment` - Params: `id: int, body: { accountId: int, type: str, amount: num }` -- Returns: `201 { payment: T39 }` +- Returns: `201 { payment: T42 }` #### List shipments of an order — `GET /order/{id}/shipment` - Params: `id: int` - Returns: `200 { shipments: T7[] }` @@ -626,10 +633,10 @@ _none_ - Returns: `201 { shipment: T7 }` #### List shippings of an order — `GET /order/{id}/shipping` - Params: `id: int` -- Returns: `200 { shippings: T33[] }` +- Returns: `200 { shippings: T36[] }` #### Create shipping for an order — `POST /order/{id}/shipping` - Params: `id: int, body: { type: str, state: str, warehouseId?: int }` -- Returns: `201 T28` +- Returns: `201 T31` ### Section: /package @@ -647,37 +654,37 @@ _none_ #### List POS terminals — `GET /posterminal` _none_ -- Returns: `200 { posterminals: T12[] }` +- Returns: `200 { posterminals: T14[] }` #### Create POS terminal — `PUT /posterminal` - Params: `body: { name: str, rootCategoryId?: int|null, syncRootArticles?: bool }` -- Returns: `200 { posterminal: T12 }` +- Returns: `200 { posterminal: T14 }` #### Delete POS terminal — `DELETE /posterminal/{id}` - Params: `id: int` - Returns: `204 void` #### Update POS terminal — `PATCH /posterminal/{id}` - Params: `id: int, body: { name?: str, rootCategoryId?: int|null, syncRootArticles?: bool, pairingpin?: str|null }` -- Returns: `200 { posterminal: T12 }` +- Returns: `200 { posterminal: T14 }` #### Disable all categories on terminal — `DELETE /posterminal/{id}/all` - Params: `id: int` -- Returns: `200 T50` +- Returns: `200 T55` #### Enable all categories on terminal — `PUT /posterminal/{id}/all` - Params: `id: int` -- Returns: `200 T50` +- Returns: `200 T55` #### Disable category on terminal — `DELETE /posterminal/{id}/category/{categoryId}` - Params: `id: int, categoryId: int` -- Returns: `200 T50` +- Returns: `200 T55` #### Enable category on terminal — `PUT /posterminal/{id}/category/{categoryId}` - Params: `id: int, categoryId: int` -- Returns: `200 T50` +- Returns: `200 T55` ### Section: /printer #### List printers — `GET /printer` _none_ -- Returns: `200 { printers: T29[] }` +- Returns: `200 { printers: T32[] }` #### Create printer — `POST /printer` - Params: `body: { address: str, type: str, model?: str|null, serial?: str|null, sort?: int, desc?: str|null }` -- Returns: `201 T23` +- Returns: `201 T26` #### Reorder printers — `PUT /printer/order` - Params: `body: { printerIds: int[] }` - Returns: `200 { printerIds: int[] }` @@ -686,22 +693,22 @@ _none_ - Returns: `204 void` #### Get printer by ID — `GET /printer/{id}` - Params: `id: int` -- Returns: `200 T23` +- Returns: `200 T26` #### Update printer (partial) — `PATCH /printer/{id}` - Params: `id: int, body: { address?: str, type?: str, model?: str|null, serial?: str|null, sort?: int, desc?: str|null }` -- Returns: `200 T23` +- Returns: `200 T26` #### Update printer — `PUT /printer/{id}` - Params: `id: int, body: { address?: str, type?: str, model?: str|null, serial?: str|null, sort?: int, desc?: str|null }` -- Returns: `200 T23` +- Returns: `200 T26` ### Section: /propertyname #### List property names — `GET /propertyname` _none_ -- Returns: `200 { propertynames: T38[] }` +- Returns: `200 { propertynames: T41[] }` #### Create property name — `POST /propertyname` - Params: `body: { name: str, sort?: int, exclusive?: bool }` -- Returns: `201 { propertyname: T38 }` +- Returns: `201 { propertyname: T41 }` #### Reorder property names — `PUT /propertyname/order` - Params: `body: { propertynameIds: int[] }` - Returns: `200 { ok: bool }` @@ -710,7 +717,7 @@ _none_ - Returns: `200 { ok: bool }` #### Update property name — `PATCH /propertyname/{id}` - Params: `id: int, body: { name?: str, sort?: int, exclusive?: bool }` -- Returns: `200 { propertyname: T38 }` +- Returns: `200 { propertyname: T41 }` ### Section: /public @@ -733,17 +740,17 @@ _none_ _none_ - Returns: `200 { quotes: { id: int, number: str, type: str, entityId: int|null, date: str, createdAt?: str }[] }` #### Create quote — `POST /quote` -- Params: `body: { number: str, date: str, lines: T30[], entityId?: int|null }` -- Returns: `201 T10` +- Params: `body: { number: str, date: str, lines: T33[], entityId?: int|null }` +- Returns: `201 T12` #### Delete quote — `DELETE /quote/{id}` - Params: `id: int` - Returns: `204 void` #### Get quote — `GET /quote/{id}` - Params: `id: int` -- Returns: `200 T10` +- Returns: `200 T12` #### Update quote — `PATCH /quote/{id}` -- Params: `id: int, body: { number?: str, date?: str, entityId?: int|null, lines?: T30[] }` -- Returns: `200 T10` +- Params: `id: int, body: { number?: str, date?: str, entityId?: int|null, lines?: T33[] }` +- Returns: `200 T12` ### Section: /serper @@ -770,10 +777,10 @@ _none_ - Returns: `200 { shipment: T7 }` #### List packages of a shipment — `GET /shipment/{id}/shipping` - Params: `id: int` -- Returns: `200 { shippings: T33[] }` +- Returns: `200 { shippings: T36[] }` #### Create package for a shipment — `POST /shipment/{id}/shipping` - Params: `id: int, body: { type: str, state: str, trackingCode?: str, carrier?: str, warehouseId?: int }` -- Returns: `201 T28` +- Returns: `201 T31` ### Section: /shipping @@ -782,7 +789,7 @@ _none_ - Returns: `204 void` #### Update shipping — `PATCH /shipping/{id}` - Params: `id: int, body: { type?: str, state?: str, trackingCode?: str, carrier?: str, warehouseId?: int }` -- Returns: `200 T28` +- Returns: `200 T31` #### List packages of a shipping — `GET /shipping/{id}/package` - Params: `id: int` - Returns: `200 { packages: { id: int, shippingId: int, entityaddressId: int, number: str, type: str, state: str, details?: str|null }[] }` @@ -800,28 +807,28 @@ _none_ #### Adjust stock manually — `POST /stock/adjust` - Params: `body: { sku?: str, warehouseId?: int, amount?: num, text?: str|null, lines?: { sku: str, amount: num, warehouseId?: int, text?: str }[] }` -- Returns: `201 { manifest: { id: int, number: str, type: str, date: str, createdAt: str }, lines: { manifestarticle_id: int, sku: str, name: str, warehouse_id: int, amount: num, text: str }[], ledger: T17[] }` +- Returns: `201 { manifest: { id: int, number: str, type: str, date: str, createdAt: str }, lines: { manifestarticle_id: int, sku: str, name: str, warehouse_id: int, amount: num, text: str }[], ledger: T20[] }` ### Section: /supplier #### List suppliers — `GET /supplier` _none_ -- Returns: `200 { suppliers: T45[] }` +- Returns: `200 { suppliers: T49[] }` #### Create supplier — `POST /supplier` - Params: `body: { name: str }` -- Returns: `201 { supplier: T45 }` +- Returns: `201 { supplier: T49 }` #### Delete supplier — `DELETE /supplier/{id}` - Params: `id: int` - Returns: `204 void` #### Update supplier — `PATCH /supplier/{id}` - Params: `id: int, body: { name: str }` -- Returns: `200 { supplier: T45 }` +- Returns: `200 { supplier: T49 }` #### List supplier articles by SKUs — `GET /supplier/{id}/articles` - Params: `id: int, query: skus?: string` -- Returns: `200 { articles: { id: int, articleId: int, entityId: int, pu: num, sort: int, article: { id: int, sku: str, name?: str|null, slug?: str|null, photos?: { sort: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str }[], eans?: str[] }, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T48|null }[] }` +- Returns: `200 { articles: { id: int, articleId: int, entityId: int, pu: num, sort: int, article: { id: int, sku: str, name?: str|null, slug?: str|null, photos?: { sort: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str }[], eans?: str[] }, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T53|null }[] }` #### Query supplier articles by SKUs (bulk) — `POST /supplier/{id}/articles` - Params: `id: int, body?: { skus?: str[] }` -- Returns: `200 { articles: { id: int, articleId: int, entityId: int, pu: num, sort: int, article: { id: int, sku: str, name?: str|null, slug?: str|null, photos?: { sort: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str }[], eans?: str[] }, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T48|null }[] }` +- Returns: `200 { articles: { id: int, articleId: int, entityId: int, pu: num, sort: int, article: { id: int, sku: str, name?: str|null, slug?: str|null, photos?: { sort: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str }[], eans?: str[] }, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T53|null }[] }` ### Section: /thumb @@ -836,10 +843,10 @@ _none_ - Returns: `204 void` #### List units — `GET /unit` _none_ -- Returns: `200 { units: T36[] }` +- Returns: `200 { units: T39[] }` #### Upsert unit — `PUT /unit` - Params: `body: { si: str, basesi: str, basesifactor: num, symbol: str, name: str }` -- Returns: `200 { unit: T36 }` +- Returns: `200 { unit: T39 }` ### Section: /v1 @@ -864,6 +871,9 @@ _none_ #### List virtual filesystem files — `GET /vfs` _none_ - Returns: `200 { files: { name: str, size: int, mime: str, updated_at: str, created_at: str, isText: bool, isImage: bool, isPdf: bool }[] }` +#### Respond to a frontend draft request — `POST /vfs/drafts/response` +- Params: `body: { requestId: str, content?: any, error?: str, files?: any[] }` +- Returns: `200 { success: bool }` #### Create directory in virtual filesystem — `POST /vfs/mkdir` - Params: `body: { path: str }` - Returns: `200 { success: bool, dir: str }` @@ -890,10 +900,10 @@ _none_ #### List warehouses — `GET /warehouse` _none_ -- Returns: `200 { warehouses: T49[] }` +- Returns: `200 { warehouses: T54[] }` #### Create warehouse — `POST /warehouse` - Params: `body: { name: str, sort?: int }` -- Returns: `201 T47` +- Returns: `201 T52` #### Reorder warehouses — `PUT /warehouse/order` - Params: `body: { warehouseIds: int[] }` - Returns: `200 { warehouseIds: int[] }` @@ -902,10 +912,10 @@ _none_ - Returns: `204 void` #### Get warehouse by ID — `GET /warehouse/{id}` - Params: `id: int` -- Returns: `200 T47` +- Returns: `200 T52` #### Update warehouse (partial) — `PATCH /warehouse/{id}` - Params: `id: int, body: { name?: str, sort?: int }` -- Returns: `200 T47` +- Returns: `200 T52` #### Update warehouse — `PUT /warehouse/{id}` - Params: `id: int, body: { name?: str, sort?: int }` -- Returns: `200 T47` +- Returns: `200 T52` diff --git a/docs/api/routes.md b/docs/api/routes.md index 8a907a6..4d4214f 100644 --- a/docs/api/routes.md +++ b/docs/api/routes.md @@ -1,6 +1,6 @@ # Dash API Routes Overview -Overview of all 184 API endpoints across all modules. +Overview of all 164 API endpoints across all modules. ### Notation @@ -58,27 +58,6 @@ Params: path values first, then `query:` and `body:` (`body?` = optional body). ### Routes -### Section: /.well-known - -#### OAuth 2.0 Authorization Server Metadata (RFC 8414) — `GET /.well-known/oauth-authorization-server` -_none_ -- Returns: `200` -#### OAuth 2.0 Protected Resource Metadata (RFC 9728) — `GET /.well-known/oauth-protected-resource` -_none_ -- Returns: `200` - -### Section: /account - -#### List accounts — `GET /account` -_none_ -- Returns: `200 { accounts: { id: int, companyId: int, type: str, name: str }[] }` -#### Create account — `POST /account` -- Params: `body: { type: str, name: str }` -- Returns: `201 { account: { id: int, companyId: int, type: str, name: str } }` -#### Delete account — `DELETE /account/{id}` -- Params: `id: int` -- Returns: `204 void` - ### Section: /article #### Create article in category — `POST /article` @@ -223,24 +202,6 @@ _none_ - Params: `id: int, image/avif` - Returns: `201 { attributevalue: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: T39[] } }` -### Section: /auth - -#### Login with Google ID token — `POST /auth/login` -- Params: `body: { idToken: str }` -- Returns: `200 { message: str, user: { id: int, email: str, selectedCompanyId: int|null, picture?: str } }` -#### Logout — `POST /auth/logout` -_none_ -- Returns: `200 { message: str }` - -### Section: /backup - -#### List backups and service status — `GET /backup` -_none_ -- Returns: `200 { status: {}, backups: {} }` -#### Trigger manual backup — `POST /backup/run` -_none_ -- Returns: `200 {}` - ### Section: /brand #### List brands — `GET /brand` @@ -448,30 +409,6 @@ _none_ - Params: `sku: str, query: transaction_type?: str` - Returns: `200 T15` -### Section: /mcp - -#### Model Context Protocol (MCP) Streamable HTTP endpoint — `POST /mcp` -_none_ -- Returns: `200` -#### List active MCP client authorizations — `GET /mcp/authorizations` -_none_ -- Returns: `200` -#### Revoke MCP client authorizations — `DELETE /mcp/authorizations/{clientId}` -- Params: `clientId: str` -- Returns: `200` -#### Get MCP authorization prompt details — `GET /mcp/authorize` -- Params: `query: client_id: str, redirect_uri: str, response_type?: str, code_challenge?: str, code_challenge_method?: str, state?: str, scope?: str` -- Returns: `200` -#### Grant or deny MCP client authorization — `POST /mcp/authorize` -- Params: `body: { client_id: str, redirect_uri: str, action: str, code_challenge?: str, code_challenge_method?: str, state?: str, scope?: str }` -- Returns: `200` -#### List registered MCP clients — `GET /mcp/clients` -_none_ -- Returns: `200` -#### Delete registered MCP client — `DELETE /mcp/clients/{clientId}` -- Params: `clientId: str` -- Returns: `200` - ### Section: /number #### List number sequences — `GET /number` @@ -481,21 +418,6 @@ _none_ - Params: `id: int, body: { prefix?: str, padding?: int, next?: int }` - Returns: `200 { number: { id: int, type: str, prefix: str, padding: int, next: int } }` -### Section: /oauth - -#### OAuth 2.1 Authorization Endpoint (RFC 6749 & RFC 7636) — `GET /oauth/authorize` -- Params: `query: client_id?: str, redirect_uri?: str, response_type?: str, code_challenge?: str, code_challenge_method?: str, state?: str` -_no response body_ -#### OAuth 2.0 Token Introspection (RFC 7662) — `POST /oauth/introspect` -_none_ -- Returns: `200` -#### Dynamic Client Registration (RFC 7591) — `POST /oauth/register` -- Params: `body: { redirect_uris: str[], client_name?: str }` -- Returns: `201` -#### OAuth 2.1 Token Endpoint (RFC 6749 & RFC 7636) — `POST /oauth/token` -- Params: `application/x-www-form-urlencoded` -- Returns: `200` - ### Section: /order #### List orders — `GET /order` diff --git a/docs/api/routes/backup.md b/docs/api/routes/backup.md index 312b67a..d0d58cc 100644 --- a/docs/api/routes/backup.md +++ b/docs/api/routes/backup.md @@ -12,8 +12,240 @@ Backup service status and listing ```json { - "status": {}, - "backups": {} + "status": { + "enabled": true, + "isRunning": true, + "dbProvider": "…", + "mssqlWarning": true, + "backupDir": "…", + "retention": { + "hourlyMax": 1, + "dailyMax": 1, + "monthly": "…" + }, + "counts": { + "hourly": 1, + "daily": 1, + "monthly": 1 + }, + "latestHourly": { + "name": "…", + "path": "…", + "totalSizeBytes": 1, + "timestamp": "2026-08-10T00:00:00.000Z", + "manifest": { + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "dateKey": "…", + "monthKey": "…", + "dbProvider": "…", + "manual": true, + "files": { + "vfs": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "storage": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "database": { + "name": "…", + "sizeBytes": 1, + "backedUp": true, + "reason": "…" + } + }, + "totalSizeBytes": 1, + "durationMs": 1 + } + }, + "latestDaily": { + "name": "…", + "path": "…", + "totalSizeBytes": 1, + "timestamp": "2026-08-10T00:00:00.000Z", + "manifest": { + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "dateKey": "…", + "monthKey": "…", + "dbProvider": "…", + "manual": true, + "files": { + "vfs": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "storage": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "database": { + "name": "…", + "sizeBytes": 1, + "backedUp": true, + "reason": "…" + } + }, + "totalSizeBytes": 1, + "durationMs": 1 + } + }, + "latestMonthly": { + "name": "…", + "path": "…", + "totalSizeBytes": 1, + "timestamp": "2026-08-10T00:00:00.000Z", + "manifest": { + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "dateKey": "…", + "monthKey": "…", + "dbProvider": "…", + "manual": true, + "files": { + "vfs": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "storage": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "database": { + "name": "…", + "sizeBytes": 1, + "backedUp": true, + "reason": "…" + } + }, + "totalSizeBytes": 1, + "durationMs": 1 + } + } + }, + "backups": { + "counts": { + "hourly": 1, + "daily": 1, + "monthly": 1 + }, + "hourly": [ + { + "name": "…", + "path": "…", + "totalSizeBytes": 1, + "timestamp": "2026-08-10T00:00:00.000Z", + "manifest": { + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "dateKey": "…", + "monthKey": "…", + "dbProvider": "…", + "manual": true, + "files": { + "vfs": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "storage": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "database": { + "name": "…", + "sizeBytes": 1, + "backedUp": true, + "reason": "…" + } + }, + "totalSizeBytes": 1, + "durationMs": 1 + } + } + ], + "daily": [ + { + "name": "…", + "path": "…", + "totalSizeBytes": 1, + "timestamp": "2026-08-10T00:00:00.000Z", + "manifest": { + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "dateKey": "…", + "monthKey": "…", + "dbProvider": "…", + "manual": true, + "files": { + "vfs": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "storage": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "database": { + "name": "…", + "sizeBytes": 1, + "backedUp": true, + "reason": "…" + } + }, + "totalSizeBytes": 1, + "durationMs": 1 + } + } + ], + "monthly": [ + { + "name": "…", + "path": "…", + "totalSizeBytes": 1, + "timestamp": "2026-08-10T00:00:00.000Z", + "manifest": { + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "dateKey": "…", + "monthKey": "…", + "dbProvider": "…", + "manual": true, + "files": { + "vfs": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "storage": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "database": { + "name": "…", + "sizeBytes": 1, + "backedUp": true, + "reason": "…" + } + }, + "totalSizeBytes": 1, + "durationMs": 1 + } + } + ] + } } ``` @@ -21,7 +253,7 @@ Backup service status and listing | Status | Description | |--------|-------------| -| 500 | Internal error | +| 500 | Internal error — `{"error":"…"}` | --- diff --git a/docs/api/routes/backup/run.md b/docs/api/routes/backup/run.md index 0f7a801..9dbfb14 100644 --- a/docs/api/routes/backup/run.md +++ b/docs/api/routes/backup/run.md @@ -11,14 +11,53 @@ Immediately triggers an on-demand backup snapshot of VFS, storage, and SQLite da Backup triggered successfully ```json -{} +{ + "success": true, + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "promotedDaily": true, + "promotedMonthly": true, + "totalSizeBytes": 1, + "pruneResult": { + "hourlyPruned": 1, + "dailyPruned": 1 + }, + "manifest": { + "id": "…", + "timestamp": "2026-08-10T00:00:00.000Z", + "dateKey": "…", + "monthKey": "…", + "dbProvider": "…", + "manual": true, + "files": { + "vfs": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "storage": { + "name": "…", + "sizeBytes": 1, + "sourceExists": true + }, + "database": { + "name": "…", + "sizeBytes": 1, + "backedUp": true, + "reason": "…" + } + }, + "totalSizeBytes": 1, + "durationMs": 1 + } +} ``` ## Errors | Status | Description | |--------|-------------| -| 500 | Backup execution failure | +| 500 | Backup execution failure — `{"error":"…"}` | --- diff --git a/docs/api/routes/events.md b/docs/api/routes/events.md index 74583de..5a49d01 100644 --- a/docs/api/routes/events.md +++ b/docs/api/routes/events.md @@ -44,6 +44,8 @@ richer payload. | `modelconversation` | `{}` | `POST /modelconversation`, `DELETE /modelconversation/{id}` | | `modelconversation-` | `{}` | Conversation-specific updates on the same model conversation thread; the concrete ID is used in the event name | | `brand` | `{ sender, brandId }` | `POST /brand`, `PATCH /brand/{id}`, `DELETE /brand/{id}`, `POST /brand/{id}/image`, `DELETE /brand/{id}/image` | +| `draft` | `{ sender, action, name, content }` | Draft update on `drafts/quote`, `drafts/order`, `drafts/delivery` (`sender` echoes the caller's `x-client-id`) | +| `draft:request` | `{ requestId, action, name, target, sender }` | Server request to frontend to read a draft or list drafts | The `brand` payload is `{ sender, brandId }`: `sender` echoes the caller's `x-client-id` header (empty string if absent) so the sender diff --git a/docs/api/routes/vfs/drafts/response.md b/docs/api/routes/vfs/drafts/response.md new file mode 100644 index 0000000..c8e8eb8 --- /dev/null +++ b/docs/api/routes/vfs/drafts/response.md @@ -0,0 +1,48 @@ +# `POST /vfs/drafts/response` + +Protected. Requires a valid session cookie (`credentials: 'include'`). + +Respond to a frontend draft request + +Used by the frontend to answer a server-initiated `draft:request` SSE event +when reading or listing virtual drafts (`drafts/quote`, `drafts/order`, `drafts/delivery`). + + +## Body (JSON) + +| Field | Required | Type | Description | +|-------|----------|------|-------------| +| `requestId` | yes | string | Unique request ID from the draft:request SSE event | +| `content` | no | | File content when action was read | +| `error` | no | string | Error message if draft retrieval failed on frontend | +| `files` | no | any[] | File listing when action was list | + +```json +{ + "requestId": "…", + "content": "…", + "error": "…", + "files": [] +} +``` + +## Response `200` + +Response received and resolved + +```json +{ + "success": true +} +``` + +## Errors + +| Status | Description | +|--------|-------------| +| 400 | Missing requestId or no company selected — `{"error":"…"}` | +| 404 | Request ID not found or already timed out — `{"error":"…"}` | + +--- + +_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._ diff --git a/scripts/generateApiDocs.js b/scripts/generateApiDocs.js index 947cc00..f09ea0e 100644 --- a/scripts/generateApiDocs.js +++ b/scripts/generateApiDocs.js @@ -53,6 +53,24 @@ function isRouteOmitted(method, apiPath) { if (apiPath === '/vfs' || apiPath.startsWith('/vfs/')) { return true; } + if (apiPath === '/backup' || apiPath.startsWith('/backup/')) { + return true; + } + if (apiPath === '/mcp' || apiPath.startsWith('/mcp/')) { + return true; + } + if (apiPath === '/oauth' || apiPath.startsWith('/oauth/')) { + return true; + } + if (apiPath === '/.well-known' || apiPath.startsWith('/.well-known/')) { + return true; + } + if (apiPath === '/account' || apiPath.startsWith('/account/')) { + return true; + } + if (apiPath === '/auth' || apiPath.startsWith('/auth/')) { + return true; + } return OMITTED_ROUTES.has(`${method.toUpperCase()} ${apiPath}`); } diff --git a/src/api/openapi.js b/src/api/openapi.js index aea7515..917fa33 100644 --- a/src/api/openapi.js +++ b/src/api/openapi.js @@ -1780,6 +1780,178 @@ * isPdf: * type: boolean * description: True if file is a PDF document + * BackupFileDetail: + * type: object + * required: [name, sizeBytes, sourceExists] + * properties: + * name: + * type: string + * sizeBytes: + * type: integer + * sourceExists: + * type: boolean + * BackupDatabaseDetail: + * type: object + * required: [name, sizeBytes, backedUp] + * properties: + * name: + * type: string + * nullable: true + * sizeBytes: + * type: integer + * backedUp: + * type: boolean + * reason: + * type: string + * nullable: true + * BackupManifest: + * type: object + * required: [id, timestamp, dateKey, monthKey, dbProvider, manual, files, totalSizeBytes, durationMs] + * properties: + * id: + * type: string + * timestamp: + * type: string + * format: date-time + * dateKey: + * type: string + * monthKey: + * type: string + * dbProvider: + * type: string + * manual: + * type: boolean + * files: + * type: object + * required: [vfs, storage, database] + * properties: + * vfs: + * $ref: '#/components/schemas/BackupFileDetail' + * storage: + * $ref: '#/components/schemas/BackupFileDetail' + * database: + * $ref: '#/components/schemas/BackupDatabaseDetail' + * totalSizeBytes: + * type: integer + * durationMs: + * type: integer + * BackupEntry: + * type: object + * required: [name, path, totalSizeBytes, timestamp] + * properties: + * name: + * type: string + * path: + * type: string + * totalSizeBytes: + * type: integer + * timestamp: + * type: string + * format: date-time + * nullable: true + * manifest: + * $ref: '#/components/schemas/BackupManifest' + * nullable: true + * BackupTierCounts: + * type: object + * required: [hourly, daily, monthly] + * properties: + * hourly: + * type: integer + * daily: + * type: integer + * monthly: + * type: integer + * BackupRetentionConfig: + * type: object + * required: [hourlyMax, dailyMax, monthly] + * properties: + * hourlyMax: + * type: integer + * dailyMax: + * type: integer + * monthly: + * type: string + * BackupStatus: + * type: object + * required: [enabled, isRunning, dbProvider, mssqlWarning, backupDir, retention, counts] + * properties: + * enabled: + * type: boolean + * isRunning: + * type: boolean + * dbProvider: + * type: string + * mssqlWarning: + * type: boolean + * backupDir: + * type: string + * retention: + * $ref: '#/components/schemas/BackupRetentionConfig' + * counts: + * $ref: '#/components/schemas/BackupTierCounts' + * latestHourly: + * $ref: '#/components/schemas/BackupEntry' + * nullable: true + * latestDaily: + * $ref: '#/components/schemas/BackupEntry' + * nullable: true + * latestMonthly: + * $ref: '#/components/schemas/BackupEntry' + * nullable: true + * BackupListing: + * type: object + * required: [counts, hourly, daily, monthly] + * properties: + * counts: + * $ref: '#/components/schemas/BackupTierCounts' + * hourly: + * type: array + * items: + * $ref: '#/components/schemas/BackupEntry' + * daily: + * type: array + * items: + * $ref: '#/components/schemas/BackupEntry' + * monthly: + * type: array + * items: + * $ref: '#/components/schemas/BackupEntry' + * BackupOverviewResponse: + * type: object + * required: [status, backups] + * properties: + * status: + * $ref: '#/components/schemas/BackupStatus' + * backups: + * $ref: '#/components/schemas/BackupListing' + * BackupRunResult: + * type: object + * required: [success, id, timestamp, promotedDaily, promotedMonthly, totalSizeBytes, pruneResult, manifest] + * properties: + * success: + * type: boolean + * id: + * type: string + * timestamp: + * type: string + * format: date-time + * promotedDaily: + * type: boolean + * promotedMonthly: + * type: boolean + * totalSizeBytes: + * type: integer + * pruneResult: + * type: object + * required: [hourlyPruned, dailyPruned] + * properties: + * hourlyPruned: + * type: integer + * dailyPruned: + * type: integer + * manifest: + * $ref: '#/components/schemas/BackupManifest' */ export {}; diff --git a/src/api/routes/backup.js b/src/api/routes/backup.js index 29fef7d..3f5dbbb 100644 --- a/src/api/routes/backup.js +++ b/src/api/routes/backup.js @@ -19,14 +19,13 @@ export function register(app, basePath = '') { * content: * application/json: * schema: - * type: object - * properties: - * status: - * type: object - * backups: - * type: object + * $ref: '#/components/schemas/BackupOverviewResponse' * 500: * description: Internal error + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ // #region GET /backup // MARK: handles GET /backup to list backups and service status @@ -54,9 +53,13 @@ export function register(app, basePath = '') { * content: * application/json: * schema: - * type: object + * $ref: '#/components/schemas/BackupRunResult' * 500: * description: Backup execution failure + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ // #region POST /backup/run // MARK: handles POST /backup/run to trigger manual backup diff --git a/src/api/routes/events.js b/src/api/routes/events.js index fd50057..515353a 100644 --- a/src/api/routes/events.js +++ b/src/api/routes/events.js @@ -53,6 +53,8 @@ export function register(app, basePath = '') { * | `modelconversation` | `{}` | `POST /modelconversation`, `DELETE /modelconversation/{id}` | * | `modelconversation-` | `{}` | Conversation-specific updates on the same model conversation thread; the concrete ID is used in the event name | * | `brand` | `{ sender, brandId }` | `POST /brand`, `PATCH /brand/{id}`, `DELETE /brand/{id}`, `POST /brand/{id}/image`, `DELETE /brand/{id}/image` | + * | `draft` | `{ sender, action, name, content }` | Draft update on `drafts/quote`, `drafts/order`, `drafts/delivery` (`sender` echoes the caller's `x-client-id`) | + * | `draft:request` | `{ requestId, action, name, target, sender }` | Server request to frontend to read a draft or list drafts | * * The `brand` payload is `{ sender, brandId }`: `sender` echoes the * caller's `x-client-id` header (empty string if absent) so the sender @@ -95,6 +97,10 @@ export function register(app, basePath = '') { * payload: "{}" * - name: brand * payload: "{ sender, brandId }" + * - name: draft + * payload: "{ sender, action, name, content }" + * - name: draft:request + * payload: "{ requestId, action, name, target, sender }" * responses: * 200: * description: | @@ -157,5 +163,6 @@ export function handleSse(req, res) { // Send an initial ping to establish frame res.write(': ping\n\n'); - subscribe(res, { companyId, userId: req.user?.id }, req); + const clientId = req.query?.cid || req.headers?.['x-client-id'] || null; + subscribe(res, { companyId, userId: req.user?.id, clientId }, req); } diff --git a/src/api/routes/vfs.js b/src/api/routes/vfs.js index c75e3bc..7788f70 100644 --- a/src/api/routes/vfs.js +++ b/src/api/routes/vfs.js @@ -4,6 +4,13 @@ import multer from 'multer'; import { emit } from '../sse.js'; import { prepareVfs, resolveVfsRoot, isReadOnlyDatabasePath, getMimeType } from '../../tools/vfs.js'; import sharp from 'sharp'; +import { + parseDraftPath, + requestDraftRead, + requestDraftList, + handleDraftResponse, + notifyDraftUpdate, +} from '../../services/draftManager.js'; // #region Helpers @@ -465,7 +472,18 @@ export function register(app, basePath = '') { } return list; } - const files = walk(vfsRoot).sort((a, b) => a.name.localeCompare(b.name)); + const diskFiles = walk(vfsRoot); + let drafts = []; + try { + drafts = await requestDraftList({ + companyId: selected.companyId, + userId: req.user.id, + clientId: req.headers?.['x-client-id'], + }); + } catch (err) { + console.error('Failed to request drafts from frontend:', err); + } + const files = [...diskFiles, ...drafts].sort((a, b) => a.name.localeCompare(b.name)); return res.json({ files }); } catch (error) { const status = vfsFileErrorStatus(error); @@ -580,6 +598,7 @@ export function register(app, basePath = '') { const parsed = parseVfsRef(relPath); if (parsed.error) continue; if (isReadOnlyDatabasePath(parsed.name)) continue; + if (parseDraftPath(parsed.name).isFolder || parseDraftPath(parsed.name).isDraft) continue; const absPath = path.resolve(vfsRoot, parsed.name); if (!absPath.startsWith(vfsRoot)) continue; @@ -680,6 +699,9 @@ export function register(app, basePath = '') { if (isReadOnlyDatabasePath(parsed.name)) { return res.status(403).json({ error: 'Cannot create directories in read-only database paths' }); } + if (parseDraftPath(parsed.name).isFolder || parseDraftPath(parsed.name).isDraft) { + return res.status(403).json({ error: 'Cannot create directories in virtual drafts folder' }); + } try { const vfsRoot = await resolveVfsRoot(req.user.id); @@ -788,6 +810,14 @@ export function register(app, basePath = '') { if (isReadOnlyDatabasePath(parsedOld.name) || isReadOnlyDatabasePath(parsedNew.name)) { return res.status(403).json({ error: 'Cannot rename read-only database paths' }); } + if ( + parseDraftPath(parsedOld.name).isFolder || + parseDraftPath(parsedOld.name).isDraft || + parseDraftPath(parsedNew.name).isFolder || + parseDraftPath(parsedNew.name).isDraft + ) { + return res.status(403).json({ error: 'Cannot rename virtual draft files or folders' }); + } try { const vfsRoot = await resolveVfsRoot(req.user.id); @@ -931,6 +961,50 @@ export function register(app, basePath = '') { return res.status(403).json({ error: 'Cannot modify read-only database files' }); } + const draftInfo = parseDraftPath(parsed.name); + if (draftInfo.isFolder) { + return res.status(400).json({ error: 'Cannot write directly to directory' }); + } + if (draftInfo.isDraft) { + let strContent; + if (typeof req.body?.content === 'string') { + strContent = req.body.content; + } else if (req.body && typeof req.body === 'object' && !Buffer.isBuffer(req.body)) { + strContent = req.body.content !== undefined + ? (typeof req.body.content === 'string' ? req.body.content : JSON.stringify(req.body.content)) + : JSON.stringify(req.body); + } else if (Buffer.isBuffer(req.body)) { + strContent = req.body.toString('utf8'); + } else if (typeof req.body === 'string') { + strContent = req.body; + } else { + return res.status(400).json({ error: 'No content provided' }); + } + + let parsedContent = strContent; + try { + parsedContent = JSON.parse(strContent); + } catch {} + + const updated = notifyDraftUpdate({ + companyId: selected.companyId, + userId: req.user.id, + clientId: req.headers?.['x-client-id'], + name: draftInfo.name, + content: parsedContent, + }); + + return res.json({ + success: true, + file: { + name: `drafts/${draftInfo.name}`, + size: updated.size, + mime: 'application/json; charset=utf-8', + updated_at: updated.updatedAt, + }, + }); + } + let buffer; let mime = parsed.mime; if (typeof req.body?.content === 'string') { @@ -1043,6 +1117,10 @@ export function register(app, basePath = '') { if (isReadOnlyDatabasePath(parsed.name)) { return res.status(403).json({ error: 'Cannot delete read-only database files' }); } + const draftDeleteInfo = parseDraftPath(parsed.name); + if (draftDeleteInfo.isFolder || draftDeleteInfo.isDraft) { + return res.status(403).json({ error: 'Cannot delete virtual draft files' }); + } try { const vfsRoot = await resolveVfsRoot(req.user.id); @@ -1210,6 +1288,35 @@ export function register(app, basePath = '') { return res.status(400).json({ error: parsed.error }); } + const draftGetInfo = parseDraftPath(parsed.name); + if (draftGetInfo.isFolder) { + return res.status(400).json({ error: 'Cannot download a directory directly' }); + } + if (draftGetInfo.isDraft) { + try { + const content = await requestDraftRead({ + companyId: selected.companyId, + userId: req.user.id, + clientId: req.headers?.['x-client-id'], + name: draftGetInfo.name, + }); + const strContent = typeof content === 'string' ? content : JSON.stringify(content ?? {}, null, 2); + const buffer = Buffer.from(strContent, 'utf8'); + const effectiveMime = 'application/json; charset=utf-8'; + const fallbackName = `${draftGetInfo.name}.json`; + + res.setHeader('Content-Type', effectiveMime); + res.setHeader('Content-Length', String(buffer.length)); + res.setHeader('X-Content-Type-Options', 'nosniff'); + res.setHeader('Cache-Control', 'private, max-age=0, must-revalidate'); + res.setHeader('Content-Disposition', `inline; filename="${fallbackName}"`); + return res.status(200).send(buffer); + } catch (err) { + const status = err.message?.includes('timed out') ? 504 : 404; + return res.status(status).json({ error: err.message }); + } + } + try { const vfsRoot = await resolveVfsRoot(req.user.id); const absPath = path.resolve(vfsRoot, parsed.name); @@ -1284,4 +1391,77 @@ export function register(app, basePath = '') { }); // #endregion + + /** + * @openapi + * /vfs/drafts/response: + * post: + * tags: [Vfs] + * summary: Respond to a frontend draft request + * description: | + * Used by the frontend to answer a server-initiated `draft:request` SSE event + * when reading or listing virtual drafts (`drafts/quote`, `drafts/order`, `drafts/delivery`). + * security: + * - cookieAuth: [] + * requestBody: + * required: true + * content: + * application/json: + * schema: + * type: object + * required: [requestId] + * properties: + * requestId: + * type: string + * description: Unique request ID from the draft:request SSE event + * content: + * description: File content when action was read + * error: + * type: string + * description: Error message if draft retrieval failed on frontend + * files: + * type: array + * description: File listing when action was list + * responses: + * 200: + * description: Response received and resolved + * content: + * application/json: + * schema: + * type: object + * properties: + * success: + * type: boolean + * 400: + * description: Missing requestId or no company selected + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * 404: + * description: Request ID not found or already timed out + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + */ + // #region POST /vfs/drafts/response + + app.post(`${basePath}/vfs/drafts/response`, async (req, res) => { + const selected = requireSelectedCompany(req); + if (selected.error) { + return res.status(400).json({ error: selected.error }); + } + const { requestId, content, error, files } = req.body || {}; + if (!requestId) { + return res.status(400).json({ error: 'requestId is required' }); + } + const result = handleDraftResponse({ requestId, content, error, files }); + if (!result.handled) { + return res.status(404).json({ error: result.error || 'Request expired or not found' }); + } + return res.json({ success: true }); + }); + + // #endregion } \ No newline at end of file diff --git a/src/api/sse.js b/src/api/sse.js index 3369884..c5e7bab 100644 --- a/src/api/sse.js +++ b/src/api/sse.js @@ -3,7 +3,7 @@ * after a successful mutation so other tabs/users can refetch. */ -/** @typedef {{ res: import('express').Response, companyId: number, userId: number, keepAlive: NodeJS.Timeout }} SseClient */ +/** @typedef {{ res: import('express').Response, companyId: number, userId: number, clientId: string|null, keepAlive: NodeJS.Timeout }} SseClient */ /** @type {Set} */ const clients = new Set(); @@ -13,16 +13,18 @@ const KEEP_ALIVE_MS = 20_000; /** * Register an open SSE response. Caller must write the initial headers. * @param {import('express').Response} res - * @param {{ companyId: number, userId: number }} meta + * @param {{ companyId: number, userId: number, clientId?: string|null }} meta * @param {import('express').Request} [req] * @returns {() => void} unsubscribe */ -export function subscribe(res, { companyId, userId }, req) { +export function subscribe(res, { companyId, userId, clientId }, req) { + const resolvedClientId = clientId || req?.headers?.['x-client-id'] || req?.query?.cid || null; /** @type {SseClient} */ const client = { res, companyId, userId, + clientId: resolvedClientId ? String(resolvedClientId) : null, keepAlive: setInterval(() => { if (res.writableEnded) return; res.write(': heartbeat\n\n'); @@ -55,15 +57,59 @@ export function closeAll() { } /** - * Broadcast a named signal to subscribers of the given company. - * @param {string} signal - SSE event name (e.g. `category`) - * @param {{ companyId: number, data?: string|object }} options + * Checks whether an active SSE client connection exists matching the given criteria. + * @param {{ companyId?: number, userId?: number, clientId?: string }} [options] + * @returns {boolean} */ -export function emit(signal, { companyId, data }) { +export function hasActiveClient({ companyId, userId, clientId } = {}) { + for (const client of clients) { + if (companyId != null && client.companyId !== companyId) continue; + if (userId != null && client.userId !== userId) continue; + if (clientId != null && client.clientId !== clientId) continue; + if (!client.res.writableEnded) return true; + } + return false; +} + +/** + * Broadcast or target a named signal to subscribers. + * If `targetClientId` or `targetUserId` is specified, sends only to matching clients of that user. + * + * @param {string} signal - SSE event name (e.g. `category`, `draft`, `draft:request`) + * @param {{ companyId: number, data?: string|object, targetClientId?: string, targetUserId?: number }} options + */ +export function emit(signal, { companyId, data, targetClientId, targetUserId }) { if (companyId == null) return; const payload = data == null ? '{}' : (typeof data === 'string' ? data : JSON.stringify(data)); const frame = `event: ${signal}\ndata: ${payload}\n\n`; + + if (targetClientId || targetUserId != null) { + let sent = false; + if (targetClientId) { + for (const client of clients) { + if (client.companyId !== companyId) continue; + if (targetUserId != null && client.userId !== targetUserId) continue; + if (client.clientId === targetClientId && !client.res.writableEnded) { + client.res.write(frame); + sent = true; + } + } + } + if (!sent && targetUserId != null) { + for (const client of clients) { + if (client.companyId !== companyId) continue; + if (client.userId === targetUserId && !client.res.writableEnded) { + client.res.write(frame); + sent = true; + } + } + } + if (sent) return; + // Targeted to a specific user but no active client was found: do not blast to other users + if (targetUserId != null) return; + } + for (const client of clients) { if (client.companyId !== companyId) continue; if (client.res.writableEnded) continue; diff --git a/src/services/draftManager.js b/src/services/draftManager.js new file mode 100644 index 0000000..7e1e0ed --- /dev/null +++ b/src/services/draftManager.js @@ -0,0 +1,316 @@ +import { emit, hasActiveClient } from '../api/sse.js'; +import { getStore } from '../db/store.js'; + +export const DRAFT_NAMES = new Set(['quote', 'order', 'delivery']); + +/** + * Checks and parses a VFS path to determine if it points to the drafts directory or a draft file. + * Accepts paths like: + * - 'drafts', '/drafts', 'drafts/' + * - 'drafts/quote', 'drafts/quote.json', '/api/vfs/drafts/order', 'vfs://drafts/delivery' + * + * @param {string} filePath + * @returns {{ isFolder: boolean, isDraft: boolean, name?: 'quote'|'order'|'delivery', filename?: string }} + */ +export function parseDraftPath(filePath) { + if (typeof filePath !== 'string' || !filePath.trim()) { + return { isFolder: false, isDraft: false }; + } + let clean = filePath.trim().replace(/^vfs:\/+/i, '').replace(/^([a-zA-Z]:|\/)+/, '').replace(/^\.\/+/, ''); + clean = clean.replace(/^api\//i, '').replace(/^vfs\//i, ''); + const segments = clean.split('/').filter(Boolean); + if (segments.length === 0) return { isFolder: false, isDraft: false }; + + if (segments[0].toLowerCase() === 'drafts') { + if (segments.length === 1) { + return { isFolder: true, isDraft: false }; + } + if (segments.length === 2) { + const rawName = segments[1]; + const lower = rawName.toLowerCase(); + const withoutExt = lower.endsWith('.json') ? lower.slice(0, -5) : lower; + if (DRAFT_NAMES.has(withoutExt)) { + return { isFolder: false, isDraft: true, name: withoutExt, filename: rawName }; + } + } + } + return { isFolder: false, isDraft: false }; +} + +/** + * In-memory cache for drafts: key: `${companyId}:${userId}:${name}` -> { content, updatedAt, size } + */ +const draftCache = new Map(); + +function cacheKey(companyId, userId, name) { + return `${companyId}:${userId}:${name}`; +} + +export function getCachedDraft({ companyId, userId, name }) { + return draftCache.get(cacheKey(companyId, userId, name)) || null; +} + +export function setCachedDraft({ companyId, userId, name, content }) { + const updatedAt = new Date().toISOString(); + const str = typeof content === 'string' ? content : JSON.stringify(content ?? {}, null, 2); + const entry = { + content, + updatedAt, + size: Buffer.byteLength(str, 'utf8'), + }; + draftCache.set(cacheKey(companyId, userId, name), entry); + return entry; +} + +/** + * Resolves the selected company ID for a given googleAuth ID if needed. + * @param {number} googleAuthId + * @returns {Promise} + */ +export async function resolveCompanyForUser(googleAuthId) { + if (!googleAuthId) return null; + try { + const store = await getStore(); + const row = await store.google_auth.getById(googleAuthId); + return row?.selectedCompanyId ?? null; + } catch { + return null; + } +} + +/** + * Pending requests map: requestId -> { resolve, reject, timer, companyId, userId, action, name } + */ +const pendingRequests = new Map(); + +/** + * Request a draft content from the frontend via SSE and wait for its response. + * + * @param {{ companyId?: number, userId: number, clientId?: string, name: string, timeoutMs?: number }} options + * @returns {Promise} + */ +export async function requestDraftRead({ companyId, userId, clientId, name, timeoutMs = 15000 }) { + const effectiveCompanyId = companyId != null ? companyId : await resolveCompanyForUser(userId); + if (effectiveCompanyId == null) { + throw new Error('No company selected'); + } + + // Check if client is active; if not and we have cache, return cache immediately + const hasClient = hasActiveClient({ companyId: effectiveCompanyId, userId, clientId }); + if (!hasClient) { + const cached = getCachedDraft({ companyId: effectiveCompanyId, userId, name }); + if (cached) { + return cached.content; + } + } + + const requestId = `draft_req_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`; + + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + pendingRequests.delete(requestId); + // Fallback to cache if available + const cached = getCachedDraft({ companyId: effectiveCompanyId, userId, name }); + if (cached) { + return resolve(cached.content); + } + reject(new Error(`Frontend draft response timed out for "${name}"`)); + }, timeoutMs); + + pendingRequests.set(requestId, { + resolve, + reject, + timer, + companyId: effectiveCompanyId, + userId, + action: 'read', + name, + }); + + // Emit request over SSE + emit('draft:request', { + companyId: effectiveCompanyId, + targetUserId: userId, + targetClientId: clientId, + data: { + requestId, + action: 'read', + name, + target: name, + sender: clientId || '', + }, + }); + }); +} + +/** + * Request draft listing from the frontend via SSE. + * If frontend doesn't respond or times out, returns default metadata for all 3 drafts. + * + * @param {{ companyId?: number, userId: number, clientId?: string, timeoutMs?: number }} options + * @returns {Promise>} + */ +export async function requestDraftList({ companyId, userId, clientId, timeoutMs = 2500 }) { + const effectiveCompanyId = companyId != null ? companyId : await resolveCompanyForUser(userId); + if (effectiveCompanyId == null) { + return []; + } + + const defaultDrafts = () => { + const now = new Date().toISOString(); + return Array.from(DRAFT_NAMES).map((name) => { + const cached = getCachedDraft({ companyId: effectiveCompanyId, userId, name }); + return { + name: `drafts/${name}`, + size: cached ? cached.size : 0, + mime: 'application/json; charset=utf-8', + updated_at: cached ? cached.updatedAt : now, + created_at: cached ? cached.updatedAt : now, + isText: true, + isImage: false, + isPdf: false, + isDraft: true, + }; + }); + }; + + // If no client is connected, return defaults immediately without delaying listing + const hasClient = hasActiveClient({ companyId: effectiveCompanyId, userId, clientId }); + if (!hasClient) { + return defaultDrafts(); + } + + const requestId = `draft_list_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`; + + return new Promise((resolve) => { + const timer = setTimeout(() => { + pendingRequests.delete(requestId); + resolve(defaultDrafts()); + }, timeoutMs); + + pendingRequests.set(requestId, { + resolve: (filesOrList) => { + if (Array.isArray(filesOrList)) { + const now = new Date().toISOString(); + const normalized = filesOrList.map((item) => { + const rawName = typeof item === 'string' ? item : (item.name || item.filename || ''); + const parsed = parseDraftPath(rawName.startsWith('drafts/') ? rawName : `drafts/${rawName}`); + const nameKey = parsed.name || rawName; + const cached = getCachedDraft({ companyId: effectiveCompanyId, userId, name: nameKey }); + return { + name: `drafts/${nameKey}`, + size: typeof item === 'object' && item.size != null ? item.size : (cached ? cached.size : 0), + mime: 'application/json; charset=utf-8', + updated_at: typeof item === 'object' && item.updated_at ? item.updated_at : (cached ? cached.updatedAt : now), + created_at: typeof item === 'object' && item.created_at ? item.created_at : (cached ? cached.updatedAt : now), + isText: true, + isImage: false, + isPdf: false, + isDraft: true, + }; + }); + resolve(normalized); + } else { + resolve(defaultDrafts()); + } + }, + reject: () => { + resolve(defaultDrafts()); + }, + timer, + companyId: effectiveCompanyId, + userId, + action: 'list', + }); + + emit('draft:request', { + companyId: effectiveCompanyId, + targetUserId: userId, + targetClientId: clientId, + data: { + requestId, + action: 'list', + sender: clientId || '', + }, + }); + }); +} + +/** + * Handle frontend response to a previous draft:request. + * + * @param {{ requestId: string, content?: any, error?: string, files?: any[] }} payload + * @returns {{ handled: boolean, error?: string }} + */ +export function handleDraftResponse({ requestId, content, error, files }) { + if (!requestId || !pendingRequests.has(requestId)) { + return { handled: false, error: 'Unknown or expired requestId' }; + } + + const pending = pendingRequests.get(requestId); + pendingRequests.delete(requestId); + clearTimeout(pending.timer); + + if (error) { + pending.reject(new Error(error)); + return { handled: true }; + } + + if (pending.action === 'list') { + pending.resolve(files !== undefined ? files : content); + return { handled: true }; + } + + // action === 'read' + setCachedDraft({ + companyId: pending.companyId, + userId: pending.userId, + name: pending.name, + content, + }); + pending.resolve(content); + return { handled: true }; +} + +/** + * Notify frontend about a draft update via the normal /events SSE endpoint. + * + * @param {{ companyId: number, userId: number, clientId?: string, name: string, content: any }} options + * @returns {{ name: string, size: number, updatedAt: string }} + */ +export function notifyDraftUpdate({ companyId, userId, clientId, name, content }) { + const entry = setCachedDraft({ companyId, userId, name, content }); + + emit('draft', { + companyId, + targetUserId: userId, + targetClientId: clientId, + data: { + sender: clientId || '', + action: 'update', + name, + content, + }, + }); + + return { + name: `drafts/${name}`, + size: entry.size, + updatedAt: entry.updatedAt, + }; +} + +/** + * Synchronous/fire-and-forget version of notifyDraftUpdate for sync writes. + * + * @param {{ googleAuthId: number, clientId?: string, name: string, content: any }} options + */ +export function notifyDraftUpdateSync({ googleAuthId, clientId, name, content }) { + resolveCompanyForUser(googleAuthId).then((companyId) => { + if (companyId != null) { + notifyDraftUpdate({ companyId, userId: googleAuthId, clientId, name, content }); + } + }).catch((err) => { + console.error('[draftManager] notifyDraftUpdateSync error:', err); + }); +} diff --git a/src/tools/find-files.js b/src/tools/find-files.js index e8b02d1..bf23dcf 100644 --- a/src/tools/find-files.js +++ b/src/tools/find-files.js @@ -4,6 +4,7 @@ import { defineTool, ToolError } from 'libllmorbiter'; import { isSkillPath, listSkillFiles, SKILL_EXT } from './skill.js'; import { prepareVfs } from './vfs.js'; import { TOOL_DESCRIPTIONS, TOOL_PARAMETER_DESCRIPTIONS } from './prompts.js'; +import { DRAFT_NAMES } from '../services/draftManager.js'; /** * find_files — lists the contents of the virtual filesystem (VFS). @@ -173,6 +174,31 @@ export function createFindFilesTool({ googleAuthId }) { ); } + if (cleanDir.replace(/\/+$/, '').toLowerCase() === 'drafts') { + const draftEntries = Array.from(DRAFT_NAMES).map((name) => ({ + path: `drafts/${name}`, + name, + type: 'file', + size: null, + modified: null, + })); + const page = draftEntries.slice(seek, seek + vfsLimit); + const truncated = Math.max(0, draftEntries.length - (seek + page.length)); + const result = { + kind: 'files', + dirname: 'drafts', + recursive: recursive === true, + total: draftEntries.length, + returned: page.length, + seek, + entries: page, + }; + if (truncated > 0) { + result.truncated = truncated; + } + return result; + } + const absDir = path.resolve(vfsRoot, cleanDir); const rel = path.relative(vfsRoot, absDir); if (rel.startsWith('..') || path.isAbsolute(rel)) { @@ -187,6 +213,16 @@ export function createFindFilesTool({ googleAuthId }) { } const all = walkVfs(absDir, vfsRoot, recursive === true, 0, maxDepth); + if (cleanDir === '.') { + if (!all.some((e) => e.path === 'drafts/')) { + all.push({ path: 'drafts/', name: 'drafts', type: 'dir', size: null, modified: null }); + } + if (recursive === true) { + for (const name of DRAFT_NAMES) { + all.push({ path: `drafts/${name}`, name, type: 'file', size: null, modified: null }); + } + } + } // Directories first, then alphabetical — makes a truncated listing predictable // instead of arbitrary. all.sort((a, b) => (a.type === b.type ? a.path.localeCompare(b.path) : a.type === 'dir' ? -1 : 1)); diff --git a/src/tools/patch.js b/src/tools/patch.js index 774a11c..4230376 100644 --- a/src/tools/patch.js +++ b/src/tools/patch.js @@ -5,6 +5,8 @@ import { isReadOnlyDatabasePath } from './vfs.js'; import { isSkillPath, renderSkill, parseSkill, SKILL_EXT, skillFileName } from './skill.js'; import { prepareVfs, syncVfsToDb } from './vfs.js'; import { TOOL_DESCRIPTIONS, PATCH_PARAMETER_DESCRIPTIONS } from './prompts.js'; +import { getStore } from '../db/store.js'; +import { parseDraftPath, requestDraftRead, notifyDraftUpdate, getCachedDraft } from '../services/draftManager.js'; /** * patch — applies edit operations to files in the virtual filesystem (VFS). @@ -175,7 +177,12 @@ export function createPatchTool({ googleAuthId }) { ); } - validated.push({ index: i, op, clean, abs, isSkill: looksSkillByExt, skillBody }); + const draftInfo = parseDraftPath(clean); + if (draftInfo.isFolder) { + throw new ToolError(`Operation at index ${i}: "${clean}" is a directory and cannot be patched.`); + } + + validated.push({ index: i, op, clean, abs, isSkill: looksSkillByExt, skillBody, draftInfo }); } // ── Apply ────────────────────────────────────────────────────── @@ -183,7 +190,57 @@ export function createPatchTool({ googleAuthId }) { const touchedSkills = new Set(); for (const v of validated) { - const { op, clean, abs, isSkill } = v; + const { op, clean, abs, isSkill, draftInfo } = v; + + if (draftInfo?.isDraft) { + const isCreate = op.search === null || op.search === undefined || op.search === ''; + let original = ''; + if (!isCreate) { + try { + const readVal = await requestDraftRead({ userId: googleAuthId, name: draftInfo.name }); + original = typeof readVal === 'string' ? readVal : JSON.stringify(readVal ?? {}, null, 2); + } catch (err) { + const cached = getCachedDraft({ userId: googleAuthId, name: draftInfo.name }); + if (cached) { + original = typeof cached.content === 'string' ? cached.content : JSON.stringify(cached.content ?? {}, null, 2); + } else { + throw new ToolError(`Cannot read draft "${clean}" before patching: ${err.message}`); + } + } + } + + let draftUpdated; + if (isCreate) { + draftUpdated = typeof op.replace === 'string' ? op.replace : JSON.stringify(op.replace, null, 2); + } else { + const haystack = original.includes('\r\n') ? original.replace(/\r\n/g, '\n') : original; + const needle = typeof op.search === 'string' ? op.search.replace(/\r\n/g, '\n') : ''; + if (!needle) { + throw new ToolError(`Operation at index ${v.index} ("${clean}") has an empty "search". Use "search": null to overwrite.`); + } + const at = haystack.indexOf(needle); + if (at === -1) { + throw new ToolError(`SEARCH/REPLACE failed in "${clean}": the search text was not found. Read the draft again with read_file.`); + } + const replacement = typeof op.replace === 'string' ? op.replace : JSON.stringify(op.replace, null, 2); + draftUpdated = haystack.slice(0, at) + replacement + haystack.slice(at + needle.length); + } + + let parsed = draftUpdated; + try { parsed = JSON.parse(draftUpdated); } catch {} + const store = await getStore(); + const row = await store.google_auth.getById(googleAuthId); + const companyId = row?.selectedCompanyId; + notifyDraftUpdate({ + companyId, + userId: googleAuthId, + name: draftInfo.name, + content: parsed, + }); + applied.push(`PATCH ${clean}`); + continue; + } + const isCreate = op.search === null || op.search === undefined || op.search === ''; const exists = fs.existsSync(abs); @@ -260,16 +317,19 @@ export function createPatchTool({ googleAuthId }) { if (isSkill) touchedSkills.add(clean); } - // Persist immediately — unlike javascript_execute, there is no trailing sync, so a + // Persist immediately for disk files — unlike javascript_execute, there is no trailing sync, so a // text edit would otherwise live only in the on-disk cache until some other tool ran. - try { - await syncVfsToDb({ googleAuthId, vfsRoot }); - } catch (err) { - console.error('[patch] failed to sync VFS to db:', err.message); - throw new ToolError( - `Patch applied to disk but could not be persisted: ${err.message}. ` + - `Files changed: ${applied.join(', ')}.` - ); + const hasDiskWrites = validated.some((v) => !v.draftInfo?.isDraft); + if (hasDiskWrites) { + try { + await syncVfsToDb({ googleAuthId, vfsRoot }); + } catch (err) { + console.error('[patch] failed to sync VFS to db:', err.message); + throw new ToolError( + `Patch applied to disk but could not be persisted: ${err.message}. ` + + `Files changed: ${applied.join(', ')}.` + ); + } } const result = { diff --git a/src/tools/read-file.js b/src/tools/read-file.js index fdb76c1..d0f52d0 100644 --- a/src/tools/read-file.js +++ b/src/tools/read-file.js @@ -5,6 +5,7 @@ import { isSkillPath, parseSkill, SKILL_EXT } from './skill.js'; import { getApiRouteSkill } from './routes-skills.js'; import { prepareVfs } from './vfs.js'; import { TOOL_DESCRIPTIONS, TOOL_PARAMETER_DESCRIPTIONS } from './prompts.js'; +import { parseDraftPath, requestDraftRead } from '../services/draftManager.js'; const DEFAULT_LIMIT = 400; const MAX_LIMIT = 5000; @@ -108,18 +109,37 @@ export function createReadFileTool({ googleAuthId }) { throw new ToolError(`Access denied: path "${filename}" escapes virtual filesystem boundary.`); } - const virtualSkill = !fs.existsSync(absPath) && isSkillPath(clean) ? getApiRouteSkill(clean) : null; - if (!virtualSkill && !fs.existsSync(absPath)) { - throw new ToolError( - `File not found in virtual filesystem: "${clean}". ` + - 'Call find_files to see what is stored, or find_files({ skills: true }) for SKILL files.' - ); - } - if (!virtualSkill && !fs.statSync(absPath).isFile()) { - throw new ToolError(`"${clean}" is not a file. Use find_files to list directories.`); + const draftInfo = parseDraftPath(clean); + if (draftInfo.isFolder) { + throw new ToolError('"drafts" is a directory. Use find_files to list its contents.'); } - const raw = virtualSkill ? Buffer.from(virtualSkill.content, 'utf8') : fs.readFileSync(absPath); + let raw; + let virtualSkill = null; + if (draftInfo.isDraft) { + try { + const content = await requestDraftRead({ + userId: googleAuthId, + name: draftInfo.name, + }); + const str = typeof content === 'string' ? content : JSON.stringify(content ?? {}, null, 2); + raw = Buffer.from(str, 'utf8'); + } catch (err) { + throw new ToolError(`Failed to read draft "${draftInfo.name}": ${err.message}`); + } + } else { + virtualSkill = !fs.existsSync(absPath) && isSkillPath(clean) ? getApiRouteSkill(clean) : null; + if (!virtualSkill && !fs.existsSync(absPath)) { + throw new ToolError( + `File not found in virtual filesystem: "${clean}". ` + + 'Call find_files to see what is stored, or find_files({ skills: true }) for SKILL files.' + ); + } + if (!virtualSkill && !fs.statSync(absPath).isFile()) { + throw new ToolError(`"${clean}" is not a file. Use find_files to list directories.`); + } + raw = virtualSkill ? Buffer.from(virtualSkill.content, 'utf8') : fs.readFileSync(absPath); + } if (looksBinary(raw)) { const ext = path.extname(clean).toLowerCase(); throw new ToolError( diff --git a/src/tools/vfs.js b/src/tools/vfs.js index 9bc2065..e861ceb 100644 --- a/src/tools/vfs.js +++ b/src/tools/vfs.js @@ -4,6 +4,14 @@ import { getStore } from '../db/store.js'; import env from '../config/env.js'; import { getDefaultSkills } from './skill.js'; import { getDefaultApplets, DEFAULT_APPLETS_VERSION, APPLET_EXT } from './applet.js'; +import { + parseDraftPath, + requestDraftRead, + notifyDraftUpdate, + notifyDraftUpdateSync, + getCachedDraft, + DRAFT_NAMES, +} from '../services/draftManager.js'; const FULL_HASH_REGEX = /^[a-zA-Z0-9]{8}$/; const VIRTUAL_IMAGE_FOLDERS = new Set(['image', 'images']); @@ -300,6 +308,16 @@ export function createVfs(vfsRoot, options = {}) { const vfs = { readFileSync: (p, opt) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isDraft) { + const cached = getCachedDraft({ userId: googleAuthId, name: draftInfo.name }); + if (cached) { + const str = typeof cached.content === 'string' ? cached.content : JSON.stringify(cached.content ?? {}, null, 2); + const encoding = typeof opt === 'string' ? opt : opt?.encoding; + return encoding ? str : Buffer.from(str, 'utf8'); + } + throw new Error(`Virtual draft "${draftInfo.name}" is not cached in memory. Use vfs.promises.readFile() to fetch it asynchronously.`); + } const hash = extractFullHash(p); if (hash) { const buf = syncFetchImage(hash); @@ -342,6 +360,19 @@ export function createVfs(vfsRoot, options = {}) { }, writeFileSync: (p, data, opt) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isDraft) { + let str = typeof data === 'string' ? data : Buffer.isBuffer(data) ? data.toString('utf8') : JSON.stringify(data); + let parsed = str; + try { parsed = JSON.parse(str); } catch {} + notifyDraftUpdateSync({ + googleAuthId, + clientId: options.clientId, + name: draftInfo.name, + content: parsed, + }); + return; + } assertNotReadOnlyDatabasePath(p); const diskPath = safeResolve(p); fs.mkdirSync(path.dirname(diskPath), { recursive: true }); @@ -382,6 +413,8 @@ export function createVfs(vfsRoot, options = {}) { } }, existsSync: (p) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isFolder || draftInfo.isDraft) return true; const hash = extractFullHash(p); if (hash) { const buf = syncFetchImage(hash); @@ -396,6 +429,31 @@ export function createVfs(vfsRoot, options = {}) { }, statSync: (p, opt) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isFolder) { + const now = new Date(); + return { + isFile: () => false, + isDirectory: () => true, + size: 0, + mtime: now, + ctime: now, + atime: now, + }; + } + if (draftInfo.isDraft) { + const cached = getCachedDraft({ userId: googleAuthId, name: draftInfo.name }); + const now = cached?.updatedAt ? new Date(cached.updatedAt) : new Date(); + const size = cached?.size ?? 0; + return { + isFile: () => true, + isDirectory: () => false, + size, + mtime: now, + ctime: now, + atime: now, + }; + } const hash = extractFullHash(p); if (hash) { const buf = syncFetchImage(hash); @@ -418,36 +476,62 @@ export function createVfs(vfsRoot, options = {}) { lstatSync: (p, opt) => vfs.statSync(p, opt), readdirSync: (p = '.', opt) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isFolder) { + return Array.from(DRAFT_NAMES); + } const clean = typeof p === 'string' ? p.trim().replace(/^([a-zA-Z]:|\/)+/, '') : ''; if (VIRTUAL_IMAGE_FOLDERS.has(clean.toLowerCase())) { return []; } const diskPath = safeResolve(p); - return fs.readdirSync(diskPath, opt); + const entries = fs.readdirSync(diskPath, opt); + if ((clean === '' || clean === '.') && Array.isArray(entries)) { + if (!entries.some((e) => (typeof e === 'string' ? e : e.name) === 'drafts')) { + entries.push('drafts'); + } + } + return entries; }, mkdirSync: (p, opt) => { - assertNotReadOnlyDatabasePath(p); - const diskPath = safeResolve(p); - try { - return fs.mkdirSync(diskPath, opt); - } catch (err) { - throw sanitizeFsError(err, p); - } - }, + const draftInfo = parseDraftPath(p); + if (draftInfo.isFolder || draftInfo.isDraft) { + throw new Error(`Access denied: "${p}" is a virtual draft and cannot be created on disk.`); + } + assertNotReadOnlyDatabasePath(p); + const diskPath = safeResolve(p); + try { + return fs.mkdirSync(diskPath, opt); + } catch (err) { + throw sanitizeFsError(err, p); + } + }, unlinkSync: (p) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isFolder || draftInfo.isDraft) { + throw new Error(`Access denied: "${p}" is a virtual draft and cannot be unlinked on disk.`); + } assertNotReadOnlyDatabasePath(p); const diskPath = safeResolve(p); return fs.unlinkSync(diskPath); }, rmdirSync: (p, opt) => { - assertNotReadOnlyDatabasePath(p); + const draftInfo = parseDraftPath(p); + if (draftInfo.isFolder || draftInfo.isDraft) { + throw new Error(`Access denied: "${p}" is a virtual draft and cannot be removed on disk.`); + } + assertNotReadOnlyDatabasePath(p); const diskPath = safeResolve(p); return fs.rmdirSync(diskPath, opt); }, - rmSync: (p, opt) => { + rmSync: (p, opt) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isFolder || draftInfo.isDraft) { + throw new Error(`Access denied: "${p}" is a virtual draft and cannot be removed on disk.`); + } assertNotReadOnlyDatabasePath(p); const diskPath = safeResolve(p); return fs.rmSync(diskPath, opt); @@ -455,6 +539,17 @@ export function createVfs(vfsRoot, options = {}) { promises: { readFile: async (p, opt) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isDraft) { + const content = await requestDraftRead({ + userId: googleAuthId, + clientId: options.clientId, + name: draftInfo.name, + }); + const str = typeof content === 'string' ? content : JSON.stringify(content ?? {}, null, 2); + const encoding = typeof opt === 'string' ? opt : opt?.encoding; + return encoding ? str : Buffer.from(str, 'utf8'); + } const hash = extractFullHash(p); if (hash) { const buf = syncFetchImage(hash); @@ -482,7 +577,29 @@ export function createVfs(vfsRoot, options = {}) { } return vfs.readFileSync(p, opt); }, - writeFile: async (p, data, opt) => vfs.writeFileSync(p, data, opt), + writeFile: async (p, data, opt) => { + const draftInfo = parseDraftPath(p); + if (draftInfo.isDraft) { + let str = typeof data === 'string' ? data : Buffer.isBuffer(data) ? data.toString('utf8') : JSON.stringify(data); + let parsed = str; + try { parsed = JSON.parse(str); } catch {} + let companyId = options.companyId; + if (companyId == null && googleAuthId) { + const store = await getStore(); + const row = await store.google_auth.getById(googleAuthId); + companyId = row?.selectedCompanyId; + } + notifyDraftUpdate({ + companyId, + userId: googleAuthId, + clientId: options.clientId, + name: draftInfo.name, + content: parsed, + }); + return; + } + return vfs.writeFileSync(p, data, opt); + }, appendFile: async (p, data, opt) => vfs.appendFileSync(p, data, opt), stat: async (p, opt) => vfs.statSync(p, opt), readdir: async (p, opt) => vfs.readdirSync(p, opt),