@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/search/index.d.ts

@@ -1,4 +1,4 @@
-import type { Transport } from '@sixtyninecommerce/core';
+import { type Transport } from '@sixtyninecommerce/core';
 import type { Call } from '../types.js';
 /** What `admin.search.entities` searches. */
 export type SearchEntityType = 'PRODUCTS' | 'ORDERS' | 'CUSTOMERS' | 'CONTENT';
@@ -76,6 +76,55 @@ export interface SearchEntitiesOptions extends Call {
 export declare const SEARCH_ENTITIES_MIN_TERM_LENGTH = 2;
 export declare const SEARCH_ENTITIES_MAX_TAKE = 10;
 export declare const SEARCH_ACROSS_ENTITIES_QUERY = "\n  query SearchAcrossEntities($input: CommandSearchInput!) {\n    searchAcrossEntities(input: $input) {\n      products {\n        id\n        name\n        slug\n        previewUrl\n      }\n      orders {\n        id\n        code\n        state\n        orderPlacedAt\n        totalWithTax\n        currencyCode\n        lifecycleStatus\n      }\n      customers {\n        id\n        firstName\n        lastName\n        emailAddress\n        company\n      }\n      content {\n        id\n        collectionId\n        collectionSlug\n        slug\n        status\n        title\n      }\n      skipped {\n        type\n        reason\n      }\n    }\n  }\n";
+/**
+ * The store's search indexes `search.index` reads, one per kind of record. Each holds the store's
+ * rows of that kind; the products index is the admin catalogue index, not the storefront's.
+ */
+export declare const SEARCH_INDEXES: readonly ["products", "orders", "customers", "facets", "promotions", "customer_groups", "stock_locations", "collections"];
+export type SearchIndex = (typeof SEARCH_INDEXES)[number];
+/** The engine's bound on the clauses of one `search.index` call, `filters` and groups together. */
+export declare const SEARCH_INDEX_MAX_FILTERS = 32;
+export interface SearchIndexInput {
+    /** Full text; `''` matches every row the filters keep. */
+    term: string;
+    /**
+     * Clauses, all of which must hold, each one of exactly these shapes on an attribute the index
+     * lets you filter on: `field = "value"`, `field = true|false`, `field STARTS WITH "value"`,
+     * `field CONTAINS "value"`, `field IN ["a", "b"]`, `field IS EMPTY`. Quote a string value with
+     * {@link escapeSearchFilterValue}: `code STARTS WITH "${escapeSearchFilterValue(prefix)}"`.
+     */
+    filters?: readonly string[];
+    /** Groups of clauses: each group must hold, and holds when ANY of its own clauses does. */
+    filterGroups?: ReadonlyArray<readonly string[]>;
+    /** `field` ascending or `-field` descending, on a field the index sorts by; relevance otherwise. */
+    sort?: string;
+    /** Rows to skip, 0 when omitted. */
+    skip?: number;
+    /** Rows to answer, 25 when omitted. */
+    take?: number;
+}
+/** One hit: the record's id, how well it matched, and the index's copy of it. */
+export interface SearchIndexHit {
+    id: string;
+    /** The search engine's ranking score, 0 to 1: higher is a better match. */
+    score: number;
+    /**
+     * The index's snapshot of the record, as the store may see it: written by a job after the
+     * record's change commits, so it can lag by seconds. Read the record itself for current values.
+     */
+    document: Record<string, unknown>;
+}
+export interface SearchIndexResult {
+    items: SearchIndexHit[];
+    /** Every hit the term and filters match, not only this page's. */
+    total: number;
+}
+export declare const SEARCH_ENTITIES_QUERY = "\n  query SearchIndex($input: EntitySearchInput!) {\n    searchEntities(input: $input) {\n      items {\n        id\n        score\n        document\n      }\n      totalItems\n    }\n  }\n";
+/**
+ * A string value inside a `search.index` filter's double quotes: its backslashes and quotes
+ * escaped, so what a person typed can never close the literal and add a clause.
+ */
+export declare function escapeSearchFilterValue(value: string): string;
 /**
  * One search across the store (spec §7 `search.entities`): products, orders, customers and
  * content items matching a term, in one call.
@@ -94,6 +143,32 @@ export declare const SEARCH_ACROSS_ENTITIES_QUERY = "\n  query SearchAcrossEntit
  * outside 1..{@link SEARCH_ENTITIES_MAX_TAKE}, or an empty `types` list.
  */
 export interface SearchModule {
+    /** @effect read */
     entities(term: string, options?: SearchEntitiesOptions): Promise<EntitySearchResult>;
+    /**
+     * One page of one search index of the store: hits in relevance order (or `sort`'s), each with
+     * the index's copy of the record. Use it to find ids by text or by an indexed attribute the
+     * record's own list cannot filter on, then read the records themselves.
+     *
+     * - **The store is always the one you act on**: no filter reaches another store's rows.
+     * - **Documents are index snapshots**, updated by a job after each change: read the record for
+     *   current values, and expect a just-written record to be missing for a few seconds.
+     * - Needs the read permission of the index's own list: `ReadCatalog` or `ReadProduct` for
+     *   products; `ReadOrder` for orders; `ReadCustomer` for customers; `ReadCustomer` or
+     *   `ReadCustomerGroup` for customer groups; `ReadCatalog`, `ReadProduct` or `ReadFacet` for
+     *   facets; `ReadPromotion`; `ReadCatalog` or `ReadStockLocation`; `ReadCatalog` or
+     *   `ReadCollection`. Without it: `PermissionDeniedError`.
+     * - An app reading customer data below `full` is refused the orders and customers indexes
+     *   (`CUSTOMER_DATA_NOT_GRANTED`): the hits alone would say which customer matches a name.
+     *
+     * Refused: an index not in {@link SEARCH_INDEXES} (`ValidationError` `SEARCH_INPUT_INVALID`, before
+     * anything is asked); and by the engine with `SEARCH_INPUT_INVALID` (400) a clause on an attribute
+     * the index does not filter on or in another syntax, more than {@link SEARCH_INDEX_MAX_FILTERS}
+     * clauses, or a negative `skip`/`take`. A `sort` field the index cannot sort on is ignored.
+     * `SERVICE_UNAVAILABLE` (503, retryable) when the search service did not answer.
+     *
+     * @effect read
+     */
+    index(index: SearchIndex, input: SearchIndexInput, options?: Call): Promise<SearchIndexResult>;
 }
 export declare function createSearchModule(transport: Transport): SearchModule;

package/dist/search/index.js

@@ -1,3 +1,4 @@
+import { ValidationError } from '@sixtyninecommerce/core';
 /** The engine's bounds, as `searchAcrossEntities` documents them. */
 export const SEARCH_ENTITIES_MIN_TERM_LENGTH = 2;
 export const SEARCH_ENTITIES_MAX_TAKE = 10;
@@ -41,6 +42,41 @@ export const SEARCH_ACROSS_ENTITIES_QUERY = /* GraphQL */ `
     }
   }
 `;
+/**
+ * The store's search indexes `search.index` reads, one per kind of record. Each holds the store's
+ * rows of that kind; the products index is the admin catalogue index, not the storefront's.
+ */
+export const SEARCH_INDEXES = [
+    'products',
+    'orders',
+    'customers',
+    'facets',
+    'promotions',
+    'customer_groups',
+    'stock_locations',
+    'collections',
+];
+/** The engine's bound on the clauses of one `search.index` call, `filters` and groups together. */
+export const SEARCH_INDEX_MAX_FILTERS = 32;
+export const SEARCH_ENTITIES_QUERY = /* GraphQL */ `
+  query SearchIndex($input: EntitySearchInput!) {
+    searchEntities(input: $input) {
+      items {
+        id
+        score
+        document
+      }
+      totalItems
+    }
+  }
+`;
+/**
+ * A string value inside a `search.index` filter's double quotes: its backslashes and quotes
+ * escaped, so what a person typed can never close the literal and add a clause.
+ */
+export function escapeSearchFilterValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
 export function createSearchModule(transport) {
     return {
         async entities(term, options = {}) {
@@ -58,5 +94,32 @@ export function createSearchModule(transport) {
             }, call);
             return data.searchAcrossEntities;
         },
+        async index(index, input, options) {
+            if (!SEARCH_INDEXES.includes(index)) {
+                throw new ValidationError({
+                    code: 'SEARCH_INPUT_INVALID',
+                    message: `The search index must be one of ${SEARCH_INDEXES.join(', ')}.`,
+                    status: 400,
+                    service: 'vendure',
+                });
+            }
+            const { term, filters, filterGroups, sort, skip, take } = input;
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SEARCH_ENTITIES_QUERY,
+                variables: {
+                    input: {
+                        term,
+                        entityType: index,
+                        ...(take === undefined ? {} : { take }),
+                        ...(skip === undefined ? {} : { skip }),
+                        ...(sort === undefined || sort === '' ? {} : { sort }),
+                        ...(filters?.length ? { filters: [...filters] } : {}),
+                        ...(filterGroups?.length ? { filterGroups: filterGroups.map((g) => [...g]) } : {}),
+                    },
+                },
+            }, options);
+            return { items: data.searchEntities.items, total: data.searchEntities.totalItems };
+        },
     };
 }

