@sixtyninecommerce/admin 0.7.0 → 0.9.0

package/dist/catalog/properties.js

@@ -0,0 +1,158 @@
+import { createPage } from '@sixtyninecommerce/core';
+import { assertDeleted, DELETION_FIELDS, fieldOf, } from './types.js';
+const PROPERTY_FIELDS = /* GraphQL */ `
+  id
+  createdAt
+  updatedAt
+  slug
+  fieldType
+  isFilterable
+  isRequired
+  position
+  config {
+    options {
+      value
+      label
+    }
+    min
+    max
+    maxLength
+    allowedCollectionIds
+    filterableFieldSlugs
+    productFilter
+  }
+  facetId
+  translations {
+    id
+    languageCode
+    name
+    helpText
+  }
+`;
+export const PROPERTY_GROUP_FIELDS = /* GraphQL */ `
+  id
+  createdAt
+  updatedAt
+  position
+  translations {
+    id
+    languageCode
+    name
+  }
+  properties { ${PROPERTY_FIELDS} }
+  editableHere
+`;
+export const PROPERTY_GROUPS_QUERY = /* GraphQL */ `
+  query CatalogPropertyGroups {
+    propertyGroups { ${PROPERTY_GROUP_FIELDS} }
+  }
+`;
+export const PROPERTY_GROUP_QUERY = /* GraphQL */ `
+  query CatalogPropertyGroup($id: ID!) {
+    propertyGroup(id: $id) { ${PROPERTY_GROUP_FIELDS} }
+  }
+`;
+export const CREATE_PROPERTY_GROUP_MUTATION = /* GraphQL */ `
+  mutation CatalogCreatePropertyGroup($input: CreatePropertyGroupInput!) {
+    createPropertyGroup(input: $input) { ${PROPERTY_GROUP_FIELDS} }
+  }
+`;
+export const UPDATE_PROPERTY_GROUP_MUTATION = /* GraphQL */ `
+  mutation CatalogUpdatePropertyGroup($input: UpdatePropertyGroupInput!) {
+    updatePropertyGroup(input: $input) { ${PROPERTY_GROUP_FIELDS} }
+  }
+`;
+export const DELETE_PROPERTY_GROUP_MUTATION = /* GraphQL */ `
+  mutation CatalogDeletePropertyGroup($id: ID!) {
+    deletePropertyGroup(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+export const REORDER_PROPERTY_GROUPS_MUTATION = /* GraphQL */ `
+  mutation CatalogReorderPropertyGroups($ids: [ID!]!) {
+    reorderPropertyGroups(ids: $ids) { ${PROPERTY_GROUP_FIELDS} }
+  }
+`;
+export const CREATE_PROPERTY_MUTATION = /* GraphQL */ `
+  mutation CatalogCreateProperty($input: CreatePropertyInput!) {
+    createProperty(input: $input) { ${PROPERTY_FIELDS} }
+  }
+`;
+export const UPDATE_PROPERTY_MUTATION = /* GraphQL */ `
+  mutation CatalogUpdateProperty($input: UpdatePropertyInput!) {
+    updateProperty(input: $input) { ${PROPERTY_FIELDS} }
+  }
+`;
+export const DELETE_PROPERTY_MUTATION = /* GraphQL */ `
+  mutation CatalogDeleteProperty($id: ID!) {
+    deleteProperty(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+export const REORDER_PROPERTIES_MUTATION = /* GraphQL */ `
+  mutation CatalogReorderProperties($groupId: ID!, $propertyIds: [ID!]!) {
+    reorderProperties(groupId: $groupId, propertyIds: $propertyIds) { ${PROPERTY_FIELDS} }
+  }
+`;
+export const PRODUCT_PROPERTY_VALUES_QUERY = /* GraphQL */ `
+  query CatalogProductPropertyValues($productId: ID!) {
+    productPropertyValues(productId: $productId) {
+      group { ${PROPERTY_GROUP_FIELDS} }
+      values {
+        id
+        propertyId
+        languageCode
+        value
+      }
+    }
+  }
+`;
+export const SET_PRODUCT_PROPERTY_VALUES_MUTATION = /* GraphQL */ `
+  mutation CatalogSetProductPropertyValues($productId: ID!, $values: [SetProductPropertyValueInput!]!) {
+    setProductPropertyValues(productId: $productId, values: $values)
+  }
+`;
+export const SYNC_PROPERTY_FACETS_MUTATION = /* GraphQL */ `
+  mutation CatalogSyncPropertyFacets($propertyId: ID!) {
+    syncPropertyFacets(propertyId: $propertyId) {
+      propertyId
+      items
+      unresolved
+      fieldFacets
+    }
+  }
+`;
+/** `catalog.syncContentFacets`; its contract is on {@link CatalogModule.syncContentFacets}. */
+export function syncContentFacets(transport, propertyId, options) {
+    return fieldOf(transport, SYNC_PROPERTY_FACETS_MUTATION, 'syncPropertyFacets', { propertyId }, 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) => {
+        assertDeleted(code, [await call(document, field, { id }, options)]);
+    };
+    return {
+        groups: {
+            async list(options) {
+                const items = await call(PROPERTY_GROUPS_QUERY, 'propertyGroups', {}, options);
+                return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+                    // Unreachable while `hasNext` is false — `Page.next()` short-circuits.
+                    throw new Error('propertyGroups returns a complete list; there is no next page');
+                });
+            },
+            get: (id, options) => call(PROPERTY_GROUP_QUERY, 'propertyGroup', { id }, options),
+            create: (input, options) => call(CREATE_PROPERTY_GROUP_MUTATION, 'createPropertyGroup', { input }, options),
+            update: (input, options) => call(UPDATE_PROPERTY_GROUP_MUTATION, 'updatePropertyGroup', { input }, options),
+            delete: (id, options) => deleted(DELETE_PROPERTY_GROUP_MUTATION, 'deletePropertyGroup', 'PROPERTY_GROUP_NOT_DELETED', id, options),
+            reorder: (ids, options) => call(REORDER_PROPERTY_GROUPS_MUTATION, 'reorderPropertyGroups', { ids }, options),
+        },
+        create: (input, options) => call(CREATE_PROPERTY_MUTATION, 'createProperty', { input }, options),
+        update: (input, options) => call(UPDATE_PROPERTY_MUTATION, 'updateProperty', { input }, options),
+        delete: (id, options) => deleted(DELETE_PROPERTY_MUTATION, 'deleteProperty', 'PROPERTY_NOT_DELETED', id, options),
+        reorder: (groupId, propertyIds, options) => call(REORDER_PROPERTIES_MUTATION, 'reorderProperties', { groupId, propertyIds }, options),
+        values: {
+            get: (productId, options) => call(PRODUCT_PROPERTY_VALUES_QUERY, 'productPropertyValues', { productId }, options),
+            async set(productId, values, options) {
+                await call(SET_PRODUCT_PROPERTY_VALUES_MUTATION, 'setProductPropertyValues', { productId, values }, options);
+            },
+        },
+    };
+}

