@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/pricing/vouchers.d.ts

@@ -0,0 +1,103 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Personal vouchers (incentives sprint 9): a voucher TEMPLATE under a promotion, codes issued one
+ * by one to a customer of the store, single use, with an optional expiry and the issuing journey
+ * recorded as an opaque `source`. Applied like any coupon (`pricing.coupons.apply`, the till's
+ * `pos.sale.applyCouponCode`), which refuse `VOUCHER_NOT_FOR_CUSTOMER`, `VOUCHER_EXPIRED` and
+ * `VOUCHER_ALREADY_REDEEMED`. Issuing needs `CreatePromotion`.
+ */
+/** A customer of this store: exactly one of its id or a master system's key (PR #1176). */
+export type VoucherCustomer = {
+    id: string;
+} | {
+    externalRef: {
+        system: string;
+        ref: string;
+    };
+};
+export interface IssueVoucherInput {
+    templateId: string;
+    customer: VoucherCustomer;
+    /** Usable through the end of the store's local day this many days after today (1 to 3650). */
+    validityDays?: number;
+    /** Or an explicit instant, ISO-8601. Neither: the template's default, else the promotion's window. */
+    expiresAt?: string;
+    /** The issuing journey; with a `ref`, an issue is exactly-once per template, customer and source. */
+    source: {
+        system: string;
+        ref?: string;
+    };
+}
+export interface IssueVouchersInput {
+    templateId: string;
+    sourceSystem: string;
+    /** At most 1,000. */
+    items: Array<{
+        customer: VoucherCustomer;
+        validityDays?: number;
+        expiresAt?: string;
+        sourceRef?: string;
+    }>;
+}
+export interface IssuedVoucher {
+    id: string;
+    code: string;
+    customerId: string;
+    /** The earlier of its own expiry and its promotion's end; null when neither ends. */
+    expiresAt: string | null;
+    /** False when this template, customer and source had issued it already: the same code. */
+    created: boolean;
+}
+export interface IssueVouchersItem {
+    index: number;
+    voucher: IssuedVoucher | null;
+    /** A `VOUCHER_*` code or `ENTITY_NOT_FOUND` for a refused item; the others were issued. */
+    errorCode: string | null;
+    message: string | null;
+}
+export type VoucherStatus = 'OPEN' | 'REDEEMED' | 'EXPIRED' | 'REVOKED';
+export interface Voucher {
+    id: string;
+    code: string;
+    templateId: string;
+    promotionId: string;
+    customerId: string | null;
+    status: VoucherStatus;
+    issuedAt: string;
+    expiresAt: string | null;
+    sourceSystem: string | null;
+    sourceRef: string | null;
+    /** The order that redeemed it. */
+    orderId: string | null;
+}
+export interface VoucherTemplate {
+    id: string;
+    promotionId: string;
+    prefix: string;
+    codeLength: number;
+    defaultValidityDays: number | null;
+}
+export interface PricingVouchersModule {
+    /** A voucher template under a promotion of this store (codes of 12 to 32 random characters). */
+    createTemplate(input: {
+        promotionId: string;
+        prefix: string;
+        codeLength?: number;
+        defaultValidityDays?: number;
+    }, options?: Call): Promise<VoucherTemplate>;
+    /**
+     * Issue one voucher. `options.idempotencyKey` replays the first answer; the same template,
+     * customer and `source.ref` answers the voucher already issued (`created: false`) under any key.
+     */
+    issue(input: IssueVoucherInput, options?: Call): Promise<IssuedVoucher>;
+    /** Issue up to 1,000 vouchers of one template; a refused item answers in its place. */
+    issueMany(input: IssueVouchersInput, options?: Call): Promise<IssueVouchersItem[]>;
+    /** A customer's vouchers in this store, newest first; every status when `status` is omitted. */
+    forCustomer(customer: VoucherCustomer, status?: VoucherStatus, options?: Call): Promise<Voucher[]>;
+}
+export declare const CREATE_VOUCHER_TEMPLATE_MUTATION = "\n  mutation CreateVoucherTemplate($input: CreateVoucherTemplateInput!) {\n    createVoucherTemplate(input: $input) {\n      id\n      promotionId\n      prefix\n      codeLength\n      defaultValidityDays\n    }\n  }\n";
+export declare const ISSUE_VOUCHER_MUTATION = "\n  mutation IssueVoucher($input: IssueVoucherInput!, $idempotencyKey: String) {\n    issueVoucher(input: $input, idempotencyKey: $idempotencyKey) { id code customerId expiresAt created }\n  }\n";
+export declare const ISSUE_VOUCHERS_MUTATION = "\n  mutation IssueVouchers($input: IssueVouchersInput!, $idempotencyKey: String) {\n    issueVouchers(input: $input, idempotencyKey: $idempotencyKey) {\n      items { index errorCode message voucher { id code customerId expiresAt created } }\n    }\n  }\n";
+export declare const VOUCHERS_FOR_CUSTOMER_QUERY = "\n  query VouchersForCustomer($customer: VoucherCustomerInput!, $status: VoucherStatus) {\n    vouchersForCustomer(customer: $customer, status: $status) {\n      id\n      code\n      templateId\n      promotionId\n      customerId\n      status\n      issuedAt\n      expiresAt\n      sourceSystem\n      sourceRef\n      orderId\n    }\n  }\n";
+export declare function createPricingVouchersModule(transport: Transport): PricingVouchersModule;

