@oneentry/mcp-platform-server 0.1.7 → 0.1.8

package/data/permissions.json

@@ -214,6 +214,7 @@
     "AdminTemplatePreviewsController_update": "settings.templatePreview.update",
     "AdminTemplatePreviewsController_remove": "settings.templatePreview.delete",
     "AdminTemplatePreviewsController_updateAttributeSetPosition": "settings.templatePreview.changePositions",
+    "AdminTemplatePreviewsController_regenerate": "settings.templatePreview.update",
     "AdminTemplatesController_create": "settings.templates.create",
     "AdminTemplatesController_update": "settings.templates.update",
     "AdminTemplatesController_remove": "settings.templates.delete",

package/dist/api/operation-notes.js

@@ -58,36 +58,39 @@ export const OPERATION_NOTES = {
             'the validator is describing the query parameter you did not send.',
     },
     AdminProductsController_setStatusForProducts: {
-        silentNoOp: 'The status id goes in "id", not "statusId". With "statusId" the handler reads ' +
-            'undefined, writes NULL over the product status and still answers 201 true. The call ' +
-            'also never re-indexes, so even a correct write stays invisible to ' +
-            'AdminProductsController_findAll. Setting statusId through ' +
-            'AdminProductsController_update is the route that works today.',
+        note: 'The status id goes in "statusId". The older field name "id" is accepted for the same ' +
+            'value, and a body carrying neither answers 400 rather than writing an empty status. ' +
+            'The call re-indexes what it changed, so the new status is visible to ' +
+            'AdminProductsController_findAll and not only to a read by id. For a single product, ' +
+            'sending statusId through AdminProductsController_update does the same job.',
         verifyWith: {
             opId: 'AdminProductsController_findOne',
             check: 'statusId',
-            why: 'the call answers 201 true whether or not any row changed',
+            why: 'the response says the call was accepted, not which products ended up with the status',
         },
     },
     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. ' +
+        note: 'Inside an attribute, "validators", "localizeInfos", "listTitles" and "additionalFields" ' +
+            'are keyed by locale first: validators.en_US.requiredValidator, not ' +
+            'validators.requiredValidator. A flat map answers 400 here, and the message names the ' +
+            'attribute and the field — only AdminAttributesSetsController_updateSchema still accepts ' +
+            'one silently. ' +
             LIST_EXTRAS_NOTE,
         example: LIST_ATTRIBUTE_WITH_EXTRAS,
         verifyWith: {
             opId: 'AdminAttributesSetsController_findOne',
             check: 'schema[].validators.<locale>',
-            why: 'the raw set shows exactly what you wrote, including a flat map that no consumer reads',
+            why: 'the raw set is where a locale key is either present or not, whatever the panel shows',
         },
     },
     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. ' +
