@sixtyninecommerce/admin 0.11.0 → 0.13.0

package/dist/catalog/metadata.js

@@ -0,0 +1,220 @@
+/**
+ * A product's SEO, social and AI-agent metadata (headless spec §9.2 `catalog`: "metadata";
+ * W10-10): what the storefront puts in a product page's `<head>`, its share cards and its
+ * structured data. One record per product and store; its texts are per language.
+ *
+ * - **Partial writes.** `upsert` changes only the fields it names. A translation is written per
+ *   language: a language not sent keeps its values, and a field not sent in a sent language keeps
+ *   its value (send `null` to clear one).
+ * - **Coverage.** `coverage` lists the store's products with their own meta title and description
+ *   in one language, optionally only those missing one, filtered by the engine BEFORE the page is
+ *   cut: every page is full and `totalItems` counts the filter.
+ * - **Bulk.** `bulkUpsert` writes many products, each through `upsert`'s rules in a transaction
+ *   of its own and reported on its own (ruling G117).
+ *
+ * Every record is the store's own: a product of another store is never answered and never
+ * written.
+ *
+ * Permissions: `get` and `coverage` need `ReadCatalog`, the writes `UpdateCatalog`.
+ *
+ * Refusals, GraphQL errors mapped by `core`:
+ * - `PRODUCT_METADATA_INPUT_INVALID` → `ValidationError` (400): an input that breaks a rule (a
+ *   length, an allowed value, an `https://` URL, an instant without an offset, a language sent
+ *   twice). `details` names each failure (`field` an RFC 6901 pointer such as
+ *   `/input/translations/0/seoTitle`, `code` the rule such as `INVALID_FIELD_LENGTH`). Nothing is
+ *   written.
+ * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): `upsert` of a product the store does not hold.
+ * - `TRANSLATION_LANGUAGE_NOT_OFFERED` → `ValidationError` (400): a new translation in a language
+ *   the store does not offer.
+ * - `BULK_ACTION_INPUT_INVALID` → `ValidationError` (400): a `bulkUpsert` of no product, more than
+ *   {@link MAX_BULK_METADATA_EDITS} or one product twice, refused before anything is sent.
+ * - `INVALID_DATETIME` → `ValidationError` (400): `metaRobotsUnavailableAfter` without an offset,
+ *   refused before anything is sent.
+ * - `FORBIDDEN` → `PermissionDeniedError` (403) without the permission.
+ *
+ * Release: `coverage` and `bulkUpsert` need a platform release with `productMetadataCoverage` and
+ * `bulkUpsertProductMetadata` (deploy vendure-server first: an older one refuses the document as
+ * `GRAPHQL_VALIDATION_FAILED`); on such a release `upsert` also answers a validation failure as an
+ * uncoded `INTERNAL_SERVER_ERROR` and writes a row for a product the store does not hold. `get`
+ * and `delete` are served by every release this SDK supports. No method deduplicates on
+ * `idempotencyKey`; every write is naturally repeatable.
+ */
+import { NotFoundError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+import { assertDeleted, assertInstant, DELETION_FIELDS, fieldOf, vendureListPage, } from './types.js';
+/** How many products one `bulkUpsert` call may name. */
+export const MAX_BULK_METADATA_EDITS = 200;
+const IMAGE_FIELDS = /* GraphQL */ `
+  id
+  name
+  preview
+  source
+  type
+  mimeType
+`;
+const METADATA_FIELDS = /* GraphQL */ `
+  id
+  productId
+  channelId
+  metaRobotsIndex
+  metaRobotsFollow
+  metaRobotsNoarchive
+  metaRobotsNosnippet
+  metaRobotsNoimageindex
+  metaRobotsMaxImagePreview
+  metaRobotsMaxSnippet
+  metaRobotsMaxVideoPreview
+  metaRobotsUnavailableAfter
+  socialImageId
+  socialImage { ${IMAGE_FIELDS} }
+  twitterImageOverrideId
+  twitterImageOverride { ${IMAGE_FIELDS} }
+  twitterCardType
+  socialOgType
+  seoIncludeReviewsInJsonld
+  aiSummaryAudience
+  aiBotOverrides
+  qaEmitFaqpageJsonld
+  hreflangOverrides
+  resolvedBotDirectives
+  translations {
+    id
+    languageCode
+    seoTitle
+    seoDescription
+    canonicalUrl
+    breadcrumbOverride
+    focusKeywords
+    socialTitle
+    socialDescription
+    socialImageAlt
+    twitterTitleOverride
+    twitterDescriptionOverride
+    aiSummary
+    qaPairs
+  }
+`;
+export const PRODUCT_METADATA_QUERY = /* GraphQL */ `
+  query CatalogProductMetadata($productId: ID!) {
+    product(id: $productId) {
+      id
+      metadata { ${METADATA_FIELDS} }
+    }
+  }
+`;
+export const UPSERT_PRODUCT_METADATA_MUTATION = /* GraphQL */ `
+  mutation CatalogUpsertProductMetadata($productId: ID!, $input: ProductMetadataInput!) {
+    upsertProductMetadata(productId: $productId, input: $input) { ${METADATA_FIELDS} }
+  }
+`;
+export const DELETE_PRODUCT_METADATA_MUTATION = /* GraphQL */ `
+  mutation CatalogDeleteProductMetadata($productId: ID!) {
+    deleteProductMetadata(productId: $productId) { ${DELETION_FIELDS} }
+  }
+`;
+export const PRODUCT_METADATA_COVERAGE_QUERY = /* GraphQL */ `
+  query CatalogProductMetadataCoverage(
+    $languageCode: LanguageCode!
+    $filter: ProductMetadataCoverageFilter
+    $term: String
+    $options: ProductMetadataCoverageListOptions
+  ) {
+    productMetadataCoverage(
+      languageCode: $languageCode
+      filter: $filter
+      term: $term
+      options: $options
+    ) {
+      items {
+        productId
+        name
+        slug
+        enabled
+        seoTitle
+        seoDescription
+      }
+      totalItems
+    }
+  }
+`;
+export const BULK_UPSERT_PRODUCT_METADATA_MUTATION = /* GraphQL */ `
+  mutation CatalogBulkUpsertProductMetadata($edits: [ProductMetadataBulkEdit!]!) {
+    bulkUpsertProductMetadata(edits: $edits) {
+      items {
+        productId
+        status
+        code
+        message
+      }
+    }
+  }
+`;
+function bulkInvalid(message) {
+    return new ValidationError({
+        code: 'BULK_ACTION_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+/** The edits as sent, refused before the request leaves when the engine would refuse them. */
+function bulkEdits(edits) {
+    if (!Array.isArray(edits))
+        throw bulkInvalid('edits must be a list.');
+    if (edits.length === 0)
+        throw bulkInvalid('Name at least one product.');
+    if (edits.length > MAX_BULK_METADATA_EDITS) {
+        throw bulkInvalid(`A bulk upsert takes at most ${String(MAX_BULK_METADATA_EDITS)} products; this one names ${String(edits.length)}.`);
+    }
+    const ids = edits.map((edit) => String(edit.productId).toLowerCase());
+    if (new Set(ids).size !== ids.length)
+        throw bulkInvalid('Name each product once.');
+    for (const edit of edits) {
+        assertInstant('metaRobotsUnavailableAfter', edit.input.metaRobotsUnavailableAfter);
+    }
+    return edits.map((edit) => ({ productId: edit.productId, input: edit.input }));
+}
+export function createProductMetadataModule(transport) {
+    return {
+        async get(productId, options) {
+            const product = await fieldOf(transport, PRODUCT_METADATA_QUERY, 'product', { productId }, options);
+            if (!product) {
+                throw new NotFoundError({
+                    code: 'PRODUCT_NOT_FOUND',
+                    message: `This store has no product ${productId}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+            return product.metadata;
+        },
+        async upsert(productId, input, options) {
+            assertInstant('metaRobotsUnavailableAfter', input.metaRobotsUnavailableAfter);
+            return fieldOf(transport, UPSERT_PRODUCT_METADATA_MUTATION, 'upsertProductMetadata', { productId, input }, options);
+        },
+        async delete(productId, options) {
+            const response = await fieldOf(transport, DELETE_PRODUCT_METADATA_MUTATION, 'deleteProductMetadata', { productId }, options);
+            assertDeleted('PRODUCT_METADATA_NOT_DELETED', [response]);
+        },
+        async coverage(query) {
+            const { languageCode, filter, term, ...options } = query;
+            return vendureListPage(transport, PRODUCT_METADATA_COVERAGE_QUERY, 'productMetadataCoverage', (skip, take) => ({
+                languageCode,
+                filter: filter ?? 'ALL',
+                ...(term === undefined || term.trim() === '' ? {} : { term }),
+                options: { skip, take },
+            }), options);
+        },
+        async bulkUpsert(edits, options) {
+            const data = await fieldOf(transport, BULK_UPSERT_PRODUCT_METADATA_MUTATION, 'bulkUpsertProductMetadata', { edits: bulkEdits(edits) }, options);
+            if (data === null) {
+                throw new UpstreamError({
+                    code: 'UNEXPECTED_RESPONSE',
+                    message: 'The engine answered bulkUpsertProductMetadata with nothing.',
+                    status: 502,
+                    service: 'vendure',
+                });
+            }
+            return data.items;
+        },
+    };
+}

package/dist/catalog/properties.d.ts

@@ -319,4 +319,42 @@ export declare const SET_PRODUCT_PROPERTY_VALUES_MUTATION = "\n  mutation Catalo
 export declare const SYNC_PROPERTY_FACETS_MUTATION = "\n  mutation CatalogSyncPropertyFacets($propertyId: ID!) {\n    syncPropertyFacets(propertyId: $propertyId) {\n      propertyId\n      items\n      unresolved\n      fieldFacets\n    }\n  }\n";
 /** `catalog.syncContentFacets`; its contract is on {@link CatalogModule.syncContentFacets}. */
 export declare function syncContentFacets(transport: Transport, propertyId: string, options?: Call): Promise<ContentFacetSyncResult>;
+/**
+ * The most different content item ids one {@link CatalogModule.syncContentItemFacets} call takes
+ * (the engine's own bound); repeats count once.
+ */
+export declare const MAX_CONTENT_ITEM_FACET_SYNC_IDS = 500;
+/** A property {@link CatalogModule.syncContentItemFacets} did not sync, and why. */
+export interface ContentItemFacetSyncSkip {
+    propertyId: string;
+    /**
+     * The refusal the property's own sync gave: `MANAGED_BY_ORGANIZATION` for a property of the
+     * store's organization workspace (it is synced in the workspace), or any refusal
+     * {@link CatalogModule.syncContentFacets} documents.
+     */
+    code: string;
+    /** The refusal's sentence, as the engine words it. */
+    message: string;
+}
+/** What {@link CatalogModule.syncContentItemFacets} did. */
+export interface ContentItemFacetSyncResult {
+    /**
+     * Each filterable `content_item` property of the store whose values name at least one of the
+     * items, synced as {@link CatalogModule.syncContentFacets} syncs it.
+     */
+    synced: ContentFacetSyncResult[];
+    /** Each such property that was refused; nothing of it was written, the others were synced. */
+    skipped: ContentItemFacetSyncSkip[];
+    /**
+     * Whether the call wrote anything: a filter value created, renamed or removed, or a product's
+     * filter assignments changed. False on a repeat that found everything in line.
+     */
+    changed: boolean;
+}
+export declare const SYNC_CONTENT_ITEM_FACETS_MUTATION = "\n  mutation CatalogSyncContentItemFacets($contentItemIds: [ID!]!) {\n    syncContentItemFacets(contentItemIds: $contentItemIds) {\n      synced {\n        propertyId\n        items\n        unresolved\n        fieldFacets\n      }\n      skipped {\n        propertyId\n        code\n        message\n      }\n      changed\n    }\n  }\n";
+/**
+ * `catalog.syncContentItemFacets`; its contract is on
+ * {@link CatalogModule.syncContentItemFacets}. The engine's own id checks run before sending.
+ */
+export declare function syncContentItemFacets(transport: Transport, contentItemIds: readonly string[], options?: Call): Promise<ContentItemFacetSyncResult>;
 export declare function createPropertiesModule(transport: Transport): PropertiesModule;

package/dist/catalog/properties.js

@@ -1,4 +1,4 @@
-import { createPage } from '@sixtyninecommerce/core';
+import { createPage, ValidationError } from '@sixtyninecommerce/core';
 import { assertDeleted, DELETION_FIELDS, fieldOf, } from './types.js';
 const PROPERTY_FIELDS = /* GraphQL */ `
   id
@@ -134,6 +134,57 @@ export const SYNC_PROPERTY_FACETS_MUTATION = /* GraphQL */ `
 export function syncContentFacets(transport, propertyId, options) {
     return fieldOf(transport, SYNC_PROPERTY_FACETS_MUTATION, 'syncPropertyFacets', { propertyId }, options);
 }
+/**
+ * The most different content item ids one {@link CatalogModule.syncContentItemFacets} call takes
+ * (the engine's own bound); repeats count once.
+ */
+export const MAX_CONTENT_ITEM_FACET_SYNC_IDS = 500;
+export const SYNC_CONTENT_ITEM_FACETS_MUTATION = /* GraphQL */ `
+  mutation CatalogSyncContentItemFacets($contentItemIds: [ID!]!) {
+    syncContentItemFacets(contentItemIds: $contentItemIds) {
+      synced {
+        propertyId
+        items
+        unresolved
+        fieldFacets
+      }
+      skipped {
+        propertyId
+        code
+        message
+      }
+      changed
+    }
+  }
+`;
+function refuseContentItemIds(message) {
+    return new ValidationError({
+        code: 'CONTENT_ITEM_IDS_INVALID',
+        message: `${message} Nothing was sent.`,
+        status: 400,
+        service: 'vendure',
+    });
+}
+/**
+ * `catalog.syncContentItemFacets`; its contract is on
+ * {@link CatalogModule.syncContentItemFacets}. The engine's own id checks run before sending.
+ */
+export function syncContentItemFacets(transport, contentItemIds, options) {
+    if (!Array.isArray(contentItemIds)) {
+        return Promise.reject(refuseContentItemIds('Send the content item ids as a list.'));
+    }
+    const distinct = new Set();
+    for (const id of contentItemIds) {
+        if (typeof id !== 'string' || id.trim() === '') {
+            return Promise.reject(refuseContentItemIds('A content item id is blank.'));
+        }
+        distinct.add(id.trim().toLowerCase());
+    }
+    if (distinct.size > MAX_CONTENT_ITEM_FACET_SYNC_IDS) {
+        return Promise.reject(refuseContentItemIds(`Send at most ${String(MAX_CONTENT_ITEM_FACET_SYNC_IDS)} different content item ids per call; this one named ${String(distinct.size)}. Split them into several calls.`));
+    }
+    return fieldOf(transport, SYNC_CONTENT_ITEM_FACETS_MUTATION, 'syncContentItemFacets', { contentItemIds: [...contentItemIds] }, options);
+}
 export function createPropertiesModule(transport) {
     const call = (document, field, variables, options) => fieldOf(transport, document, field, variables, options);
     const deleted = async (document, field, code, id, options) => {

package/dist/catalog/recommendations.d.ts

@@ -30,6 +30,11 @@
  *   not hold, each named in the message and in `details` (`field` `/targetProductIds/<index>`).
  * - `RECOMMENDATION_GROUP_SLUG_TAKEN` → `ConflictError` (409): another of the store's groups holds
  *   the slug, also when two writes race for one free slug.
+ * - `RECOMMENDATION_MAX_ITEMS_INVALID` → `ValidationError` (400): a group's `maxItems` that is not
+ *   a whole number from 1 to 50 ({@link RECOMMENDATION_MAX_ITEMS_RANGE}), on `groups.create` and
+ *   on a `groups.update` that sends it, `details[0].field` `/input/maxItems`. This SDK refuses it
+ *   before anything is sent, with the same code and detail, so an older platform release (which
+ *   stores any value) never receives one.
  * - `USER_INPUT_ERROR` → `ValidationError` (400), in the engine's words: a rule that does not fit
  *   its group or its type (a `MANUAL` group, a `sourceId` missing or sent where none goes), picks
  *   in a `DYNAMIC` group.
@@ -47,8 +52,17 @@
  * No release gate: every operation here is served by every platform release this SDK supports.
  * No method deduplicates on `idempotencyKey`: repeating a `create` makes a second row.
  */
-import type { Transport } from '@sixtyninecommerce/core';
+import { type Transport } from '@sixtyninecommerce/core';
 import type { Call } from '../types.js';
+/**
+ * The fewest and the most products a group may show (`maxItems`), both included. The platform
+ * refuses any other value with `RECOMMENDATION_MAX_ITEMS_INVALID`, and so does this SDK before
+ * sending.
+ */
+export declare const RECOMMENDATION_MAX_ITEMS_RANGE: {
+    readonly min: 1;
+    readonly max: 50;
+};
 /** What a `DYNAMIC` group's entry draws its products from. */
 export type RecommendationSourceType = 'PRODUCT' | 'COLLECTION' | 'FACET_VALUE' | 'SAME_COLLECTION' | 'SAME_PROPERTIES';
 /** `DYNAMIC`: rules (entries). `MANUAL`: products picked per viewed product (`manual.set`). */
@@ -82,7 +96,10 @@ export interface RecommendationGroupSummary {
     /** Unique within the store; the storefront asks for one group by it. */
     slug: string;
     description: string | null;
-    /** The most products the storefront shows for this group. */
+    /**
+     * The most products the storefront shows for this group. Written as 1 to 50; a group stored
+     * outside that range before the platform enforced it keeps its value until `maxItems` is sent.
+     */
     maxItems: number;
     position: number;
     enabled: boolean;
@@ -107,7 +124,10 @@ export interface CreateRecommendationGroupInput {
     /** Defaults to the name, lower-cased, every run of other characters than `a-z0-9` a `-`. */
     slug?: string;
     description?: string;
-    /** Defaults to 10. The engine sets no bounds. */
+    /**
+     * Defaults to 10. A whole number from 1 to 50 ({@link RECOMMENDATION_MAX_ITEMS_RANGE}); any
+     * other is refused `RECOMMENDATION_MAX_ITEMS_INVALID` before it is sent.
+     */
     maxItems?: number;
     /** Defaults to after the store's last group. */
     position?: number;
@@ -121,6 +141,11 @@ export interface UpdateRecommendationGroupInput {
     name?: string;
     slug?: string;
     description?: string | null;
+    /**
+     * A whole number from 1 to 50, else refused `RECOMMENDATION_MAX_ITEMS_INVALID` before it is
+     * sent. Left out, the stored value stays (and is not judged, so a group stored outside the
+     * range before the rule can still be renamed, moved or disabled).
+     */
     maxItems?: number;
     position?: number;
     enabled?: boolean;
@@ -155,14 +180,16 @@ export interface RecommendationsModule {
          */
         get(id: string, options?: Call): Promise<RecommendationGroup | null>;
         /**
-         * Refused (`RECOMMENDATION_GROUP_SLUG_TAKEN`) when the store already has a group with that
-         * slug, the defaulted one included.
+         * Refused: a `maxItems` outside 1–50 (`RECOMMENDATION_MAX_ITEMS_INVALID`, before anything is
+         * sent); a slug the store's other group already holds, the defaulted one included
+         * (`RECOMMENDATION_GROUP_SLUG_TAKEN`).
          *
          * @effect write
          */
         create(input: CreateRecommendationGroupInput, options?: Call): Promise<RecommendationGroup>;
         /**
-         * Refused: a group the store does not have (`ENTITY_NOT_FOUND`), a slug another of its groups
+         * Refused: a `maxItems` sent outside 1–50 (`RECOMMENDATION_MAX_ITEMS_INVALID`, before anything
+         * is sent); a group the store does not have (`ENTITY_NOT_FOUND`); a slug another of its groups
          * holds (`RECOMMENDATION_GROUP_SLUG_TAKEN`).
          *
          * @effect write

package/dist/catalog/recommendations.js

@@ -1,4 +1,65 @@
+/**
+ * Product recommendations (headless spec §9.2 `catalog`: "recommendations"; W10-13): the store's
+ * recommendation groups ("Customers also bought", "Complete the look"), what each one draws its
+ * products from, and the products hand-picked per product for a manual group.
+ *
+ * - **A `DYNAMIC` group's entries are its rules**, read in `position` order: one named product
+ *   (`PRODUCT`), the products of a collection (`COLLECTION`) or with a facet value
+ *   (`FACET_VALUE`), or the viewed product's own collections (`SAME_COLLECTION`) or properties
+ *   (`SAME_PROPERTIES`). The storefront fills the group up to `maxItems` from the first entry on,
+ *   never with the viewed product, a disabled product or one the store hides from the shopper.
+ * - **A `MANUAL` group has no entries**: its products are picked per viewed product
+ *   (`manual.set`), and the storefront shows them in the order picked. A group's mode is chosen
+ *   when it is created and never changes.
+ * - **A disabled group** (`enabled: false`) is kept but never shown on the storefront.
+ * - **Positions** are integers; a group or entry created without one goes after the last.
+ *   `reorder` rewrites them as `0, 1, 2…` in the order given.
+ *
+ * Permissions: reads need `ReadCatalog`, writes `UpdateCatalog`. Every row is the store's own: a
+ * group or entry of another store is never answered and never changed (a read answers `null` or
+ * leaves it out; a write refuses it as unknown), and a rule only ever draws from the store's own
+ * products, collections and facet values.
+ *
+ * Refusals, GraphQL errors mapped by `core`. An unknown id and another store's get the same answer,
+ * so none tells whether another store holds the row:
+ * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a group or entry the store does not have, and the
+ *   viewed product of `manual.set` when the store does not hold it.
+ * - `RECOMMENDATION_SOURCE_NOT_FOUND` → `NotFoundError` (404): a rule's `sourceId` that is not a
+ *   product, collection or facet value of the store (`entries.create`, `entries.update`).
+ * - `RECOMMENDATION_TARGET_NOT_FOUND` → `NotFoundError` (404): `manual.set` picks the store does
+ *   not hold, each named in the message and in `details` (`field` `/targetProductIds/<index>`).
+ * - `RECOMMENDATION_GROUP_SLUG_TAKEN` → `ConflictError` (409): another of the store's groups holds
+ *   the slug, also when two writes race for one free slug.
+ * - `RECOMMENDATION_MAX_ITEMS_INVALID` → `ValidationError` (400): a group's `maxItems` that is not
+ *   a whole number from 1 to 50 ({@link RECOMMENDATION_MAX_ITEMS_RANGE}), on `groups.create` and
+ *   on a `groups.update` that sends it, `details[0].field` `/input/maxItems`. This SDK refuses it
+ *   before anything is sent, with the same code and detail, so an older platform release (which
+ *   stores any value) never receives one.
+ * - `USER_INPUT_ERROR` → `ValidationError` (400), in the engine's words: a rule that does not fit
+ *   its group or its type (a `MANUAL` group, a `sourceId` missing or sent where none goes), picks
+ *   in a `DYNAMIC` group.
+ * - `FORBIDDEN` → `PermissionDeniedError` (403) without the permission.
+ *
+ * An id that is not a uuid (any id argument, a `sourceId` and each pick included) is refused
+ * before all of these with core's `ENTITY_NOT_FOUND` (`NotFoundError`, 404, no `details`), so
+ * branch on the class for not-found and on the code only to tell which row is missing.
+ *
+ * A platform release older than these codes answers each not-found and a taken slug as
+ * `USER_INPUT_ERROR` (400) in its own words ("Recommendation group not found"), a slug lost in a
+ * race as `DUPLICATE_RECORD`, and takes another store's collection or facet value as a rule's
+ * source.
+ *
+ * No release gate: every operation here is served by every platform release this SDK supports.
+ * No method deduplicates on `idempotencyKey`: repeating a `create` makes a second row.
+ */
+import { ValidationError } from '@sixtyninecommerce/core';
 import { assertDeleted, DELETION_FIELDS, fieldOf } from './types.js';
+/**
+ * The fewest and the most products a group may show (`maxItems`), both included. The platform
+ * refuses any other value with `RECOMMENDATION_MAX_ITEMS_INVALID`, and so does this SDK before
+ * sending.
+ */
+export const RECOMMENDATION_MAX_ITEMS_RANGE = { min: 1, max: 50 };
 /** The source types whose entry names a row (`sourceId`); the others must name none. */
 export const RECOMMENDATION_SOURCE_TYPES_WITH_ID = [
     'PRODUCT',
@@ -103,6 +164,31 @@ export const SET_PRODUCT_MANUAL_RECOMMENDATIONS_MUTATION = /* GraphQL */ `
     ) { ${GROUP_SUMMARY_FIELDS} }
   }
 `;
+/**
+ * The platform's `maxItems` rule, checked before sending: a value present and not null must be a
+ * whole number in {@link RECOMMENDATION_MAX_ITEMS_RANGE}. Same code, message and detail as the
+ * engine's refusal, so a caller handles one shape whichever side refused.
+ */
+function assertMaxItems(input) {
+    const maxItems = input?.maxItems;
+    if (maxItems == null)
+        return;
+    const { min, max } = RECOMMENDATION_MAX_ITEMS_RANGE;
+    if (typeof maxItems === 'number' &&
+        Number.isInteger(maxItems) &&
+        maxItems >= min &&
+        maxItems <= max) {
+        return;
+    }
+    const message = `Max items must be a whole number from ${min} to ${max}; got ${JSON.stringify(maxItems)}`;
+    throw new ValidationError({
+        code: 'RECOMMENDATION_MAX_ITEMS_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field: '/input/maxItems', code: 'OUT_OF_RANGE', message }],
+    });
+}
 /** Entries in `position` order, the older first on a tie, as the engine's own entry reads sort. */
 function byPosition(entries) {
     return [...entries].sort((a, b) => a.position - b.position || a.createdAt.localeCompare(b.createdAt));
@@ -120,8 +206,14 @@ export function createRecommendationsModule(transport) {
                 const group = await call(RECOMMENDATION_GROUP_QUERY, 'recommendationGroup', { id }, options);
                 return group === null ? null : withSortedEntries(group);
             },
-            create: async (input, options) => withSortedEntries(await call(CREATE_RECOMMENDATION_GROUP_MUTATION, 'createRecommendationGroup', { input }, options)),
-            update: async (id, input, options) => withSortedEntries(await call(UPDATE_RECOMMENDATION_GROUP_MUTATION, 'updateRecommendationGroup', { id, input }, options)),
+            create: async (input, options) => {
+                assertMaxItems(input);
+                return withSortedEntries(await call(CREATE_RECOMMENDATION_GROUP_MUTATION, 'createRecommendationGroup', { input }, options));
+            },
+            update: async (id, input, options) => {
+                assertMaxItems(input);
+                return withSortedEntries(await call(UPDATE_RECOMMENDATION_GROUP_MUTATION, 'updateRecommendationGroup', { id, input }, options));
+            },
             async delete(id, options) {
                 const response = await call(DELETE_RECOMMENDATION_GROUP_MUTATION, 'deleteRecommendationGroup', { id }, options);
                 assertDeleted('RECOMMENDATION_GROUP_NOT_DELETED', [response]);

package/dist/catalog/reviews.d.ts

@@ -21,6 +21,13 @@
  * `CUSTOMER_DATA_NOT_GRANTED` (`PermissionDeniedError`, 403). The answers of the writes are
  * blanked the same way.
  *
+ * Publishing needs `full` (user decision O6): approving a review (`moderate`, or `bulkModerate`
+ * with `APPROVED`) and `reply.set` publish under the store's name next to text a caller below
+ * `full` reads blanked, so an app installation below it (or a request narrowed below it) is
+ * refused them with `CUSTOMER_DATA_NOT_GRANTED` (`PermissionDeniedError`, 403; `bulkModerate`
+ * reports it on each review). It may still reject, flag or re-open a review and remove the
+ * store's reply. A staff session and a personal API token act at `full`.
+ *
  * Permissions: reads need `ReadCatalog`, writes `UpdateCatalog`. Every row is the store's own: a
  * review or attribute of another store is never answered and never changed.
  *
@@ -266,7 +273,9 @@ export interface ReviewsModule {
      * Give one review a status: `APPROVED` publishes it on the storefront; `REJECTED`, `FLAGGED`
      * and `PENDING` take it off. Recorded in its moderation log with `reason`. The product's
      * average rating follows within seconds. Refused (`ENTITY_NOT_FOUND`) for a review the store
-     * does not have.
+     * does not have. `APPROVED` is refused `CUSTOMER_DATA_NOT_GRANTED` (`PermissionDeniedError`) to
+     * a caller below `customerData: full`, whatever the review; the other statuses are open at every
+     * level.
      *
      * @effect write
      */
@@ -277,7 +286,9 @@ export interface ReviewsModule {
      * (`ENTITY_NOT_FOUND`) changes nothing, and the others still go through. A selection of no
      * review, more than {@link MAX_BULK_REVIEWS} or one twice is refused
      * `BULK_ACTION_INPUT_INVALID` (400) before anything is sent. Not keyed: a repeat moderates
-     * again (and logs again). Needs a platform release with `moderateReviews`.
+     * again (and logs again). Needs a platform release with `moderateReviews`. `APPROVED` below
+     * `customerData: full` reports every review `FAILED` with code `CUSTOMER_DATA_NOT_GRANTED` and
+     * changes none; the call itself succeeds.
      *
      * @effect write
      */
@@ -287,13 +298,15 @@ export interface ReviewsModule {
         /**
          * Set (or replace) the store's reply, trimmed; shown under the review on the storefront once
          * it is approved. Over 2,000 characters is refused (`USER_INPUT_ERROR`). An empty reply is
-         * stored as one: use `remove` to take a reply away.
+         * stored as one: use `remove` to take a reply away. Refused `CUSTOMER_DATA_NOT_GRANTED`
+         * (`PermissionDeniedError`) below `customerData: full`: the reply is published under the
+         * store's name.
          *
          * @effect write
          */
         set(reviewId: string, reply: string, options?: Call): Promise<ProductReviewSummary>;
         /**
-         * Take the store's reply away.
+         * Take the store's reply away. Open at every customer-data level: it publishes nothing.
          *
          * @effect destructive
          */

package/dist/catalog/reviews.js

@@ -21,6 +21,13 @@
  * `CUSTOMER_DATA_NOT_GRANTED` (`PermissionDeniedError`, 403). The answers of the writes are
  * blanked the same way.
  *
+ * Publishing needs `full` (user decision O6): approving a review (`moderate`, or `bulkModerate`
+ * with `APPROVED`) and `reply.set` publish under the store's name next to text a caller below
+ * `full` reads blanked, so an app installation below it (or a request narrowed below it) is
+ * refused them with `CUSTOMER_DATA_NOT_GRANTED` (`PermissionDeniedError`, 403; `bulkModerate`
+ * reports it on each review). It may still reject, flag or re-open a review and remove the
+ * store's reply. A staff session and a personal API token act at `full`.
+ *
  * Permissions: reads need `ReadCatalog`, writes `UpdateCatalog`. Every row is the store's own: a
  * review or attribute of another store is never answered and never changed.
  *