package/dist/pricing/vouchers.js

@@ -0,0 +1,69 @@
+const ISSUED_VOUCHER_FIELDS = `id code customerId expiresAt created`;
+export const CREATE_VOUCHER_TEMPLATE_MUTATION = /* GraphQL */ `
+  mutation CreateVoucherTemplate($input: CreateVoucherTemplateInput!) {
+    createVoucherTemplate(input: $input) {
+      id
+      promotionId
+      prefix
+      codeLength
+      defaultValidityDays
+    }
+  }
+`;
+export const ISSUE_VOUCHER_MUTATION = /* GraphQL */ `
+  mutation IssueVoucher($input: IssueVoucherInput!, $idempotencyKey: String) {
+    issueVoucher(input: $input, idempotencyKey: $idempotencyKey) { ${ISSUED_VOUCHER_FIELDS} }
+  }
+`;
+export const ISSUE_VOUCHERS_MUTATION = /* GraphQL */ `
+  mutation IssueVouchers($input: IssueVouchersInput!, $idempotencyKey: String) {
+    issueVouchers(input: $input, idempotencyKey: $idempotencyKey) {
+      items { index errorCode message voucher { ${ISSUED_VOUCHER_FIELDS} } }
+    }
+  }
+`;
+export const VOUCHERS_FOR_CUSTOMER_QUERY = /* GraphQL */ `
+  query VouchersForCustomer($customer: VoucherCustomerInput!, $status: VoucherStatus) {
+    vouchersForCustomer(customer: $customer, status: $status) {
+      id
+      code
+      templateId
+      promotionId
+      customerId
+      status
+      issuedAt
+      expiresAt
+      sourceSystem
+      sourceRef
+      orderId
+    }
+  }
+`;
+export function createPricingVouchersModule(transport) {
+    return {
+        async createTemplate(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREATE_VOUCHER_TEMPLATE_MUTATION, variables: { input } }, options);
+            return data.createVoucherTemplate;
+        },
+        async issue(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ISSUE_VOUCHER_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.issueVoucher;
+        },
+        async issueMany(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ISSUE_VOUCHERS_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.issueVouchers.items;
+        },
+        async forCustomer(customer, status, options) {
+            const data = await transport.graphql({ api: 'admin', query: VOUCHERS_FOR_CUSTOMER_QUERY, variables: { customer, status } }, options);
+            return data.vouchersForCustomer;
+        },
+    };
+}

package/dist/purchasing/alerts.d.ts

