@sixtyninecommerce/admin 0.7.0 → 0.9.0

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