@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/orders/bulk.js

@@ -0,0 +1,150 @@
+/**
+ * `admin.orders.bulk`, `admin.orders.bulkRun` and `admin.orders.delete` (headless spec §7
+ * `orders.bulk`, plan W9-43; rulings G19, G28, G29).
+ */
+import { idempotencyKey, ValidationError } from '@sixtyninecommerce/core';
+import { assertDeleted, fieldOf } from '../catalog/types.js';
+import { bulkActionHandle, } from '../jobs/bulk-action-run.js';
+export const ORDER_BULK_ACTIONS = [
+    'TRANSITION',
+    'CANCEL',
+    'DELETE',
+    'MARK_PAID',
+];
+/** The engine's bound on one bulk run (`MAX_BULK_ACTION_ITEMS`). Split a larger selection. */
+export const MAX_BULK_ORDERS = 50;
+/**
+ * The states a TRANSITION never names, each with its own action or door: `Cancelled` (CANCEL),
+ * `PaymentSettled` (MARK_PAID), `Modifying` (the order edit) and `AddingItems`.
+ */
+export const ORDER_BULK_TRANSITION_REFUSED = [
+    'Cancelled',
+    'PaymentSettled',
+    'Modifying',
+    'AddingItems',
+];
+export const BULK_ORDER_ACTION_MUTATION = /* GraphQL */ `
+  mutation BulkOrderAction($input: BulkOrderActionInput!, $idempotencyKey: String) {
+    bulkOrderAction(input: $input, idempotencyKey: $idempotencyKey) {
+      runId
+    }
+  }
+`;
+/**
+ * The run read with the order fields. Its own document, so `catalog.products.bulkRun` keeps
+ * selecting only what an engine without the orders kind has.
+ */
+export const ORDER_BULK_RUN_QUERY = /* GraphQL */ `
+  query OrderBulkRun($runId: ID!) {
+    bulkActionRun(runId: $runId) {
+      id
+      kind
+      action
+      status
+      total
+      done
+      items {
+        id
+        status
+        code
+        message
+        newId
+        reasonCode
+        captured {
+          paymentId
+          state
+          code
+          message
+        }
+      }
+      failure {
+        code
+        message
+      }
+    }
+  }
+`;
+export const DELETE_ORDER_MUTATION = /* GraphQL */ `
+  mutation DeleteOrder($orderId: ID!) {
+    deleteOrder(orderId: $orderId) {
+      result
+      message
+    }
+  }
+`;
+function refuse(message) {
+    return new ValidationError({
+        code: 'BULK_ACTION_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+/** The engine's own checks of a submit (`BULK_ACTION_INPUT_INVALID`), before sending. */
+function assertBulkInput(input) {
+    if (!ORDER_BULK_ACTIONS.includes(input?.action)) {
+        throw refuse(`"${String(input?.action)}" is not a bulk order action: ${ORDER_BULK_ACTIONS.join(', ')}. Nothing was sent.`);
+    }
+    const ids = input.orderIds;
+    if (!Array.isArray(ids) || ids.length === 0) {
+        throw refuse('Name at least one order. Nothing was sent.');
+    }
+    if (ids.length > MAX_BULK_ORDERS) {
+        throw refuse(`Name at most ${String(MAX_BULK_ORDERS)} orders in one bulk action; this one named ${String(ids.length)}. Split the selection into several actions. Nothing was sent.`);
+    }
+    if (new Set(ids.map((id) => String(id).toLowerCase())).size !== ids.length) {
+        throw refuse('The selection names an order more than once. Name each order once. Nothing was sent.');
+    }
+    const toState = input.toState?.trim() ?? '';
+    if (input.action === 'TRANSITION') {
+        if (toState === '')
+            throw refuse('Name the status to move the orders to. Nothing was sent.');
+        if (ORDER_BULK_TRANSITION_REFUSED.includes(toState)) {
+            throw refuse(`Orders are not moved to "${toState}" by a status change${toState === 'Cancelled'
+                ? ': use CANCEL'
+                : toState === 'PaymentSettled'
+                    ? ': use MARK_PAID'
+                    : ''}. Nothing was sent.`);
+        }
+    }
+    else if (toState !== '') {
+        throw refuse(`toState is only for TRANSITION, not ${input.action}. Nothing was sent.`);
+    }
+    if ((input.reason?.trim() ?? '') !== '' && input.action !== 'CANCEL') {
+        throw refuse(`reason is only for CANCEL, not ${input.action}. Nothing was sent.`);
+    }
+}
+/** One read of a bulk order run. A run of another store, or a missing one, is `NotFoundError`. */
+export function readOrderBulkRun(transport, runId, options) {
+    return fieldOf(transport, ORDER_BULK_RUN_QUERY, 'bulkActionRun', { runId }, options);
+}
+/** `orders.bulk`; see `OrdersModule.bulk`. */
+export async function bulkOrders(transport, input, options) {
+    assertBulkInput(input);
+    // Minted when the caller gave none, so a retry of THIS call answers the same run instead of
+    // starting a second one (and capturing nothing twice).
+    const key = options?.idempotencyKey ?? idempotencyKey();
+    const toState = input.toState?.trim();
+    const reason = input.reason?.trim();
+    const { runId } = await fieldOf(transport, BULK_ORDER_ACTION_MUTATION, 'bulkOrderAction', {
+        input: {
+            action: input.action,
+            orderIds: [...input.orderIds],
+            // Omitted, never null, when not given: an absent option stays off the wire.
+            ...(toState ? { toState } : {}),
+            ...(reason ? { reason } : {}),
+        },
+        idempotencyKey: key,
+    }, { ...options, idempotencyKey: key });
+    return bulkActionHandle(transport, runId, options, (id, call) => readOrderBulkRun(transport, id, call));
+}
+/**
+ * `orders.delete`; see `OrdersModule.delete`. The engine's `NOT_DELETED` is raised as every other
+ * `*_NOT_DELETED` refusal of this SDK is (`assertDeleted`): a `ConflictError` with the engine's own
+ * reason.
+ */
+export async function deleteOrder(transport, orderId, options) {
+    assertDeleted('ORDER_NOT_DELETED', [
+        await fieldOf(transport, DELETE_ORDER_MUTATION, 'deleteOrder', { orderId }, options),
+    ]);
+}

package/dist/orders/commit-edit.d.ts

@@ -0,0 +1,123 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import type { OrderEditDiff, OrderEditPlan } from './plan-edit.js';
+import type { OrderOverpaymentChoice } from './surcharges.js';
+/** The order as a committed edit left it: what a head refreshes its view from. */
+export interface OrderEditCommittedOrder {
+    id: string;
+    code: string;
+    /** The order's state: for an edit that raised a paid order's total online, `ArrangingAdditionalPayment`. */
+    state: string;
+    currencyCode: string;
+    /** Minor units. */
+    totalWithTax: number;
+}
+/** The refund an edit ended with. */
+export interface OrderEditCommittedRefund {
+    id: string;
+    /**
+     * The payment provider's answer: `Pending` until a gateway confirms it, `Settled` for money
+     * returned by hand (an offline method). `Failed` is never answered here: a refusal throws.
+     */
+    state: string;
+    /** Minor units, as the refund row records it. */
+    total: number;
+    paymentId: string;
+}
+/** How the edit settled its plan's `overpayment`. */
+export interface OrderEditOverpaymentSettlement {
+    choice: OrderOverpaymentChoice;
+    /** Minor units the choice settled: the plan's `overpayment.amount`. */
+    amount: number;
+    currencyCode: string;
+    /** For `ACCOUNT_CREDIT`: the receipts on the customer's account, one per payment it came from. */
+    unappliedCashIds: string[];
+}
+export interface OrderEditCommit {
+    order: OrderEditCommittedOrder;
+    /**
+     * The plan that was carried out, as `planEdit` answered it. A repeat under the same
+     * `idempotencyKey` answers the plan as it was, and the order and refund as they are now.
+     */
+    plan: OrderEditPlan;
+    /**
+     * The ONE refund the edit ended with, made last, or `null`: the plan's `refund`, or with
+     * `overpaymentChoice: 'REFUND'` its `overpayment.refundWhenChosen`.
+     */
+    refund: OrderEditCommittedRefund | null;
+    /** How the plan's `overpayment` was settled; `null` when it had none. */
+    overpayment: OrderEditOverpaymentSettlement | null;
+}
+export interface CommitOrderEditCall extends Call {
+    /** The `planHash` of the plan the merchant saw (`planEdit`). Required. */
+    expectedPlanHash: string;
+    /**
+     * One key per attempt to save, re-sent unchanged on a retry of THAT attempt. Pass your own:
+     * left out, one is made up (a UUIDv7) and returned as `idempotencyKey` on the result, but on a
+     * thrown error only as an untyped own property of the error. Never reuse a key for a
+     * different edit or a fresh attempt.
+     */
+    idempotencyKey?: string;
+    /**
+     * How the merchant settles the plan's `overpayment` (a surcharge lowered or removed on a paid
+     * order): `REFUND` returns it to the customer's payment in the same one refund as the plan's
+     * `refund`; `ACCOUNT_CREDIT` credits it to the customer's account first, and the plan's
+     * `refund` follows. Required when the plan has an `overpayment`; ignored when it has none.
+     * Part of the request: a retry under the same key re-sends the same choice.
+     */
+    overpaymentChoice?: OrderOverpaymentChoice;
+}
+/**
+ * Its own document on purpose: `commitOrderEdit` exists only on an engine with the order-edit
+ * commit, so on an older one this call alone fails validation and no other order call does.
+ */
+export declare const COMMIT_ORDER_EDIT_MUTATION = "\n  mutation CommitOrderEdit(\n    $orderId: ID!\n    $diff: OrderEditDiffInput!\n    $expectedPlanHash: String!\n    $idempotencyKey: String!\n    $overpaymentChoice: OrderOverpaymentChoice\n  ) {\n    commitOrderEdit(\n      orderId: $orderId\n      diff: $diff\n      expectedPlanHash: $expectedPlanHash\n      idempotencyKey: $idempotencyKey\n      overpaymentChoice: $overpaymentChoice\n    ) {\n      order {\n        id\n        code\n        state\n        currencyCode\n        totalWithTax\n      }\n      plan {\n        orderId\n        planHash\n        orderVersion\n        steps {\n          kind\n          input\n          moneyEffect\n        }\n        refund {\n          paymentId\n          amount\n        }\n        overpayment {\n          amount\n          currencyCode\n          surchargeIds\n          refund {\n            available\n            code\n            message\n          }\n          accountCredit {\n            available\n            code\n            message\n          }\n          refundWhenChosen {\n            paymentId\n            amount\n          }\n        }\n        returnState\n        blockers {\n          code\n          message\n          details\n        }\n        notices {\n          code\n          message\n          details\n        }\n        payment {\n          collected\n          reason\n          method\n        }\n        preview {\n          currencyCode\n          subTotal\n          subTotalWithTax\n          shipping\n          shippingWithTax\n          surcharges\n          surchargesWithTax\n          total\n          totalWithTax\n          taxSummary {\n            description\n            taxRate\n            taxBase\n            taxTotal\n          }\n          totalWithTaxBefore\n        }\n      }\n      refund {\n        id\n        state\n        total\n        paymentId\n      }\n      overpayment {\n        choice\n        amount\n        currencyCode\n        unappliedCashIds\n      }\n    }\n  }\n";
+export interface OrderCommitEditModule {
+    /**
+     * Carry out an edit of a placed order as its plan (`planEdit`) states it, once. Needs
+     * `UpdateOrder`, and an engine that serves `commitOrderEdit`.
+     *
+     * Hand it the SAME `diff` you planned and the plan's `planHash` as `expectedPlanHash`. The
+     * engine runs the plan again inside one transaction and keeps that run only when its hash is
+     * yours and it has no blockers; otherwise nothing of the edit is saved. The plan's refund, if
+     * it has one, is made LAST, after every other step, through the platform's refund guard.
+     *
+     * When the plan has an `overpayment` (a surcharge lowered or removed on a paid order), pass the
+     * merchant's `overpaymentChoice`: `REFUND` makes the plan's `overpayment.refundWhenChosen`
+     * (one refund of both parts); `ACCOUNT_CREDIT` credits the share to the customer's account,
+     * then makes the plan's `refund`.
+     *
+     * `idempotencyKey`: one per attempt to save. A retry of that attempt (a timeout, a dropped
+     * connection) re-sends it and gets the first answer back, with nothing done twice. Left out,
+     * one is made up and returned as `idempotencyKey` on the result and on a thrown error.
+     *
+     * Refusals, with nothing saved:
+     * - `ORDER_EDIT_PLAN_CONFLICT` (`ConflictError`, 409): the order changed since the plan (another
+     *   change landed, a price or tax answer moved). Plan again, show the merchant the new totals,
+     *   and save under a NEW key.
+     * - `ORDER_EDIT_BLOCKED` (`BusinessRuleError`, 422): the plan has blockers; `error.details`
+     *   lists them, `code` = the blocker's code.
+     * - `ORDER_BUSY` (`ConflictError`, 409): another change of the order was being applied. Retry
+     *   under the same key.
+     * - `ORDER_EDIT_OVERPAYMENT_CHOICE_REQUIRED` (`BusinessRuleError`, 422): the plan has an
+     *   `overpayment` and no `overpaymentChoice` was given. Ask the merchant, then save under a
+     *   NEW key (the choice is part of the request).
+     * - A closed option chosen anyway: its own refusal (`REFUND_EXCEEDS_PAYMENT`,
+     *   `REFUND_METHOD_UNAVAILABLE`, `AR_ACCOUNT_IN_ERP`, `AR_LEDGER_NOT_ENABLED`, …), as the
+     *   plan's option names it.
+     * - `IDEMPOTENCY_CONFLICT` (409): the key was used for another request.
+     * - `planEdit`'s refusals of the call, and the refund guard's `REFUND_*` when the refund was
+     *   refused before money moved.
+     *
+     * `IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`): the refund reached the payment
+     * provider and its answer never came. The edit is NOT saved; the refund attempt is recorded
+     * and reserved on the order, and this key answers the same until the provider's answer is
+     * recorded (`admin.payments.reconcileRefund`), which frees it. Until then an edit that gives
+     * money back is blocked (`ORDER_OVERPAYMENT_REFUND_UNRECONCILED`). Then plan and save again:
+     * a refund recorded as made is not made a second time.
+     */
+    commitEdit(orderId: string, diff: OrderEditDiff, options: CommitOrderEditCall): Promise<OrderEditCommit & {
+        idempotencyKey: string;
+    }>;
+}
+export declare function createOrderCommitEditModule(transport: Transport): OrderCommitEditModule;

package/dist/orders/commit-edit.js

@@ -0,0 +1,142 @@
+import { idempotencyKey as mintIdempotencyKey } from '@sixtyninecommerce/core';
+/**
+ * Its own document on purpose: `commitOrderEdit` exists only on an engine with the order-edit
+ * commit, so on an older one this call alone fails validation and no other order call does.
+ */
+export const COMMIT_ORDER_EDIT_MUTATION = /* GraphQL */ `
+  mutation CommitOrderEdit(
+    $orderId: ID!
+    $diff: OrderEditDiffInput!
+    $expectedPlanHash: String!
+    $idempotencyKey: String!
+    $overpaymentChoice: OrderOverpaymentChoice
+  ) {
+    commitOrderEdit(
+      orderId: $orderId
+      diff: $diff
+      expectedPlanHash: $expectedPlanHash
+      idempotencyKey: $idempotencyKey
+      overpaymentChoice: $overpaymentChoice
+    ) {
+      order {
+        id
+        code
+        state
+        currencyCode
+        totalWithTax
+      }
+      plan {
+        orderId
+        planHash
+        orderVersion
+        steps {
+          kind
+          input
+          moneyEffect
+        }
+        refund {
+          paymentId
+          amount
+        }
+        overpayment {
+          amount
+          currencyCode
+          surchargeIds
+          refund {
+            available
+            code
+            message
+          }
+          accountCredit {
+            available
+            code
+            message
+          }
+          refundWhenChosen {
+            paymentId
+            amount
+          }
+        }
+        returnState
+        blockers {
+          code
+          message
+          details
+        }
+        notices {
+          code
+          message
+          details
+        }
+        payment {
+          collected
+          reason
+          method
+        }
+        preview {
+          currencyCode
+          subTotal
+          subTotalWithTax
+          shipping
+          shippingWithTax
+          surcharges
+          surchargesWithTax
+          total
+          totalWithTax
+          taxSummary {
+            description
+            taxRate
+            taxBase
+            taxTotal
+          }
+          totalWithTaxBefore
+        }
+      }
+      refund {
+        id
+        state
+        total
+        paymentId
+      }
+      overpayment {
+        choice
+        amount
+        currencyCode
+        unappliedCashIds
+      }
+    }
+  }
+`;
+export function createOrderCommitEditModule(transport) {
+    return {
+        async commitEdit(orderId, diff, options) {
+            const key = options.idempotencyKey ?? mintIdempotencyKey();
+            try {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: COMMIT_ORDER_EDIT_MUTATION,
+                    // The diff goes out as given, never normalised (see `planEdit`): left out, `null` and
+                    // a value are three different requests.
+                    variables: {
+                        orderId,
+                        diff,
+                        expectedPlanHash: options.expectedPlanHash,
+                        idempotencyKey: key,
+                        // Sent only when given: left out, the engine reads no choice.
+                        ...(options.overpaymentChoice !== undefined
+                            ? { overpaymentChoice: options.overpaymentChoice }
+                            : {}),
+                    },
+                }, { ...options, idempotencyKey: key });
+                return { ...data.commitOrderEdit, idempotencyKey: key };
+            }
+            catch (error) {
+                // The key the caller retries under, when it did not choose one.
+                if (error !== null && typeof error === 'object' && !('idempotencyKey' in error)) {
+                    Object.defineProperty(error, 'idempotencyKey', { value: key, enumerable: true });
+                }
+                throw error;
+            }
+        },
+    };
+}

package/dist/orders/deposit-policy.d.ts

@@ -0,0 +1,103 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** The fewest days `autoCancelAfterDays` may be; `null` means never. */
+export declare const DEPOSIT_POLICY_AUTO_CANCEL_DAYS_MIN = 1;
+/** The largest `storefront.minimumPercent`: a whole percentage of the order total. */
+export declare const DEPOSIT_POLICY_MINIMUM_PERCENT_MAX = 100;
+/** The most payment method codes `storefront.methods` may name. */
+export declare const DEPOSIT_POLICY_STOREFRONT_METHODS_MAX = 50;
+/** Deposits a SHOPPER pays online at checkout. Applies only while `enabled` is on as well. */
+export interface StorefrontDepositPolicy {
+    /** The online switch. */
+    enabled: boolean;
+    /**
+     * Payment method CODES a shopper may pay a deposit with: offline methods and
+     * Mollie. Empty: none, so no shopper can pay a deposit online.
+     */
+    methods: string[];
+    /**
+     * The least an online deposit may be, as a whole percentage (0–100) of the
+     * order's total, judged in the order's currency. Beside `minimum`, not instead
+     * of it: the larger of the two applies.
+     */
+    minimumPercent: number;
+}
+/**
+ * The store's deposit policy (`Channel.customFields.orderDepositPolicy`): whether
+ * staff may take a deposit and park an order (`orders.park`), and whether a
+ * shopper may pay one at checkout. Every field present: this is what the engine
+ * APPLIES, absent and malformed fields read as their defaults.
+ */
+export interface OrderDepositPolicy {
+    /**
+     * The store-wide switch. Off: a payment must cover the whole outstanding
+     * amount (`payments.record` refuses a part payment `DEPOSITS_NOT_ENABLED`) and
+     * no order can be parked.
+     */
+    enabled: boolean;
+    /**
+     * The least a deposit must be before an order can be parked, in minor units of
+     * the store's DEFAULT currency; 0 means any deposit will do. An order in another
+     * currency is held to it converted at the rate checkout charges with.
+     */
+    minimum: number;
+    /** Whether an order may be parked with nothing paid at all. */
+    allowZeroDepositPark: boolean;
+    /**
+     * Whether the storefront shows a parked order's reason to the shopper. Off by
+     * default: staff write that reason for staff.
+     */
+    showParkReasonToCustomer: boolean;
+    /**
+     * RESERVED: days after which a parked order is cancelled. Saved and read back,
+     * but nothing cancels a parked order automatically yet. `null`: never.
+     */
+    autoCancelAfterDays: number | null;
+    storefront: StorefrontDepositPolicy;
+}
+/**
+ * The policy of a store that never set one, and of every field that cannot be
+ * read: deposits off, no minimum, no zero-deposit park, the reason kept from the
+ * shopper, never auto-cancelled, no online deposits.
+ */
+export declare const DEFAULT_ORDER_DEPOSIT_POLICY: Readonly<OrderDepositPolicy>;
+/**
+ * The ACTIVE store's deposit policy (`admin.orders.depositPolicy`), stored as a
+ * Channel custom field and written through core `updateChannel`.
+ *
+ * Reading needs an authenticated administrator on the store; writing needs
+ * `UpdateChannel`.
+ */
+export interface OrderDepositPolicyModule {
+    /**
+     * The policy the engine applies, read as tolerantly as the engine reads it: a
+     * store that never set one, a malformed column and a field of the wrong type
+     * all answer their defaults ({@link DEFAULT_ORDER_DEPOSIT_POLICY}), so this is
+     * what `orders.park` and `payments.record` will hold an order to.
+     */
+    get(options?: Call): Promise<OrderDepositPolicy>;
+    /**
+     * Replace the whole policy, and answer it as the engine now applies it.
+     *
+     * Every field is required: read it with {@link get}, change what you mean to,
+     * and send it back. Only the schema's fields are stored (anything else on the
+     * object is left out), and the method codes are stored as given.
+     *
+     * Refused before any request with `DEPOSIT_POLICY_INVALID` ({@link ValidationError},
+     * one `details[]` entry per failing field, named by its path such as
+     * `storefront.minimumPercent`): a non-boolean switch, a `minimum` that is not a
+     * whole number of 0 or more, an `autoCancelAfterDays` that is neither `null` nor
+     * a whole number of 1 or more, a `minimumPercent` outside 0–100, a blank or
+     * repeated method code, or more than 50 of them. The engine itself stores any
+     * JSON in the column and reads what it cannot use as the default, so this check
+     * is what keeps a bad value from silently turning deposits off.
+     *
+     * Absent and "set to the defaults" mean the same thing to the engine, and a
+     * store's column is never backfilled: write the policy when a merchant changed
+     * it, not as a side effect of saving something else.
+     */
+    set(policy: OrderDepositPolicy, options?: Call): Promise<OrderDepositPolicy>;
+}
+export declare const ORDER_DEPOSIT_POLICY_QUERY = "\n  query OrderDepositPolicy {\n    activeChannel { \n  id\n  customFields {\n    orderDepositPolicy\n  }\n }\n  }\n";
+export declare const SET_ORDER_DEPOSIT_POLICY_MUTATION = "\n  mutation SetOrderDepositPolicy($input: UpdateChannelInput!) {\n    updateChannel(input: $input) {\n      ... on Channel { \n  id\n  customFields {\n    orderDepositPolicy\n  }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+export declare function createOrderDepositPolicyModule(transport: Transport): OrderDepositPolicyModule;