package/dist/catalog/types.d.ts

@@ -0,0 +1,174 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/** A language code as Vendure spells it: `en`, `nl`, `pt_BR`. */
+export type LanguageCode = string;
+/** An asset as the catalog projects it — enough to render and to re-assign it. */
+export interface AssetRef {
+    id: string;
+    name: string;
+    /** A preview URL the asset server scales; absolute or relative to the engine. */
+    preview: string;
+    source: string;
+}
+export interface FacetValueRef {
+    id: string;
+    code: string;
+    name: string;
+    facet: {
+        id: string;
+        code: string;
+        name: string;
+    };
+}
+/**
+ * A product's own availability (the pre-order engine, merged 2026-09-18).
+ *
+ * - `none` — ordinary stock rules.
+ * - `comingSoon` — shown, but nobody can order it, not even from stock.
+ * - `preorder` — customers allowed to backorder may order beyond stock; everyone
+ *   else can still buy what is in stock.
+ */
+export type ProductAvailabilityState = 'none' | 'comingSoon' | 'preorder';
+/** A variant's: the product's states plus `inherit` (use the product's state, date and limit). */
+export type VariantAvailabilityState = 'inherit' | ProductAvailabilityState;
+/**
+ * Availability fields as they are READ. Every writer shares one shape: a state
+ * that is not `inherit` uses this row's own `availableFrom` and `preorderLimit`,
+ * empty ones included.
+ */
+export interface Availability<State extends string> {
+    availabilityState: State;
+    /**
+     * ISO-8601 UTC instant at which the state ends on its own — from then on the
+     * ordinary stock and backorder rules apply again. Null: it ends by hand.
+     */
+    availableFrom: string | null;
+    /**
+     * Under `preorder`: the most units per variant that may be pre-ordered beyond
+     * stock across all open orders. Null: no limit. Ignored under every other
+     * state.
+     */
+    preorderLimit: number | null;
+}
+/**
+ * Availability fields as they are WRITTEN. Omit a field to leave it alone, pass
+ * null to clear it.
+ */
+export interface AvailabilityInput<State extends string> {
+    availabilityState?: State;
+    /**
+     * An ISO-8601 instant WITH an explicit offset (`Z` or `±HH:mm`). One without
+     * is refused before the request leaves (`INVALID_DATETIME`), because the
+     * engine would read it in its own zone, not yours or the store's.
+     */
+    availableFrom?: string | null;
+    /** A whole number ≥ 0, or null for no limit. */
+    preorderLimit?: number | null;
+}
+/**
+ * A price the caller STATES. `basis` says which side of tax the amount is on,
+ * and must equal the store's own (`pricesIncludeTax`): the Admin API stores
+ * one amount in the store's basis and derives the other, so a net amount
+ * written into a gross store would silently lose a whole VAT rate. A mismatch
+ * is refused (`PRICE_BASIS_MISMATCH`) — the SDK never converts, because the
+ * rate that would convert it depends on the zone of each order.
+ */
+export type PriceBasis = 'net' | 'gross';
+/** Omit a key to leave it; unknown keys are not accepted by the Admin API. */
+export interface TranslationInput {
+    languageCode: LanguageCode;
+    /** Present on update to edit that translation row rather than add one. */
+    id?: string;
+}
+/** Vendure's `ConfigurableOperationInput`: a collection filter, a promotion action. */
+export interface ConfigurableOperationInput {
+    code: string;
+    /** Every argument is a STRING on the wire — lists and booleans JSON-encoded. */
+    arguments: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/** Vendure's `ConfigurableOperation`, as read back. */
+export interface ConfigurableOperation {
+    code: string;
+    args: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * Whose catalogue a row belongs to, as the ACTIVE channel sees it (multi-region spec §5.4):
+ * - `LOCAL` — the store's own row, or a row its organization keeps but has not shared yet.
+ * - `SHARED` — kept by the organization and shared: in a member store, a row of its
+ *   organization's workspace; in the workspace, a row at least one member store holds.
+ *
+ * A string on the wire: a newer engine may answer a state this SDK does not name yet.
+ */
+export type CatalogueOwnershipState = 'LOCAL' | 'SHARED';
+export interface CatalogueOwnership {
+    state: CatalogueOwnershipState | (string & {});
+    /** The organization that keeps the row while it is `SHARED`; null while `LOCAL`. */
+    organizationName: string | null;
+    /**
+     * Whether the caller may change the row from the active channel: it holds the update permission
+     * here and on every other store holding the row, and, in a member store, a `SHARED` row is
+     * changed only in its organization's workspace, by everyone (a write from the store is refused
+     * `MANAGED_BY_ORGANIZATION`). A store's own values on a shared row (its prices, its exclusion)
+     * stay the store's to change. Disable an edit form on `false`; the engine refuses it anyway.
+     */
+    editableHere: boolean;
+}
+/** `catalogueOwnership` on the top-level row of each catalogue read (never on nested refs). */
+export declare const CATALOGUE_OWNERSHIP_FIELDS = "\n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n";
+export declare const ASSET_REF_FIELDS = "\n  id\n  name\n  preview\n  source\n";
+export declare const FACET_VALUE_REF_FIELDS = "\n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n";
+/**
+ * Refuse a datetime with no offset, or one that is not a date at all (spec
+ * §9.3). Returns the value unchanged — the engine stores the instant, and
+ * re-serialising it here would only risk changing its precision.
+ */
+export declare function assertInstant(field: string, value: string | null | undefined): void;
+/**
+ * Split an availability input into the custom fields the Admin API takes. Only
+ * PRESENT keys are copied — an omitted field must reach the server as omitted,
+ * never as null, or a partial update would clear it.
+ */
+export declare function availabilityCustomFields<State extends string>(input: AvailabilityInput<State>): Record<string, unknown>;
+/** Vendure's `DeletionResponse`. */
+export interface DeletionResponse {
+    result: 'DELETED' | 'NOT_DELETED';
+    message?: string | null;
+}
+export declare const DELETION_FIELDS = "\n  result\n  message\n";
+/**
+ * `NOT_DELETED` arrives at HTTP 200 with no error, so a caller awaiting a void
+ * promise would read a refusal as success. It becomes a `ConflictError`
+ * carrying the server's own sentence ("The FacetValue … is assigned to 3
+ * Products").
+ */
+export declare function assertDeleted(code: string, responses: DeletionResponse[]): void;
+/** Throw a Vendure ErrorResult (`MimeTypeError`, `ProductOptionInUseError`) as itself. */
+export declare function unwrapResult<T>(value: T | {
+    errorCode: string;
+    message: string;
+}): T;
+export declare const DEFAULT_PAGE_SIZE = 25;
+/** Vendure's `adminListQueryLimit` default; a larger `take` is refused by the engine. */
+export declare const MAX_PAGE_SIZE = 1000;
+/**
+ * Wrap one of Vendure's `skip/take` lists in a `Page<T>`. The offset hides
+ * inside the cursor (spec §9.3), and every following page re-sends the same
+ * filter, sort and per-call options — a page that forgot its tenant would walk
+ * another store's catalogue.
+ */
+export declare function vendureListPage<W, T = W>(transport: Transport, document: string, field: string, variables: (skip: number, take: number) => Record<string, unknown>, options: ListOptions | undefined, map?: (wire: W) => T): Promise<Page<T>>;
+/**
+ * Run one Admin API document and answer its single root field — the shape of
+ * almost every catalog call. The field is read by NAME from the response, so a
+ * document and its field name must be kept in step: an ABSENT field is refused
+ * rather than answered as `undefined` (a null one is a real answer), and
+ * `catalog-call-sites.spec.ts` drives every call site with a responder keyed
+ * on the document's own root field.
+ */
+export declare function fieldOf<T>(transport: Transport, document: string, field: string, variables: Record<string, unknown>, options: Call | undefined): Promise<T>;

package/dist/catalog/types.js

@@ -0,0 +1,141 @@
+import { ConflictError, errorFromErrorResult, isErrorResult, pageFromVendureList, readOffsetCursor, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+/** `catalogueOwnership` on the top-level row of each catalogue read (never on nested refs). */
+export const CATALOGUE_OWNERSHIP_FIELDS = /* GraphQL */ `
+  catalogueOwnership {
+    state
+    organizationName
+    editableHere
+  }
+`;
+export const ASSET_REF_FIELDS = /* GraphQL */ `
+  id
+  name
+  preview
+  source
+`;
+export const FACET_VALUE_REF_FIELDS = /* GraphQL */ `
+  id
+  code
+  name
+  facet {
+    id
+    code
+    name
+  }
+`;
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+/**
+ * Refuse a datetime with no offset, or one that is not a date at all (spec
+ * §9.3). Returns the value unchanged — the engine stores the instant, and
+ * re-serialising it here would only risk changing its precision.
+ */
+export function assertInstant(field, value) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === 'string' && INSTANT.test(value) && !Number.isNaN(Date.parse(value)))
+        return;
+    throw new ValidationError({
+        code: 'INVALID_DATETIME',
+        message: `${field} must be an ISO-8601 instant with an explicit offset, such as "2026-10-01T09:00:00+02:00" or "2026-10-01T07:00:00Z"; got ${JSON.stringify(value)}.`,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'INVALID_DATETIME', message: 'An offset (Z or ±HH:mm) is required.' }],
+    });
+}
+/**
+ * Split an availability input into the custom fields the Admin API takes. Only
+ * PRESENT keys are copied — an omitted field must reach the server as omitted,
+ * never as null, or a partial update would clear it.
+ */
+export function availabilityCustomFields(input) {
+    assertInstant('availableFrom', input.availableFrom);
+    const fields = {};
+    if (input.availabilityState !== undefined)
+        fields.availabilityState = input.availabilityState;
+    if (input.availableFrom !== undefined)
+        fields.availableFrom = input.availableFrom;
+    if (input.preorderLimit !== undefined)
+        fields.preorderLimit = input.preorderLimit;
+    return fields;
+}
+export const DELETION_FIELDS = /* GraphQL */ `
+  result
+  message
+`;
+/**
+ * `NOT_DELETED` arrives at HTTP 200 with no error, so a caller awaiting a void
+ * promise would read a refusal as success. It becomes a `ConflictError`
+ * carrying the server's own sentence ("The FacetValue … is assigned to 3
+ * Products").
+ */
+export function assertDeleted(code, responses) {
+    const refused = responses.filter((response) => response.result !== 'DELETED');
+    if (refused.length === 0)
+        return;
+    throw new ConflictError({
+        code,
+        message: refused.map((response) => response.message ?? 'The server gave no reason.').join('; '),
+        status: 409,
+        service: 'vendure',
+    });
+}
+/** Throw a Vendure ErrorResult (`MimeTypeError`, `ProductOptionInUseError`) as itself. */
+export function unwrapResult(value) {
+    if (isErrorResult(value))
+        throw errorFromErrorResult(value);
+    return value;
+}
+export const DEFAULT_PAGE_SIZE = 25;
+/** Vendure's `adminListQueryLimit` default; a larger `take` is refused by the engine. */
+export const MAX_PAGE_SIZE = 1000;
+/**
+ * Wrap one of Vendure's `skip/take` lists in a `Page<T>`. The offset hides
+ * inside the cursor (spec §9.3), and every following page re-sends the same
+ * filter, sort and per-call options — a page that forgot its tenant would walk
+ * another store's catalogue.
+ */
+export async function vendureListPage(transport, document, field, variables, options, map = (wire) => wire) {
+    const take = options?.limit ?? DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(take) || take < 1 || take > MAX_PAGE_SIZE) {
+        throw new ValidationError({
+            code: 'INVALID_PAGE_SIZE',
+            message: `limit must be a whole number from 1 to ${String(MAX_PAGE_SIZE)}; got ${String(take)}.`,
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    const fetchPage = async (skip) => {
+        const data = await transport.graphql({ api: 'admin', query: document, variables: variables(skip, take) }, options);
+        const list = data[field];
+        if (!list) {
+            throw new UpstreamError({
+                code: 'UNEXPECTED_RESPONSE',
+                message: `The engine answered without "${field}".`,
+                status: 502,
+                service: 'vendure',
+            });
+        }
+        return pageFromVendureList({ items: list.items.map(map), totalItems: list.totalItems }, skip, take, (cursor) => fetchPage(readOffsetCursor(cursor)));
+    };
+    return fetchPage(options?.after === undefined ? 0 : readOffsetCursor(options.after));
+}
+/**
+ * Run one Admin API document and answer its single root field — the shape of
+ * almost every catalog call. The field is read by NAME from the response, so a
+ * document and its field name must be kept in step: an ABSENT field is refused
+ * rather than answered as `undefined` (a null one is a real answer), and
+ * `catalog-call-sites.spec.ts` drives every call site with a responder keyed
+ * on the document's own root field.
+ */
+export async function fieldOf(transport, document, field, variables, options) {
+    const data = await transport.graphql({ api: 'admin', query: document, variables }, options);
+    if (data === null || typeof data !== 'object' || !Object.hasOwn(data, field)) {
+        throw new UpstreamError({
+            code: 'UNEXPECTED_RESPONSE',
+            message: `The engine answered without "${field}".`,
+            status: 502,
+            service: 'vendure',
+        });
+    }
+    return data[field];
+}