@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/auth/index.d.ts

@@ -1,7 +1,13 @@
 import { type Transport } from '@sixtyninecommerce/core';
 import type { Call, Me, WhoAmI } from '../types.js';
 export interface AuthModule {
-    /** Establishes a session. The bearer arrives on a response header, not here. */
+    /**
+     * Establishes a session. The bearer arrives on a response header, not here.
+     * It is stored even when a concurrent call rotated the old bearer while this
+     * one was in flight: a sign-in is the newest word on the session.
+     *
+     * @effect write
+     */
     login(username: string, password: string, options?: Call): Promise<Me>;
     /**
      * Ends the session server-side AND clears the bearer, in the caller's own

package/dist/auth/index.js

@@ -112,7 +112,14 @@ export function createAuthModule(transport, session) {
     return {
         async login(username, password, options) {
             const rotationsBefore = session?.rotations();
-            const data = await transport.graphql({ api: 'admin', query: LOGIN_MUTATION, variables: { username, password } }, unscoped(options));
+            const data = await transport.graphql({
+                api: 'admin',
+                query: LOGIN_MUTATION,
+                variables: { username, password },
+                // Its bearer is adopted even if a concurrent call rotated the old
+                // one first; otherwise this sign-in would read as NO_SESSION_BEARER.
+                startsSession: true,
+            }, unscoped(options));
             // Vendure answers a bad password with HTTP 200 and an ErrorResult member.
             if (isErrorResult(data.login))
                 throw errorFromErrorResult(data.login);

package/dist/catalog/documents.d.ts

@@ -0,0 +1,142 @@
+/**
+ * A product's documents (headless spec §9.2 `catalog`: "documents"; W10-10): the downloads the
+ * storefront lists on a product page (a data sheet, a manual, a certificate), each pointing at a
+ * file in the asset library.
+ *
+ * - **Universal or localized.** A universal document (`isLocalized: false`) has exactly ONE
+ *   translation, with no language code, and it names the file. A localized one has one
+ *   translation per language (each language once), and at least one of them names a file; the
+ *   storefront shows the request's language, else the store's default, else one with a file.
+ * - **Who sees it** on the storefront: everyone (`PUBLIC`), signed-in customers
+ *   (`AUTHENTICATED`), or customers in the listed groups (`CUSTOMER_GROUP`, which needs at least
+ *   one group). The Admin API always lists every document.
+ * - **Order.** A new document goes after the product's last; `reorder` sets the order.
+ *
+ * Every document is the store's own: a product, document or customer group of another store is
+ * never answered and never written.
+ *
+ * Permissions: `list` needs `ReadCatalog`, the writes `UpdateCatalog`.
+ *
+ * Refusals, GraphQL errors mapped by `core`:
+ * - `USER_INPUT_ERROR` → `ValidationError` (400), in the engine's words: a product of another
+ *   store or none ("Product … not found"), a document of another store or none
+ *   ("ProductDocument … not found"), a translation set that breaks the rules above, a
+ *   `CUSTOMER_GROUP` document with no group, a `reorder` naming a document that is not one of the
+ *   product's.
+ * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a customer group the store does not hold.
+ * - `TRANSLATION_LANGUAGE_NOT_OFFERED` → `ValidationError` (400): a translation in a language the
+ *   store does not offer (a language the document already has stays editable).
+ * - `FORBIDDEN` → `PermissionDeniedError` (403) without the permission.
+ *
+ * No release gate: every operation here is served by every platform release this SDK supports.
+ * No method deduplicates on `idempotencyKey`: repeating a `create` adds a second document.
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import { type LanguageCode } from './types.js';
+export type ProductDocumentVisibility = 'PUBLIC' | 'AUTHENTICATED' | 'CUSTOMER_GROUP';
+/** The file a document translation points at: an asset of the library. */
+export interface ProductDocumentFile {
+    id: string;
+    name: string;
+    /** A string on the wire: a newer engine may add a type. */
+    type: 'IMAGE' | 'VIDEO' | 'BINARY' | (string & {});
+    mimeType: string;
+    /** Bytes. */
+    fileSize: number;
+    /** The asset's own URL (absolute or relative to the engine). */
+    source: string;
+    preview: string;
+}
+export interface ProductDocumentTranslation {
+    id: string;
+    /** Null on a universal document's one translation. */
+    languageCode: LanguageCode | null;
+    title: string;
+    description: string | null;
+    assetId: string | null;
+    /** Null when the translation names no file, or its file is gone. */
+    asset: ProductDocumentFile | null;
+}
+export interface ProductDocument {
+    id: string;
+    productId: string;
+    /** 0 first. */
+    position: number;
+    visibility: ProductDocumentVisibility | (string & {});
+    isLocalized: boolean;
+    translations: ProductDocumentTranslation[];
+    /** The groups a `CUSTOMER_GROUP` document is shown to; empty under the other two. */
+    customerGroups: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    /** ISO-8601 UTC. */
+    updatedAt: string;
+}
+export interface ProductDocumentTranslationInput {
+    /** Null (or omitted) on a universal document; required, once per language, on a localized one. */
+    languageCode?: LanguageCode | null;
+    title: string;
+    description?: string | null;
+    /** The asset (`catalog.assets`) the translation points at. */
+    assetId?: string | null;
+}
+export interface CreateProductDocumentInput {
+    productId: string;
+    visibility: ProductDocumentVisibility;
+    isLocalized: boolean;
+    /** Required (one or more) under `CUSTOMER_GROUP`; ignored under the other two. */
+    customerGroupIds?: string[];
+    translations: ProductDocumentTranslationInput[];
+}
+/**
+ * Only the fields named change. `translations`, when sent, REPLACES the document's translations;
+ * `customerGroupIds`, when sent, replaces its groups. Leaving `CUSTOMER_GROUP` drops its groups.
+ */
+export interface UpdateProductDocumentInput {
+    visibility?: ProductDocumentVisibility;
+    isLocalized?: boolean;
+    customerGroupIds?: string[];
+    translations?: ProductDocumentTranslationInput[];
+}
+export interface ProductDocumentsModule {
+    /**
+     * The product's documents, in their order (ties: the older first). A product of another store,
+     * or none, answers `[]`.
+     *
+     * @effect read
+     */
+    list(productId: string, options?: Call): Promise<ProductDocument[]>;
+    /**
+     * Adds a document after the product's last.
+     *
+     * @effect write
+     */
+    create(input: CreateProductDocumentInput, options?: Call): Promise<ProductDocument>;
+    /** @effect write */
+    update(id: string, input: UpdateProductDocumentInput, options?: Call): Promise<ProductDocument>;
+    /**
+     * Deletes the document; its file stays in the asset library. A document the store does not
+     * have (another store's, or already deleted) is refused `PRODUCT_DOCUMENT_NOT_FOUND`
+     * (`NotFoundError`, 404, raised by this SDK: the engine answers it as `false`).
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * Puts the named documents in this order (`0, 1, 2…`). Name the product's documents: one that
+     * is not the product's refuses the whole call and nothing moves; one left out keeps its position.
+     *
+     * @effect write
+     */
+    reorder(productId: string, orderedIds: string[], options?: Call): Promise<void>;
+}
+export declare const PRODUCT_DOCUMENTS_QUERY = "\n  query CatalogProductDocuments($productId: ID!) {\n    productDocuments(productId: $productId) { \n  id\n  productId\n  position\n  visibility\n  isLocalized\n  createdAt\n  updatedAt\n  translations {\n    id\n    languageCode\n    title\n    description\n    assetId\n    asset {\n      id\n      name\n      type\n      mimeType\n      fileSize\n      source\n      preview\n    }\n  }\n  customerGroups {\n    id\n    name\n  }\n }\n  }\n";
+export declare const CREATE_PRODUCT_DOCUMENT_MUTATION = "\n  mutation CatalogCreateProductDocument($input: CreateProductDocumentInput!) {\n    createProductDocument(input: $input) { \n  id\n  productId\n  position\n  visibility\n  isLocalized\n  createdAt\n  updatedAt\n  translations {\n    id\n    languageCode\n    title\n    description\n    assetId\n    asset {\n      id\n      name\n      type\n      mimeType\n      fileSize\n      source\n      preview\n    }\n  }\n  customerGroups {\n    id\n    name\n  }\n }\n  }\n";
+export declare const UPDATE_PRODUCT_DOCUMENT_MUTATION = "\n  mutation CatalogUpdateProductDocument($input: UpdateProductDocumentInput!) {\n    updateProductDocument(input: $input) { \n  id\n  productId\n  position\n  visibility\n  isLocalized\n  createdAt\n  updatedAt\n  translations {\n    id\n    languageCode\n    title\n    description\n    assetId\n    asset {\n      id\n      name\n      type\n      mimeType\n      fileSize\n      source\n      preview\n    }\n  }\n  customerGroups {\n    id\n    name\n  }\n }\n  }\n";
+export declare const DELETE_PRODUCT_DOCUMENT_MUTATION = "\n  mutation CatalogDeleteProductDocument($id: ID!) {\n    deleteProductDocument(id: $id)\n  }\n";
+export declare const REORDER_PRODUCT_DOCUMENTS_MUTATION = "\n  mutation CatalogReorderProductDocuments($productId: ID!, $orderedIds: [ID!]!) {\n    reorderProductDocuments(productId: $productId, orderedIds: $orderedIds)\n  }\n";
+export declare function createProductDocumentsModule(transport: Transport): ProductDocumentsModule;

package/dist/catalog/documents.js

@@ -0,0 +1,114 @@
+/**
+ * A product's documents (headless spec §9.2 `catalog`: "documents"; W10-10): the downloads the
+ * storefront lists on a product page (a data sheet, a manual, a certificate), each pointing at a
+ * file in the asset library.
+ *
+ * - **Universal or localized.** A universal document (`isLocalized: false`) has exactly ONE
+ *   translation, with no language code, and it names the file. A localized one has one
+ *   translation per language (each language once), and at least one of them names a file; the
+ *   storefront shows the request's language, else the store's default, else one with a file.
+ * - **Who sees it** on the storefront: everyone (`PUBLIC`), signed-in customers
+ *   (`AUTHENTICATED`), or customers in the listed groups (`CUSTOMER_GROUP`, which needs at least
+ *   one group). The Admin API always lists every document.
+ * - **Order.** A new document goes after the product's last; `reorder` sets the order.
+ *
+ * Every document is the store's own: a product, document or customer group of another store is
+ * never answered and never written.
+ *
+ * Permissions: `list` needs `ReadCatalog`, the writes `UpdateCatalog`.
+ *
+ * Refusals, GraphQL errors mapped by `core`:
+ * - `USER_INPUT_ERROR` → `ValidationError` (400), in the engine's words: a product of another
+ *   store or none ("Product … not found"), a document of another store or none
+ *   ("ProductDocument … not found"), a translation set that breaks the rules above, a
+ *   `CUSTOMER_GROUP` document with no group, a `reorder` naming a document that is not one of the
+ *   product's.
+ * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a customer group the store does not hold.
+ * - `TRANSLATION_LANGUAGE_NOT_OFFERED` → `ValidationError` (400): a translation in a language the
+ *   store does not offer (a language the document already has stays editable).
+ * - `FORBIDDEN` → `PermissionDeniedError` (403) without the permission.
+ *
+ * No release gate: every operation here is served by every platform release this SDK supports.
+ * No method deduplicates on `idempotencyKey`: repeating a `create` adds a second document.
+ */
+import { NotFoundError } from '@sixtyninecommerce/core';
+import { fieldOf } from './types.js';
+const DOCUMENT_FIELDS = /* GraphQL */ `
+  id
+  productId
+  position
+  visibility
+  isLocalized
+  createdAt
+  updatedAt
+  translations {
+    id
+    languageCode
+    title
+    description
+    assetId
+    asset {
+      id
+      name
+      type
+      mimeType
+      fileSize
+      source
+      preview
+    }
+  }
+  customerGroups {
+    id
+    name
+  }
+`;
+export const PRODUCT_DOCUMENTS_QUERY = /* GraphQL */ `
+  query CatalogProductDocuments($productId: ID!) {
+    productDocuments(productId: $productId) { ${DOCUMENT_FIELDS} }
+  }
+`;
+export const CREATE_PRODUCT_DOCUMENT_MUTATION = /* GraphQL */ `
+  mutation CatalogCreateProductDocument($input: CreateProductDocumentInput!) {
+    createProductDocument(input: $input) { ${DOCUMENT_FIELDS} }
+  }
+`;
+export const UPDATE_PRODUCT_DOCUMENT_MUTATION = /* GraphQL */ `
+  mutation CatalogUpdateProductDocument($input: UpdateProductDocumentInput!) {
+    updateProductDocument(input: $input) { ${DOCUMENT_FIELDS} }
+  }
+`;
+export const DELETE_PRODUCT_DOCUMENT_MUTATION = /* GraphQL */ `
+  mutation CatalogDeleteProductDocument($id: ID!) {
+    deleteProductDocument(id: $id)
+  }
+`;
+export const REORDER_PRODUCT_DOCUMENTS_MUTATION = /* GraphQL */ `
+  mutation CatalogReorderProductDocuments($productId: ID!, $orderedIds: [ID!]!) {
+    reorderProductDocuments(productId: $productId, orderedIds: $orderedIds)
+  }
+`;
+/** The engine reads the list in `position` order; keep that, with the older first on a tie. */
+function byPosition(documents) {
+    return [...documents].sort((a, b) => a.position - b.position || a.createdAt.localeCompare(b.createdAt));
+}
+export function createProductDocumentsModule(transport) {
+    return {
+        list: async (productId, options) => byPosition(await fieldOf(transport, PRODUCT_DOCUMENTS_QUERY, 'productDocuments', { productId }, options)),
+        create: (input, options) => fieldOf(transport, CREATE_PRODUCT_DOCUMENT_MUTATION, 'createProductDocument', { input }, options),
+        update: (id, input, options) => fieldOf(transport, UPDATE_PRODUCT_DOCUMENT_MUTATION, 'updateProductDocument', { input: { ...input, id } }, options),
+        async delete(id, options) {
+            const deleted = await fieldOf(transport, DELETE_PRODUCT_DOCUMENT_MUTATION, 'deleteProductDocument', { id }, options);
+            if (!deleted) {
+                throw new NotFoundError({
+                    code: 'PRODUCT_DOCUMENT_NOT_FOUND',
+                    message: `This store has no product document ${id}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+        },
+        async reorder(productId, orderedIds, options) {
+            await fieldOf(transport, REORDER_PRODUCT_DOCUMENTS_MUTATION, 'reorderProductDocuments', { productId, orderedIds }, options);
+        },
+    };
+}

package/dist/catalog/index.d.ts

@@ -2,19 +2,21 @@ import type { Transport } from '@sixtyninecommerce/core';
 import type { Call } from '../types.js';
 import { type AssetsModule } from './assets.js';
 import { type CollectionsModule } from './collections.js';
+import { type ProductDocumentsModule } from './documents.js';
 import { type FacetsModule } from './facets.js';
+import { type ProductMetadataModule } from './metadata.js';
 import { type OptionsModule } from './options.js';
 import { type ProductsModule } from './products.js';
-import { type ContentFacetSyncResult, type PropertiesModule } from './properties.js';
+import { type ContentFacetSyncResult, type ContentItemFacetSyncResult, type PropertiesModule } from './properties.js';
 import { type RecommendationsModule } from './recommendations.js';
 import { type ReviewsModule } from './reviews.js';
 import { type VariantsModule } from './variants.js';
 import { type VisibilityModule } from './visibility.js';
 /**
  * The catalogue (spec §9.2 `catalog`): products, variants, options, facets,
- * collections, assets, storefront visibility, product properties, product
- * recommendations and product reviews — one resource per namespace, over the Admin API the
- * dashboard itself uses.
+ * collections, assets, storefront visibility, product documents, product SEO metadata, product
+ * properties, product recommendations and product reviews — one resource per namespace, over the
+ * Admin API the dashboard itself uses.
  *
  * **Per-resource, not per-intent.** Saving a product form is several calls
  * here (the product, its variants, its properties, its collections), and they
@@ -72,6 +74,10 @@ export interface CatalogModule {
     collections: CollectionsModule;
     assets: AssetsModule;
     visibility: VisibilityModule;
+    /** A product's downloads: data sheets, manuals, certificates (W10-10). */
+    documents: ProductDocumentsModule;
+    /** A product's SEO, social and AI-agent metadata, and the SEO coverage list (W10-10). */
+    metadata: ProductMetadataModule;
     properties: PropertiesModule;
     /** Recommendation groups, their rules and the products picked per product (W10-13). */
     recommendations: RecommendationsModule;
@@ -93,9 +99,11 @@ export interface CatalogModule {
      * anything changes. Repeating the call is safe: a label that did not change is not written
      * again, so a repeat answers the same counts and changes nothing.
      *
-     * Nothing runs it automatically in this release: rename a content item or a product, then call
-     * it (or press "Sync filter values") to update the filter label (ruling G17; an event-driven
-     * update is a later phase).
+     * Automatic for PUBLISHED content items (headless W10-19, ruling G115): when a published item
+     * is edited, published or unpublished, the platform syncs the properties naming it by itself
+     * within about a minute ({@link CatalogModule.syncContentItemFacets}). Call this after renaming
+     * a DRAFT or archived item (the content system announces nothing for one until it is
+     * published), after renaming a product, or to sync one property at once.
      *
      * Needs `UpdateCatalog`. Platform releases before this method do not have the mutation and refuse
      * it as `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400).
@@ -116,7 +124,40 @@ export interface CatalogModule {
      * - `PROPERTY_SYNC_SOURCE_UNAVAILABLE` → `BusinessRuleError` (422): a `content_item` property on
      *   a platform with no content system wired.
      * - `FORBIDDEN` → `PermissionDeniedError` (403): no `UpdateCatalog`.
+     *
+     * @effect write
      */
     syncContentFacets(propertyId: string, options?: Call): Promise<ContentFacetSyncResult>;
+    /**
+     * "Sync filter values" for every filterable `content_item` property of the store whose values
+     * name one of `contentItemIds` (headless W10-19): each is synced as
+     * {@link CatalogModule.syncContentFacets} syncs it, so a renamed content item's filter label
+     * follows its title. The platform calls it by itself, within about a minute, for the items a
+     * change to a PUBLISHED item touched (published, edited while published, unpublished); call it
+     * yourself for items you know changed otherwise (an app importing content, a draft renamed).
+     *
+     * Per property: a property its own sync refuses is reported in `skipped` with that refusal
+     * (`MANAGED_BY_ORGANIZATION` for the organization workspace's property, synced in the
+     * workspace) and nothing of it is written; the others are synced. `changed` says whether
+     * anything was written. Every label is read before anything is written, and the writes are
+     * one transaction: a content system that cannot be read, or any failure other than a
+     * property's refusal, refuses the whole call and writes nothing. Repeating it is safe.
+     *
+     * At most {@link MAX_CONTENT_ITEM_FACET_SYNC_IDS} different ids per call (repeats count once);
+     * an id no property names syncs nothing. Needs `UpdateCatalog`. Platform releases before this
+     * method do not have the mutation and refuse it as `ValidationError`
+     * `GRAPHQL_VALIDATION_FAILED` (400).
+     *
+     * Refusals of the whole call (nothing is written):
+     * - `CONTENT_ITEM_IDS_INVALID` → `ValidationError` (400): a blank id, or more than 500
+     *   different ids; checked before sending as well.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): an id that is not a uuid.
+     * - `CMS_REQUEST_FAILED` → `BusinessRuleError` (422): the content system could not be read;
+     *   try again.
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): no `UpdateCatalog`.
+     *
+     * @effect write
+     */
+    syncContentItemFacets(contentItemIds: readonly string[], options?: Call): Promise<ContentItemFacetSyncResult>;
 }
 export declare function createCatalogModule(transport: Transport): CatalogModule;

package/dist/catalog/index.js

@@ -1,9 +1,11 @@
 import { createAssetsModule } from './assets.js';
 import { createCollectionsModule } from './collections.js';
+import { createProductDocumentsModule } from './documents.js';
 import { createFacetsModule } from './facets.js';
+import { createProductMetadataModule } from './metadata.js';
 import { createOptionsModule } from './options.js';
 import { createProductsModule } from './products.js';
-import { createPropertiesModule, syncContentFacets, } from './properties.js';
+import { createPropertiesModule, syncContentFacets, syncContentItemFacets, } from './properties.js';
 import { createRecommendationsModule } from './recommendations.js';
 import { createReviewsModule } from './reviews.js';
 import { createVariantsModule } from './variants.js';
@@ -17,9 +19,12 @@ export function createCatalogModule(transport) {
         collections: createCollectionsModule(transport),
         assets: createAssetsModule(transport),
         visibility: createVisibilityModule(transport),
+        documents: createProductDocumentsModule(transport),
+        metadata: createProductMetadataModule(transport),
         properties: createPropertiesModule(transport),
         recommendations: createRecommendationsModule(transport),
         reviews: createReviewsModule(transport),
         syncContentFacets: (propertyId, options) => syncContentFacets(transport, propertyId, options),
+        syncContentItemFacets: (contentItemIds, options) => syncContentItemFacets(transport, contentItemIds, options),
     };
 }

package/dist/catalog/metadata.d.ts

@@ -0,0 +1,244 @@
+/**
+ * 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 { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import { type LanguageCode } from './types.js';
+/** How many products one `bulkUpsert` call may name. */
+export declare const MAX_BULK_METADATA_EDITS = 200;
+/** An image the metadata names (the share image, the X/Twitter override). */
+export interface ProductMetadataImage {
+    id: string;
+    name: string;
+    preview: string;
+    source: string;
+    /** A string on the wire: a newer engine may add a type. */
+    type: 'IMAGE' | 'VIDEO' | 'BINARY' | (string & {});
+    mimeType: string;
+}
+/**
+ * One language's texts. The four JSON fields are read as the engine stores them; every write
+ * checks them (`breadcrumbOverride` `{ label, url }[]` of at most 5, `focusKeywords` up to 10
+ * distinct strings, `qaPairs` `{ question, answer }[]` of at most 20), but read them defensively.
+ */
+export interface ProductMetadataTranslation {
+    id: string;
+    languageCode: LanguageCode;
+    seoTitle: string | null;
+    seoDescription: string | null;
+    canonicalUrl: string | null;
+    breadcrumbOverride: unknown;
+    focusKeywords: unknown;
+    socialTitle: string | null;
+    socialDescription: string | null;
+    socialImageAlt: string | null;
+    twitterTitleOverride: string | null;
+    twitterDescriptionOverride: string | null;
+    aiSummary: string | null;
+    qaPairs: unknown;
+}
+export interface ProductMetadata {
+    id: string;
+    productId: string;
+    channelId: string;
+    /** `index` or `noindex`. */
+    metaRobotsIndex: string;
+    /** `follow` or `nofollow`. */
+    metaRobotsFollow: string;
+    metaRobotsNoarchive: boolean;
+    metaRobotsNosnippet: boolean;
+    metaRobotsNoimageindex: boolean;
+    /** `none`, `standard` or `large`. */
+    metaRobotsMaxImagePreview: string;
+    metaRobotsMaxSnippet: number | null;
+    metaRobotsMaxVideoPreview: number | null;
+    /** ISO-8601 UTC instant after which search engines should drop the page; null when none. */
+    metaRobotsUnavailableAfter: string | null;
+    socialImageId: string | null;
+    socialImage: ProductMetadataImage | null;
+    twitterImageOverrideId: string | null;
+    twitterImageOverride: ProductMetadataImage | null;
+    twitterCardType: string;
+    socialOgType: string;
+    seoIncludeReviewsInJsonld: boolean;
+    aiSummaryAudience: string;
+    /** The product's own `{ [botKey]: 'allow' | 'deny' }`; null when it has none. */
+    aiBotOverrides: Record<string, unknown> | null;
+    qaEmitFaqpageJsonld: boolean;
+    hreflangOverrides: unknown;
+    /** The product's overrides on top of the store's defaults, as the storefront applies them. */
+    resolvedBotDirectives: Record<string, unknown>;
+    translations: ProductMetadataTranslation[];
+}
+export interface ProductMetadataTranslationInput {
+    languageCode: LanguageCode;
+    seoTitle?: string | null;
+    seoDescription?: string | null;
+    /** An absolute `https://` URL. */
+    canonicalUrl?: string | null;
+    breadcrumbOverride?: Array<{
+        label: string;
+        url: string;
+    }> | null;
+    focusKeywords?: string[] | null;
+    socialTitle?: string | null;
+    socialDescription?: string | null;
+    socialImageAlt?: string | null;
+    twitterTitleOverride?: string | null;
+    twitterDescriptionOverride?: string | null;
+    aiSummary?: string | null;
+    qaPairs?: Array<{
+        question: string;
+        answer: string;
+    }> | null;
+}
+/** Only the fields named change. */
+export interface ProductMetadataInput {
+    metaRobotsIndex?: 'index' | 'noindex';
+    metaRobotsFollow?: 'follow' | 'nofollow';
+    metaRobotsNoarchive?: boolean;
+    metaRobotsNosnippet?: boolean;
+    metaRobotsNoimageindex?: boolean;
+    metaRobotsMaxImagePreview?: 'none' | 'standard' | 'large';
+    metaRobotsMaxSnippet?: number | null;
+    metaRobotsMaxVideoPreview?: number | null;
+    /**
+     * An ISO-8601 instant WITH an explicit offset (`Z` or `±HH:mm`). One without is refused before
+     * the request leaves (`INVALID_DATETIME`).
+     */
+    metaRobotsUnavailableAfter?: string | null;
+    socialImageId?: string | null;
+    twitterImageOverrideId?: string | null;
+    twitterCardType?: 'summary' | 'summary_large_image';
+    socialOgType?: 'product' | 'website';
+    seoIncludeReviewsInJsonld?: boolean;
+    aiSummaryAudience?: 'customers' | 'developers' | 'both';
+    aiBotOverrides?: Record<string, 'allow' | 'deny'> | null;
+    qaEmitFaqpageJsonld?: boolean;
+    hreflangOverrides?: Array<{
+        language: string;
+        country?: string;
+        url: string;
+    }> | null;
+    translations?: ProductMetadataTranslationInput[];
+}
+export type ProductMetadataCoverageFilter = 'ALL' | 'MISSING_TITLE' | 'MISSING_DESCRIPTION';
+export interface ProductMetadataCoverageQuery extends ListOptions {
+    /** The language whose meta each row shows, and which the filter judges. */
+    languageCode: LanguageCode;
+    /** Defaults to `ALL`. A value is missing when it is null or empty. */
+    filter?: ProductMetadataCoverageFilter;
+    /** Matches the product's name. */
+    term?: string;
+}
+/** One product of the coverage list. */
+export interface ProductMetadataCoverageRow {
+    productId: string;
+    /** The product's name in the request's language. */
+    name: string;
+    slug: string;
+    enabled: boolean;
+    /** The product's own meta title in the query's language; null when it has none. */
+    seoTitle: string | null;
+    /** The product's own meta description in the query's language; null when it has none. */
+    seoDescription: string | null;
+}
+export interface ProductMetadataBulkEdit {
+    productId: string;
+    input: ProductMetadataInput;
+}
+/** One product's outcome in a `bulkUpsert` call. */
+export interface ProductMetadataBulkOutcome {
+    productId: string;
+    /** `OK`, or `FAILED` (a string on the wire: read anything else as not done). */
+    status: 'OK' | 'FAILED' | (string & {});
+    /**
+     * When FAILED: the single door's own code (`ENTITY_NOT_FOUND`,
+     * `PRODUCT_METADATA_INPUT_INVALID`, …); `INTERNAL_SERVER_ERROR` for a fault the engine logged.
+     */
+    code: string | null;
+    /** When FAILED: the door's sentence. */
+    message: string | null;
+}
+export interface ProductMetadataModule {
+    /**
+     * The product's metadata; null when it has none yet. `NotFoundError` (`PRODUCT_NOT_FOUND`) for
+     * a product the store does not hold.
+     *
+     * @effect read
+     */
+    get(productId: string, options?: Call): Promise<ProductMetadata | null>;
+    /**
+     * Creates the product's metadata or changes the fields named, and answers the whole record.
+     *
+     * @effect write
+     */
+    upsert(productId: string, input: ProductMetadataInput, options?: Call): Promise<ProductMetadata>;
+    /**
+     * Removes the product's metadata in this store: the storefront falls back to the product's own
+     * name and description. Resolves the same way whether or not there was any.
+     *
+     * @effect destructive
+     */
+    delete(productId: string, options?: Call): Promise<void>;
+    /**
+     * The store's products, name first, each with its own meta in `languageCode`; with a `filter`,
+     * only those missing a title (or a description) there. Filtered before paging: pages are full
+     * and `totalItems` counts the filter and the term. Never answers a deleted product.
+     *
+     * @effect read
+     */
+    coverage(query: ProductMetadataCoverageQuery): Promise<Page<ProductMetadataCoverageRow>>;
+    /**
+     * Upserts 1 to {@link MAX_BULK_METADATA_EDITS} products, each through `upsert`'s rules in a
+     * transaction of its own, and answers one outcome per product in the order named: a refused
+     * product changes nothing and the others still go through. Not keyed: a repeat writes again.
+     *
+     * @effect write
+     */
+    bulkUpsert(edits: readonly ProductMetadataBulkEdit[], options?: Call): Promise<ProductMetadataBulkOutcome[]>;
+}
+export declare const PRODUCT_METADATA_QUERY = "\n  query CatalogProductMetadata($productId: ID!) {\n    product(id: $productId) {\n      id\n      metadata { \n  id\n  productId\n  channelId\n  metaRobotsIndex\n  metaRobotsFollow\n  metaRobotsNoarchive\n  metaRobotsNosnippet\n  metaRobotsNoimageindex\n  metaRobotsMaxImagePreview\n  metaRobotsMaxSnippet\n  metaRobotsMaxVideoPreview\n  metaRobotsUnavailableAfter\n  socialImageId\n  socialImage { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n }\n  twitterImageOverrideId\n  twitterImageOverride { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n }\n  twitterCardType\n  socialOgType\n  seoIncludeReviewsInJsonld\n  aiSummaryAudience\n  aiBotOverrides\n  qaEmitFaqpageJsonld\n  hreflangOverrides\n  resolvedBotDirectives\n  translations {\n    id\n    languageCode\n    seoTitle\n    seoDescription\n    canonicalUrl\n    breadcrumbOverride\n    focusKeywords\n    socialTitle\n    socialDescription\n    socialImageAlt\n    twitterTitleOverride\n    twitterDescriptionOverride\n    aiSummary\n    qaPairs\n  }\n }\n    }\n  }\n";
+export declare const UPSERT_PRODUCT_METADATA_MUTATION = "\n  mutation CatalogUpsertProductMetadata($productId: ID!, $input: ProductMetadataInput!) {\n    upsertProductMetadata(productId: $productId, input: $input) { \n  id\n  productId\n  channelId\n  metaRobotsIndex\n  metaRobotsFollow\n  metaRobotsNoarchive\n  metaRobotsNosnippet\n  metaRobotsNoimageindex\n  metaRobotsMaxImagePreview\n  metaRobotsMaxSnippet\n  metaRobotsMaxVideoPreview\n  metaRobotsUnavailableAfter\n  socialImageId\n  socialImage { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n }\n  twitterImageOverrideId\n  twitterImageOverride { \n  id\n  name\n  preview\n  source\n  type\n  mimeType\n }\n  twitterCardType\n  socialOgType\n  seoIncludeReviewsInJsonld\n  aiSummaryAudience\n  aiBotOverrides\n  qaEmitFaqpageJsonld\n  hreflangOverrides\n  resolvedBotDirectives\n  translations {\n    id\n    languageCode\n    seoTitle\n    seoDescription\n    canonicalUrl\n    breadcrumbOverride\n    focusKeywords\n    socialTitle\n    socialDescription\n    socialImageAlt\n    twitterTitleOverride\n    twitterDescriptionOverride\n    aiSummary\n    qaPairs\n  }\n }\n  }\n";
+export declare const DELETE_PRODUCT_METADATA_MUTATION = "\n  mutation CatalogDeleteProductMetadata($productId: ID!) {\n    deleteProductMetadata(productId: $productId) { \n  result\n  message\n }\n  }\n";
+export declare const PRODUCT_METADATA_COVERAGE_QUERY = "\n  query CatalogProductMetadataCoverage(\n    $languageCode: LanguageCode!\n    $filter: ProductMetadataCoverageFilter\n    $term: String\n    $options: ProductMetadataCoverageListOptions\n  ) {\n    productMetadataCoverage(\n      languageCode: $languageCode\n      filter: $filter\n      term: $term\n      options: $options\n    ) {\n      items {\n        productId\n        name\n        slug\n        enabled\n        seoTitle\n        seoDescription\n      }\n      totalItems\n    }\n  }\n";
+export declare const BULK_UPSERT_PRODUCT_METADATA_MUTATION = "\n  mutation CatalogBulkUpsertProductMetadata($edits: [ProductMetadataBulkEdit!]!) {\n    bulkUpsertProductMetadata(edits: $edits) {\n      items {\n        productId\n        status\n        code\n        message\n      }\n    }\n  }\n";
+export declare function createProductMetadataModule(transport: Transport): ProductMetadataModule;