@sixtyninecommerce/admin 0.11.0 → 0.13.0

package/dist/purchasing/index.d.ts

@@ -1,23 +1,33 @@
 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) and `alerts` (what needs attention,
- * and who the alert emails go to) so far; `receipts` and `returns` join them as their engine
- * surfaces ship.
+ * `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. */
@@ -32,5 +42,13 @@ export interface PurchasingModule {
     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

@@ -1,7 +1,11 @@
 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) {
@@ -12,5 +16,9 @@ export function createPurchasingModule(transport) {
         replenishment: createPurchasingReplenishmentModule(transport),
         alerts: createPurchasingAlertsModule(transport),
         cost: createPurchasingCostModule(transport),
+        receipts: createPurchasingReceiptsModule(transport),
+        returns: createPurchasingReturnsModule(transport),
+        backorders: createPurchasingBackordersModule(transport),
+        links: createPurchasingLinksModule(transport),
     };
 }

package/dist/purchasing/links.d.ts

@@ -0,0 +1,263 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { OrderAddress } from '../orders/get.js';
+import type { Call } from '../types.js';
+import { type PurchaseOrder, type PurchaseOrderKeyedCall } from './purchase-orders.js';
+/** What a link buys for: a back-to-back claim, or a drop-ship decision. A string on the wire. */
+export type PurchaseOrderLinkKind = 'back_to_back' | 'drop_ship' | (string & {});
+/**
+ * A link's state, derived on the server: `open` (waiting for goods), `partially_allocated`,
+ * `allocated` (every unit it claims arrived for the order line), `released` (the order or line was
+ * cancelled, or the link removed) or `supplier_cancelled` (its purchase order line can no longer
+ * supply it: show "Supplier cancelled"). A drop-ship link reads `partially_shipped` and `shipped`
+ * (its supplier sent part or all of it to the customer) where a back-to-back one reads the
+ * allocation states; an engine before step 5.2 answers `open` for every drop-ship link.
+ */
+export type PurchaseOrderLinkStatus = 'open' | 'partially_allocated' | 'allocated' | 'partially_shipped' | 'shipped' | 'released' | 'supplier_cancelled' | (string & {});
+/** Why a link ended. */
+export type PurchaseOrderLinkReleaseReason = 'order_cancelled' | 'line_cancelled' | 'po_line_cancelled' | 'removed' | (string & {});
+/**
+ * A customer order line bought on a purchase order line (purchase-orders spec §8.12). Quantities
+ * are base (stock) units.
+ */
+export interface PurchaseOrderLink {
+    id: string;
+    kind: PurchaseOrderLinkKind;
+    status: PurchaseOrderLinkStatus;
+    orderId: string;
+    /** Null when the order is another store's of the legal entity. */
+    orderCode: string | null;
+    orderLineId: string;
+    productVariantId: string;
+    sku: string | null;
+    purchaseOrderId: string | null;
+    /** The purchase order's number. */
+    purchaseOrderCode: string | null;
+    purchaseOrderStatus: string | null;
+    purchaseOrderLineId: string | null;
+    supplierId: string;
+    supplierName: string;
+    /** Where the purchase order delivers: the goods are allocated to the order line there. */
+    stockLocationId: string | null;
+    /** What the link claims. */
+    baseQuantity: number;
+    /** Of those, what receipts gave the order line. */
+    allocatedBaseQuantity: number;
+    /** Drop-ship: what the supplier shipped to the customer. */
+    shippedBaseQuantity: number;
+    /** `YYYY-MM-DD`: the purchase order line's confirmed day, else its requested day. */
+    expectedOn: string | null;
+    /** Whether `expectedOn` is the supplier's confirmed day. */
+    expectedOnConfirmed: boolean;
+    /** ISO-8601 UTC; null while the link is active. */
+    releasedAt: string | null;
+    releaseReason: PurchaseOrderLinkReleaseReason | null;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+}
+export interface CreateBackToBackLinkInput {
+    /** A line of an order of the active store. */
+    orderLineId: string;
+    /** Base units to buy for it, at most its open units not yet linked. Default: all of those. */
+    baseQuantity?: number;
+    /** Default: the variant's preferred supplier. */
+    supplierId?: string;
+    /** The purchase order's destination. Default: the tenant's location, else the store's only one. */
+    stockLocationId?: string;
+    /** A draft of the supplier to add the line to. Default: its newest draft, else a new one. */
+    purchaseOrderId?: string;
+}
+export interface BackToBackLinkResult {
+    link: PurchaseOrderLink;
+    /** The draft the line went onto. */
+    purchaseOrder: PurchaseOrder;
+    /** Whether a new draft was created for it. */
+    createdPurchaseOrder: boolean;
+}
+/**
+ * What "Order from supplier" may order for an order line: the figures a dialog defaults to. The
+ * link judges them again when it is made. Quantities are base (stock) units.
+ */
+export interface BackToBackLinkQuantities {
+    orderLineId: string;
+    /** Its units not yet in a live fulfilment. */
+    openBaseQuantity: number;
+    /** What its active back-to-back links claim. */
+    linkedBaseQuantity: number;
+    /** The most a new link may claim: more is refused `PURCHASE_LINK_EXCEEDS_OPEN_QUANTITY`. */
+    maxBaseQuantity: number;
+    /**
+     * What `backToBack.create` takes when `baseQuantity` is left out. Below `maxBaseQuantity` (0
+     * included) when goods that arrived for the line's earlier links may already cover it: name the
+     * quantity to order more anyway.
+     */
+    suggestedBaseQuantity: number;
+}
+/**
+ * The customer order a drop-ship purchase order ships to (purchase-orders spec §8.12.2), and what
+ * each of its lines has left to ship. Quantities are base (stock) units.
+ */
+export interface PurchaseOrderDropShip {
+    purchaseOrderId: string;
+    /** The purchase order's number. */
+    purchaseOrderCode: string;
+    /** The customer's order. */
+    orderId: string;
+    /** Null when the order is another store's of the legal entity. */
+    orderCode: string | null;
+    /**
+     * The delivery address taken from the order when the draft was made; null once the customer is
+     * erased, and for an order of another store of the legal entity (its staff read the purchase
+     * order, never its customer). `country` (the name) is null: the snapshot keeps the code.
+     */
+    address: OrderAddress | null;
+    lines: PurchaseOrderDropShipLine[];
+}
+export interface PurchaseOrderDropShipLine {
+    purchaseOrderLineId: string;
+    /** The customer's order line it ships; null when no link names it. */
+    orderLineId: string | null;
+    sku: string;
+    /** What the line orders less what was cancelled. */
+    orderedBaseQuantity: number;
+    /** What the supplier shipped to the customer so far. */
+    shippedBaseQuantity: number;
+    /**
+     * What may be recorded shipped now: what the line still orders, at most what the customer's
+     * line still waits for. 0 once that line is cancelled or fulfilled.
+     */
+    toShipBaseQuantity: number;
+}
+export interface RecordDropShipShipmentInput {
+    /** A sent drop-ship purchase order of an order of the active store. */
+    purchaseOrderId: string;
+    /** Left out: every line, all it still has to ship. */
+    lines?: Array<{
+        purchaseOrderLineId: string;
+        baseQuantity: number;
+    }>;
+    /** The supplier's carrier, shown on the fulfilment. */
+    carrier?: string;
+    /** The supplier's tracking code. */
+    trackingCode?: string;
+    /**
+     * `YYYY-MM-DD`: the day the supplier shipped, in the legal entity's time zone, never after
+     * today. Default: today. The cost's exchange rate is this day's.
+     */
+    shippedOn?: string;
+    /**
+     * The rate from the purchase order's currency to the customer order's, when they differ (a
+     * positive decimal string, at most 8 decimals). Needs `ManageInventoryCost`. Default: the
+     * platform rate of `shippedOn`, or of up to 7 days earlier.
+     */
+    fxRate?: string;
+}
+/** The fulfilment a drop-ship shipment created on the customer's order. */
+export interface DropShipShipmentFulfillment {
+    id: string;
+    /** `Shipped`: the supplier sent it. */
+    state: string;
+    /**
+     * The carrier, else "Shipment" in the store's language. Never the supplier: the shopper reads it
+     * (a store may drop-ship white-label).
+     */
+    method: string;
+    trackingCode: string | null;
+}
+export interface DropShipShipmentResult {
+    purchaseOrder: PurchaseOrder;
+    /** The drop-ship links the shipment moved, with what they have shipped now. */
+    links: PurchaseOrderLink[];
+    fulfillment: DropShipShipmentFulfillment;
+    /** Whether every line has now shipped, so the purchase order closed. */
+    closedPurchaseOrder: boolean;
+}
+export declare const PURCHASE_ORDER_LINK_FIELDS = "\n  id\n  kind\n  status\n  orderId\n  orderCode\n  orderLineId\n  productVariantId\n  sku\n  purchaseOrderId\n  purchaseOrderCode\n  purchaseOrderStatus\n  purchaseOrderLineId\n  supplierId\n  supplierName\n  stockLocationId\n  baseQuantity\n  allocatedBaseQuantity\n  shippedBaseQuantity\n  expectedOn\n  expectedOnConfirmed\n  releasedAt\n  releaseReason\n  createdAt\n";
+export declare const ORDER_PURCHASE_ORDER_LINKS_QUERY = "\n  query OrderPurchaseOrderLinks($orderId: ID!) {\n    orderPurchaseOrderLinks(orderId: $orderId) { \n  id\n  kind\n  status\n  orderId\n  orderCode\n  orderLineId\n  productVariantId\n  sku\n  purchaseOrderId\n  purchaseOrderCode\n  purchaseOrderStatus\n  purchaseOrderLineId\n  supplierId\n  supplierName\n  stockLocationId\n  baseQuantity\n  allocatedBaseQuantity\n  shippedBaseQuantity\n  expectedOn\n  expectedOnConfirmed\n  releasedAt\n  releaseReason\n  createdAt\n }\n  }\n";
+export declare const PURCHASE_ORDER_LINKS_QUERY = "\n  query PurchaseOrderLinks($purchaseOrderId: ID!) {\n    purchaseOrderLinks(purchaseOrderId: $purchaseOrderId) { \n  id\n  kind\n  status\n  orderId\n  orderCode\n  orderLineId\n  productVariantId\n  sku\n  purchaseOrderId\n  purchaseOrderCode\n  purchaseOrderStatus\n  purchaseOrderLineId\n  supplierId\n  supplierName\n  stockLocationId\n  baseQuantity\n  allocatedBaseQuantity\n  shippedBaseQuantity\n  expectedOn\n  expectedOnConfirmed\n  releasedAt\n  releaseReason\n  createdAt\n }\n  }\n";
+export declare const BACK_TO_BACK_LINK_QUANTITIES_QUERY = "\n  query PurchaseOrderBackToBackLinkQuantities($orderLineId: ID!) {\n    purchaseOrderBackToBackLinkQuantities(orderLineId: $orderLineId) {\n      orderLineId\n      openBaseQuantity\n      linkedBaseQuantity\n      maxBaseQuantity\n      suggestedBaseQuantity\n    }\n  }\n";
+export declare const CREATE_BACK_TO_BACK_LINK_MUTATION = "\n  mutation CreatePurchaseOrderBackToBackLink(\n    $input: CreatePurchaseOrderBackToBackLinkInput!\n    $idempotencyKey: String\n  ) {\n    createPurchaseOrderBackToBackLink(input: $input, idempotencyKey: $idempotencyKey) {\n      link { \n  id\n  kind\n  status\n  orderId\n  orderCode\n  orderLineId\n  productVariantId\n  sku\n  purchaseOrderId\n  purchaseOrderCode\n  purchaseOrderStatus\n  purchaseOrderLineId\n  supplierId\n  supplierName\n  stockLocationId\n  baseQuantity\n  allocatedBaseQuantity\n  shippedBaseQuantity\n  expectedOn\n  expectedOnConfirmed\n  releasedAt\n  releaseReason\n  createdAt\n }\n      purchaseOrder { \n  \n  id\n  scopeId\n  legalEntityId\n  originChannelId\n  code\n  kind\n  status\n  supplierId\n  supplier { id code name status }\n  destinationStockLocationId\n  destinationStockLocation { id name }\n  currencyCode\n  revision\n  approvedRevision\n  approvedAmount\n  requestedDeliveryOn\n  supplierReference\n  notesToSupplier\n  internalNotes\n  managedBy\n  externalId\n  externalNumber\n  externalApprovalStatus\n  sentAt\n  closedAt\n  closeReason\n  createdByRef\n  total\n  lineCount\n  confirmation\n  lines { \n  id\n  purchaseOrderId\n  position\n  productVariantId\n  supplierItemId\n  sku\n  name\n  supplierSku\n  purchaseUnitLabel\n  purchaseUnitFactor\n  orderedQuantity\n  orderedBaseQuantity\n  cancelledBaseQuantity\n  receivedBaseQuantity\n  returnedForReplacementBaseQuantity\n  unitPrice\n  discountBps\n  priceSource\n  vatRateBps\n  lineTotal\n  requestedOn\n  confirmedBaseQuantity\n  confirmedOn\n  confirmedAt\n  externalLineId\n  createdAt\n  updatedAt\n }\n  createdAt\n  updatedAt\n\n  statusHistory { id fromStatus status actorRef reason metadata createdAt }\n  revisions {\n    id\n    revision\n    state\n    diff\n    totalAfter\n    createdByRef\n    createdAt\n    appliedAt\n    sentAt\n    sentVia\n  }\n }\n      createdPurchaseOrder\n    }\n  }\n";
+export declare const REMOVE_BACK_TO_BACK_LINK_MUTATION = "\n  mutation RemovePurchaseOrderBackToBackLink($id: ID!, $idempotencyKey: String) {\n    removePurchaseOrderBackToBackLink(id: $id, idempotencyKey: $idempotencyKey) {\n      \n  id\n  kind\n  status\n  orderId\n  orderCode\n  orderLineId\n  productVariantId\n  sku\n  purchaseOrderId\n  purchaseOrderCode\n  purchaseOrderStatus\n  purchaseOrderLineId\n  supplierId\n  supplierName\n  stockLocationId\n  baseQuantity\n  allocatedBaseQuantity\n  shippedBaseQuantity\n  expectedOn\n  expectedOnConfirmed\n  releasedAt\n  releaseReason\n  createdAt\n\n    }\n  }\n";
+export declare const PURCHASE_ORDER_DROP_SHIP_QUERY = "\n  query PurchaseOrderDropShip($purchaseOrderId: ID!) {\n    purchaseOrderDropShip(purchaseOrderId: $purchaseOrderId) {\n      purchaseOrderId\n      purchaseOrderCode\n      orderId\n      orderCode\n      address {\n        fullName\n        company\n        streetLine1\n        streetLine2\n        city\n        province\n        postalCode\n        country\n        countryCode\n        phoneNumber\n      }\n      lines {\n        purchaseOrderLineId\n        orderLineId\n        sku\n        orderedBaseQuantity\n        shippedBaseQuantity\n        toShipBaseQuantity\n      }\n    }\n  }\n";
+export declare const RECORD_DROP_SHIP_SHIPMENT_MUTATION = "\n  mutation RecordPurchaseOrderDropShipShipment(\n    $input: RecordDropShipShipmentInput!\n    $idempotencyKey: String!\n  ) {\n    recordPurchaseOrderDropShipShipment(input: $input, idempotencyKey: $idempotencyKey) {\n      purchaseOrder { \n  \n  id\n  scopeId\n  legalEntityId\n  originChannelId\n  code\n  kind\n  status\n  supplierId\n  supplier { id code name status }\n  destinationStockLocationId\n  destinationStockLocation { id name }\n  currencyCode\n  revision\n  approvedRevision\n  approvedAmount\n  requestedDeliveryOn\n  supplierReference\n  notesToSupplier\n  internalNotes\n  managedBy\n  externalId\n  externalNumber\n  externalApprovalStatus\n  sentAt\n  closedAt\n  closeReason\n  createdByRef\n  total\n  lineCount\n  confirmation\n  lines { \n  id\n  purchaseOrderId\n  position\n  productVariantId\n  supplierItemId\n  sku\n  name\n  supplierSku\n  purchaseUnitLabel\n  purchaseUnitFactor\n  orderedQuantity\n  orderedBaseQuantity\n  cancelledBaseQuantity\n  receivedBaseQuantity\n  returnedForReplacementBaseQuantity\n  unitPrice\n  discountBps\n  priceSource\n  vatRateBps\n  lineTotal\n  requestedOn\n  confirmedBaseQuantity\n  confirmedOn\n  confirmedAt\n  externalLineId\n  createdAt\n  updatedAt\n }\n  createdAt\n  updatedAt\n\n  statusHistory { id fromStatus status actorRef reason metadata createdAt }\n  revisions {\n    id\n    revision\n    state\n    diff\n    totalAfter\n    createdByRef\n    createdAt\n    appliedAt\n    sentAt\n    sentVia\n  }\n }\n      links { \n  id\n  kind\n  status\n  orderId\n  orderCode\n  orderLineId\n  productVariantId\n  sku\n  purchaseOrderId\n  purchaseOrderCode\n  purchaseOrderStatus\n  purchaseOrderLineId\n  supplierId\n  supplierName\n  stockLocationId\n  baseQuantity\n  allocatedBaseQuantity\n  shippedBaseQuantity\n  expectedOn\n  expectedOnConfirmed\n  releasedAt\n  releaseReason\n  createdAt\n }\n      fulfillment {\n        id\n        state\n        method\n        trackingCode\n      }\n      closedPurchaseOrder\n    }\n  }\n";
+/**
+ * `admin.purchasing.links.backToBack` (purchase-orders spec §8.12.1, §10.1): "Order from supplier"
+ * on a customer order line. The received goods are allocated to the line first, at the purchase
+ * order's destination, whatever the order's payment terms.
+ */
+export interface PurchasingBackToBackLinksModule {
+    /**
+     * Adds a line for the order line to a draft purchase order (the one named, else the supplier's
+     * newest draft into the destination, else a new one) and links it. Needs `UpdatePurchaseOrder`,
+     * and `CreatePurchaseOrder` when a new draft is made (`PURCHASE_LINK_DRAFT_DENIED`, 403).
+     * Refusals: `PURCHASE_LINK_ORDER_LINE_NOT_FOUND` (404, another store's order included),
+     * `PURCHASE_LINK_ORDER_NOT_LINKABLE` (422: not placed, cancelled, imported, or drop-shipped),
+     * `PURCHASE_LINK_EXCEEDS_OPEN_QUANTITY` (422; `details[0].maxBaseQuantity`),
+     * `PURCHASE_LINK_SUPPLIER_REQUIRED` (422: no preferred supplier), `PURCHASE_LINK_INVALID` (400),
+     * `PURCHASE_ORDER_NOT_EDITABLE` (422: the named order is no draft), `SUPPLIER_ARCHIVED` (422),
+     * `STOCK_LOCATION_REQUIRED`, `LOCATION_NOT_IN_CHANNEL`, `LOCATION_NOT_ALLOWED` (403).
+     */
+    create(input: CreateBackToBackLinkInput, call?: Call): Promise<BackToBackLinkResult>;
+    /**
+     * What `create` may order for an order line: its open units, what its active links claim, the
+     * most a new link may claim and what `create` takes with no `baseQuantity` (a dialog's
+     * defaults). Needs `UpdatePurchaseOrder`, as `create` does. Refused as `create` is for a line it
+     * would refuse whatever the quantity: `PURCHASE_LINK_ORDER_LINE_NOT_FOUND` (404),
+     * `PURCHASE_LINK_ORDER_NOT_LINKABLE` (422). Needs an engine with purchase-orders step 5.4.
+     */
+    quantities(orderLineId: string, call?: Call): Promise<BackToBackLinkQuantities>;
+    /**
+     * Ends a link (`removed`): the order line no longer waits for that purchase order, whose line
+     * keeps its quantity. Refusals: `PURCHASE_LINK_NOT_FOUND` (404),
+     * `PURCHASE_LINK_ALREADY_RELEASED` (422), `MANAGED_BY_PROVIDER` (422).
+     */
+    remove(id: string, call?: Call): Promise<PurchaseOrderLink>;
+}
+/**
+ * `admin.purchasing.links.dropShip` (purchase-orders spec §8.12.2, §10.1): purchase orders a
+ * supplier ships straight to the customer. They are drafted by the platform when an order with
+ * drop-ship lines is placed (one per supplier, with the order's address); staff then approve and
+ * send them as any purchase order, and record what the supplier shipped here.
+ */
+export interface PurchasingDropShipLinksModule {
+    /**
+     * The customer order, address and lines left to ship of a drop-ship purchase order; null for a
+     * standard purchase order or an unknown id. Needs `ReadPurchaseOrder`.
+     */
+    get(purchaseOrderId: string, call?: Call): Promise<PurchaseOrderDropShip | null>;
+    /**
+     * Records what the supplier of a SENT drop-ship purchase order shipped: a fulfilment of the
+     * customer's lines (method `drop-ship`, no stock of ours moves), shipped at once, which sends
+     * the customer's shipping email; each line's cost in the order's currency; and the purchase
+     * order closes once no line can ship more (what no customer line waits for, such as whole
+     * purchase units beyond the customer's quantity, is cancelled as a close short would). Needs
+     * `UpdatePurchaseOrder` and `UpdateOrder`. The key is required: a retried shipment must never
+     * fulfil twice. Refusals:
+     * `PURCHASE_ORDER_NOT_FOUND` (404), `PURCHASE_ORDER_INVALID_TRANSITION` (422: not sent),
+     * `PURCHASE_LINK_INVALID` (400: a standard purchase order, a line named twice or not its own, a
+     * day after today), `DROP_SHIP_SHIPMENT_EXCEEDS_ORDERED` (422; `details[0].maxBaseQuantity`),
+     * `DROP_SHIP_SHIPMENT_DENIED` (403: no `UpdateOrder`), `DROP_SHIP_FULFILLMENT_REFUSED` (422),
+     * `FX_RATE_UNAVAILABLE` (422: no platform rate for the day, state `fxRate`),
+     * `FX_RATE_OVERRIDE_NOT_ALLOWED` (403), `LOCATION_NOT_ALLOWED` (403: a location-restricted
+     * credential), `MANAGED_BY_PROVIDER` (422).
+     */
+    recordShipment(input: RecordDropShipShipmentInput, call: PurchaseOrderKeyedCall): Promise<DropShipShipmentResult>;
+}
+/**
+ * `admin.purchasing.links` (purchase-orders spec §10.1): customer order lines bought on purchase
+ * order lines. Every method needs the Purchasing plugin on the store and purchasing switched on
+ * for its legal entity (`PURCHASING_NOT_ENABLED`, 422); the reads need `ReadPurchaseOrder`.
+ */
+export interface PurchasingLinksModule {
+    /** Back-to-back (special-order) links. */
+    backToBack: PurchasingBackToBackLinksModule;
+    /** Drop-ship purchase orders and their supplier shipments. */
+    dropShip: PurchasingDropShipLinksModule;
+    /**
+     * The links of an order of the active store, oldest first, ended ones included ("Supplier
+     * cancelled" reads from them). Another store's order answers none.
+     */
+    forOrder(orderId: string, call?: Call): Promise<PurchaseOrderLink[]>;
+    /** The links of a purchase order, oldest first, ended ones included. */
+    forPurchaseOrder(purchaseOrderId: string, call?: Call): Promise<PurchaseOrderLink[]>;
+}
+export declare function createPurchasingLinksModule(transport: Transport): PurchasingLinksModule;

package/dist/purchasing/links.js

@@ -0,0 +1,192 @@
+import { PURCHASE_ORDER_FIELDS, } from './purchase-orders.js';
+export const PURCHASE_ORDER_LINK_FIELDS = /* GraphQL */ `
+  id
+  kind
+  status
+  orderId
+  orderCode
+  orderLineId
+  productVariantId
+  sku
+  purchaseOrderId
+  purchaseOrderCode
+  purchaseOrderStatus
+  purchaseOrderLineId
+  supplierId
+  supplierName
+  stockLocationId
+  baseQuantity
+  allocatedBaseQuantity
+  shippedBaseQuantity
+  expectedOn
+  expectedOnConfirmed
+  releasedAt
+  releaseReason
+  createdAt
+`;
+export const ORDER_PURCHASE_ORDER_LINKS_QUERY = /* GraphQL */ `
+  query OrderPurchaseOrderLinks($orderId: ID!) {
+    orderPurchaseOrderLinks(orderId: $orderId) { ${PURCHASE_ORDER_LINK_FIELDS} }
+  }
+`;
+export const PURCHASE_ORDER_LINKS_QUERY = /* GraphQL */ `
+  query PurchaseOrderLinks($purchaseOrderId: ID!) {
+    purchaseOrderLinks(purchaseOrderId: $purchaseOrderId) { ${PURCHASE_ORDER_LINK_FIELDS} }
+  }
+`;
+export const BACK_TO_BACK_LINK_QUANTITIES_QUERY = /* GraphQL */ `
+  query PurchaseOrderBackToBackLinkQuantities($orderLineId: ID!) {
+    purchaseOrderBackToBackLinkQuantities(orderLineId: $orderLineId) {
+      orderLineId
+      openBaseQuantity
+      linkedBaseQuantity
+      maxBaseQuantity
+      suggestedBaseQuantity
+    }
+  }
+`;
+export const CREATE_BACK_TO_BACK_LINK_MUTATION = /* GraphQL */ `
+  mutation CreatePurchaseOrderBackToBackLink(
+    $input: CreatePurchaseOrderBackToBackLinkInput!
+    $idempotencyKey: String
+  ) {
+    createPurchaseOrderBackToBackLink(input: $input, idempotencyKey: $idempotencyKey) {
+      link { ${PURCHASE_ORDER_LINK_FIELDS} }
+      purchaseOrder { ${PURCHASE_ORDER_FIELDS} }
+      createdPurchaseOrder
+    }
+  }
+`;
+export const REMOVE_BACK_TO_BACK_LINK_MUTATION = /* GraphQL */ `
+  mutation RemovePurchaseOrderBackToBackLink($id: ID!, $idempotencyKey: String) {
+    removePurchaseOrderBackToBackLink(id: $id, idempotencyKey: $idempotencyKey) {
+      ${PURCHASE_ORDER_LINK_FIELDS}
+    }
+  }
+`;
+export const PURCHASE_ORDER_DROP_SHIP_QUERY = /* GraphQL */ `
+  query PurchaseOrderDropShip($purchaseOrderId: ID!) {
+    purchaseOrderDropShip(purchaseOrderId: $purchaseOrderId) {
+      purchaseOrderId
+      purchaseOrderCode
+      orderId
+      orderCode
+      address {
+        fullName
+        company
+        streetLine1
+        streetLine2
+        city
+        province
+        postalCode
+        country
+        countryCode
+        phoneNumber
+      }
+      lines {
+        purchaseOrderLineId
+        orderLineId
+        sku
+        orderedBaseQuantity
+        shippedBaseQuantity
+        toShipBaseQuantity
+      }
+    }
+  }
+`;
+export const RECORD_DROP_SHIP_SHIPMENT_MUTATION = /* GraphQL */ `
+  mutation RecordPurchaseOrderDropShipShipment(
+    $input: RecordDropShipShipmentInput!
+    $idempotencyKey: String!
+  ) {
+    recordPurchaseOrderDropShipShipment(input: $input, idempotencyKey: $idempotencyKey) {
+      purchaseOrder { ${PURCHASE_ORDER_FIELDS} }
+      links { ${PURCHASE_ORDER_LINK_FIELDS} }
+      fulfillment {
+        id
+        state
+        method
+        trackingCode
+      }
+      closedPurchaseOrder
+    }
+  }
+`;
+const RECORD_SHIPMENT_INPUT_FIELDS = [
+    'purchaseOrderId',
+    'lines',
+    'carrier',
+    'trackingCode',
+    'shippedOn',
+    'fxRate',
+];
+const CREATE_INPUT_FIELDS = [
+    'orderLineId',
+    'baseQuantity',
+    'supplierId',
+    'stockLocationId',
+    'purchaseOrderId',
+];
+function picked(input, fields) {
+    const out = {};
+    for (const field of fields) {
+        const value = input[field];
+        if (value !== undefined)
+            out[field] = value;
+    }
+    return out;
+}
+export function createPurchasingLinksModule(transport) {
+    return {
+        backToBack: {
+            async create(input, call) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: CREATE_BACK_TO_BACK_LINK_MUTATION,
+                    variables: {
+                        input: picked(input, CREATE_INPUT_FIELDS),
+                        idempotencyKey: call?.idempotencyKey,
+                    },
+                }, call);
+                return data.createPurchaseOrderBackToBackLink;
+            },
+            async quantities(orderLineId, call) {
+                const data = await transport.graphql({ api: 'admin', query: BACK_TO_BACK_LINK_QUANTITIES_QUERY, variables: { orderLineId } }, call);
+                return data.purchaseOrderBackToBackLinkQuantities;
+            },
+            async remove(id, call) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: REMOVE_BACK_TO_BACK_LINK_MUTATION,
+                    variables: { id, idempotencyKey: call?.idempotencyKey },
+                }, call);
+                return data.removePurchaseOrderBackToBackLink;
+            },
+        },
+        dropShip: {
+            async get(purchaseOrderId, call) {
+                const data = await transport.graphql({ api: 'admin', query: PURCHASE_ORDER_DROP_SHIP_QUERY, variables: { purchaseOrderId } }, call);
+                return data.purchaseOrderDropShip;
+            },
+            async recordShipment(input, call) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: RECORD_DROP_SHIP_SHIPMENT_MUTATION,
+                    variables: {
+                        input: picked(input, RECORD_SHIPMENT_INPUT_FIELDS),
+                        idempotencyKey: call.idempotencyKey,
+                    },
+                }, call);
+                return data.recordPurchaseOrderDropShipShipment;
+            },
+        },
+        async forOrder(orderId, call) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_PURCHASE_ORDER_LINKS_QUERY, variables: { orderId } }, call);
+            return data.orderPurchaseOrderLinks;
+        },
+        async forPurchaseOrder(purchaseOrderId, call) {
+            const data = await transport.graphql({ api: 'admin', query: PURCHASE_ORDER_LINKS_QUERY, variables: { purchaseOrderId } }, call);
+            return data.purchaseOrderLinks;
+        },
+    };
+}

package/dist/purchasing/purchase-orders.d.ts

@@ -541,7 +541,10 @@ export interface PurchasingPurchaseOrdersModule {
     reopen(id: string, options?: PurchaseOrderReasonOptions): Promise<PurchaseOrder>;
     /**
      * A five-minute link to a sent revision's PDF (`ReadPurchaseOrder`), the latest sent one when
-     * `revision` is left out. Refusal: `PURCHASE_ORDER_DOCUMENT_NOT_FOUND` (404, never sent).
+     * `revision` is left out. Refusal: `PURCHASE_ORDER_DOCUMENT_NOT_FOUND` (404: never sent, or a
+     * drop-ship order of another store's customer). A drop-ship order's PDF prints its customer's
+     * address, so it opens only from that order's store, and an app installed below
+     * `customerData: full` reads `url` as `''` for every purchase order (engine step 5.2 on).
      */
     document(id: string, options?: PurchaseOrderDocumentOptions): Promise<PurchaseOrderDocumentUrl>;
 }