@oneentry/mcp-platform-server 0.1.10 → 0.1.12

package/dist/api/operation-notes.js

@@ -48,7 +48,12 @@ const LIST_EXTRAS_NOTE = 'The curated example is ONE attribute as it appears in
     '"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.';
+    'the product. The form read by marker now returns "multiselect" too, beside listTitles, ' +
+    'validators and settings, so a site can tell a multi-select field from a single-select one. ' +
+    'The VALUE an entity stores for such an attribute is an array of option objects, ' +
+    '[{ "value": "<optionId>", "title": "<label>" }] — a bare string or a list of strings ' +
+    'answers 400, but ONLY when the attribute key is named list_id<id>; under any other key the ' +
+    'malformed value is accepted with 200. A radioButton value is the bare option-id string.';
 export const OPERATION_NOTES = {
     AdminProductsController_findAll: {
         readOnly: true,
@@ -185,38 +190,63 @@ export const OPERATION_NOTES = {
     },
     AdminMenusController_updatePosition: {
         example: {
-            position: { leftObjectId: null, rightObjectId: null },
+            position: {
+                leftObjectId: 459,
+                leftObjectType: 'menu-custom-item',
+                rightObjectId: 4,
+                rightObjectType: 'menu-page',
+            },
             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.',
+            'and a public read returns the items in that order — the order is reproducible, for a row ' +
+            'of pages and for a mixed row alike. Neighbours are addressed by the id of the item, not ' +
+            'of its position, and page items and custom items are numbered separately, so in a mixed ' +
+            'row each neighbour is named with its kind. The body then carries TWO different ' +
+            'vocabularies for "kind", and that is where this operation is lost: ' +
+            '"leftObjectType" / "rightObjectType" take the object type of the position record — ' +
+            '"menu-page" or "menu-custom-item" — while "newParentType" takes "page" or "custom". ' +
+            'Sending "page" or "custom" as a neighbour kind is not refused: the neighbour is not ' +
+            'resolved, the moved item\'s rank is reset to the middle of the range and the answer is ' +
+            'still 200, so the resulting order can look intended and be arbitrary. Omit the neighbour ' +
+            'kinds only in a row of one kind — then each neighbour is read as the kind of the item ' +
+            'being moved. Omit "newParentType" and the number is looked up among pages first, which ' +
+            'is not necessarily the parent you meant. Omitting "position" while changing the parent ' +
+            'leaves the order alone.',
         verifyWith: {
             opId: 'AdminMenusController_findOne',
-            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',
+            check: 'the lexorank of the item you moved against its two neighbours\', and its parent ' +
+                'and parentType',
+            why: 'an unresolved neighbour answers 200 and resets the rank to the middle of the range, ' +
+                'which the order alone can still show as the one you asked for',
         },
     },
     AdminMenusController_updateCustomItemPosition: {
         example: {
-            position: { leftObjectId: null, rightObjectId: null },
+            position: {
+                leftObjectId: 3,
+                leftObjectType: 'menu-page',
+                rightObjectId: 4,
+                rightObjectType: 'menu-page',
+            },
             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 — and ' +
-            'the kind of every neighbour and of the new parent is named alongside its number.',
+            'the kind of every neighbour and of the new parent is named alongside its number, in the ' +
+            'two vocabularies that body uses: "menu-page" / "menu-custom-item" for a neighbour, ' +
+            '"page" / "custom" for the new parent. A custom item does move in among pages this way; ' +
+            'a neighbour kind the instance does not know is not refused but resets the rank.',
         verifyWith: {
             opId: 'AdminMenusController_findOne',
-            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',
+            check: 'the lexorank of the item you moved against its two neighbours\', and its parent ' +
+                'and parentType',
+            why: 'an unresolved neighbour answers 200 and resets the rank to the middle of the range, ' +
+                'which the order alone can still show as the one you asked for',
         },
     },
     AdminFormsController_create: {
@@ -288,16 +318,32 @@ export const OPERATION_NOTES = {
             'attribute of type text uses (htmlValue, mdValue, plainValue, params) are each ' +
             'rejected, the last two with a message that names no field. 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.',
+            'form is invalid with "Form must have a rating marker". The one-rating-per-entity rule ' +
+            'counts only submissions that CARRY A SCORE: a second scored submission answers 400 "You ' +
+            'have already rated this entity", while a scoreless one — a shop reply, a helpfulness ' +
+            'note — is accepted against an entity that is already rated, and naming the review in ' +
+            '"replayTo" stores it as that review\'s child (the extended read returns parentId and ' +
+            'depth 1). A bulk import of scored visitor reviews still needs one fingerprint per ' +
+            'review and has to use the visitor route, which this server does not call.',
         verifyWith: {
             opId: 'AdminFormDataController_findByFormMarker',
             check: 'the submission you sent',
             why: 'the stored submission is the only proof the binding it names is the intended one',
         },
     },
+    AdminFormDataController_update: {
+        note: 'A submission of a rating form is updatable — this used to answer 404 "Form has incorrect ' +
+            'type rating". The update rewrites the submission\'s content only: the original author ' +
+            '(userIdentifier, isUserAdmin) and the fingerprint the one-rating-per-entity rule keys on ' +
+            'are both preserved, so correcting a review neither reassigns it to whoever edited it nor ' +
+            'frees that visitor to score the entity a second time. The types still refused here are ' +
+            'order, sign_in_up and collection.',
+        verifyWith: {
+            opId: 'AdminFormDataController_findByFormMarker',
+            check: 'userIdentifier and the values you changed, with isExtended',
+            why: 'the point of the operation is that the author survives it, and only the read shows that',
+        },
+    },
     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 ' +
@@ -335,7 +381,16 @@ export const OPERATION_NOTES = {
             '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.',
+            'AdminEventsController_findEmailLogs. For an event on the forms module (moduleId 2), ' +
+            '"formType" is an enum — registration | send_code | change_password | submit_data — and ' +
+            'anything else answers 400 "formType must be a valid enum value", a message that does NOT ' +
+            'list the four. "forms.emails" is what decides where the mail goes: a list of objects, ' +
+            'each either { "attr": "<form field marker>" } to take the address from the submission or ' +
+            '{ "plain": "<address>" } for a fixed one. While it is empty the event looks fully ' +
+            'configured and sends nothing, leaving a "skipped" row reading no-recipient-configured. ' +
+            '"forms.mode" is any_data | reply | status, "forms.status" applies when mode is status, ' +
+            '"formIdentifier" binds the event to a form, and "formEmailFieldIdentifier" is legacy and ' +
+            'is not read. Every event bound to a form fires, so a duplicate doubles the mail.',
         verifyWith: {
             opId: 'AdminEventsController_findOne',
             check: 'moduleId and localizeInfos.<locale>.title',
@@ -347,7 +402,10 @@ export const OPERATION_NOTES = {
             '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 answers 400, ' +
-            'checked against the merged result so a partial update cannot slip past it.',
+            'checked against the merged result so a partial update cannot slip past it. On a forms ' +
+            'event the recipient lives in "forms.emails" — entries of { "attr": "<marker>" } or ' +
+            '{ "plain": "<address>" } — and "formType" is the enum registration | send_code | ' +
+            'change_password | submit_data. See AdminEventsController_create for the whole shape.',
         example: {
             localizeInfos: {
                 en_US: {
@@ -404,6 +462,29 @@ export const OPERATION_NOTES = {
             'it. A product status can be set here with "statusId", or for many products in one call ' +
             'with AdminProductsController_setStatusForProducts.',
     },
+    AdminUsersController_update: {
+        note: 'groupIds is a full replacement: send every group the user should end up in, [] to clear ' +
+            'them, or omit the field to leave membership alone. formData and notificationData are ' +
+            'written from whatever the body carries, so omitting them replaces them with empty ' +
+            'values — read the user first and echo them back. One attribute of the sign-in form ' +
+            'carries the flag isLogin, and its value is not an ordinary profile field: it is the ' +
+            'credential the person signs in with, so writing it here moves the credential too. No ' +
+            'form is named for that — the form of the user\'s own sign-in provider is used. A value ' +
+            'counts as a change only when it differs from what the profile already holds under that ' +
+            'marker, so echoing the field back untouched is never refused. A real change answers 400 ' +
+            'when the value is blank, when another user already has it (removed users included), ' +
+            'when the body carries the marker under several locales with different values, or when ' +
+            'the account came from a social network, where the credential belongs to the network. ' +
+            'Every one of those refusals happens before the first write, so neither the profile nor ' +
+            'group membership changes even when the same call also sends groupIds. The value is ' +
+            'stored exactly as sent rather than escaped.',
+        verifyWith: {
+            opId: 'AdminUsersController_findOne',
+            check: 'groupIds and the sign-in field in formData',
+            why: 'an omitted groupIds or formData is applied as "leave alone" and "clear" respectively, ' +
+                'and a sign-in value that was refused leaves the whole call unapplied',
+        },
+    },
     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.',
@@ -427,7 +508,21 @@ export const OPERATION_NOTES = {
     AdminProductsController_countByCategoryMarker: { readOnly: true },
     AdminUsersController_findAllByConditions: { readOnly: true },
     AdminUsersController_search: { readOnly: true },
-    AdminFormDataController_findByFormMarker: { readOnly: true },
+    AdminFormDataController_findByFormMarker: {
+        readOnly: true,
+        note: 'The only listing of submissions: the flat route answers 405, and there is no GET form of ' +
+            'this one either, because the filter travels in the body. Two filters narrow it and they ' +
+            'are not interchangeable. entityIdentifier picks one entity — send the same value the ' +
+            'submission was made with as moduleEntityIdentifier (a page identifier, a product id, a ' +
+            'login for a user or an admin); an integer value is matched against the entity id as ' +
+            'well, so an id taken from a listing keeps working. formModuleConfigId narrows to one ' +
+            'module binding and cannot separate the entities of one form, because a form has a single ' +
+            'config per module; a config id belonging to another form returns no rows, so an empty ' +
+            'answer there means the id is foreign rather than that nothing was submitted. The rest of ' +
+            'the filter body is parentId (null for root-level entries, and a non-integer answers 400), ' +
+            'dateFrom, dateTo, status, userIdentifier and isAdmin. Both listing modes already return ' +
+            'entityIdentifier, entityId and formModuleConfigId; isExtended adds the comment fields.',
+    },
     AdminBlocksController_findCartComplementProductsByBody: { readOnly: true },
     AdminBlocksController_findCartSimilarProductsByBody: { readOnly: true },
     AdminBlocksController_findWishlistSimilarProductsByBody: { readOnly: true },

package/package.json

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