@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/purchasing/alerts.d.ts

@@ -0,0 +1,104 @@
+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;
+    /**
+     * The ACTIVE store's backordered order lines that stock on hand can ship now (its own orders,
+     * never another store's of the legal entity): `backorders.ready()`'s total. Purchase-orders
+     * step 3.6; `null` from an engine before it (the SDK asks again without the two counts).
+     */
+    backordersReadyLines: number | null;
+    /** The orders holding those lines, each counted once; `null` as `backordersReadyLines`. */
+    backordersReadyOrders: number | null;
+}
+/** 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`, `ReceivePurchaseOrder` (`UpdatePurchaseOrder` on an engine before
+     * purchase-orders step 3.6) 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  \n  localDay\n  awaitingApproval\n  overdueLines\n  overdueOrders\n  attentionOrders\n  reorderSuggestions\n  newReorderSuggestions\n\n  backordersReadyLines\n  backordersReadyOrders\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  \n  localDay\n  awaitingApproval\n  overdueLines\n  overdueOrders\n  attentionOrders\n  reorderSuggestions\n  newReorderSuggestions\n\n  backordersReadyLines\n  backordersReadyOrders\n }\n  }\n";
+/**
+ * The summary without the backorder counts, for an engine before purchase-orders step 3.6: the SDK
+ * retries once with it when the engine refuses the fields, and answers the two counts null.
+ */
+export declare const LEGACY_PURCHASING_ALERTS_QUERY = "\n  query PurchasingAlertsLegacy {\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. Against an engine before
+     * purchase-orders step 3.6 the backorder counts answer `null` and the rest as ever.
+     */
+    summary(call?: Call): Promise<PurchasingAlertSummary | null>;
+    recipients: PurchasingAlertRecipientsModule;
+}
+export declare function createPurchasingAlertsModule(transport: Transport): PurchasingAlertsModule;

package/dist/purchasing/alerts.js