package/dist/shipping/definitions.d.ts

@@ -0,0 +1,29 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call, ConfigurableOperationDefinition } from '../types.js';
+/** What a shipping method's three operations may be, each with the arguments it takes. */
+export interface ShippingDefinitions {
+    /** What a method's `calculator` may be: how it prices an order. */
+    calculators: ConfigurableOperationDefinition[];
+    /** What a method's `checker` may be: which orders it is offered for. */
+    eligibilityCheckers: ConfigurableOperationDefinition[];
+    /** What a method's `fulfillmentHandler` may be (`manual-fulfillment`, a carrier's handler). */
+    fulfillmentHandlers: ConfigurableOperationDefinition[];
+}
+/** `admin.shipping.definitions`. */
+export interface ShippingDefinitionsModule {
+    /**
+     * The calculators, eligibility checkers and fulfillment handlers the engine has registered, in
+     * one request: the same whichever store the client is on (a handler whose plugin the store does
+     * not hold is listed, and refused `PLUGIN_ACCESS_DENIED` when a method picks it). Labels and
+     * descriptions are in the language of the request. Needs `ReadSettings`, `ReadOrder` or
+     * `ReadShippingMethod` (any one).
+     *
+     * `args[].required` is NOT the enforced rule (see `ConfigArgDefinition.required`); never gate
+     * a form on it.
+     *
+     * @effect read
+     */
+    get(options?: Call): Promise<ShippingDefinitions>;
+}
+export declare const SHIPPING_DEFINITIONS_QUERY = "\n  query ShippingDefinitions {\n    shippingCalculators { \n  code\n  description\n  args {\n    name\n    type\n    list\n    required\n    defaultValue\n    label\n    description\n    ui\n  }\n }\n    shippingEligibilityCheckers { \n  code\n  description\n  args {\n    name\n    type\n    list\n    required\n    defaultValue\n    label\n    description\n    ui\n  }\n }\n    fulfillmentHandlers { \n  code\n  description\n  args {\n    name\n    type\n    list\n    required\n    defaultValue\n    label\n    description\n    ui\n  }\n }\n  }\n";
+export declare function createShippingDefinitionsModule(transport: Transport): ShippingDefinitionsModule;

