@oneentry/mcp-platform-server 0.1.5 → 0.1.6

package/README.md

@@ -71,7 +71,7 @@ arguments, so a prompt-injected instruction cannot swap identities:
 
 Sessions never share tokens or confirm tokens. `GET /health` reports liveness and session count.
 
-## The seven tools
+## The nine tools
 
 | tool | what it does |
 |---|---|
@@ -79,12 +79,39 @@ Sessions never share tokens or confirm tokens. `GET /health` reports liveness an
 | `cms_docs_search` | search the knowledge base, returns sections with snippets |
 | `cms_docs_read` | read one section, with its sibling sections listed for paging |
 | `cms_api_search` | find operations by keyword / tag / method / mutating |
-| `cms_api_describe` | params, body schema, required permission, risk, confirm gating |
+| `cms_api_describe` | params, body schema, required permission, risk, confirm gating, and `curatedBody` where a shape has been verified on a live instance |
 | `cms_api_call` | execute one operation; `dryRun` and confirm-gating for mutations |
+| `cms_upload_file` | upload one file from this machine as `multipart/form-data` (local mode only) |
+| `cms_import_file_from_url` | fetch one file over http(s) and upload it in a single step |
 | `cms_whoami` | mode, base URL, admin + permissions, knowledge commit, catalog state and warnings |
 
 Plus two MCP resources: `oneentry://knowledge/mcp/operating-rules` and `oneentry://knowledge/index`.
 
+### Uploading files
+
+`cms_api_call` sends JSON only, and the upload endpoint wants `multipart/form-data` — which is why
+the two upload tools exist rather than a note telling the agent to go around the server. They run
+through the same gate as any other write: `--allow=write`, the local permission check, `dryRun`, and
+the audit line.
+
+Both bound their **source**, because a path or a URL arrives as a tool argument and a tool argument
+can be prompt-injected:
+
+| flag | env | default | what it bounds |
+|---|---|---|---|
+| `--upload-root` | `ONEENTRY_MCP_UPLOAD_ROOT` | the process working directory | `cms_upload_file` reads nothing outside this directory, symlinks resolved first |
+| `--upload-max-bytes` | `ONEENTRY_MCP_UPLOAD_MAX_BYTES` | 25 MiB | size of one file, checked on disk and on the wire |
+| `--upload-allowed-hosts` | `ONEENTRY_MCP_UPLOAD_ALLOWED_HOSTS` | empty | hosts `cms_import_file_from_url` may fetch from |
+
+`cms_upload_file` is refused in remote mode: there is no shared filesystem, and a session-supplied
+path would read the host's files. `cms_import_file_from_url` refuses any address resolving to a
+loopback, private, link-local or carrier-grade-NAT range, re-checks every redirect hop, and in remote
+mode stays disabled until the operator sets an allowlist.
+
+Pass `template` — the **numeric id** of a `/template-previews` record — on the first upload. Without
+it the file is stored with no `previewLink`, nothing reports the omission, and the only repair is
+uploading the file again.
+
 ## Write safety
 
 Read-only by default. `--allow` (or `ONEENTRY_MCP_ALLOW`) raises it:

package/dist/api/build-catalog.js

@@ -217,6 +217,7 @@ export const buildCatalog = (params) => {
                     ? { responseSummary: responseSummary(operation['responses']) }
                     : {}),
                 ...(notes?.note ? { note: notes.note } : {}),
+                ...(notes?.example !== undefined ? { curatedExample: notes.example } : {}),
                 ...(notes?.verifyWith ? { verifyWith: notes.verifyWith } : {}),
                 ...(notes?.silentNoOp ? { silentNoOp: notes.silentNoOp } : {}),
                 searchText: '',

package/dist/api/client.d.ts

@@ -33,5 +33,11 @@ export declare class AdminApiClient {
         timeoutMs: number;
     });
     call(operation: Operation, args: CallArgs): Promise<CallResult>;
+    upload(operation: Operation, args: CallArgs, payload: {
+        bytes: Uint8Array;
+        filename: string;
+        contentType: string;
+    }): Promise<CallResult>;
+    private send;
     fetchPermissions(adminId: number): Promise<string[]>;
 }

