@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/stock/index.d.ts

@@ -0,0 +1,166 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import { type StockTransfersModule } from './transfers.js';
+/**
+ * One variant's stock at one location, in integer units.
+ *
+ * - `onHand` / `allocated` — what the location holds, and how much of it is
+ *   reserved for orders.
+ * - `reserved` — what the location's out-of-stock threshold holds back from
+ *   sale (the location's own threshold when it sets one, else the variant's or
+ *   the store's): `max(0, threshold)`.
+ * - `available` — `onHand − allocated − threshold`, exactly what the allocator
+ *   can still reserve here. NOT floored at zero: an order allowed to backorder
+ *   allocates past on-hand, and that shortfall shows as a negative figure. A
+ *   negative threshold (an oversell allowance) raises it above
+ *   `onHand − allocated`.
+ * - `incoming` — open units expected at this location (purchase orders).
+ * - `trackInventory: false` — the variant does not track stock, so none of
+ *   these figures gates a sale.
+ */
+export interface StockPosition {
+    locationId: string;
+    locationName: string | null;
+    onHand: number;
+    allocated: number;
+    available: number;
+    incoming: number;
+    reserved: number;
+    trackInventory: boolean;
+}
+export type StockMovementType = 'ADJUSTMENT' | 'ALLOCATION' | 'RELEASE' | 'SALE' | 'CANCELLATION' | 'RETURN';
+/** One line of a variant's stock ledger. */
+export interface StockMovement {
+    id: string;
+    createdAt: string;
+    type: StockMovementType;
+    /**
+     * The movement's own signed quantity as the engine stores it. A `SALE` is
+     * negative; a `RELEASE` is stored positive although it lowers `allocated`.
+     */
+    quantity: number;
+    stockLocation: {
+        id: string;
+        name: string;
+    } | null;
+    /**
+     * Why it moved, in the store's own words. Null for movements made anywhere
+     * but `stock.adjust` (orders, imports, the dashboard's variant form) — and
+     * for a reason another store recorded at a location you share.
+     */
+    reason: string | null;
+    referenceDocumentRef: string | null;
+    /** The staff member a machine credential vouched for (`actor.staffRef`). */
+    actorRef: string | null;
+}
+export interface StockMovementFilter extends ListOptions {
+    /**
+     * One location of this store; omitted → the tenant's `location`, else every
+     * location the credential may use.
+     */
+    locationId?: string;
+    type?: StockMovementType;
+}
+export interface StockPositionOptions extends Call {
+    /**
+     * One location of this store; omitted → the tenant's `location`, else every
+     * location the credential may use.
+     */
+    locationId?: string;
+}
+export interface AdjustStockInput {
+    variantId: string;
+    /** Omitted → the tenant's `location` (`x-location`). One of the two is required. */
+    locationId?: string;
+    /** Units to add (positive) or remove (negative). Never zero. */
+    delta: number;
+    /**
+     * REQUIRED — 1 to 255 printable characters, in your own vocabulary
+     * (`cycle count`, `damaged`, `found in aisle 4`). The platform never
+     * interprets it; it exists so no adjustment is ever unexplained.
+     */
+    reason: string;
+    /** The document behind it — a count sheet, a PO, a damage report. Up to 255 characters. */
+    referenceDocumentRef?: string;
+}
+export interface ReleasedAllocation {
+    orderId: string;
+    /** Units handed back to the stock they were reserved from. */
+    releasedQuantity: number;
+}
+export interface StockAllocationsModule {
+    /**
+     * Hand back every unit an order has reserved, WITHOUT changing the order's
+     * state — for an order stuck before fulfilment whose stock is needed.
+     * Refused (`BusinessRuleError`) with `ORDER_NOT_IN_RELEASABLE_STATE_ERROR`
+     * once anything has shipped, `ORDER_INVOICE_LOCKED` for an invoiced order
+     * (no caller releases one), and `NO_ALLOCATIONS_TO_RELEASE_ERROR` when
+     * nothing is reserved; `NotFoundError` for an order of another store.
+     * A token or app restricted with `locationIds` is refused
+     * `LOCATION_NOT_ALLOWED` (→ `PermissionDeniedError`) unless it holds every
+     * location the order's reservation sits at: the release is all-or-nothing.
+     * Needs `UpdateOrder`.
+     */
+    release(orderId: string, options?: Call): Promise<ReleasedAllocation>;
+}
+/**
+ * Stock per location (spec §9.2 `stock`, §8.7).
+ *
+ * Reads need `ReadStockLocation`; `adjust` needs `AdjustStock` (the `stock` API-token
+ * template). `UpdateStockLocation` still admits `adjust` for credentials minted before
+ * `AdjustStock` existed; a later release ends that, announced in the changelog first.
+ * Everything is scoped to the store the client is on: a location another store
+ * owns is refused, never read — and a location SHARED with another store shows
+ * the same levels and movements to both, but each store's reasons only to
+ * itself.
+ *
+ * **The tenant's `location` is the default place.** Set it once
+ * (`withTenant({ location })`) and `position`, `movements` and `adjust` act at
+ * that location unless a call names another.
+ *
+ * **Coded refusals**, as GraphQL errors with `extensions.code`:
+ * `STOCK_REASON_INVALID`, `STOCK_REFERENCE_INVALID` and `STOCK_DELTA_INVALID`
+ * (→ `ValidationError`); `STOCK_VARIANT_NOT_FOUND` (→ `NotFoundError`, also the
+ * answer for another store's variant); `LOCATION_NOT_IN_CHANNEL`
+ * (→ `ValidationError`, a location of another store); `LOCATION_NOT_ALLOWED`
+ * (→ `PermissionDeniedError`, a location of this store that a token or app
+ * restricted with `locationIds` may not use — reads without a location are
+ * narrowed to that list instead); `STOCK_LOCATION_REQUIRED` and
+ * `STOCK_WOULD_GO_NEGATIVE` (→ `BusinessRuleError`).
+ */
+export interface StockModule {
+    /** The variant's stock at every location of this store (or one). A location that never held it has no entry. */
+    position(variantId: string, options?: StockPositionOptions): Promise<StockPosition[]>;
+    /** The variant's ledger at this store's locations, with each movement's reason. */
+    movements(variantId: string, filter?: StockMovementFilter): Promise<Page<StockMovement>>;
+    /**
+     * Add or remove stock at one location, with the reason, and get the
+     * location's position back.
+     *
+     * `options.idempotencyKey` is honoured: a retry under the same key answers
+     * the FIRST call's position and moves nothing — that position is the stock as
+     * it stood right after the first call, not as it stands now. A decrease may
+     * not take on-hand below zero (`STOCK_WOULD_GO_NEGATIVE`); an increase is
+     * always allowed, so a level that has drifted negative can be corrected.
+     *
+     * The movement also reaches event subscribers twice: as `stock.level_changed`
+     * with `cause: 'adjustment'` (the levels, no reason), and as `stock.adjusted`
+     * (the delta, resulting on-hand, `reason` and `reference_document_ref`). The
+     * second is flagged as personal data because the text is yours and free; a
+     * subscription on it cannot ask for customer-identity redaction.
+     *
+     * While an app or API token owns Stock on the store, an adjustment by anyone else is refused
+     * `FIELD_GROUP_LOCKED` (`BusinessRuleError`), as are stock levels set through
+     * `catalog.variants.update` and the stock moves of a transfer. Moves that follow an order
+     * (sales, reservations, fulfilments, a return put back in stock) always pass.
+     */
+    adjust(input: AdjustStockInput, options?: Call): Promise<StockPosition>;
+    /** Stock transfers between this store's locations, and consumptions at one. */
+    transfers: StockTransfersModule;
+    allocations: StockAllocationsModule;
+}
+export declare const STOCK_POSITION_QUERY = "\n  query StockPosition($variantId: ID!, $locationId: ID) {\n    stockPosition(variantId: $variantId, locationId: $locationId) { \n  locationId\n  locationName\n  onHand\n  allocated\n  available\n  incoming\n  reserved\n  trackInventory\n }\n  }\n";
+export declare const STOCK_MOVEMENTS_QUERY: string;
+export declare const ADJUST_STOCK_MUTATION = "\n  mutation AdjustStock($input: AdjustStockInput!, $idempotencyKey: String) {\n    adjustStock(input: $input, idempotencyKey: $idempotencyKey) { \n  locationId\n  locationName\n  onHand\n  allocated\n  available\n  incoming\n  reserved\n  trackInventory\n }\n  }\n";
+export declare const RELEASE_ORDER_ALLOCATION_MUTATION = "\n  mutation ReleaseOrderAllocation($orderId: ID!) {\n    releaseOrderAllocation(orderId: $orderId) {\n      __typename\n      ... on ReleaseOrderAllocationSuccess { orderId releasedQuantity }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+export declare function createStockModule(transport: Transport): StockModule;