@@ -0,0 +1,89 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A purchasing staff alert (purchase-orders spec §8.14), named as its email under Management →
+ * Notifications. A string on the wire: more alerts may come (a provider push failing, phase 6).
+ */
+export type PurchasingAlert = 'purchase_order_approval_requested' | 'purchase_order_lines_overdue' | 'reorder_suggestions_digest' | (string & {});
+/**
+ * What needs attention in the active store's purchasing, counted over its legal entity: the
+ * dashboard's nav badges and Overview cards.
+ */
+export interface PurchasingAlertSummary {
+    /** `YYYY-MM-DD` in the legal entity's time zone: the day overdue lines are judged against. */
+    localDay: string;
+    /**
+     * Purchase orders waiting for an approver: submitted above the approval threshold, or sent with
+     * a revision above it.
+     */
+    awaitingApproval: number;
+    /**
+     * Lines of sent purchase orders with something still to come whose expected day (the supplier's
+     * confirmed day, else the requested one) is before `localDay`.
+     */
+    overdueLines: number;
+    /** Sent purchase orders with at least one overdue line. */
+    overdueOrders: number;
+    /** Purchase orders awaiting approval or with an overdue line, each counted once. */
+    attentionOrders: number;
+    /** Reorder suggestions of the last compute that are listed (not dismissed). */
+    reorderSuggestions: number;
+    /** Of those, the ones the last compute found new (not suggested before, or grown). */
+    newReorderSuggestions: number;
+}
+/** Who one purchasing alert email goes to. */
+export interface PurchasingAlertRecipients {
+    alert: PurchasingAlert;
+    /**
+     * The permission whose holders get the alert when no addresses are set:
+     * `ApprovePurchaseOrder`, `UpdatePurchaseOrder` or `CreatePurchaseOrder`.
+     */
+    permission: string;
+    /** The addresses set for this alert; empty when it goes to the permission's holders. */
+    emails: string[];
+    /**
+     * Who the alert goes to now: the addresses set, else the administrators of the legal entity's
+     * stores holding the permission (never a platform administrator or an API credential).
+     */
+    recipients: string[];
+}
+/** One alert's addresses: up to 20; an empty list sends it to the permission's holders again. */
+export interface PurchasingAlertRecipientsInput {
+    alert: PurchasingAlert;
+    emails: string[];
+}
+export declare const PURCHASING_ALERT_SUMMARY_FIELDS = "\n  localDay\n  awaitingApproval\n  overdueLines\n  overdueOrders\n  attentionOrders\n  reorderSuggestions\n  newReorderSuggestions\n";
+export declare const PURCHASING_ALERT_RECIPIENTS_FIELDS = "\n  alert\n  permission\n  emails\n  recipients\n";
+export declare const PURCHASING_ALERTS_QUERY = "\n  query PurchasingAlerts {\n    purchasingAlerts { \n  localDay\n  awaitingApproval\n  overdueLines\n  overdueOrders\n  attentionOrders\n  reorderSuggestions\n  newReorderSuggestions\n }\n  }\n";
+export declare const PURCHASING_ALERT_RECIPIENTS_QUERY = "\n  query PurchasingAlertRecipients {\n    purchasingAlertRecipients { \n  alert\n  permission\n  emails\n  recipients\n }\n  }\n";
+export declare const UPDATE_PURCHASING_ALERT_RECIPIENTS_MUTATION = "\n  mutation UpdatePurchasingAlertRecipients(\n    $input: [PurchasingAlertRecipientsInput!]!\n    $idempotencyKey: String\n  ) {\n    updatePurchasingAlertRecipients(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  alert\n  permission\n  emails\n  recipients\n\n    }\n  }\n";
+export interface PurchasingAlertRecipientsModule {
+    /**
+     * Who each alert goes to, in a fixed order (approval requests, overdue lines, reorder digest).
+     * Needs `ManagePurchasingSettings`.
+     */
+    list(call?: Call): Promise<PurchasingAlertRecipients[]>;
+    /**
+     * Sets who the named alerts go to; an alert not named keeps its own, and an empty `emails`
+     * sends it to the permission's holders again. Answers every alert, as `list` does. Needs
+     * `ManagePurchasingSettings` on EVERY store of the legal entity (`SHARED_SELLER_NOT_ALLOWED`,
+     * 403). Refusals: `PURCHASING_SETTINGS_INVALID` (400: an unknown alert, an alert named twice, an
+     * address that is not one, more than 20 addresses).
+     */
+    update(input: PurchasingAlertRecipientsInput[], call?: Call): Promise<PurchasingAlertRecipients[]>;
+}
+/**
+ * `admin.purchasing.alerts` (purchase-orders spec §8.14): what needs attention in the legal
+ * entity's purchasing, and who its alert emails go to. Every method needs the Purchasing plugin
+ * (`PURCHASING_NOT_ENABLED`, 422) and a store that purchases (`HUB_HAS_NO_PURCHASING`,
+ * `LEGAL_ENTITY_REQUIRED`, 422).
+ */
+export interface PurchasingAlertsModule {
+    /**
+     * The counts behind the nav badges and the Overview cards. Needs `ReadPurchaseOrder`. `null`
+     * while purchasing is not switched on for the store's legal entity.
+     */
+    summary(call?: Call): Promise<PurchasingAlertSummary | null>;
+    recipients: PurchasingAlertRecipientsModule;
+}
+export declare function createPurchasingAlertsModule(transport: Transport): PurchasingAlertsModule;