package/dist/api/client.js

@@ -21,9 +21,15 @@ export const unsupportedBodyFormat = (operation) => {
     if (contentType === undefined || /^application\/(\w[\w.+-]*\+)?json$/.test(contentType)) {
         return undefined;
     }
-    return (`Operation ${operation.opId} expects a "${contentType}" request body, and this server ` +
-        'can only send application/json. The call is not executable through MCP — no body ' +
-        'shape will help. Report it to the human and use another route to that instance.');
+    const base = `Operation ${operation.opId} expects a "${contentType}" request body, and cms_api_call ` +
+        'can only send application/json. The call is not executable through cms_api_call — no ' +
+        'body shape will help.';
+    if (contentType === 'multipart/form-data') {
+        return (`${base} Upload through cms_upload_file (a file on the machine running this server) or ` +
+            'cms_import_file_from_url (this server fetches it). Both keep the allow level, the ' +
+            'confirm gate and the audit line.');
+    }
+    return `${base} Report it to the human and use another route to that instance.`;
 };
 export const buildUrl = (baseUrl, operation, args) => {
     let path = operation.path;
@@ -57,6 +63,10 @@ const hintFor = (status, operation) => {
     if (status === 400 || status === 422) {
         const loose = operation.body?.schema['x-loose'] === true;
         return (`Validation rejected the payload. ${loose ? 'This body has loosely typed fields — copy the shape from the example in cms_api_describe. ' : ''}` +
+            (operation.curatedExample !== undefined
+                ? 'A body shape verified on a live instance is in cms_api_describe under "curatedBody" — ' +
+                    'compare yours with it before changing anything else. '
+                : '') +
             'Search the knowledge base with cms_docs_search before retrying.');
     }
     if (status === 403) {
@@ -84,6 +94,12 @@ const readBody = async (response) => {
         return text.slice(0, 2000);
     }
 };
+const isLoginPage = (response, body) => {
+    if ((response.headers.get('content-type') ?? '').includes('text/html')) {
+        return true;
+    }
+    return typeof body === 'string' && body.trimStart().startsWith('<');
+};
 const extractMessage = (body, fallback) => {
     if (typeof body === 'string') {
         return body.slice(0, 500);
@@ -110,7 +126,7 @@ export class AdminApiClient {
     }
     async call(operation, args) {
         const url = buildUrl(this.baseUrl, operation, args);
-        const send = async (token) => {
+        return this.send(operation, url, (token) => {
             const headers = { authorization: `Bearer ${token}` };
             let payload;
             if (args.body !== undefined && operation.method !== 'get') {
@@ -123,12 +139,46 @@ export class AdminApiClient {
                 ...(payload !== undefined ? { body: payload } : {}),
                 signal: AbortSignal.timeout(this.timeoutMs),
             });
-        };
+        });
+    }
+    async upload(operation, args, payload) {
+        const url = buildUrl(this.baseUrl, operation, args);
+        return this.send(operation, url, (token) => {
+            const form = new FormData();
+            form.append('file', new Blob([payload.bytes], { type: payload.contentType }), payload.filename);
+            return fetch(url, {
+                method: operation.method.toUpperCase(),
+                headers: { authorization: `Bearer ${token}` },
+                body: form,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        });
+    }
+    async send(operation, url, attempt) {
         let response;
+        let body;
         try {
-            response = await send(await this.tokens.accessToken());
+            response = await attempt(await this.tokens.accessToken());
             if (response.status === 401) {
-                response = await send(await this.tokens.refresh());
+                response = await attempt(await this.tokens.refresh());
+            }
+            body = await readBody(response);
+            if (response.ok && isLoginPage(response, body)) {
+                response = await attempt(await this.tokens.refresh());
+                body = await readBody(response);
+                if (response.ok && isLoginPage(response, body)) {
+                    return {
+                        ok: false,
+                        error: {
+                            status: response.status,
+                            message: `${operation.method.toUpperCase()} ${url} answered ${String(response.status)} with ` +
+                                'the instance login page instead of a result: the admin session is not valid and ' +
+                                're-authenticating did not change that. Nothing was written by this call.',
+                            hint: 'Check the credentials this server runs with, then retry. Treat every write since ' +
+                                'the last verified read as unconfirmed and read those entities back.',
+                        },
+                    };
+                }
             }
         }
         catch (error) {
@@ -141,7 +191,6 @@ export class AdminApiClient {
                 },
             };
         }
-        const body = await readBody(response);
         if (!response.ok) {
             const hint = hintFor(response.status, operation);
             return {

package/dist/api/operation-notes.d.ts

@@ -1,6 +1,7 @@
 import type { VerifyWith } from './types.js';
 export interface OperationNote {
     note?: string;
+    example?: unknown;
     verifyWith?: VerifyWith;
     silentNoOp?: string;
     readOnly?: true;

package/dist/api/operation-notes.js

@@ -8,6 +8,47 @@ export const ALWAYS_CONFIRM_PREFIXES = [
     '/settings-general',
     '/system/captcha-keys',
 ];
+const LIST_ATTRIBUTE_WITH_EXTRAS = {
+    type: 'list',
+    identifier: 'labels',
+    multiselect: true,
+    localizeInfos: { en_US: { title: 'Labels' } },
+    listTitles: {
+        en_US: [
+            {
+                title: 'Dishwasher safe',
+                value: 'dishwasher-safe',
+                position: 1,
+                extended: {
+                    type: 'image',
+                    value: {
+                        filename: 'dishwasher-safe.png',
+                        downloadLink: 'https://your-instance.example/files/dishwasher-safe.png',
+                    },
+                },
+            },
+            {
+                title: 'Cherry',
+                value: 'cherry',
+                position: 2,
+                extended: { type: 'string', value: '#d11241' },
+            },
+        ],
+    },
+};
+const LIST_EXTRAS_NOTE = 'The curated example is ONE attribute as it appears in the set\'s schema list. Three ' +
+    'details in it are each enough on their own to leave the field blank in the admin panel ' +
+    'while every read returns exactly what you sent. "extended" carries NO locale key — it is ' +
+    'flat, "type" and "value", and it is the one exception to the locale-first rule that ' +
+    'applies to "localizeInfos", "validators" and "listTitles" around it. Its "type" is one of ' +
+    'string, integer, realNumber, fixedPointNumber, date, dateAndTime, time, image, file, json, ' +
+    'and for image or file the value is ONE object, not a list. "multiselect": true belongs to ' +
+    'the attribute: without it every selected option is stored and read back, and the panel ' +
+    'shows only the first one. Two neighbouring fields look right and are not: ' +
+    '"additionalFields" is a separate marker-keyed list of fields and holds no option extras, ' +
+    'and an "image" key on the option itself is stored and read by nothing. Option extras are ' +
+    'also absent from entity reads — a site gets them from the attribute definition, not from ' +
+    'the product.';
 export const OPERATION_NOTES = {
     AdminProductsController_findAll: {
         readOnly: true,
@@ -31,7 +72,9 @@ export const OPERATION_NOTES = {
     AdminAttributesSetsController_create: {
         note: 'Inside an attribute, "validators", "localizeInfos" and "listTitles" are keyed by ' +
             'locale first: validators.en_US.requiredValidator, not validators.requiredValidator. ' +
-            'A flat map is stored verbatim and read by nobody.',
+            'A flat map is stored verbatim and read by nobody. ' +
+            LIST_EXTRAS_NOTE,
+        example: LIST_ATTRIBUTE_WITH_EXTRAS,
         verifyWith: {
             opId: 'AdminAttributesSetsController_findOne',
             check: 'schema[].validators.<locale>',
@@ -40,7 +83,13 @@ export const OPERATION_NOTES = {
     },
     AdminAttributesSetsController_update: {
         note: 'Inside an attribute, "validators", "localizeInfos" and "listTitles" are keyed by ' +
-            'locale first. A flat map is accepted and stored where nothing reads it.',
+            'locale first. A flat map is accepted and stored where nothing reads it. ' +
+            'Dropping an attribute from the set does not remove the values entities already hold ' +
+            'under its key: they stay on every entity, are invisible in the panel, and a ' +
+            'read-modify-write cycle sends them back, so they outlive the attribute indefinitely. ' +
+            'Strip the removed keys from each entity yourself, in the same run. ' +
+            LIST_EXTRAS_NOTE,
+        example: LIST_ATTRIBUTE_WITH_EXTRAS,
         verifyWith: {
             opId: 'AdminAttributesSetsController_findOne',
             check: 'schema[].validators.<locale>',
@@ -50,7 +99,10 @@ export const OPERATION_NOTES = {
     AdminAttributesSetsController_updateSchema: {
         note: 'The body is the schema object itself, never wrapped as { "schema": … }. The wrapped ' +
             'form answers 200 and replaces the set with a single attribute called "schema". ' +
-            'Locale-keyed rules apply here too.',
+            'Locale-keyed rules apply here too, and so does the residue rule: an attribute removed ' +
+            'here leaves its values on every entity that had one. ' +
+            LIST_EXTRAS_NOTE,
+        example: LIST_ATTRIBUTE_WITH_EXTRAS,
         verifyWith: {
             opId: 'AdminAttributesSetsController_findOne',
             check: 'schema[].validators.<locale>',
@@ -58,15 +110,83 @@ export const OPERATION_NOTES = {
         },
     },
     AdminFileUploadController_uploadFiles: {
-        note: 'The "template" query parameter is the NUMERIC id of a /template-previews record, not ' +
-            'a boolean flag. A fresh instance has no such records, and an upload without a valid ' +
-            'template id stores the file with no preview and reports no error.',
+        note: 'The body is multipart, so cms_api_call cannot send it — use cms_upload_file for a file ' +
+            'on the machine running this server, or cms_import_file_from_url to have the server ' +
+            'fetch it. Both keep the allow level, the confirm gate and the audit line. The binary ' +
+            'part is accepted under "file" and under "files" alike; everything else — type, entity, ' +
+            'id, compress, edit, template — is a query parameter. The "template" parameter is the ' +
+            'NUMERIC id of a /template-previews record, not a boolean flag. A fresh instance has no ' +
+            'such records, and an upload without a valid template id stores the file with no preview ' +
+            'and reports no error; the only repair is uploading the file again. That matters because ' +
+            'previewLink.default[0] is the inline placeholder a site renders while the full image ' +
+            'loads, so an image without it cannot be shown progressively. The stored record carries ' +
+            'no "alt" and no "title": alternative text has to live in a sibling attribute, and the ' +
+            'project has to agree on one naming convention for it before the first upload.',
     },
     AdminMenusController_create: {
         note: 'Create the menu with an empty pagesIds, then attach pages with AdminMenusController_update. ' +
             'A non-empty pagesIds on create answers 500 (null value in column "page_id"). That 500 is ' +
             'known — do not report it as an unexplained server failure.',
     },
+    AdminMenusController_update: {
+        note: '"pagesIds" is a flat set of page ids and nothing else: nesting is NOT taken from the ' +
+            'page tree, so a menu whose pages are nested in the content tree still reads back flat. ' +
+            'Build the levels afterwards, top down, with the position operations. A page can appear ' +
+            'in the set once — a page that has to sit in two places gets a custom item with the same ' +
+            'target for the second one, otherwise one of the two silently disappears. The label a ' +
+            'menu item shows is the page\'s "menuTitle", not its "title", so a menu built without ' +
+            'setting menuTitle arrives carrying page headings.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the included pages, their parents and their labels',
+            why: 'the update answers 200 for a flat result as readily as for the tree you intended',
+        },
+    },
+    AdminMenusController_createCustomItem: {
+        note: 'A custom item is for anything that is not a page: a product, an external address, a ' +
+            'column heading. An empty "value" is rejected, so a heading with no link needs a ' +
+            'placeholder target such as "#". The parent reference is a bare number with no kind ' +
+            'attached, while custom items and page items are numbered separately — so a custom item ' +
+            'and a page item can share an id, and children hung on that number are then returned ' +
+            'under BOTH parents. Before nesting anything, read the menu and check that the included ' +
+            'pages and the custom items share no id; if they do, the only route today is to recreate ' +
+            'the custom item until its id differs.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the ids of included pages against the ids of customItems',
+            why: 'a shared id duplicates a whole branch, and the write that caused it answers 200',
+        },
+    },
+    AdminMenusController_updatePosition: {
+        example: { position: { leftObjectId: null, rightObjectId: null }, newParentId: 12 },
+        note: '"position" is required even when the order does not matter, and it must be an object: ' +
+            'omitting it answers 500 about destructuring, and an empty object is not enough — send ' +
+            '{ leftObjectId: null, rightObjectId: null }. Re-parenting through "newParentId" does ' +
+            'apply; the ordering does not.',
+        silentNoOp: 'Re-parenting lands, but sibling order does not change: the call answers success and ' +
+            'every root item keeps the position it had. Public reads do not take item order from ' +
+            'positions either — page items arrive ordered by page id and custom items after them. ' +
+            'There is no body that produces a chosen order today, so build the menu correct in ' +
+            'composition and nesting, tell the human the order is not reproducible, and report it ' +
+            'rather than trying further bodies.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the parent of the item you moved, and the order of its siblings',
+            why: 'the parent change applies while the order does not, and one response covers both',
+        },
+    },
+    AdminMenusController_updateCustomItemPosition: {
+        example: { position: { leftObjectId: null, rightObjectId: null }, newParentId: 12 },
+        note: 'Same body as AdminMenusController_updatePosition: "position" is required and must be an ' +
+            'object — { leftObjectId: null, rightObjectId: null } when the order does not matter.',
+        silentNoOp: 'Re-parenting lands; sibling order does not. See AdminMenusController_updatePosition — ' +
+            'public reads order items by page id rather than by the positions stored here.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the parent of the item you moved, and the order of its siblings',
+            why: 'the parent change applies while the order does not, and one response covers both',
+        },
+    },
     AdminFormsController_create: {
         note: 'Send the payload wrapped under "newForm". The form "type" is missing from the schema but ' +
             'is accepted and persisted: order | sign_in_up | collection | data | rating. A contact ' +
@@ -82,7 +202,27 @@ export const OPERATION_NOTES = {
             'module binding of the form AND the submissions recorded against those bindings, and the ' +
             'call still answers 200 true. Read the form first and send its current formModuleConfigs ' +
             'back unless changing them is the point. This is also the only operation that creates a ' +
-            'binding: an entry with formId, moduleId and either isGlobal or entityIdentifiers.',
+            'binding: an entry with formId, moduleId and either isGlobal or entityIdentifiers. ' +
+            'The rating behaviour of a review form lives in that same entry and has no operation of ' +
+            'its own: isRating, ratingCalculation, maxRatingScale, allowHalfRatings, allowRerating ' +
+            'and isAnonymous. There is no other route to them, which is why they are worth reading ' +
+            'here before asking a human to set them in the panel.',
+        example: {
+            formModuleConfigs: [
+                {
+                    formId: 5,
+                    moduleId: 3,
+                    isGlobal: true,
+                    entityIdentifiers: [],
+                    isRating: true,
+                    ratingCalculation: 'average',
+                    maxRatingScale: 5,
+                    allowHalfRatings: false,
+                    allowRerating: false,
+                    isAnonymous: true,
+                },
+            ],
+        },
         verifyWith: {
             opId: 'AdminFormsController_findOne',
             check: 'formModuleConfigs',
@@ -101,7 +241,13 @@ export const OPERATION_NOTES = {
             'not mean the config is optional. A form with type null fails earlier with "Form has ' +
             'incorrect type". Field validation is wired into the Content API only: through the Admin ' +
             'API a missing required field is stored rather than rejected, so a submission accepted ' +
-            'here does not prove a visitor\'s submission would pass.',
+            'here does not prove a visitor\'s submission would pass. A field of type text takes ' +
+            '[{ "htmlValue": "…" }] — a bare string, a list of strings and [{ "value": … }] are all ' +
+            'rejected. On a rating form the score attribute must be marked isRatingValue, or the ' +
+            'form is invalid with "Form must have a rating marker". This route also treats one ' +
+            'authenticated author as one submission per entity, so it rejects the second review of a ' +
+            'product with "You have already rated": a bulk import of visitor reviews cannot go ' +
+            'through the Admin API and has to use the visitor route, which this server does not call.',
         verifyWith: {
             opId: 'AdminFormDataController_findByFormMarker',
             check: 'the submission you sent',
@@ -111,13 +257,109 @@ export const OPERATION_NOTES = {
     AdminPagesController_update: {
         note: 'Omitting parentId does not leave the parent alone — it moves the page to the root and ' +
             'decrements the former parent\'s childrenCount. Read the page first and send parentId ' +
-            'back unchanged unless you mean to re-parent it.',
+            'back unchanged unless you mean to re-parent it. One field cannot be echoed back at all: ' +
+            'a listing returns "position" as a lexorank string while this operation expects an object ' +
+            'and answers 400 "position must be either object or array" — drop the field from a ' +
+            'read-modify-write body and reorder with the page position operation instead.',
         verifyWith: {
             opId: 'AdminPagesController_findOne',
             check: 'parentId',
             why: 'an omitted parentId is applied as "move to root", and the update still answers 200',
         },
     },
+    AdminEventsController_create: {
+        example: {
+            moduleId: 1,
+            localizeInfos: {
+                en_US: {
+                    title: 'New product published',
+                    subject: 'A new product is live',
+                    template: '<p>{{ product.title }} is now available.</p>',
+                    push: '{{ product.title }} is now available',
+                },
+            },
+        },
+        note: 'The name shown in the events list is localizeInfos.<locale>.title. "name" is what the ' +
+            'create body declares as required, and a name written only there is stored and never ' +
+            'displayed, so send both. The message itself lives in the same locale object — "subject" ' +
+            'for the mail subject, "template" for the mail body, "push" for the push body — and not ' +
+            'under "mailing", which belongs to the mailing module. Placeholders depend on the module: ' +
+            '{{ product.title }} and {{ product.<marker> }} for the catalogue, {{ user.<marker> }} ' +
+            'for the recipient. Events support six modules — catalog, forms, orders, users, payments ' +
+            'and discounts. There is no content module among them, so an event on a page or a block ' +
+            'attribute cannot be built this way; see silentNoOp.',
+        silentNoOp: 'A moduleId outside the six supported modules is accepted: the event is created, reads ' +
+            'back complete, and never fires — the panel draws no settings for it and nothing is ever ' +
+            'sent. Nothing in the response distinguishes it from a working event. If the task needs ' +
+            '"notify when this page changes", say that events do not cover it rather than creating ' +
+            'the object and reporting success.',
+        verifyWith: {
+            opId: 'AdminEventsController_findOne',
+            check: 'moduleId and localizeInfos.<locale>.title',
+            why: 'an event on an unsupported module reads back fully populated and still does nothing',
+        },
+    },
+    AdminEventsController_update: {
+        note: 'The event name, the mail subject and the mail body all live in ' +
+            'localizeInfos.<locale> as "title", "subject" and "template", with "push" for the push ' +
+            'channel. Nothing about the message belongs under "mailing". Supported modules are ' +
+            'catalog, forms, orders, users, payments and discounts; any other moduleId is accepted ' +
+            'and the event never fires.',
+        example: {
+            localizeInfos: {
+                en_US: {
+                    title: 'New product published',
+                    subject: 'A new product is live',
+                    template: '<p>{{ product.title }} is now available.</p>',
+                    push: '{{ product.title }} is now available',
+                },
+            },
+        },
+        verifyWith: {
+            opId: 'AdminEventsController_findOne',
+            check: 'localizeInfos.<locale>.subject and .template',
+            why: 'a subject written under "mailing" is stored there and never used',
+        },
+    },
+    AdminDiscountsController_create: {
+        note: 'A discount with an empty "conditions" and no coupons applies to every order of every ' +
+            'customer, without end. The object is created, the amount is right, and the meaning is ' +
+            'the opposite of "15% off the first order for a subscriber" — a sentence that carries ' +
+            'three limits, none of which is expressed by the amount. State the discount in words, ' +
+            'then check each limit against the body: coupons are the gate (with coupons present, the ' +
+            'conditions apply only when a coupon is used), and conditions narrow which products, ' +
+            'categories or totals are touched. Conditions over attributes work on indexed attributes ' +
+            'only and match nothing, silently, on the rest.',
+        verifyWith: {
+            opId: 'AdminDiscountsController_findOne',
+            check: 'conditions and the coupon list',
+            why: 'a discount meant for some customers cannot have both of them empty',
+        },
+    },
+    AdminDiscountsController_createCoupon: {
+        note: 'A coupon created from a code you supply comes back isReusable: true — one code, valid ' +
+            'for everyone, any number of times. "isReusable" is not accepted in the body, only ' +
+            'reported in the response, so the reuse behaviour follows from WHICH operation created ' +
+            'the coupon. For codes that expire on first use, generate them with ' +
+            'AdminDiscountsController_generateCouponsByMask instead. On a "first order" discount the ' +
+            'difference decides whether one customer gets a discount or everyone does, permanently.',
+        verifyWith: {
+            opId: 'AdminDiscountsController_findOne',
+            check: 'the coupon\'s isReusable',
+            why: 'reuse is not something the create body can set, so the response is the only place it appears',
+        },
+    },
+    AdminDiscountsController_generateCouponsByMask: {
+        note: 'Coupons generated from a mask come back isReusable: false — each code stops working ' +
+            'after the order that used it. That is the only route to single-use codes: a coupon ' +
+            'created from a supplied string is reusable and cannot be changed through the body.',
+    },
+    AdminProductsController_update: {
+        note: 'Always include "blocks" — send [] when there is nothing to set, because omitting it ' +
+            'fails the update. Never include "forms": the schema accepts the field and saving rejects ' +
+            'it. This is also the working route for a product status: send statusId here rather than ' +
+            'through the bulk set-status operation.',
+    },
     AdminBlocksController_update: {
         note: 'Omitting blockPages detaches the block from every page it was on. Read the block first ' +
             'and send its current page list back unless you mean to change it.',
@@ -128,7 +370,13 @@ export const OPERATION_NOTES = {
         },
     },
     AdminProductsController_countAll: { readOnly: true },
-    AdminProductsController_findByIds: { readOnly: true },
+    AdminProductsController_findByIds: {
+        readOnly: true,
+        note: 'The way to verify a batch write without one read per entity: pass every id you wrote and ' +
+            'compare the values in the response. A batch write that reports success can still miss a ' +
+            'single entity, and a per-entity read loop is what makes agents verify a sample instead ' +
+            'of the whole set.',
+    },
     AdminProductsController_findAllByWithOutCategory: { readOnly: true },
     AdminProductsController_findAllByCategoryIdForAdmin: { readOnly: true },
     AdminProductsController_countByCategoryId: { readOnly: true },

package/dist/api/types.d.ts

@@ -47,6 +47,7 @@ export interface Operation {
     };
     responseSummary?: string;
     note?: string;
+    curatedExample?: unknown;
     verifyWith?: VerifyWith;
     silentNoOp?: string;
     searchText: string;

package/dist/api/upload.d.ts

@@ -0,0 +1,23 @@
+import type { OperationCatalog } from './catalog.js';
+import type { Operation } from './types.js';
+export interface UploadPayload {
+    bytes: Uint8Array;
+    filename: string;
+    contentType: string;
+}
+export declare class UploadSourceError extends Error {
+}
+export declare const contentTypeOf: (filename: string) => string;
+export declare const resolveUploadOperation: (catalog: OperationCatalog) => Operation | undefined;
+export declare const readLocalUpload: (params: {
+    path: string;
+    root: string;
+    maxBytes: number;
+}) => Promise<UploadPayload>;
+export declare const fetchRemoteUpload: (params: {
+    url: string;
+    allowedHosts: readonly string[];
+    maxBytes: number;
+    timeoutMs: number;
+    filename?: string;
+}) => Promise<UploadPayload>;