package/dist/shipping/definitions.js

@@ -0,0 +1,47 @@
+import { UpstreamError } from '@sixtyninecommerce/core';
+const DEFINITION_FIELDS = /* GraphQL */ `
+  code
+  description
+  args {
+    name
+    type
+    list
+    required
+    defaultValue
+    label
+    description
+    ui
+  }
+`;
+export const SHIPPING_DEFINITIONS_QUERY = /* GraphQL */ `
+  query ShippingDefinitions {
+    shippingCalculators { ${DEFINITION_FIELDS} }
+    shippingEligibilityCheckers { ${DEFINITION_FIELDS} }
+    fulfillmentHandlers { ${DEFINITION_FIELDS} }
+  }
+`;
+export function createShippingDefinitionsModule(transport) {
+    return {
+        async get(options) {
+            const data = await transport.graphql({ api: 'admin', query: SHIPPING_DEFINITIONS_QUERY, variables: {} }, options);
+            // Each list is read by name, so a response missing one is refused, never answered empty.
+            const list = (field) => {
+                const value = data?.[field];
+                if (!Array.isArray(value)) {
+                    throw new UpstreamError({
+                        code: 'UNEXPECTED_RESPONSE',
+                        message: `The engine answered without "${field}".`,
+                        status: 502,
+                        service: 'vendure',
+                    });
+                }
+                return value;
+            };
+            return {
+                calculators: list('shippingCalculators'),
+                eligibilityCheckers: list('shippingEligibilityCheckers'),
+                fulfillmentHandlers: list('fulfillmentHandlers'),
+            };
+        },
+    };
+}