package/dist/purchasing/alerts.js

@@ -0,0 +1,62 @@
+export const PURCHASING_ALERT_SUMMARY_FIELDS = /* GraphQL */ `
+  localDay
+  awaitingApproval
+  overdueLines
+  overdueOrders
+  attentionOrders
+  reorderSuggestions
+  newReorderSuggestions
+`;
+export const PURCHASING_ALERT_RECIPIENTS_FIELDS = /* GraphQL */ `
+  alert
+  permission
+  emails
+  recipients
+`;
+export const PURCHASING_ALERTS_QUERY = /* GraphQL */ `
+  query PurchasingAlerts {
+    purchasingAlerts { ${PURCHASING_ALERT_SUMMARY_FIELDS} }
+  }
+`;
+export const PURCHASING_ALERT_RECIPIENTS_QUERY = /* GraphQL */ `
+  query PurchasingAlertRecipients {
+    purchasingAlertRecipients { ${PURCHASING_ALERT_RECIPIENTS_FIELDS} }
+  }
+`;
+export const UPDATE_PURCHASING_ALERT_RECIPIENTS_MUTATION = /* GraphQL */ `
+  mutation UpdatePurchasingAlertRecipients(
+    $input: [PurchasingAlertRecipientsInput!]!
+    $idempotencyKey: String
+  ) {
+    updatePurchasingAlertRecipients(input: $input, idempotencyKey: $idempotencyKey) {
+      ${PURCHASING_ALERT_RECIPIENTS_FIELDS}
+    }
+  }
+`;
+export function createPurchasingAlertsModule(transport) {
+    return {
+        async summary(call) {
+            const data = await transport.graphql({ api: 'admin', query: PURCHASING_ALERTS_QUERY }, call);
+            return data.purchasingAlerts ?? null;
+        },
+        recipients: {
+            async list(call) {
+                const data = await transport.graphql({ api: 'admin', query: PURCHASING_ALERT_RECIPIENTS_QUERY }, call);
+                return data.purchasingAlertRecipients;
+            },
+            async update(input, call) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: UPDATE_PURCHASING_ALERT_RECIPIENTS_MUTATION,
+                    variables: {
+                        // Only the input's own fields: a caller spreading what `list` answered sends no
+                        // `permission` or `recipients`, which the engine's input does not declare.
+                        input: input.map(({ alert, emails }) => ({ alert, emails: [...emails] })),
+                        idempotencyKey: call?.idempotencyKey,
+                    },
+                }, call);
+                return data.updatePurchasingAlertRecipients;
+            },
+        },
+    };
+}

package/dist/purchasing/cost.d.ts

