@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/catalog/index.d.ts

@@ -0,0 +1,115 @@
+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 FacetsModule } from './facets.js';
+import { type OptionsModule } from './options.js';
+import { type ProductsModule } from './products.js';
+import { type ContentFacetSyncResult, type PropertiesModule } from './properties.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 and product properties — 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
+ * are NOT one transaction: a failure part-way leaves the earlier writes in
+ * place. `products.save(input)` as one atomic intent operation is a later
+ * phase (spec §7, phase 6); until then, order your writes so a retry of the
+ * remainder is safe, and read back before retrying a create.
+ *
+ * **Idempotency.** No catalogue mutation deduplicates on `idempotencyKey`
+ * except `products.bulk`: elsewhere the key is sent and acts on nothing (see
+ * `Call`), so repeating a `create` makes a second product. Updates and deletes
+ * are naturally repeatable.
+ *
+ * **Lists** are `Page<T>` over the Admin API's `skip/take` (`limit` 1–1000,
+ * default 25). Every following page re-sends the same filter and the same
+ * per-call tenant.
+ *
+ * **Money** is integer minor units; a price input states its basis
+ * (`priceBasis`), and a basis other than the store's is refused rather than
+ * converted — see `catalog.variants`.
+ *
+ * **Time** inputs (`availableFrom`) need an explicit offset; outputs are
+ * ISO-8601 UTC.
+ *
+ * **Errors.** Vendure's own refusals keep its words and its code: an unknown
+ * id is `NotFoundError` (`ENTITY_NOT_FOUND`), a rejected value `ValidationError`
+ * (`USER_INPUT_ERROR`), a missing permission `PermissionDeniedError`
+ * (`FORBIDDEN`). A delete the engine declines at HTTP 200 (`NOT_DELETED`)
+ * becomes a `ConflictError` named `<RESOURCE>_NOT_DELETED` carrying the
+ * engine's reason. Module-specific codes are listed on each namespace.
+ *
+ * **An organization's catalogue** (multi-region spec §5.4). Products, variants,
+ * collections, facets, assets, option groups and property values a member
+ * store holds from its organization's workspace are changed in the workspace
+ * only, by everyone, SuperAdmin included: a write from the store, or one that
+ * reaches such a row through a product, a parent collection or an option group
+ * link, is refused `MANAGED_BY_ORGANIZATION` (422 `BusinessRuleError`), and
+ * the message says where to make the change instead. Each catalogue read
+ * carries `catalogueOwnership` (see `CatalogueOwnership`; the property groups
+ * `properties.values.get` answers carry `editableHere`): show the row
+ * read-only while `editableHere` is false.
+ * What the store adds to such a row stays its own to change: its prices, its
+ * stock at its own locations, its own facet values on the product, its own
+ * collections under a workspace collection. Requires a platform release that
+ * serves `catalogueOwnership` and `PropertyGroup.editableHere`: against an older
+ * engine every call that answers such a row, writes included, fails as a whole
+ * and writes nothing.
+ */
+export interface CatalogModule {
+    products: ProductsModule;
+    variants: VariantsModule;
+    /** Option groups ("Size") and options ("M"): what a product's variants differ by. */
+    options: OptionsModule;
+    facets: FacetsModule;
+    collections: CollectionsModule;
+    assets: AssetsModule;
+    visibility: VisibilityModule;
+    properties: PropertiesModule;
+    /**
+     * "Sync filter values" for one filterable `content_item` or `product` property, done by the
+     * engine (headless spec §7 `catalog.syncContentFacets`, by property, the unit the merchant syncs).
+     * Every filter value the property's values name gets its CURRENT label: a content item's title
+     * (read by the engine from the store's CMS content, drafts and archived items included), a
+     * product's name in the request's language. A `content_item` property whose SAVED configuration
+     * names fields to filter by also has its field-level facets brought in line with the items'
+     * field values: what the property was saved with decides, never an unsaved form. The store's
+     * products' filter assignments follow their property values, and a value no product names any
+     * more is removed.
+     *
+     * One transaction: the labels and the field facets are written together, or not at all. The
+     * labels are read first, so a content system that cannot be read refuses the call before
+     * 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).
+     *
+     * Needs `UpdateCatalog`. Platform releases before this method do not have the mutation and refuse
+     * it as `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400).
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `PROPERTY_NOT_FOUND` → `NotFoundError` (404): no property with that id among this store's
+     *   own (another store's included); `ENTITY_NOT_FOUND` (404) for an id that is not an id.
+     * - `PROPERTY_FACET_SYNC_INVALID` → `ValidationError` (400): the property is not filterable, or
+     *   is neither a `content_item` nor a `product` property.
+     * - `MANAGED_BY_ORGANIZATION` → `BusinessRuleError` (422): a property of the store's
+     *   organization workspace (`editableHere` false), or one whose filter values the workspace
+     *   holds: sync it in the workspace.
+     * - `SHARED_FACET_NOT_ALLOWED` / `SHARED_PRODUCT_NOT_ALLOWED` → `PermissionDeniedError` (403):
+     *   the property's filter, or a product it re-assigns, is also another store's, and you cannot
+     *   change that store's catalogue.
+     * - `CMS_REQUEST_FAILED` → `BusinessRuleError` (422): the content system could not be read
+     *   (unreachable, too slow, failing); try again.
+     * - `PROPERTY_SYNC_SOURCE_UNAVAILABLE` → `BusinessRuleError` (422): a `content_item` property on
+     *   a platform with no content system wired.
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): no `UpdateCatalog`.
+     */
+    syncContentFacets(propertyId: string, options?: Call): Promise<ContentFacetSyncResult>;
+}
+export declare function createCatalogModule(transport: Transport): CatalogModule;