package/dist/shipping/fulfillment-profiles.d.ts

@@ -0,0 +1,174 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A store's fulfillment profile: a named binding of a warehouse, a fulfillment handler, a
+ * shipping method and a minimum order. A fulfilment created with a profile is judged against its
+ * minimum and charged its shipping method's delivery cost (`fulfillments.profileChargePreview`
+ * prices it beforehand).
+ */
+export interface FulfillmentProfile {
+    id: string;
+    /** Stable per store; unique within the store. */
+    code: string;
+    name: string;
+    /** A disabled profile is not offered when fulfilling an order. */
+    enabled: boolean;
+    /** The warehouse (stock location) the profile ships from. */
+    stockLocationId: string;
+    /** The fulfillment handler (carrier) code, e.g. `manual-fulfillment`. */
+    defaultHandlerCode: string;
+    /** The shipping method whose price is the profile's delivery charge. */
+    shippingMethodId: string;
+    /**
+     * The minimum a fulfilment's selected lines must reach, in MINOR units of the store's default
+     * currency, NET of tax. `0` is no minimum.
+     */
+    minOrder: number;
+    /** True for the store's default profile, the one storefront checkout applies. */
+    isDefault: boolean;
+    /** ISO-8601, UTC. */
+    createdAt: string;
+    /** ISO-8601, UTC. */
+    updatedAt: string;
+}
+export interface CreateFulfillmentProfileInput {
+    name: string;
+    code: string;
+    /** Default `true`. */
+    enabled?: boolean;
+    /** One of the store's own stock locations. */
+    stockLocationId: string;
+    defaultHandlerCode: string;
+    /** One of the store's own shipping methods. */
+    shippingMethodId: string;
+    /** Minor units, net, in the store's default currency. Default `0`. */
+    minOrder?: number;
+}
+/** A PATCH: a key left out keeps the stored value. */
+export interface UpdateFulfillmentProfileInput {
+    name?: string;
+    code?: string;
+    enabled?: boolean;
+    stockLocationId?: string;
+    defaultHandlerCode?: string;
+    shippingMethodId?: string;
+    minOrder?: number;
+}
+/**
+ * Who is emailed when a fulfilment is created with a handler, in this store. One record per
+ * handler; a handler with no record notifies nobody.
+ */
+export interface FulfillmentHandlerNotification {
+    id: string;
+    handlerCode: string;
+    /** Off pauses the mails without forgetting the recipients. */
+    enabled: boolean;
+    /** Trimmed, de-duplicated (case-insensitive) addresses, at most 25. */
+    emails: string[];
+    /** ISO-8601, UTC. */
+    createdAt: string;
+    /** ISO-8601, UTC. */
+    updatedAt: string;
+}
+export interface SetFulfillmentHandlerNotificationInput {
+    handlerCode: string;
+    /** Left out: `true` for a new record, unchanged for an existing one. */
+    enabled?: boolean;
+    /** The WHOLE list: it replaces the stored one. `[]` clears it. */
+    emails: string[];
+}
+/** `admin.shipping.fulfillmentProfiles.handlerNotifications`. */
+export interface FulfillmentHandlerNotificationsModule {
+    /**
+     * Every handler's recipients in the store, by handler code. Needs `ReadShippingMethod`.
+     *
+     * @effect read
+     * @permission ReadShippingMethod
+     */
+    list(options?: Call): Promise<FulfillmentHandlerNotification[]>;
+    /**
+     * Create or replace one handler's recipients. Needs `UpdateShippingMethod`. Refused, with
+     * nothing saved, for a blank handler code, an address that is not one, or more than 25
+     * addresses (`USER_INPUT_ERROR`, a `ValidationError`). The handler code is not checked against
+     * the store's handlers: a record for a handler nothing uses is kept and never mails.
+     *
+     * @effect write
+     * @permission UpdateShippingMethod
+     */
+    set(input: SetFulfillmentHandlerNotificationInput, options?: Call): Promise<FulfillmentHandlerNotification>;
+}
+/**
+ * `admin.shipping.fulfillmentProfiles`: the fulfillment profiles of the store the client is
+ * scoped to. There is no channel argument; another store is addressed with
+ * `admin.withTenant(...)`.
+ *
+ * A well-formed profile id the store does not have (another store's, or none at all) is refused
+ * on every write with `FULFILLMENT_PROFILE_NOT_FOUND` (`NotFoundError`, 404), worded the same
+ * either way, and `get` answers `null` for it. An id that is not a uuid is refused by the engine
+ * before any of that, on every method `get` included, with `ENTITY_NOT_FOUND` (`NotFoundError`).
+ */
+export interface FulfillmentProfilesModule {
+    /**
+     * Every profile of the store, oldest first. Needs `ReadShippingMethod`.
+     *
+     * @effect read
+     * @permission ReadShippingMethod
+     */
+    list(options?: Call): Promise<FulfillmentProfile[]>;
+    /**
+     * One profile, or `null` when the store has none with that id.
+     *
+     * @effect read
+     * @permission ReadShippingMethod
+     */
+    get(id: string, options?: Call): Promise<FulfillmentProfile | null>;
+    /**
+     * Create a profile. Needs `UpdateShippingMethod`. A warehouse or shipping method the store
+     * does not have is refused `ENTITY_NOT_FOUND` (`NotFoundError`), the same for another store's
+     * id as for one that exists nowhere.
+     *
+     * @effect write
+     * @permission UpdateShippingMethod
+     */
+    create(input: CreateFulfillmentProfileInput, options?: Call): Promise<FulfillmentProfile>;
+    /**
+     * Change a profile; a key left out keeps its value. Needs `UpdateShippingMethod`. Refused
+     * `FULFILLMENT_PROFILE_NOT_FOUND` for a profile the store does not have, and
+     * `ENTITY_NOT_FOUND` for a warehouse or shipping method it does not have. A changed minimum
+     * binds the next fulfilment; fulfilments already created keep what they were charged.
+     *
+     * @effect write
+     * @permission UpdateShippingMethod
+     */
+    update(id: string, input: UpdateFulfillmentProfileInput, options?: Call): Promise<FulfillmentProfile>;
+    /**
+     * Delete a profile for good. When it was the store's default the store is left with NO
+     * default profile, so checkout applies no profile minimum until another is set. Fulfilments
+     * already created with it are unchanged. Needs `UpdateShippingMethod`; refused
+     * `FULFILLMENT_PROFILE_NOT_FOUND` for a profile the store does not have.
+     *
+     * @effect destructive
+     * @permission UpdateShippingMethod
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * Make a profile the store's default (the one storefront checkout applies); answers it.
+     * Needs `UpdateShippingMethod`; refused `FULFILLMENT_PROFILE_NOT_FOUND` for a profile the
+     * store does not have.
+     *
+     * @effect write
+     * @permission UpdateShippingMethod
+     */
+    setDefault(id: string, options?: Call): Promise<FulfillmentProfile>;
+    /** Who is emailed when a fulfilment is created with a handler. */
+    handlerNotifications: FulfillmentHandlerNotificationsModule;
+}
+export declare const FULFILLMENT_PROFILES_QUERY = "\n  query FulfillmentProfiles {\n    fulfillmentProfiles { \n  id\n  code\n  name\n  enabled\n  stockLocationId\n  defaultHandlerCode\n  shippingMethodId\n  minOrder\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const FULFILLMENT_PROFILE_QUERY = "\n  query FulfillmentProfile($id: ID!) {\n    fulfillmentProfile(id: $id) { \n  id\n  code\n  name\n  enabled\n  stockLocationId\n  defaultHandlerCode\n  shippingMethodId\n  minOrder\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const CREATE_FULFILLMENT_PROFILE_MUTATION = "\n  mutation CreateFulfillmentProfile($input: CreateFulfillmentProfileInput!) {\n    createFulfillmentProfile(input: $input) { \n  id\n  code\n  name\n  enabled\n  stockLocationId\n  defaultHandlerCode\n  shippingMethodId\n  minOrder\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_FULFILLMENT_PROFILE_MUTATION = "\n  mutation UpdateFulfillmentProfile($input: UpdateFulfillmentProfileInput!) {\n    updateFulfillmentProfile(input: $input) { \n  id\n  code\n  name\n  enabled\n  stockLocationId\n  defaultHandlerCode\n  shippingMethodId\n  minOrder\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_FULFILLMENT_PROFILE_MUTATION = "\n  mutation DeleteFulfillmentProfile($id: ID!) {\n    deleteFulfillmentProfile(id: $id) { result message }\n  }\n";
+export declare const SET_DEFAULT_FULFILLMENT_PROFILE_MUTATION = "\n  mutation SetDefaultFulfillmentProfile($id: ID!) {\n    setDefaultFulfillmentProfile(id: $id) { \n  id\n  code\n  name\n  enabled\n  stockLocationId\n  defaultHandlerCode\n  shippingMethodId\n  minOrder\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const FULFILLMENT_HANDLER_NOTIFICATIONS_QUERY = "\n  query FulfillmentHandlerNotifications {\n    fulfillmentHandlerNotifications { \n  id\n  handlerCode\n  enabled\n  emails\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const SET_FULFILLMENT_HANDLER_NOTIFICATION_MUTATION = "\n  mutation SetFulfillmentHandlerNotification($input: SetFulfillmentHandlerNotificationInput!) {\n    setFulfillmentHandlerNotification(input: $input) { \n  id\n  handlerCode\n  enabled\n  emails\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare function createFulfillmentProfilesModule(transport: Transport): FulfillmentProfilesModule;

package/dist/shipping/fulfillment-profiles.js

@@ -0,0 +1,104 @@
+import { assertDeleted } from '../catalog/types.js';
+const PROFILE_FIELDS = /* GraphQL */ `
+  id
+  code
+  name
+  enabled
+  stockLocationId
+  defaultHandlerCode
+  shippingMethodId
+  minOrder
+  isDefault
+  createdAt
+  updatedAt
+`;
+const NOTIFICATION_FIELDS = /* GraphQL */ `
+  id
+  handlerCode
+  enabled
+  emails
+  createdAt
+  updatedAt
+`;
+export const FULFILLMENT_PROFILES_QUERY = /* GraphQL */ `
+  query FulfillmentProfiles {
+    fulfillmentProfiles { ${PROFILE_FIELDS} }
+  }
+`;
+export const FULFILLMENT_PROFILE_QUERY = /* GraphQL */ `
+  query FulfillmentProfile($id: ID!) {
+    fulfillmentProfile(id: $id) { ${PROFILE_FIELDS} }
+  }
+`;
+export const CREATE_FULFILLMENT_PROFILE_MUTATION = /* GraphQL */ `
+  mutation CreateFulfillmentProfile($input: CreateFulfillmentProfileInput!) {
+    createFulfillmentProfile(input: $input) { ${PROFILE_FIELDS} }
+  }
+`;
+export const UPDATE_FULFILLMENT_PROFILE_MUTATION = /* GraphQL */ `
+  mutation UpdateFulfillmentProfile($input: UpdateFulfillmentProfileInput!) {
+    updateFulfillmentProfile(input: $input) { ${PROFILE_FIELDS} }
+  }
+`;
+export const DELETE_FULFILLMENT_PROFILE_MUTATION = /* GraphQL */ `
+  mutation DeleteFulfillmentProfile($id: ID!) {
+    deleteFulfillmentProfile(id: $id) { result message }
+  }
+`;
+export const SET_DEFAULT_FULFILLMENT_PROFILE_MUTATION = /* GraphQL */ `
+  mutation SetDefaultFulfillmentProfile($id: ID!) {
+    setDefaultFulfillmentProfile(id: $id) { ${PROFILE_FIELDS} }
+  }
+`;
+export const FULFILLMENT_HANDLER_NOTIFICATIONS_QUERY = /* GraphQL */ `
+  query FulfillmentHandlerNotifications {
+    fulfillmentHandlerNotifications { ${NOTIFICATION_FIELDS} }
+  }
+`;
+export const SET_FULFILLMENT_HANDLER_NOTIFICATION_MUTATION = /* GraphQL */ `
+  mutation SetFulfillmentHandlerNotification($input: SetFulfillmentHandlerNotificationInput!) {
+    setFulfillmentHandlerNotification(input: $input) { ${NOTIFICATION_FIELDS} }
+  }
+`;
+export function createFulfillmentProfilesModule(transport) {
+    const call = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        async list(options) {
+            const data = await call(FULFILLMENT_PROFILES_QUERY, undefined, options);
+            return data.fulfillmentProfiles;
+        },
+        async get(id, options) {
+            const data = await call(FULFILLMENT_PROFILE_QUERY, { id }, options);
+            return data.fulfillmentProfile ?? null;
+        },
+        async create(input, options) {
+            const data = await call(CREATE_FULFILLMENT_PROFILE_MUTATION, { input }, options);
+            return data.createFulfillmentProfile;
+        },
+        async update(id, input, options) {
+            const data = await call(UPDATE_FULFILLMENT_PROFILE_MUTATION, 
+            // The id goes last: an `id` key smuggled into the patch cannot redirect the write.
+            { input: { ...input, id } }, options);
+            return data.updateFulfillmentProfile;
+        },
+        async delete(id, options) {
+            const data = await call(DELETE_FULFILLMENT_PROFILE_MUTATION, { id }, options);
+            // The engine refuses by throwing today; a NOT_DELETED answer must still never pass as done.
+            assertDeleted('FULFILLMENT_PROFILE_NOT_DELETED', [data.deleteFulfillmentProfile]);
+        },
+        async setDefault(id, options) {
+            const data = await call(SET_DEFAULT_FULFILLMENT_PROFILE_MUTATION, { id }, options);
+            return data.setDefaultFulfillmentProfile;
+        },
+        handlerNotifications: {
+            async list(options) {
+                const data = await call(FULFILLMENT_HANDLER_NOTIFICATIONS_QUERY, undefined, options);
+                return data.fulfillmentHandlerNotifications;
+            },
+            async set(input, options) {
+                const data = await call(SET_FULFILLMENT_HANDLER_NOTIFICATION_MUTATION, { input }, options);
+                return data.setFulfillmentHandlerNotification;
+            },
+        },
+    };
+}

package/dist/shipping/hendriks.d.ts

@@ -0,0 +1,97 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** How the order reference sent to C.J. Hendriks is prefixed. */
+export type HendriksWirePrefixMode = 'year' | 'custom';
+/** A store's C.J. Hendriks 3PL settings: one record per store. */
+export interface HendriksConfig {
+    id: string;
+    channelId: string;
+    /** Gates every Hendriks export of the store. */
+    enabled: boolean;
+    /** The plugins-service export pipeline that sends the orders; `null` is not linked. */
+    pipelineId: string | null;
+    /** `year` prefixes the current UTC year; `custom` prefixes {@link wirePrefixDigits}. */
+    wirePrefixMode: HendriksWirePrefixMode;
+    /** 1 to 4 digits without a leading zero. Only read in `custom` mode; `null` in `year` mode. */
+    wirePrefixDigits: string | null;
+    /**
+     * Refuse to export an order the source platform already sent to its own fulfillment
+     * provider. On by default: while a migrated shop is still live both systems feed the same
+     * warehouse, and neither can spot the other's reference, so the goods would ship twice.
+     */
+    blockSourceFulfilledOrders: boolean;
+    /** ISO-8601, UTC. */
+    createdAt: string;
+    /** ISO-8601, UTC. */
+    updatedAt: string;
+}
+/**
+ * A PATCH: a key left out keeps the stored value. The custom-prefix rule is judged on the
+ * RESULTING settings, so switching to `custom` needs `wirePrefixDigits` in the same call unless
+ * valid digits are already stored.
+ */
+export interface UpdateHendriksConfigInput {
+    enabled?: boolean;
+    /** `null` unlinks the pipeline. */
+    pipelineId?: string | null;
+    wirePrefixMode?: HendriksWirePrefixMode;
+    /** Cleared by the engine whenever the resulting mode is `year`. */
+    wirePrefixDigits?: string | null;
+    blockSourceFulfilledOrders?: boolean;
+}
+/**
+ * The C.J. Hendriks 3PL settings of the store the client is scoped to
+ * (`admin.shipping.hendriks.config`). There is no channel argument: a SuperAdmin head configures
+ * ANOTHER store with `admin.withTenant({ scope: { kind: 'channel', code } })`, or a per-call
+ * `tenant`.
+ */
+export interface HendriksConfigModule {
+    /**
+     * The store's settings, or `null` when it never saved any. Needs `ReadSettings`, and is
+     * answered for a store without the Hendriks plugin too (a head reads it to decide whether to
+     * show the integration).
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    get(options?: Call): Promise<HendriksConfig | null>;
+    /**
+     * Save the settings; the first call creates the record (`enabled` off, `year` prefix,
+     * `blockSourceFulfilledOrders` on, unless given). Needs `UpdateSettings`.
+     *
+     * Refused, with nothing saved:
+     * - `HENDRIKS_CONFIG_INVALID` (`ValidationError`, 400): `custom` mode without 1 to 4 digits not
+     *   starting with 0. `details[]` names each field (`wirePrefixDigits`, `wirePrefixMode`), so a
+     *   form can put the reason on it;
+     * - `PLUGIN_ACCESS_DENIED` (`PermissionDeniedError`, 403): the store does not hold the
+     *   Hendriks plugin. An ordinary caller only: the engine never refuses a SuperAdmin on this
+     *   ground, so a SuperAdmin head that must know reads `tenant.entitlements()` on that store;
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` (`BusinessRuleError`, 422): switching the export on,
+     *   or linking a pipeline, in an organization's workspace.
+     *
+     * `pipelineId` is not checked against the store's pipelines; an export through a pipeline
+     * that does not exist fails when it runs.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    update(input: UpdateHendriksConfigInput, options?: Call): Promise<HendriksConfig>;
+    /**
+     * Delete the store's settings record. Every Hendriks export of the store is refused until
+     * settings are saved again, and the prefix and pipeline link are gone with it. `true` when a
+     * record was deleted, `false` when the store had none. Needs `UpdateSettings`; allowed for a
+     * store that no longer holds the plugin, so it can always remove its connection.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    delete(options?: Call): Promise<boolean>;
+}
+/** `admin.shipping.hendriks`: the C.J. Hendriks 3PL integration of the store. */
+export interface HendriksModule {
+    config: HendriksConfigModule;
+}
+export declare const HENDRIKS_CONFIG_QUERY = "\n  query HendriksConfig {\n    hendriksConfig { \n  id\n  channelId\n  enabled\n  pipelineId\n  wirePrefixMode\n  wirePrefixDigits\n  blockSourceFulfilledOrders\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_HENDRIKS_CONFIG_MUTATION = "\n  mutation UpdateHendriksConfig($input: UpdateHendriksConfigInput!) {\n    updateHendriksConfig(input: $input) { \n  id\n  channelId\n  enabled\n  pipelineId\n  wirePrefixMode\n  wirePrefixDigits\n  blockSourceFulfilledOrders\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_HENDRIKS_CONFIG_MUTATION = "\n  mutation DeleteHendriksConfig {\n    deleteHendriksConfig\n  }\n";
+export declare function createHendriksModule(transport: Transport): HendriksModule;