@solumflow-app/crm-mcp-server 0.6.0 → 0.8.0

package/dist/index.js

@@ -6,7 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { createClient } from "@solumflow-app/crm-client";
 
 // package.json
-var version = "0.6.0";
+var version = "0.8.0";
 
 // src/catalog-migration-tools.ts
 import { z as z4 } from "zod";
@@ -38,6 +38,11 @@ var CatalogFieldSlugSchema = z.string().max(63).regex(FIELD_SLUG, {
   )
 });
 var cents = z.number().int().min(0).max(MAX_AMOUNT_CENTS);
+var CatalogCategoryPlacementSchema = z.object({
+  slug: CatalogWebSlugSchema,
+  /** Lowest first; equal places stand in id order. */
+  position: z.number().int().min(-1e6).max(1e6).optional()
+}).strict();
 var text = (max) => z.string().trim().max(max).nullable().optional();
 var CatalogPriceSchema = z.object({
   /** The price's own id at the source, so a renamed price stays itself. */
@@ -199,8 +204,13 @@ var CatalogProductUpsertSchema = z.object({
   socialTitle: text(300),
   socialDescription: text(1e3),
   socialImage: CatalogFileRefSchema.nullable().optional(),
-  /** Replaces the product's categories, by slug. */
-  categories: z.array(CatalogWebSlugSchema).max(50).optional(),
+  /**
+   * Replaces the product's categories, by slug, the first one leading. An
+   * entry may be `{ slug, position }` instead, to also set where the
+   * product stands on that category's page (`?sort=position`, lowest
+   * first); a plain slug leaves a stored place as it is.
+   */
+  categories: z.array(z.union([CatalogWebSlugSchema, CatalogCategoryPlacementSchema])).max(50).optional(),
   /**
    * Make a category that does not exist yet instead of refusing. Off unless
    * asked for, so a typo cannot become a category on a customer's website.
@@ -499,6 +509,13 @@ function more(nextCursor) {
 function money(cents2, currency2) {
   return `${(cents2 / 100).toFixed(2)} ${currency2.toUpperCase()}`;
 }
+function fieldsNotOnPageNote(slugs) {
+  if (!slugs?.length) {
+    return "";
+  }
+  const count = slugs.length === 1 ? "1 public field has" : `${slugs.length} public fields have`;
+  return ` ${count} a value but ${slugs.length === 1 ? "is" : "are"} not on this product's page: ${slugs.join(", ")}; send them in publicFields to show them.`;
+}
 
 // src/catalog-tools.ts
 var objectInput = {
@@ -589,7 +606,7 @@ function registerCatalogTools(server, client) {
     "get_product",
     {
       title: "Read one product",
-      description: "One product as its page needs it: name, prices, pictures, categories, variants and `fields`, keyed by field slug. Published products only unless you pass `status` (needs catalog:write), and a published one may be a minute old: to read back exactly what you just wrote, use get_product_by_ref. Answers that it is not found for an unknown product, or one not in the status asked. " + CONTENT_BLOCKS,
+      description: "One product as its page needs it: name, prices, pictures, categories, variants and `fields`, keyed by field slug. Published products only unless you pass `status` (needs a server key), and a published one may be a minute old: to read back exactly what you just wrote, use get_product_by_ref. Answers that it is not found for an unknown product, or one not in the status asked. " + CONTENT_BLOCKS,
       inputSchema: { slugOrId, currency, status: productStatus },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
@@ -619,7 +636,7 @@ function registerCatalogTools(server, client) {
     "list_products",
     {
       title: "List the products",
-      description: "One page of the catalogue: name, address (slug), lowest price, whether it is in stock, its first picture and the public fields a listing shows. Narrow it to one category\u2019s whole branch by its id or address, or by the reference upsert_category recorded (`categorySource` + `categoryRef`), to one catalogue by the slug of its object, or to the product carrying an article number (`sku`). Read get_product for everything a product page needs. Published products only, and may be a minute old; `status` lists concepts, scheduled and archived ones too (needs catalog:write).",
+      description: "One page of the catalogue: name, address (slug), lowest price, whether it is in stock, its first picture and the public fields a listing shows. Narrow it to one category\u2019s whole branch by its id or address, or by the reference upsert_category recorded (`categorySource` + `categoryRef`), to one catalogue by the slug of its object, or to the product carrying an article number (`sku`). Read get_product for everything a product page needs. Published products only, and may be a minute old; `status` lists concepts, scheduled and archived ones too (needs a server key). `sort` orders the published ones: -publishedAt (newest first, the default), publishedAt, name, or position -- the seller\u2019s own order on the page of `category`, which it needs. Each item carries `sku`, `publishedAt` and `stockQuantity` (null when not counted).",
       inputSchema: {
         ...page,
         category: z3.string().regex(
@@ -636,7 +653,10 @@ function registerCatalogTools(server, client) {
           'One catalogue, by the slug of its object, such as "product".'
         ),
         currency,
-        status: productStatus
+        status: productStatus,
+        sort: z3.enum(["-publishedAt", "publishedAt", "name", "position"]).optional().describe(
+          "The order: newest first by default; position needs `category`."
+        )
       },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
@@ -664,7 +684,7 @@ function registerCatalogTools(server, client) {
     "list_categories",
     {
       title: "List the categories",
-      description: 'The categories of the catalogue, each with its path from the top and how many products are in it. Left without `parent`, every category comes back, which is what building a menu in one go needs; "root" asks for the top level, a category id for its children. Published categories only unless you pass `status` (draft or all, needs catalog:write).',
+      description: 'The categories of the catalogue, each with its path from the top and how many products are in it. Left without `parent`, every category comes back, which is what building a menu in one go needs; "root" asks for the top level, a category id for its children. Published categories only unless you pass `status` (draft or all, needs a server key).',
       inputSchema: {
         ...page,
         parent: z3.union([z3.literal("root"), z3.string().uuid()]).optional().describe('"root" or the id of a category.'),
@@ -688,7 +708,7 @@ function registerCatalogTools(server, client) {
     "get_category",
     {
       title: "Read one category page",
-      description: "One category as its page needs it: name, description, the texts for search engines and social media, and the first page of its products. Pass the nextCursor back to page through the products. A category that is not on the website yet needs `status` (draft or all, catalog:write); its products are the published ones.",
+      description: "One category as its page needs it: name, description, the texts for search engines and social media, and the first page of its products. Pass the nextCursor back to page through the products. A category that is not on the website yet needs `status` (draft or all, a server key); its products are the published ones.",
       inputSchema: {
         slugOrId: z3.string().min(1).max(200).describe("The address (slug) or the id of the category."),
         ...page,
@@ -852,7 +872,7 @@ function registerCatalogMigrationTools(server, client) {
           (file) => file.status === "pending"
         );
         return answer(
-          `${product.name} (${product.slug || "no address"}), ${product.status} (${product.availability}); ${Object.keys(product.fields).length} fields, ${product.categories.length} categories, ${product.images.length} pictures; files: ${pending.length} pending, ${refused.length} refused${refused.length ? ` (${refused.map((file) => `${file.ref}: ${file.reason}`).join("; ")})` : ""}.`,
+          `${product.name} (${product.slug || "no address"}), ${product.status} (${product.availability}); ${Object.keys(product.fields).length} fields, ${product.categories.length} categories, ${product.images.length} pictures; files: ${pending.length} pending, ${refused.length} refused${refused.length ? ` (${refused.map((file) => `${file.ref}: ${file.reason}`).join("; ")})` : ""}.` + fieldsNotOnPageNote(product.fieldsNotOnPage),
           product
         );
       } catch (error) {
@@ -886,12 +906,15 @@ function registerCatalogMigrationTools(server, client) {
           target(object2)
         );
         const count = (kind) => outcomes.filter((outcome) => outcome.outcome === kind).length;
+        const offPage = new Set(
+          outcomes.flatMap((outcome) => outcome.product?.fieldsNotOnPage ?? [])
+        );
         const refusals = outcomes.filter((outcome) => outcome.outcome === "refused").map(
           (outcome) => `- ${outcome.externalRef}: ${outcome.error?.message ?? "refused"}` + (outcome.error?.fields.length ? ` (${outcome.error.fields.map((field) => `${field.path}: ${field.message}`).join("; ")})` : "")
         );
         return answer(
           [
-            `${count("created")} made, ${count("changed")} changed, ${count("refused")} refused, ${count("skipped")} skipped.`,
+            `${count("created")} made, ${count("changed")} changed, ${count("refused")} refused, ${count("skipped")} skipped.` + (offPage.size ? ` Some products hold public fields that are not on their page (${[...offPage].join(", ")}); send them in publicFields to show them.` : ""),
             ...refusals
           ].join("\n"),
           outcomes
@@ -949,7 +972,7 @@ function registerCatalogMigrationTools(server, client) {
     "get_category_by_ref",
     {
       title: "Find a category by its reference",
-      description: 'The category upsert_category recorded with this `source` and `externalRef` -- the id of a series in your own system -- also after its address was changed in the app. A published category unless you pass `status`: "draft" finds a concept or scheduled one, "all" any (needs catalog:write).',
+      description: 'The category upsert_category recorded with this `source` and `externalRef` -- the id of a series in your own system -- also after its address was changed in the app. A published category unless you pass `status`: "draft" finds a concept or scheduled one, "all" any (needs a server key).',
       inputSchema: {
         source: CatalogSourceSchema,
         externalRef: CatalogExternalRefSchema,
@@ -1061,7 +1084,7 @@ function registerCatalogWriteTools(server, client) {
         );
         const verb = product.created ? "Made" : "Changed";
         return answer(
-          `${verb} ${product.name} (${product.slug ?? "no address"}), ${product.availability}; ${product.variants.length} variants; pictures ${product.images}.`,
+          `${verb} ${product.name} (${product.slug ?? "no address"}), ${product.availability}; ${product.variants.length} variants; pictures ${product.images}.` + fieldsNotOnPageNote(product.fieldsNotOnPage),
           product
         );
       } catch (error) {