package/dist/stock/index.js

@@ -0,0 +1,115 @@
+import { errorFromErrorResult, isErrorResult, pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+import { createStockTransfersModule } from './transfers.js';
+const POSITION_FIELDS = /* GraphQL */ `
+  locationId
+  locationName
+  onHand
+  allocated
+  available
+  incoming
+  reserved
+  trackInventory
+`;
+const MOVEMENT_TYPES = [
+    'StockAdjustment',
+    'Allocation',
+    'Sale',
+    'Cancellation',
+    'Return',
+    'Release',
+];
+// `stockLocation` is declared per concrete type, not on the `StockMovement`
+// interface, so it is selected through one fragment per type.
+const MOVEMENT_FIELDS = /* GraphQL */ `
+  ... on StockMovement {
+    id
+    createdAt
+    type
+    quantity
+    reason
+    referenceDocumentRef
+    actorRef
+  }
+  ${MOVEMENT_TYPES.map((type) => `... on ${type} { stockLocation { id name } }`).join('\n  ')}
+`;
+export const STOCK_POSITION_QUERY = /* GraphQL */ `
+  query StockPosition($variantId: ID!, $locationId: ID) {
+    stockPosition(variantId: $variantId, locationId: $locationId) { ${POSITION_FIELDS} }
+  }
+`;
+export const STOCK_MOVEMENTS_QUERY = /* GraphQL */ `
+  query StockMovements($variantId: ID!, $locationId: ID, $options: StockMovementListOptions) {
+    stockMovements(variantId: $variantId, locationId: $locationId, options: $options) {
+      items { ${MOVEMENT_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const ADJUST_STOCK_MUTATION = /* GraphQL */ `
+  mutation AdjustStock($input: AdjustStockInput!, $idempotencyKey: String) {
+    adjustStock(input: $input, idempotencyKey: $idempotencyKey) { ${POSITION_FIELDS} }
+  }
+`;
+export const RELEASE_ORDER_ALLOCATION_MUTATION = /* GraphQL */ `
+  mutation ReleaseOrderAllocation($orderId: ID!) {
+    releaseOrderAllocation(orderId: $orderId) {
+      __typename
+      ... on ReleaseOrderAllocationSuccess { orderId releasedQuantity }
+      ... on ErrorResult { errorCode message }
+    }
+  }
+`;
+const DEFAULT_PAGE_SIZE = 50;
+export function createStockModule(transport) {
+    const movementsPage = async (variantId, skip, take, filter) => {
+        const data = await transport.graphql({
+            api: 'admin',
+            query: STOCK_MOVEMENTS_QUERY,
+            variables: {
+                variantId,
+                locationId: filter?.locationId ?? null,
+                options: { skip, take, ...(filter?.type ? { type: filter.type } : {}) },
+            },
+        }, filter);
+        const items = data.stockMovements.items.map((item) => ({
+            ...item,
+            stockLocation: item.stockLocation ?? null,
+        }));
+        return pageFromVendureList({ items, totalItems: data.stockMovements.totalItems }, skip, take, (cursor) => movementsPage(variantId, readOffsetCursor(cursor), take, filter));
+    };
+    return {
+        async position(variantId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: STOCK_POSITION_QUERY,
+                variables: { variantId, locationId: options?.locationId ?? null },
+            }, options);
+            return data.stockPosition;
+        },
+        movements(variantId, filter) {
+            // Offset-paged underneath; the offset rides inside the cursor (spec §9.3).
+            const take = filter?.limit ?? DEFAULT_PAGE_SIZE;
+            const skip = filter?.after === undefined ? 0 : readOffsetCursor(filter.after);
+            return movementsPage(variantId, skip, take, filter);
+        },
+        async adjust(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ADJUST_STOCK_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.adjustStock;
+        },
+        transfers: createStockTransfersModule(transport),
+        allocations: {
+            async release(orderId, options) {
+                const data = await transport.graphql({ api: 'admin', query: RELEASE_ORDER_ALLOCATION_MUTATION, variables: { orderId } }, options);
+                const result = data.releaseOrderAllocation;
+                if (isErrorResult(result))
+                    throw errorFromErrorResult(result);
+                const released = result;
+                return { orderId: released.orderId, releasedQuantity: released.releasedQuantity };
+            },
+        },
+    };
+}