@@ -0,0 +1,110 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A variant's unit cost in the active store's PURCHASING SCOPE (purchase-orders spec §8.10,
+ * §10.1 `cost`): its legal entity, shared by every store of that entity, or a sandbox store's own
+ * scope. The weighted average of what the scope received, in minor units of the scope's
+ * purchasing currency.
+ */
+export interface VariantCost {
+    productVariantId: string;
+    /** The legal entity's id, or `sandbox:<channelId>` for a sandbox store. */
+    scopeId: string;
+    /** The legal entity (Seller) id; null for a sandbox store's own scope. */
+    legalEntityId: string | null;
+    /** ISO 4217: the scope's purchasing currency the cost is in. */
+    currencyCode: string;
+    /**
+     * The average as stored: a decimal string of minor units with six decimals (`"1249.500000"`),
+     * never rounded. Parse it with a decimal library, not `Number`, when the decimals matter.
+     */
+    averageUnitCost: string;
+    /** The average rounded half up to whole minor units (what the variant's cost field mirrors). */
+    unitCost: number;
+    /** `average` (receipts, seeding), `manual` (an override), `provider` (an ERP's cost). */
+    method: 'average' | 'manual' | 'provider' | (string & {});
+    /** The scope's on-hand quantity the last change averaged over. */
+    onHandAtLastEntry: number;
+    /** ISO-8601 UTC. */
+    updatedAt: string;
+}
+/** What changed a variant's cost. A string on the wire: more values may come. */
+export type VariantCostCause = 'receipt' | 'reversal' | 'landed_charge' | 'supplier_return' | 'manual' | 'provider_sync' | 'seed' | (string & {});
+/** One change in a variant's cost ledger. Amounts are decimal strings of minor units. */
+export interface VariantCostEntry {
+    id: string;
+    productVariantId: string;
+    scopeId: string;
+    cause: VariantCostCause;
+    currencyCode: string;
+    /** Base units the change moved: positive for a receipt, negative for a reversal or return. */
+    deltaQuantity: number;
+    /** The scope's on-hand quantity the change averaged over. */
+    onHandBefore: number;
+    /** The per-unit cost the change brought in or took out; null for a landed charge. */
+    unitCost: string | null;
+    /** A landed charge's amount for this variant; null otherwise. */
+    chargeAmount: string | null;
+    /** The part of a landed charge that went to units already sold, outside the average. */
+    unabsorbedAmount: string | null;
+    /** The average before the change; null when the scope had no cost yet. */
+    averageBefore: string | null;
+    resultingAverage: string;
+    /** Whether the variant's cost field was set to the rounded result. */
+    mirrorWritten: boolean;
+    /** The document the change belongs to, such as a goods receipt number. */
+    referenceDocumentRef: string | null;
+    /** Why a manual override changed the cost. */
+    reason: string | null;
+    actorRef: string | null;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+}
+export interface VariantCostEntryList {
+    items: VariantCostEntry[];
+    totalItems: number;
+}
+/** A page of the ledger, newest first. */
+export interface VariantCostHistoryOptions {
+    /** 0 or more. Default 0. */
+    skip?: number;
+    /** 1 to 100. Default 25. */
+    take?: number;
+}
+export interface OverrideVariantCostInput {
+    variantId: string;
+    /**
+     * The new unit cost in minor units of the scope's purchasing currency: a non-negative decimal
+     * string of at most 6 decimals, no more than 2147483647 (`"1250"`, `"1249.5"`), or a whole
+     * number of minor units.
+     */
+    unitCost: string | number;
+    /** Why the cost changes: 1 to 255 characters, kept in the ledger. */
+    reason: string;
+}
+export declare const VARIANT_COST_FIELDS = "\n  productVariantId\n  scopeId\n  legalEntityId\n  currencyCode\n  averageUnitCost\n  unitCost\n  method\n  onHandAtLastEntry\n  updatedAt\n";
+export declare const VARIANT_COST_ENTRY_FIELDS = "\n  id\n  productVariantId\n  scopeId\n  cause\n  currencyCode\n  deltaQuantity\n  onHandBefore\n  unitCost\n  chargeAmount\n  unabsorbedAmount\n  averageBefore\n  resultingAverage\n  mirrorWritten\n  referenceDocumentRef\n  reason\n  actorRef\n  createdAt\n";
+export declare const VARIANT_COST_QUERY = "\n  query VariantCost($variantId: ID!) {\n    variantCost(variantId: $variantId) { \n  productVariantId\n  scopeId\n  legalEntityId\n  currencyCode\n  averageUnitCost\n  unitCost\n  method\n  onHandAtLastEntry\n  updatedAt\n }\n  }\n";
+export declare const VARIANT_COST_HISTORY_QUERY = "\n  query VariantCostHistory($variantId: ID!, $options: VariantCostHistoryOptions) {\n    variantCostHistory(variantId: $variantId, options: $options) {\n      items { \n  id\n  productVariantId\n  scopeId\n  cause\n  currencyCode\n  deltaQuantity\n  onHandBefore\n  unitCost\n  chargeAmount\n  unabsorbedAmount\n  averageBefore\n  resultingAverage\n  mirrorWritten\n  referenceDocumentRef\n  reason\n  actorRef\n  createdAt\n }\n      totalItems\n    }\n  }\n";
+export declare const OVERRIDE_VARIANT_COST_MUTATION = "\n  mutation OverrideVariantCost($input: OverrideVariantCostInput!, $idempotencyKey: String) {\n    overrideVariantCost(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  productVariantId\n  scopeId\n  legalEntityId\n  currencyCode\n  averageUnitCost\n  unitCost\n  method\n  onHandAtLastEntry\n  updatedAt\n\n    }\n  }\n";
+/**
+ * `admin.purchasing.cost` (spec §10.1). Every method needs the Purchasing plugin on the store and
+ * purchasing switched on for its legal entity (`PURCHASING_NOT_ENABLED`, 422; `PLUGIN_ACCESS_DENIED`,
+ * 403, for an ordinary caller), and a store that purchases (`HUB_HAS_NO_PURCHASING`,
+ * `LEGAL_ENTITY_REQUIRED`). A variant not in the store is `PURCHASING_VARIANT_NOT_FOUND` (404).
+ * Reads need `ReadCatalog`, `ReadProduct` or `ManageInventoryCost`.
+ */
+export interface PurchasingCostModule {
+    /** The variant's cost in the scope; null while the scope has none (its cost field answers). */
+    get(variantId: string, call?: Call): Promise<VariantCost | null>;
+    /** The variant's cost ledger, newest first. Refusals: `VARIANT_COST_INVALID` (400) for a page. */
+    history(variantId: string, options?: VariantCostHistoryOptions, call?: Call): Promise<VariantCostEntryList>;
+    /**
+     * Sets the variant's cost in the scope, with a reason (cause `manual`); averaging continues
+     * from it, and the variant's cost field follows when one legal entity alone holds it. Needs
+     * `ManageInventoryCost` on EVERY store of the legal entity (`SHARED_SELLER_NOT_ALLOWED`, 403).
+     * Refusals: `VARIANT_COST_INVALID` (400) for the amount or the reason.
+     */
+    override(input: OverrideVariantCostInput, call?: Call): Promise<VariantCost>;
+}
+export declare function createPurchasingCostModule(transport: Transport): PurchasingCostModule;

