@sixtyninecommerce/admin 0.10.0 → 0.11.0

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),
+    };
+}