package/dist/catalog/index.js

@@ -0,0 +1,21 @@
+import { createAssetsModule } from './assets.js';
+import { createCollectionsModule } from './collections.js';
+import { createFacetsModule } from './facets.js';
+import { createOptionsModule } from './options.js';
+import { createProductsModule } from './products.js';
+import { createPropertiesModule, syncContentFacets, } from './properties.js';
+import { createVariantsModule } from './variants.js';
+import { createVisibilityModule } from './visibility.js';
+export function createCatalogModule(transport) {
+    return {
+        products: createProductsModule(transport),
+        variants: createVariantsModule(transport),
+        options: createOptionsModule(transport),
+        facets: createFacetsModule(transport),
+        collections: createCollectionsModule(transport),
+        assets: createAssetsModule(transport),
+        visibility: createVisibilityModule(transport),
+        properties: createPropertiesModule(transport),
+        syncContentFacets: (propertyId, options) => syncContentFacets(transport, propertyId, options),
+    };
+}

package/dist/catalog/options.d.ts

@@ -0,0 +1,89 @@
+import type { Page, Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import { type CatalogueOwnership, type LanguageCode, type TranslationInput } from './types.js';
+export interface ProductOption {
+    id: string;
+    code: string;
+    name: string;
+    groupId: string;
+    translations: Array<{
+        id: string;
+        languageCode: LanguageCode;
+        name: string;
+    }>;
+}
+/** "Size", "Colour": what a product's variants differ by. */
+export interface ProductOptionGroup {
+    id: string;
+    code: string;
+    name: string;
+    options: ProductOption[];
+    translations: Array<{
+        id: string;
+        languageCode: LanguageCode;
+        name: string;
+    }>;
+    /** The store's own option group, or its organization's; see {@link CatalogueOwnership}. */
+    catalogueOwnership: CatalogueOwnership;
+}
+export interface OptionTranslationInput extends TranslationInput {
+    name?: string;
+}
+export interface CreateOptionGroupInput {
+    code: string;
+    translations: OptionTranslationInput[];
+    /** Created with the group, in this order. */
+    options?: Array<{
+        code: string;
+        translations: OptionTranslationInput[];
+    }>;
+}
+export interface UpdateOptionGroupInput {
+    id: string;
+    code?: string;
+    translations?: OptionTranslationInput[];
+}
+export interface CreateOptionInput {
+    productOptionGroupId: string;
+    code: string;
+    translations: OptionTranslationInput[];
+}
+export interface UpdateOptionInput {
+    id: string;
+    code?: string;
+    translations?: OptionTranslationInput[];
+}
+/**
+ * Option groups and their options. A group is attached to a product with
+ * `catalog.products.addOptionGroup`, and each variant then names one option per
+ * group (`optionIds`).
+ *
+ * Deletion refusals carry the engine's words: "Cannot delete the option group
+ * "{code}" as it is assigned to N Products" (unless `force`) and "Cannot delete
+ * the option "{code}" as it is being used by N ProductVariants" — both as
+ * `ConflictError` (`OPTION_GROUP_NOT_DELETED` / `OPTION_NOT_DELETED`).
+ */
+export interface OptionsModule {
+    groups: {
+        list(options?: ListOptions): Promise<Page<ProductOptionGroup>>;
+        get(id: string, options?: Call): Promise<ProductOptionGroup | null>;
+        create(input: CreateOptionGroupInput, options?: Call): Promise<ProductOptionGroup>;
+        update(input: UpdateOptionGroupInput, options?: Call): Promise<ProductOptionGroup>;
+        delete(id: string, options?: Call & {
+            force?: boolean;
+        }): Promise<void>;
+    };
+    create(input: CreateOptionInput, options?: Call): Promise<ProductOption>;
+    update(input: UpdateOptionInput, options?: Call): Promise<ProductOption>;
+    delete(id: string, options?: Call): Promise<void>;
+}
+export declare const OPTION_GROUP_FIELDS = "\n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  code\n  name\n  options { \n  id\n  code\n  name\n  groupId\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n";
+export declare const OPTION_GROUPS_QUERY = "\n  query CatalogOptionGroups($options: ProductOptionGroupListOptions) {\n    productOptionGroups(options: $options) {\n      items { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  code\n  name\n  options { \n  id\n  code\n  name\n  groupId\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n      totalItems\n    }\n  }\n";
+export declare const OPTION_GROUP_QUERY = "\n  query CatalogOptionGroup($id: ID!) {\n    productOptionGroup(id: $id) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  code\n  name\n  options { \n  id\n  code\n  name\n  groupId\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  }\n";
+export declare const CREATE_OPTION_GROUP_MUTATION = "\n  mutation CatalogCreateOptionGroup($input: CreateProductOptionGroupInput!) {\n    createProductOptionGroup(input: $input) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  code\n  name\n  options { \n  id\n  code\n  name\n  groupId\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  }\n";
+export declare const UPDATE_OPTION_GROUP_MUTATION = "\n  mutation CatalogUpdateOptionGroup($input: UpdateProductOptionGroupInput!) {\n    updateProductOptionGroup(input: $input) { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  code\n  name\n  options { \n  id\n  code\n  name\n  groupId\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  }\n";
+export declare const DELETE_OPTION_GROUP_MUTATION = "\n  mutation CatalogDeleteOptionGroup($id: ID!, $force: Boolean) {\n    deleteProductOptionGroup(id: $id, force: $force) { \n  result\n  message\n }\n  }\n";
+export declare const CREATE_OPTION_MUTATION = "\n  mutation CatalogCreateOption($input: CreateProductOptionInput!) {\n    createProductOption(input: $input) { \n  id\n  code\n  name\n  groupId\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  }\n";
+export declare const UPDATE_OPTION_MUTATION = "\n  mutation CatalogUpdateOption($input: UpdateProductOptionInput!) {\n    updateProductOption(input: $input) { \n  id\n  code\n  name\n  groupId\n  translations {\n    id\n    languageCode\n    name\n  }\n }\n  }\n";
+export declare const DELETE_OPTION_MUTATION = "\n  mutation CatalogDeleteOption($id: ID!) {\n    deleteProductOption(id: $id) { \n  result\n  message\n }\n  }\n";
+export declare function createOptionsModule(transport: Transport): OptionsModule;

package/dist/catalog/options.js

@@ -0,0 +1,88 @@
+import { assertDeleted, CATALOGUE_OWNERSHIP_FIELDS, DELETION_FIELDS, fieldOf, vendureListPage, } from './types.js';
+const OPTION_FIELDS = /* GraphQL */ `
+  id
+  code
+  name
+  groupId
+  translations {
+    id
+    languageCode
+    name
+  }
+`;
+export const OPTION_GROUP_FIELDS = /* GraphQL */ `
+  id
+  ${CATALOGUE_OWNERSHIP_FIELDS}
+  code
+  name
+  options { ${OPTION_FIELDS} }
+  translations {
+    id
+    languageCode
+    name
+  }
+`;
+export const OPTION_GROUPS_QUERY = /* GraphQL */ `
+  query CatalogOptionGroups($options: ProductOptionGroupListOptions) {
+    productOptionGroups(options: $options) {
+      items { ${OPTION_GROUP_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const OPTION_GROUP_QUERY = /* GraphQL */ `
+  query CatalogOptionGroup($id: ID!) {
+    productOptionGroup(id: $id) { ${OPTION_GROUP_FIELDS} }
+  }
+`;
+export const CREATE_OPTION_GROUP_MUTATION = /* GraphQL */ `
+  mutation CatalogCreateOptionGroup($input: CreateProductOptionGroupInput!) {
+    createProductOptionGroup(input: $input) { ${OPTION_GROUP_FIELDS} }
+  }
+`;
+export const UPDATE_OPTION_GROUP_MUTATION = /* GraphQL */ `
+  mutation CatalogUpdateOptionGroup($input: UpdateProductOptionGroupInput!) {
+    updateProductOptionGroup(input: $input) { ${OPTION_GROUP_FIELDS} }
+  }
+`;
+export const DELETE_OPTION_GROUP_MUTATION = /* GraphQL */ `
+  mutation CatalogDeleteOptionGroup($id: ID!, $force: Boolean) {
+    deleteProductOptionGroup(id: $id, force: $force) { ${DELETION_FIELDS} }
+  }
+`;
+export const CREATE_OPTION_MUTATION = /* GraphQL */ `
+  mutation CatalogCreateOption($input: CreateProductOptionInput!) {
+    createProductOption(input: $input) { ${OPTION_FIELDS} }
+  }
+`;
+export const UPDATE_OPTION_MUTATION = /* GraphQL */ `
+  mutation CatalogUpdateOption($input: UpdateProductOptionInput!) {
+    updateProductOption(input: $input) { ${OPTION_FIELDS} }
+  }
+`;
+export const DELETE_OPTION_MUTATION = /* GraphQL */ `
+  mutation CatalogDeleteOption($id: ID!) {
+    deleteProductOption(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+export function createOptionsModule(transport) {
+    const call = (document, field, variables, options) => fieldOf(transport, document, field, variables, options);
+    return {
+        groups: {
+            list: (options) => vendureListPage(transport, OPTION_GROUPS_QUERY, 'productOptionGroups', (skip, take) => ({ options: { skip, take } }), options),
+            get: (id, options) => call(OPTION_GROUP_QUERY, 'productOptionGroup', { id }, options),
+            create: (input, options) => call(CREATE_OPTION_GROUP_MUTATION, 'createProductOptionGroup', { input }, options),
+            update: (input, options) => call(UPDATE_OPTION_GROUP_MUTATION, 'updateProductOptionGroup', { input }, options),
+            async delete(id, options) {
+                const response = await call(DELETE_OPTION_GROUP_MUTATION, 'deleteProductOptionGroup', { id, force: options?.force ?? false }, options);
+                assertDeleted('OPTION_GROUP_NOT_DELETED', [response]);
+            },
+        },
+        create: (input, options) => call(CREATE_OPTION_MUTATION, 'createProductOption', { input }, options),
+        update: (input, options) => call(UPDATE_OPTION_MUTATION, 'updateProductOption', { input }, options),
+        async delete(id, options) {
+            const response = await call(DELETE_OPTION_MUTATION, 'deleteProductOption', { id }, options);
+            assertDeleted('OPTION_NOT_DELETED', [response]);
+        },
+    };
+}

package/dist/catalog/products-bulk.d.ts

@@ -0,0 +1,21 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import { type BulkActionRun } from '../jobs/bulk-action-run.js';
+import type { JobHandle } from '../jobs/index.js';
+import type { Call } from '../types.js';
+/** What each product of one bulk run gets: switched on or off, deleted, or copied. */
+export type ProductBulkAction = 'ENABLE' | 'DISABLE' | 'DELETE' | 'CLONE';
+export declare const PRODUCT_BULK_ACTIONS: readonly ProductBulkAction[];
+/** The engine's bound on one bulk run (`MAX_BULK_ACTION_ITEMS`). Split a larger selection. */
+export declare const MAX_BULK_PRODUCTS = 50;
+export interface ProductBulkInput {
+    action: ProductBulkAction;
+    /** 1 to {@link MAX_BULK_PRODUCTS} products of the store, each named once. */
+    productIds: readonly string[];
+}
+/** A bulk product run, as `wait()` and `bulkRun()` answer it. */
+export type ProductBulkRun = BulkActionRun<ProductBulkAction>;
+export declare const BULK_PRODUCT_ACTION_MUTATION = "\n  mutation BulkProductAction($input: BulkProductActionInput!, $idempotencyKey: String) {\n    bulkProductAction(input: $input, idempotencyKey: $idempotencyKey) {\n      runId\n    }\n  }\n";
+/** `catalog.products.bulk`; see `ProductsModule.bulk`. */
+export declare function bulkProducts(transport: Transport, input: ProductBulkInput, options?: Call): Promise<JobHandle<ProductBulkRun>>;
+/** `catalog.products.bulkRun`; see `ProductsModule.bulkRun`. */
+export declare function readProductBulkRun(transport: Transport, runId: string, options?: Call): Promise<ProductBulkRun>;

package/dist/catalog/products-bulk.js

@@ -0,0 +1,58 @@
+import { idempotencyKey, ValidationError } from '@sixtyninecommerce/core';
+import { bulkActionHandle, readBulkActionRun, } from '../jobs/bulk-action-run.js';
+import { fieldOf } from './types.js';
+export const PRODUCT_BULK_ACTIONS = [
+    'ENABLE',
+    'DISABLE',
+    'DELETE',
+    'CLONE',
+];
+/** The engine's bound on one bulk run (`MAX_BULK_ACTION_ITEMS`). Split a larger selection. */
+export const MAX_BULK_PRODUCTS = 50;
+export const BULK_PRODUCT_ACTION_MUTATION = /* GraphQL */ `
+  mutation BulkProductAction($input: BulkProductActionInput!, $idempotencyKey: String) {
+    bulkProductAction(input: $input, idempotencyKey: $idempotencyKey) {
+      runId
+    }
+  }
+`;
+function refuse(message) {
+    return new ValidationError({
+        code: 'BULK_ACTION_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+/** The engine's own checks of a submit (`BULK_ACTION_INPUT_INVALID`), before sending. */
+function assertBulkInput(input) {
+    if (!PRODUCT_BULK_ACTIONS.includes(input?.action)) {
+        throw refuse(`"${String(input?.action)}" is not a bulk product action: ${PRODUCT_BULK_ACTIONS.join(', ')}. Nothing was sent.`);
+    }
+    const ids = input.productIds;
+    if (!Array.isArray(ids) || ids.length === 0) {
+        throw refuse('Name at least one product. Nothing was sent.');
+    }
+    if (ids.length > MAX_BULK_PRODUCTS) {
+        throw refuse(`Name at most ${String(MAX_BULK_PRODUCTS)} products in one bulk action; this one named ${String(ids.length)}. Split the selection into several actions. Nothing was sent.`);
+    }
+    if (new Set(ids.map((id) => String(id).toLowerCase())).size !== ids.length) {
+        throw refuse('The selection names a product more than once. Name each product once. Nothing was sent.');
+    }
+}
+/** `catalog.products.bulk`; see `ProductsModule.bulk`. */
+export async function bulkProducts(transport, input, options) {
+    assertBulkInput(input);
+    // Minted when the caller gave none, so a retry of THIS call by the transport or the caller's
+    // own code under the same options answers the same run instead of starting a second one.
+    const key = options?.idempotencyKey ?? idempotencyKey();
+    const { runId } = await fieldOf(transport, BULK_PRODUCT_ACTION_MUTATION, 'bulkProductAction', {
+        input: { action: input.action, productIds: [...input.productIds] },
+        idempotencyKey: key,
+    }, { ...options, idempotencyKey: key });
+    return bulkActionHandle(transport, runId, options);
+}
+/** `catalog.products.bulkRun`; see `ProductsModule.bulkRun`. */
+export function readProductBulkRun(transport, runId, options) {
+    return readBulkActionRun(transport, runId, options);
+}