-            '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. ' +
+        note: 'Inside an attribute, "validators", "localizeInfos", "listTitles" and "additionalFields" ' +
+            'are keyed by locale first, and a flat map answers 400 here as it does on create. ' +
+            'Dropping an attribute from the set clears the values entities held under its key, but ' +
+            'not by the time the call returns: the cleanup runs behind the write, so for a short ' +
+            'window a read still shows the removed key. Do not build an update from a read taken ' +
+            'immediately after removing an attribute — compare the keys you are about to send against ' +
+            'the current set and drop the ones it no longer defines. ' +
             LIST_EXTRAS_NOTE,
         example: LIST_ATTRIBUTE_WITH_EXTRAS,
         verifyWith: {
@@ -97,12 +100,18 @@ 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, and so does the residue rule: an attribute removed ' +
-            'here leaves its values on every entity that had one. ' +
+        note: 'The body is the schema object itself, never wrapped as { "schema": … }. Locale-keyed ' +
+            'rules apply here too, and so does the cleanup rule: an attribute removed here has its ' +
+            'values cleared behind the write, so a read taken straight afterwards can still show the ' +
+            'old key. ' +
             LIST_EXTRAS_NOTE,
         example: LIST_ATTRIBUTE_WITH_EXTRAS,
+        silentNoOp: 'This is the one route that does NOT check locale keying: a flat "validators", ' +
+            '"localizeInfos", "listTitles" or "additionalFields" answers 200 and is stored where no ' +
+            'consumer reads it, so a field you meant to make required is simply not enforced. Create ' +
+            'and update of the set answer 400 for the same body. Wrapping the body as ' +
+            '{ "schema": … } is worse and equally quiet: it answers 200 and replaces the set with a ' +
+            'single attribute called "schema". Read the set back after every schema replace.',
         verifyWith: {
             opId: 'AdminAttributesSetsController_findOne',
             check: 'schema[].validators.<locale>',
@@ -120,13 +129,20 @@ export const OPERATION_NOTES = {
             '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.',
+            'no "alt" and no "title", but the attribute slot you write it into keeps whatever keys ' +
+            'you add: send "alt" and "title" beside the upload\'s own fields and they come back from ' +
+            'the public read. Use exactly those two names — the admin panel offers the same pair on ' +
+            'an image attribute value and writes them into the same slot, so text set either way ' +
+            'survives an edit made the other way.',
     },
     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.',
+        note: 'A create may carry pagesIds. The ids are checked before anything is written: one that ' +
+            'does not exist answers 404 naming it and no menu is created, so a typo costs nothing to ' +
+            'clean up. What the create does NOT do is nest anything — pagesIds is a flat set wherever ' +
+            'it appears, and the pages arrive as siblings at the top level whatever their relationship ' +
+            'in the page tree. Creating the menu empty and attaching with ' +
+            'AdminMenusController_update is equally valid and the better shape when you are building ' +
+            'the tree level by level.',
     },
     AdminMenusController_update: {
         note: '"pagesIds" is a flat set of page ids and nothing else: nesting is NOT taken from the ' +
@@ -145,46 +161,52 @@ export const OPERATION_NOTES = {
     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.',
+            'placeholder target such as "#". The create body takes localizeInfos and value only: the ' +
+            'item arrives at the top level and is nested afterwards with ' +
+            'AdminMenusController_updateCustomItemPosition. Custom items and page items are numbered ' +
+            'separately, so the same number can name one of each — which is why a parent is addressed ' +
+            'by kind as well as number. Reads return "parentType" beside "parentId", and a public read ' +
+            'also returns "itemType" for the item itself, which is the value its children have to send.',
         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',
+            check: 'the parent of the item, its parentType, and where it appears in the tree',
+            why: 'a parent resolved to the other kind puts the item under a plausible wrong branch',
         },
     },
     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.',
+        example: {
+            position: { leftObjectId: null, rightObjectId: null },
+            newParentId: 12,
+            newParentType: 'custom',
+        },
+        note: '"position" is required even when the order does not matter, and it must be an object: a ' +
+            'body without it answers 400 naming the field, and an empty object is not enough — send ' +
+            '{ leftObjectId: null, rightObjectId: null }. Both re-parenting and sibling order apply, ' +
+            'and a public read returns the items in that order. Neighbours are addressed by the id of ' +
+            'the item, not of its position, and page items and custom items are numbered separately: ' +
+            'in a mixed row name each neighbour with "leftObjectType" and "rightObjectType", or a ' +
+            'neighbour of the other kind is not found and the item lands at the edge of the list. ' +
+            '"newParentType" says which kind the new parent is; omit it and the number is looked up ' +
+            'among pages first, which is not necessarily the parent you meant.',
         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',
+            check: 'the parent of the item you moved, its parentType, and the order of its siblings',
+            why: 'a neighbour or parent resolved to the other kind answers success and moves it elsewhere',
         },
     },
     AdminMenusController_updateCustomItemPosition: {
-        example: { position: { leftObjectId: null, rightObjectId: null }, newParentId: 12 },
+        example: {
+            position: { leftObjectId: null, rightObjectId: null },
+            newParentId: 12,
+            newParentType: 'custom',
+        },
         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.',
+            'object — { leftObjectId: null, rightObjectId: null } when the order does not matter — and ' +
+            'the kind of every neighbour and of the new parent is named alongside its number.',
         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',
+            check: 'the parent of the item you moved, its parentType, and the order of its siblings',
+            why: 'a neighbour or parent resolved to the other kind answers success and moves it elsewhere',
         },
     },
     AdminFormsController_create: {
@@ -257,10 +279,10 @@ 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. 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.',
+            'back unchanged unless you mean to re-parent it. "position" is safe to echo back: a ' +
+            'listing returns it as a lexorank string, and this operation accepts that string and ' +
+            'ignores it, so a read-modify-write body no longer has to be stripped of the field. It ' +
+            'also does not reorder anything — the page position operation is what changes order.',
         verifyWith: {
             opId: 'AdminPagesController_findOne',
             check: 'parentId',
@@ -286,25 +308,24 @@ export const OPERATION_NOTES = {
             '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.',
+            'and discounts. A moduleId outside those six answers 400 and the message names every ' +
+            'module that is accepted; the same check runs on update, so an event cannot be moved onto ' +
+            'an unsupported one either. There is no content module among them, so "notify when this ' +
+            'page changes" is not an events task: say so rather than looking for a body that gets ' +
+            'through. Whether an event that fired actually reached anyone is a separate read — ' +
+            'AdminEventsController_findEmailLogs.',
         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',
+            why: 'a name sent only as "name" is stored and never displayed, and the create still answers 201',
         },
     },
     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.',
+            'catalog, forms, orders, users, payments and discounts; any other moduleId answers 400, ' +
+            'checked against the merged result so a partial update cannot slip past it.',
         example: {
             localizeInfos: {
                 en_US: {
@@ -337,28 +358,29 @@ export const OPERATION_NOTES = {
         },
     },
     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.',
+        note: '"isReusable" is accepted in the body, and the default when you omit it is TRUE for this ' +
+            'operation — one code, valid for everyone, any number of times. That default is the ' +
+            'opposite of the one AdminDiscountsController_generateCouponsByMask applies, so on a ' +
+            '"first order" discount the field decides whether one customer gets the discount or ' +
+            'everyone does, permanently. State the reuse you mean rather than relying on either ' +
+            'default.',
         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',
+            why: 'an omitted field takes a default that differs between the two ways of making a coupon',
         },
     },
     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.',
+        note: '"isReusable" is accepted in the body here too, and the default when you omit it is ' +
+            'FALSE — each generated code stops working after the order that used it. Send the field ' +
+            'explicitly when the reuse matters; the two coupon operations disagree only in what an ' +
+            'omitted value means.',
     },
     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.',
+            'it. A product status can be set here with "statusId", or for many products in one call ' +
+            'with AdminProductsController_setStatusForProducts.',
     },
     AdminBlocksController_update: {
         note: 'Omitting blockPages detaches the block from every page it was on. Read the block first ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneentry/mcp-platform-server",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "MCP server that lets an AI agent operate the OneEntry Admin API, grounded in the project's own rules",
   "license": "MIT",
   "type": "module",