@@ -0,0 +1,88 @@
+import { isUnknownFieldRejection } from '../payments/store-credit-fields.js';
+/** The summary's counts an engine before purchase-orders step 3.6 answers. */
+const STEP_4_3_SUMMARY_FIELDS = /* GraphQL */ `
+  localDay
+  awaitingApproval
+  overdueLines
+  overdueOrders
+  attentionOrders
+  reorderSuggestions
+  newReorderSuggestions
+`;
+export const PURCHASING_ALERT_SUMMARY_FIELDS = /* GraphQL */ `
+  ${STEP_4_3_SUMMARY_FIELDS}
+  backordersReadyLines
+  backordersReadyOrders
+`;
+export const PURCHASING_ALERT_RECIPIENTS_FIELDS = /* GraphQL */ `
+  alert
+  permission
+  emails
+  recipients
+`;
+export const PURCHASING_ALERTS_QUERY = /* GraphQL */ `
+  query PurchasingAlerts {
+    purchasingAlerts { ${PURCHASING_ALERT_SUMMARY_FIELDS} }
+  }
+`;
+/**
+ * The summary without the backorder counts, for an engine before purchase-orders step 3.6: the SDK
+ * retries once with it when the engine refuses the fields, and answers the two counts null.
+ */
+export const LEGACY_PURCHASING_ALERTS_QUERY = /* GraphQL */ `
+  query PurchasingAlertsLegacy {
+    purchasingAlerts { ${STEP_4_3_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) {
+            try {
+                const data = await transport.graphql({ api: 'admin', query: PURCHASING_ALERTS_QUERY }, call);
+                return data.purchasingAlerts ?? null;
+            }
+            catch (error) {
+                if (!isUnknownFieldRejection(error))
+                    throw error;
+                const data = await transport.graphql({ api: 'admin', query: LEGACY_PURCHASING_ALERTS_QUERY }, call);
+                return data.purchasingAlerts === null
+                    ? null
+                    : { ...data.purchasingAlerts, backordersReadyLines: null, backordersReadyOrders: 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/backorders.d.ts

@@ -0,0 +1,61 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { ListOptions } from '../types.js';
+/**
+ * An open backordered order line of the active store that stock on hand can ship now
+ * (purchase-orders spec §8.11): the store's free on-hand of the variant shared out over its open
+ * backorders, oldest order first.
+ */
+export interface BackorderReadyLine {
+    orderId: string;
+    orderCode: string;
+    /** The order's state; a parked or approval-waiting order keeps its turn too. */
+    orderState: string;
+    /** ISO-8601 UTC; null for an order never placed. */
+    orderPlacedAt: string | null;
+    orderLineId: string;
+    productVariantId: string;
+    sku: string;
+    /** The variant's name in the request's language. */
+    name: string;
+    /** The line's quantity. */
+    quantity: number;
+    /** Its backordered units not yet in a fulfilment. */
+    backorderedQuantity: number;
+    /** Of those, what stock on hand covers now (at least 1). */
+    readyQuantity: number;
+    /** The variant's on-hand, summed over the store's stock locations. */
+    stockOnHand: number;
+    /**
+     * True when the line was ordered from a supplier for this customer (a back-to-back link) and
+     * the supplier side cancelled it: it is an ordinary backorder again ("Supplier cancelled").
+     */
+    supplierCancelled: boolean;
+}
+export interface BackordersReadyOptions extends ListOptions {
+    /** Only the variants this goods receipt (of the store's legal entity) brought in. */
+    goodsReceiptId?: string;
+}
+export declare const BACKORDER_READY_LINE_FIELDS = "\n  orderId\n  orderCode\n  orderState\n  orderPlacedAt\n  orderLineId\n  productVariantId\n  sku\n  name\n  quantity\n  backorderedQuantity\n  readyQuantity\n  stockOnHand\n  supplierCancelled\n";
+export declare const BACKORDERS_READY_QUERY = "\n  query BackordersReadyToShip($options: BackordersReadyOptions) {\n    backordersReadyToShip(options: $options) {\n      items { \n  orderId\n  orderCode\n  orderState\n  orderPlacedAt\n  orderLineId\n  productVariantId\n  sku\n  name\n  quantity\n  backorderedQuantity\n  readyQuantity\n  stockOnHand\n  supplierCancelled\n }\n      totalItems\n    }\n  }\n";
+/**
+ * The list without `supplierCancelled`, for an engine before purchase-orders step 5.1: the SDK
+ * retries once with it when the engine refuses the field, and answers it `false` (that engine has
+ * no order links, so no supplier cancelled one).
+ */
+export declare const LEGACY_BACKORDERS_READY_QUERY = "\n  query BackordersReadyToShipLegacy($options: BackordersReadyOptions) {\n    backordersReadyToShip(options: $options) {\n      items { \n  orderId\n  orderCode\n  orderState\n  orderPlacedAt\n  orderLineId\n  productVariantId\n  sku\n  name\n  quantity\n  backorderedQuantity\n  readyQuantity\n  stockOnHand\n }\n      totalItems\n    }\n  }\n";
+/**
+ * `admin.purchasing.backorders` (purchase-orders spec §8.11, §8.14): what a goods receipt let the
+ * store ship. A read only: nothing is allocated. Needs the Purchasing plugin on the store and
+ * purchasing switched on for its legal entity (`PURCHASING_NOT_ENABLED`, 422), a store that
+ * purchases (`HUB_HAS_NO_PURCHASING`, `LEGAL_ENTITY_REQUIRED`), and `ReadOrder`.
+ */
+export interface PurchasingBackordersModule {
+    /**
+     * The active store's open backordered order lines that stock on hand can ship now, oldest order
+     * first (pages of at most 100). `goodsReceiptId` narrows them to the variants that receipt
+     * brought in. Refusals: `GOODS_RECEIPT_NOT_FOUND` (404, a receipt of another legal entity too),
+     * `GOODS_RECEIPT_INVALID` (400, a page out of range).
+     */
+    ready(options?: BackordersReadyOptions): Promise<Page<BackorderReadyLine>>;
+}
+export declare function createPurchasingBackordersModule(transport: Transport): PurchasingBackordersModule;

package/dist/purchasing/backorders.js

@@ -0,0 +1,92 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+import { isUnknownFieldRejection } from '../payments/store-credit-fields.js';
+/** The line's fields an engine before purchase-orders step 5.1 serves. */
+const STEP_3_6_LINE_FIELDS = /* GraphQL */ `
+  orderId
+  orderCode
+  orderState
+  orderPlacedAt
+  orderLineId
+  productVariantId
+  sku
+  name
+  quantity
+  backorderedQuantity
+  readyQuantity
+  stockOnHand
+`;
+export const BACKORDER_READY_LINE_FIELDS = /* GraphQL */ `
+  orderId
+  orderCode
+  orderState
+  orderPlacedAt
+  orderLineId
+  productVariantId
+  sku
+  name
+  quantity
+  backorderedQuantity
+  readyQuantity
+  stockOnHand
+  supplierCancelled
+`;
+export const BACKORDERS_READY_QUERY = /* GraphQL */ `
+  query BackordersReadyToShip($options: BackordersReadyOptions) {
+    backordersReadyToShip(options: $options) {
+      items { ${BACKORDER_READY_LINE_FIELDS} }
+      totalItems
+    }
+  }
+`;
+/**
+ * The list without `supplierCancelled`, for an engine before purchase-orders step 5.1: the SDK
+ * retries once with it when the engine refuses the field, and answers it `false` (that engine has
+ * no order links, so no supplier cancelled one).
+ */
+export const LEGACY_BACKORDERS_READY_QUERY = /* GraphQL */ `
+  query BackordersReadyToShipLegacy($options: BackordersReadyOptions) {
+    backordersReadyToShip(options: $options) {
+      items { ${STEP_3_6_LINE_FIELDS} }
+      totalItems
+    }
+  }
+`;
+const DEFAULT_PAGE_SIZE = 25;
+export function createPurchasingBackordersModule(transport) {
+    const readyPage = async (skip, take, options) => {
+        const variables = {
+            options: {
+                skip,
+                take,
+                ...(options?.goodsReceiptId === undefined
+                    ? {}
+                    : { goodsReceiptId: options.goodsReceiptId }),
+            },
+        };
+        let list;
+        try {
+            const data = await transport.graphql({ api: 'admin', query: BACKORDERS_READY_QUERY, variables }, options);
+            list = data.backordersReadyToShip;
+        }
+        catch (error) {
+            if (!isUnknownFieldRejection(error))
+                throw error;
+            const data = await transport.graphql({ api: 'admin', query: LEGACY_BACKORDERS_READY_QUERY, variables }, options);
+            list = {
+                items: data.backordersReadyToShip.items.map((line) => ({
+                    ...line,
+                    supplierCancelled: false,
+                })),
+                totalItems: data.backordersReadyToShip.totalItems,
+            };
+        }
+        return pageFromVendureList(list, skip, take, (cursor) => readyPage(readOffsetCursor(cursor), take, options));
+    };
+    return {
+        async ready(options) {
+            const take = options?.limit ?? DEFAULT_PAGE_SIZE;
+            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return readyPage(skip, take, options);
+        },
+    };
+}

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,54 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import { type PurchasingAlertsModule } from './alerts.js';
+import { type PurchasingBackordersModule } from './backorders.js';
+import { type PurchasingCostModule } from './cost.js';
+import { type PurchasingLinksModule } from './links.js';
+import { type PurchasingPurchaseOrdersModule } from './purchase-orders.js';
+import { type PurchasingReceiptsModule } from './receipts.js';
+import { type PurchasingReplenishmentModule } from './replenishment.js';
+import { type PurchasingReturnsModule } from './returns.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 { BackorderReadyLine, BackordersReadyOptions, PurchasingBackordersModule, } from './backorders.js';
+export type { OverrideVariantCostInput, PurchasingCostModule, VariantCost, VariantCostCause, VariantCostEntry, VariantCostEntryList, VariantCostHistoryOptions, } from './cost.js';
+export type { BackToBackLinkQuantities, BackToBackLinkResult, CreateBackToBackLinkInput, DropShipShipmentFulfillment, DropShipShipmentResult, PurchaseOrderDropShip, PurchaseOrderDropShipLine, PurchaseOrderLink, PurchaseOrderLinkKind, PurchaseOrderLinkReleaseReason, PurchaseOrderLinkStatus, PurchasingBackToBackLinksModule, PurchasingDropShipLinksModule, PurchasingLinksModule, RecordDropShipShipmentInput, } from './links.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 { AddGoodsReceiptChargeInput, GoodsReceipt, GoodsReceiptChargesModule, GoodsReceiptDetail, GoodsReceiptKeyedCall, GoodsReceiptKind, GoodsReceiptLine, GoodsReceiptListOptions, GoodsReceiptReference, GoodsReceiptTraceability, GoodsReceiptTraceabilityInput, LandedCharge, LandedChargeAllocation, LandedChargeAllocationBasis, LandedChargeKind, PostGoodsReceiptInput, PostGoodsReceiptLineInput, PurchasingReceiptsModule, ReceivablePurchaseOrderLine, ReceivablePurchaseOrderLinesOptions, RemoveGoodsReceiptChargeInput, ReverseGoodsReceiptInput, } from './receipts.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 { CreateSupplierReturnInput, PurchasingReturnsModule, ResolveSupplierReturnLineInput, ShipSupplierReturnInput, SupplierReturn, SupplierReturnCancelOptions, SupplierReturnDocumentUrl, SupplierReturnKeyedCall, SupplierReturnLine, SupplierReturnLineInput, SupplierReturnListOptions, SupplierReturnOrigin, SupplierReturnOutcome, SupplierReturnResolution, SupplierReturnStatus, SupplierReturnStatusEntry, UpdateSupplierReturnInput, } from './returns.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), `alerts` (what needs attention,
+ * and who the alert emails go to), `receipts` (goods receipts and what can be received),
+ * `backorders` (the store's backordered order lines stock on hand can ship now),
+ * `returns` (goods sent back to suppliers) and `links` (customer order lines bought on purchase
+ * order lines: back-to-back links, phase 5).
+ */
+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;
+    /** Receiving goods against the legal entity's sent purchase orders, and its receipts. */
+    receipts: PurchasingReceiptsModule;
+    /** Returns of goods to the legal entity's suppliers: refused at a receipt, or from stock. */
+    returns: PurchasingReturnsModule;
+    /** The active store's backordered order lines that stock on hand can ship now. */
+    backorders: PurchasingBackordersModule;
+    /** Customer order lines bought on purchase order lines: "Order from supplier" and its reads. */
+    links: PurchasingLinksModule;
+}
+export declare function createPurchasingModule(transport: Transport): PurchasingModule;

package/dist/purchasing/index.js

@@ -0,0 +1,24 @@
+import { createPurchasingAlertsModule } from './alerts.js';
+import { createPurchasingBackordersModule } from './backorders.js';
+import { createPurchasingCostModule } from './cost.js';
+import { createPurchasingLinksModule } from './links.js';
+import { createPurchasingPurchaseOrdersModule, } from './purchase-orders.js';
+import { createPurchasingReceiptsModule } from './receipts.js';
+import { createPurchasingReplenishmentModule, } from './replenishment.js';
+import { createPurchasingReturnsModule } from './returns.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),
+        receipts: createPurchasingReceiptsModule(transport),
+        returns: createPurchasingReturnsModule(transport),
+        backorders: createPurchasingBackordersModule(transport),
+        links: createPurchasingLinksModule(transport),
+    };
+}