package/dist/purchasing/cost.js

@@ -0,0 +1,86 @@
+export const VARIANT_COST_FIELDS = /* GraphQL */ `
+  productVariantId
+  scopeId
+  legalEntityId
+  currencyCode
+  averageUnitCost
+  unitCost
+  method
+  onHandAtLastEntry
+  updatedAt
+`;
+export const VARIANT_COST_ENTRY_FIELDS = /* GraphQL */ `
+  id
+  productVariantId
+  scopeId
+  cause
+  currencyCode
+  deltaQuantity
+  onHandBefore
+  unitCost
+  chargeAmount
+  unabsorbedAmount
+  averageBefore
+  resultingAverage
+  mirrorWritten
+  referenceDocumentRef
+  reason
+  actorRef
+  createdAt
+`;
+export const VARIANT_COST_QUERY = /* GraphQL */ `
+  query VariantCost($variantId: ID!) {
+    variantCost(variantId: $variantId) { ${VARIANT_COST_FIELDS} }
+  }
+`;
+export const VARIANT_COST_HISTORY_QUERY = /* GraphQL */ `
+  query VariantCostHistory($variantId: ID!, $options: VariantCostHistoryOptions) {
+    variantCostHistory(variantId: $variantId, options: $options) {
+      items { ${VARIANT_COST_ENTRY_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const OVERRIDE_VARIANT_COST_MUTATION = /* GraphQL */ `
+  mutation OverrideVariantCost($input: OverrideVariantCostInput!, $idempotencyKey: String) {
+    overrideVariantCost(input: $input, idempotencyKey: $idempotencyKey) {
+      ${VARIANT_COST_FIELDS}
+    }
+  }
+`;
+export function createPurchasingCostModule(transport) {
+    return {
+        async get(variantId, call) {
+            const data = await transport.graphql({ api: 'admin', query: VARIANT_COST_QUERY, variables: { variantId } }, call);
+            return data.variantCost;
+        },
+        async history(variantId, options, call) {
+            const page = {};
+            if (options?.skip !== undefined)
+                page.skip = options.skip;
+            if (options?.take !== undefined)
+                page.take = options.take;
+            const data = await transport.graphql({
+                api: 'admin',
+                query: VARIANT_COST_HISTORY_QUERY,
+                variables: { variantId, ...(Object.keys(page).length > 0 ? { options: page } : {}) },
+            }, call);
+            return data.variantCostHistory;
+        },
+        async override(input, call) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: OVERRIDE_VARIANT_COST_MUTATION,
+                variables: {
+                    input: {
+                        variantId: input.variantId,
+                        unitCost: String(input.unitCost),
+                        reason: input.reason,
+                    },
+                    idempotencyKey: call?.idempotencyKey,
+                },
+            }, call);
+            return data.overrideVariantCost;
+        },
+    };
+}

package/dist/purchasing/index.d.ts

@@ -0,0 +1,36 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import { type PurchasingAlertsModule } from './alerts.js';
+import { type PurchasingCostModule } from './cost.js';
+import { type PurchasingPurchaseOrdersModule } from './purchase-orders.js';
+import { type PurchasingReplenishmentModule } from './replenishment.js';
+import { type PurchasingSettingsModule } from './settings.js';
+import { type PurchasingSuppliersModule } from './suppliers.js';
+export type { PurchasingAlert, PurchasingAlertRecipients, PurchasingAlertRecipientsInput, PurchasingAlertRecipientsModule, PurchasingAlertSummary, PurchasingAlertsModule, } from './alerts.js';
+export type { OverrideVariantCostInput, PurchasingCostModule, VariantCost, VariantCostCause, VariantCostEntry, VariantCostEntryList, VariantCostHistoryOptions, } from './cost.js';
+export type { CreatePurchaseOrderInput, PurchaseOrder, PurchaseOrderCancelOptions, PurchaseOrderConfirmation, PurchaseOrderConfirmationInput, PurchaseOrderDocumentOptions, PurchaseOrderDocumentUrl, PurchaseOrderHeaderFields, PurchaseOrderKeyedCall, PurchaseOrderLine, PurchaseOrderLineConfirmationInput, PurchaseOrderLineImportOptions, PurchaseOrderLineImportResult, PurchaseOrderLineImportRow, PurchaseOrderLineInput, PurchaseOrderLinesModule, PurchaseOrderListOptions, PurchaseOrderLocation, PurchaseOrderReasonOptions, PurchaseOrderRevision, PurchaseOrderRevisionInput, PurchaseOrderRevisionsModule, PurchaseOrderSendVia, PurchaseOrderStatus, PurchaseOrderStatusEntry, PurchaseOrderSupplier, PurchasingPurchaseOrdersModule, UpdatePurchaseOrderInput, UpdatePurchaseOrderLineInput, } from './purchase-orders.js';
+export type { PurchasingReplenishmentModule, ReplenishmentComputeResult, ReplenishmentDraftLine, ReplenishmentDrafts, ReplenishmentLocation, ReplenishmentRule, ReplenishmentRuleFields, ReplenishmentRuleImportInput, ReplenishmentRuleImportResult, ReplenishmentRuleImportRow, ReplenishmentRuleListOptions, ReplenishmentRulesModule, ReplenishmentSuggestion, ReplenishmentSuggestionListOptions, ReplenishmentSuggestionsModule, ReplenishmentSupplier, ReplenishmentVariant, } from './replenishment.js';
+export type { PurchasingNumbering, PurchasingNumberingKind, PurchasingNumberingModule, PurchasingSettings, PurchasingSettingsModule, UpdatePurchasingNumberingInput, UpdatePurchasingSettingsInput, } from './settings.js';
+export type { CreateSupplierContactInput, CreateSupplierInput, PurchasingSuppliersModule, Supplier, SupplierAddress, SupplierAddressInput, SupplierContact, SupplierContactFields, SupplierContactsModule, SupplierFields, SupplierItem, SupplierItemFields, SupplierItemImportResult, SupplierItemImportRowResult, SupplierItemListOptions, SupplierItemPrice, SupplierItemPriceInput, SupplierItemPricesModule, SupplierItemPricesOptions, SupplierItemRow, SupplierItemSupplier, SupplierItemsBulkUpsertInput, SupplierItemsModule, SupplierItemVariant, SupplierListOptions, SupplierPriceListImportInput, SupplierStatusOptions, UpdateSupplierContactInput, UpdateSupplierInput, } from './suppliers.js';
+/**
+ * `admin.purchasing` (purchase-orders spec §10.1): buying stock from suppliers, per legal entity.
+ * `settings` (with its document `numbering`), `suppliers` (with their `contacts`),
+ * `purchaseOrders` (with their `lines`; the spec's `orders` submodule), `replenishment` (reorder
+ * `rules` and `suggestions`), `cost` (a variant's cost ledger) and `alerts` (what needs attention,
+ * and who the alert emails go to) so far; `receipts` and `returns` join them as their engine
+ * surfaces ship.
+ */
+export interface PurchasingModule {
+    /** The legal entity's purchasing settings and document numbering. */
+    settings: PurchasingSettingsModule;
+    /** The legal entity's suppliers, their contacts and their catalog (`items`). */
+    suppliers: PurchasingSuppliersModule;
+    /** The legal entity's purchase orders, their lines and lifecycle. */
+    purchaseOrders: PurchasingPurchaseOrdersModule;
+    /** The legal entity's reorder rules and its reorder suggestions. */
+    replenishment: PurchasingReplenishmentModule;
+    /** What needs attention in the legal entity's purchasing, and who its alert emails go to. */
+    alerts: PurchasingAlertsModule;
+    /** A variant's cost in the legal entity's ledger: read it, its history, and override it. */
+    cost: PurchasingCostModule;
+}
+export declare function createPurchasingModule(transport: Transport): PurchasingModule;

package/dist/purchasing/index.js

@@ -0,0 +1,16 @@
+import { createPurchasingAlertsModule } from './alerts.js';
+import { createPurchasingCostModule } from './cost.js';
+import { createPurchasingPurchaseOrdersModule, } from './purchase-orders.js';
+import { createPurchasingReplenishmentModule, } from './replenishment.js';
+import { createPurchasingSettingsModule } from './settings.js';
+import { createPurchasingSuppliersModule } from './suppliers.js';
+export function createPurchasingModule(transport) {
+    return {
+        settings: createPurchasingSettingsModule(transport),
+        suppliers: createPurchasingSuppliersModule(transport),
+        purchaseOrders: createPurchasingPurchaseOrdersModule(transport),
+        replenishment: createPurchasingReplenishmentModule(transport),
+        alerts: createPurchasingAlertsModule(transport),
+        cost: createPurchasingCostModule(transport),
+    };
+}