@sixtyninecommerce/admin 0.7.0 → 0.9.0

package/dist/orders/get.js

@@ -0,0 +1,530 @@
+/**
+ * `admin.orders.get(orderId)`: one order, typed (headless spec §9.2 `orders`
+ * "read", plan W9-9).
+ *
+ * The read has two layers. The CORE is what the engine itself serves for an
+ * order, and it is all a call without `include` asks for. Around it sit the
+ * blocks a plugin adds to an order (payment terms, delivery terms, the order's
+ * own price list, the ERP and carrier references). Each is asked for by name
+ * in `include`, so a caller reads only what it uses, and the core document
+ * names no field an engine without that plugin lacks.
+ *
+ * Money is an integer in minor units of the order's currency, with three
+ * exceptions that are NOT converted to it: a line's `productVariant.price` and
+ * `priceWithTax` (the catalogue price in the currency of the request, which is
+ * the store's default unless the call names another), and a line's
+ * `customFields.cost` (the store's default currency). An instant is an ISO-8601
+ * string with its offset.
+ */
+import { ValidationError } from '@sixtyninecommerce/core';
+import { redactionWatcher } from '../customer-data-redaction.js';
+/**
+ * The blocks a plugin adds to an order, in the order the document lists them.
+ *
+ * - `paymentTerms`: the payment terms the order was placed under, and the
+ *   order's own override of them (the B2B credit plugin).
+ * - `deliveryTerms`: the delivery terms accepted at placement (the shipping
+ *   calculator plugin).
+ * - `priceList`: the order's own price list, which is its one-time pricing
+ *   (the price-list plugin).
+ * - `lineAllocations`: each line's raw allocation rows (the stock-transfer
+ *   plugin). They never decrement: `OrderLine.outstandingAllocations` is what a
+ *   line reserves now, and needs no include.
+ * - `fulfillmentDetails`: each fulfillment's handler (code, name, its detail
+ *   rows) and packing slips (the order-documents plugin).
+ * - `vatValidation`: the customer's VAT number and its validation status (the
+ *   VAT-validation plugin).
+ * - `afas`, `parasut`: the references those ERP plugins keep on the order, its
+ *   customer and the customer's addresses.
+ * - `myparcel`: the MyParcel shipment and label state on each fulfillment.
+ */
+export const ORDER_INCLUDES = [
+    'paymentTerms',
+    'deliveryTerms',
+    'priceList',
+    'lineAllocations',
+    'fulfillmentDetails',
+    'vatValidation',
+    'afas',
+    'parasut',
+    'myparcel',
+];
+/**
+ * The order document with EVERY block, written out whole.
+ *
+ * One static literal on purpose. The repository's GraphQL cost guard
+ * (`services/vendure/src/rate-limit/__tests__/graphql-cost-fits-repo.spec.ts`)
+ * measures every document this package holds against the engine's caps, and it
+ * can only read a literal. This is the largest operation the dashboard sends,
+ * so it has to be the one that is measured: do not assemble it at run time.
+ *
+ * A block's fields sit between a `#[name` line and its `#]` line. Both are
+ * GraphQL comments, so the literal parses as it stands. `orderQuery` keeps a
+ * marked part when the call included the block, drops it otherwise, and drops
+ * the marker lines either way. `#[a|b` marks a part that is kept when ANY of
+ * the named blocks is included: an object whose every field belongs to a block
+ * (an empty selection is not valid GraphQL).
+ */
+export const ORDER_QUERY_EVERY_BLOCK = /* GraphQL */ `
+  query Order($id: ID!) {
+    order(id: $id) {
+      id
+      code
+      state
+      active
+      total
+      totalWithTax
+      subTotal
+      subTotalWithTax
+      shipping
+      shippingWithTax
+      currencyCode
+      orderPlacedAt
+      #[paymentTerms
+      paymentTerms {
+        source
+        managedExternally
+        status
+        conditionCode
+        conditionDescription
+        summary
+        classification
+        paymentDays
+        paymentEndOfMonths
+        paymentMethod
+        percentage
+        discountPaymentDays
+        discountPercentage
+        paymentDiscountType
+        stale
+        syncedAt
+        error
+        resolvedAt
+        remoteConditionCode
+        remoteConfirmedAt
+        remoteMismatch
+      }
+      #]
+      #[deliveryTerms
+      deliveryTerms {
+        source
+        sourceScope
+        governingCustomerId
+        sourceCustomerId
+        managedExternally
+        status
+        shippingMethodStatus
+        policyStatus
+        summary
+        selectionSource
+        selectedShippingMethodId
+        selectedShippingMethodCode
+        selectedShippingMethodName
+        platformShippingMethodCode
+        platformShippingMethodName
+        platformShippingMethodDescription
+        platformShippingPrice
+        platformShippingPriceWithTax
+        preferredShippingMethodId
+        incotermStatus
+        incotermCode
+        incotermVersion
+        incotermAddress
+        incotermDescription
+        shippingLeadDays
+        deliveryAdvice
+        stale
+        syncedAt
+        warning
+        resolvedAt
+        remoteShippingMethodCode
+        remoteShippingMethodName
+        remoteIncotermCode
+        remoteIncotermVersion
+        remoteIncotermAddress
+        remoteDeliveryDate
+        remoteConfirmedAt
+        remoteMismatch
+      }
+      #]
+      couponCodes
+      customer {
+        id
+        firstName
+        lastName
+        emailAddress
+        phoneNumber
+        #[vatValidation|afas|parasut
+        customFields {
+          #[vatValidation
+          vatNumber
+          vatValidationStatus
+          #]
+          #[afas
+          afasVrId
+          afasOrgId
+          afasContactId
+          afasPersId
+          #]
+          #[parasut
+          parasutContactId
+          #]
+        }
+        #]
+        addresses {
+          id
+          fullName
+          company
+          streetLine1
+          streetLine2
+          city
+          postalCode
+          country {
+            code
+          }
+          defaultShippingAddress
+          defaultBillingAddress
+          #[afas
+          customFields {
+            afasAddressId
+          }
+          #]
+        }
+      }
+      lines {
+        id
+        quantity
+        unitPrice
+        unitPriceWithTax
+        listPriceIncludesTax
+        discountedUnitPrice
+        discountedUnitPriceWithTax
+        linePrice
+        linePriceWithTax
+        discountedLinePrice
+        discountedLinePriceWithTax
+        proratedLinePrice
+        proratedLinePriceWithTax
+        taxRate
+        productVariant {
+          id
+          name
+          sku
+          price
+          priceWithTax
+          stockOnHand
+          stockAllocated
+          trackInventory
+          outOfStockThreshold
+          useGlobalOutOfStockThreshold
+          stockLevels {
+            stockLocationId
+            stockOnHand
+            stockAllocated
+            stockLocation {
+              id
+              name
+            }
+          }
+          product {
+            id
+            name
+            featuredAsset {
+              id
+              preview
+            }
+          }
+        }
+        featuredAsset {
+          id
+          preview
+        }
+        #[lineAllocations
+        allocations {
+          id
+          stockLocation {
+            id
+            name
+          }
+          quantity
+        }
+        #]
+        outstandingAllocatedQuantity
+        outstandingAllocations {
+          stockLocationId
+          stockLocationName
+          quantity
+        }
+        customFields {
+          unitPriceOverride
+          priceOverrideReason
+          unitPriceImported
+          priceListId
+          priceListName
+          retailPrice
+          priceListPrice
+          priceListDiscountType
+          priceListDiscountValue
+          priceListDiscountChain
+          cost
+          preferredStockLocationId
+          backorderedQuantity
+        }
+      }
+      surcharges {
+        id
+        description
+        sku
+        price
+        priceWithTax
+        taxRate
+      }
+      discounts {
+        description
+        amount
+        amountWithTax
+      }
+      shippingLines {
+        shippingMethod {
+          id
+          name
+        }
+      }
+      payments {
+        id
+        state
+        method
+        amount
+        transactionId
+        createdAt
+        refunds {
+          id
+          state
+          total
+          reason
+        }
+      }
+      fulfillments {
+        id
+        state
+        nextStates
+        method
+        trackingCode
+        lines {
+          orderLineId
+          quantity
+        }
+        #[fulfillmentDetails
+        handlerCode
+        handlerName
+        handlerDetails {
+          label
+          value
+        }
+        packingSlips {
+          id
+          packingSlipNumber
+          fulfillmentId
+          languageCode
+          storageKey
+          createdAt
+        }
+        #]
+        stockLocationName
+        linkedOrders {
+          id
+          code
+        }
+        customFields {
+          #[myparcel
+          myparcelShipmentId
+          myparcelLabelStatus
+          myparcelLabelFormat
+          myparcelLabelUrlA4
+          myparcelLabelUrlA6
+          myparcelLabelLastError
+          myparcelLabelHandoff
+          #]
+          bookingStatus
+        }
+        createdAt
+      }
+      shippingAddress {
+        fullName
+        company
+        streetLine1
+        streetLine2
+        city
+        province
+        postalCode
+        country
+        countryCode
+        phoneNumber
+      }
+      billingAddress {
+        fullName
+        company
+        streetLine1
+        streetLine2
+        city
+        province
+        postalCode
+        country
+        countryCode
+        phoneNumber
+      }
+      history(options: { take: 50, sort: { createdAt: DESC } }) {
+        items {
+          id
+          type
+          data
+          createdAt
+          isPublic
+          administrator {
+            id
+            firstName
+            lastName
+          }
+        }
+      }
+      taxSummary {
+        description
+        taxRate
+        taxBase
+        taxTotal
+      }
+      nextStates
+      createdAt
+      updatedAt
+      customFields {
+        isLocked
+        externalOrderId
+        externalPlatform
+        sourceFulfillmentHandedOff
+        originalPlacedAt
+        sourceWarehouse
+        pickupLocation
+        allocationExpiresAt
+        goodwillRoundingMinor
+        removeTax
+        isGift
+        giftNote
+        hidePricesOnPackingSlip
+        poNumber
+        requestedDeliveryDate
+        orderNotes
+        customerShippingAddressId
+        customerBillingAddressId
+        shippingAddressIsTemporary
+        billingAddressIsTemporary
+        paymentStatus
+        fulfillmentStatus
+        returnStatus
+        lifecycleStatus
+        #[paymentTerms
+        paymentTermsDays
+        paymentConditionCode
+        #]
+        #[afas
+        afasSalesOrderId
+        afasDirectInvoiceOrNu
+        afasInvoiceNumber
+        afasInvoiceDate
+        afasLocked
+        afasLockReason
+        afasLastSyncAt
+        #]
+        #[parasut
+        parasutInvoiceId
+        parasutEInvoiceStatus
+        parasutEInvoiceUuid
+        parasutLastError
+        #]
+      }
+      fulfillmentHold {
+        reason
+        note
+        heldAt
+        heldByUserId
+        heldBy
+      }
+      #[priceList
+      priceList {
+        id
+        name
+        description
+        defaultDiscountBps
+        defaultDiscountAmount
+        entries {
+          id
+          variantId
+          discountType
+          discountValue
+        }
+      }
+      #]
+    }
+  }
+`;
+const BLOCK_OPEN = '#[';
+const BLOCK_CLOSE = '#]';
+/**
+ * The document `get` sends for a set of blocks: {@link ORDER_QUERY_EVERY_BLOCK}
+ * without the blocks the call did not include, and without the marker lines.
+ * It depends on the SET only, never on the order the caller listed them in, so
+ * one set is one document.
+ */
+export function orderQuery(include = []) {
+    const asked = new Set(include);
+    const kept = [];
+    // One entry per marked part that is open: whether its lines are kept. A part
+    // inside a dropped part is dropped whatever it names.
+    const open = [];
+    for (const line of ORDER_QUERY_EVERY_BLOCK.split('\n')) {
+        const text = line.trim();
+        const outerKept = open.at(-1) ?? true;
+        if (text.startsWith(BLOCK_OPEN)) {
+            const names = text.slice(BLOCK_OPEN.length).split('|');
+            open.push(outerKept && names.some((name) => asked.has(name)));
+        }
+        else if (text === BLOCK_CLOSE) {
+            open.pop();
+        }
+        else if (outerKept) {
+            kept.push(line);
+        }
+    }
+    return kept.join('\n');
+}
+export function createOrderGetModule(transport) {
+    async function get(orderId, options) {
+        // Typed callers cannot get here wrong. A JavaScript caller can, and an
+        // unknown name would otherwise be dropped in silence: the read would
+        // answer an order without the block the caller believes it asked for.
+        const include = options?.include ?? [];
+        const known = (name) => ORDER_INCLUDES.includes(name);
+        if (!Array.isArray(include) || !include.every(known)) {
+            const given = Array.isArray(include)
+                ? include.filter((name) => !known(name)).map((name) => `"${String(name)}"`)
+                : [String(include)];
+            throw new ValidationError({
+                code: 'INVALID_ORDER_INCLUDE',
+                message: `\`include\` takes a list of an order's blocks, and ${given.join(', ')} is not one. The blocks are: ${ORDER_INCLUDES.join(', ')}.`,
+                status: 400,
+                service: 'vendure',
+            });
+        }
+        const redaction = redactionWatcher();
+        const data = await transport.graphql({
+            api: 'admin',
+            query: orderQuery(include),
+            variables: { id: orderId },
+            onExtensions: redaction.onExtensions,
+        }, options);
+        return redaction.mark(data.order);
+    }
+    // The answer holds exactly the blocks asked for; `OrderGetAnswer` decides how
+    // many of them the caller's type of the options may rely on. The overloads
+    // narrow this one implementation, which TypeScript cannot check for them.
+    return { get: get };
+}

package/dist/orders/index.d.ts

@@ -1,8 +1,42 @@
-import type { Transport } from '@sixtyninecommerce/core';
+import { type Transport } from '@sixtyninecommerce/core';
 import type { OrderPaymentPosition, PaidOrder } from '../payments/index.js';
 import type { Call } from '../types.js';
+import { type OrderCommitEditModule } from './commit-edit.js';
+import { type OrderGetModule } from './get.js';
+import { type OrderLinePricePreviewModule } from './line-price-preview.js';
+import { type ManualDiscountsModule } from './manual-discounts.js';
+import { type OrderManualPricingModule } from './manual-pricing.js';
+import { type OrderEntryModule } from './order-entry.js';
+import { type OrderParcelChargeModule } from './parcel-charge.js';
+import { type OrderPlanEditModule } from './plan-edit.js';
+import { type OrderStatusModule } from './status.js';
 import { type SurchargesModule } from './surcharges.js';
 export type { PaidOrder } from '../payments/index.js';
+export type { DiscountPolicy, DiscountPolicyInput, DiscountPolicyModule, DiscountReason, DiscountReasonInput, DiscountReasonsModule, ManualDiscountsModule, OrderManualDiscount, } from './manual-discounts.js';
+export type { ExternalLinePriceBasis, ExternalOrder, ExternalOrderAddressInput, ExternalOrderCall, ExternalOrderCatalogLine, ExternalOrderExternalLine, ExternalOrderFulfilment, ExternalOrderInput, ExternalOrderLine, ExternalOrderLineInput, ExternalOrderSurcharge, ExternalOrderSurchargeInput, ExternalOrderTargetState, ExternalOrderTaxLine, } from './order-entry.js';
+/** An app provider an order is running without (`admin.orders.providerFallbacks`). */
+export interface OrderProviderFallback {
+    /** `shipping.rates` or `tax.calculate`. */
+    kind: string;
+    installationId: string;
+    /**
+     * `timeout`, `network`, `tls`, `redirect`, `http_status`, `invalid_response`,
+     * `private_host`, `suspended`, `not_configured` — the app could not answer, or
+     * was not asked because it is switched off (`suspended`: after 20 failures, or
+     * the installation or app suspended) — or one the MERCHANT fixes, not the app
+     * vendor:
+     * - `tax_class` (`shipping.rates`): the app answered, but the store's tax
+     *   classes cannot tax any rate it offered; map the class.
+     * - `withdrawn` (`tax.calculate`): the store's assigned tax provider no longer
+     *   declares the hook, or its installation no longer consents to it; approve
+     *   the app's pending consent, or unassign the provider.
+     *
+     * Treat an unknown value as "not available": reasons are added over time.
+     */
+    reason: string;
+    /** ISO-8601 with offset: when the order started running without it. */
+    since: string;
+}
 /** The result of settling an order. */
 export interface OrderSettlement {
     order: PaidOrder;
@@ -21,8 +55,24 @@ export interface OrderSettlement {
  * deposit flow: hold an order while the rest of the money is arranged, read
  * what it stands at, and settle it once the money is really there.
  */
-export interface OrdersModule {
+/**
+ * `OrderEntryModule`'s three methods sit DIRECTLY on `admin.orders` rather than
+ * under a nested namespace: composing an order and recovering it are order
+ * operations, not a sub-resource, and `admin.orders.byExternalRef(ref)` is the
+ * sentence a vertical's own code wants to write.
+ *
+ * The manual pricing doors (`setLinePrices`, `setOneTimeDiscounts`) sit there too, beside their
+ * read twin `previewLinePrices`, which prices the same changes without saving them.
+ */
+export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderParcelChargeModule, OrderLinePricePreviewModule, OrderManualPricingModule, OrderPlanEditModule, OrderCommitEditModule, OrderStatusModule {
     surcharges: SurchargesModule;
+    /**
+     * Manual discounts with a reason (incentives spec §4 decision 6): read an order's records,
+     * and the store's reason list and policy (`reasons`, `policy`). A discount itself is given
+     * through the doors that move the money, each taking a reason code: `setLinePrices` and
+     * `setOneTimeDiscounts` on this module.
+     */
+    manualDiscounts: ManualDiscountsModule;
     /**
      * Hold a placed order while the rest of its money is arranged. Needs
      * `UpdateOrder`.
@@ -32,16 +82,21 @@ export interface OrdersModule {
      * is off unless a merchant chose it. Refusals carry the order's position:
      * `DEPOSITS_NOT_ENABLED` (the store has not turned deposits on — the default,
      * so this is the first one you will meet), `DEPOSIT_REQUIRED` (nothing paid,
-     * and the store does not allow that), `DEPOSIT_BELOW_MINIMUM`,
-     * `ORDER_NOT_PARKABLE` (wrong state), `PARK_REASON_TOO_LONG` (500
-     * characters).
+     * and the store does not allow that), `DEPOSIT_BELOW_MINIMUM` (the minimum is
+     * set in the store's default currency and converted into the order's),
+     * `EXCHANGE_RATE_UNAVAILABLE` (no exchange rate to convert it into the
+     * order's currency),
+     * `ORDER_NOT_PARKABLE` (wrong state), `INSUFFICIENT_STOCK` (the goods sold
+     * since the order reached payment; `extensions.lines` names each short line),
+     * `PARK_REASON_TOO_LONG` (500 characters).
      *
-     * Parking does not RESERVE stock: the platform allocates at the payment edge,
-     * so an order parked while arranging payment usually holds no allocations
-     * yet. What it protects is the ORDER — the stock-allocation sweeper leaves a
-     * parked order alone deliberately, so an expiring allocation TTL cannot
-     * cancel an order a customer has already paid a deposit on, and allocations
-     * it does hold stay put while it waits.
+     * Parking RESERVES the order's stock for the life of the park, without
+     * placing the order: no confirmation email, no `order.created`, no ERP push
+     * until it settles, and settling does not reserve twice. `unpark` and a
+     * cancellation give the stock back. A line's backorder or pre-order part is
+     * reserved as it would be at payment. The stock-allocation sweeper leaves a
+     * parked order alone, so an expiring allocation TTL cannot cancel an order a
+     * customer has already paid a deposit on.
      */
     park(orderId: string, options?: Call & {
         reason?: string;
@@ -55,11 +110,16 @@ export interface OrdersModule {
      * parked it. `PARK_ORIGIN_UNKNOWN` is the refusal when that history does not
      * say — move such an order on explicitly with a state transition instead.
      *
-     * There is no storefront equivalent today: a parked order's remainder is
-     * recorded WHERE IT STANDS with `payments.record`, and the payment that
-     * clears it settles, places and allocates the order without ever leaving
-     * `Parked` first. Use this when the order has to be EDITED, which is the one
-     * thing it cannot do while held.
+     * A shopper can pay a parked order's remainder from the storefront
+     * (`commerce.payParkedOrder` / `commerce.createParkedOrderPaymentIntent`),
+     * and a merchant records it WHERE IT STANDS with `payments.record`; the
+     * payment that clears it settles and places the order, keeping the stock the
+     * park reserved, without ever leaving `Parked` first. Use this when the order
+     * has to be EDITED, which is the one thing it cannot do while held; it gives
+     * the park's reserved stock back. On a paid order an installed app held for
+     * review it does NOT accept it: the hold goes back to `ArrangingPayment` with the
+     * order, and nothing places it until staff accept it with {@link OrdersModule.settle}
+     * (or it goes back to the cart and the apps are asked again).
      *
      * It moves no money and changes no payment. Other refusals:
      * `ORDER_NOT_PARKED`, `UNPARK_TRANSITION_REFUSED` (the origin was known and
@@ -76,10 +136,27 @@ export interface OrdersModule {
      * Refuses `COVERAGE_INSUFFICIENT` while the order's SETTLED money does not
      * cover its total, with the position attached. Settled, not covered: an
      * authorization is permission to take money, not money, so an order whose
-     * remainder is merely authorized is settled from `ArrangingPayment` after the
-     * authorization is captured, like any other order. `ORDER_NOT_SETTLEABLE` is
-     * the other refusal — a state a settlement cannot be reached from, which
-     * paying more can never fix.
+     * remainder is merely authorized settles once that authorization is captured
+     * where it stands (`settlePayment` on the Admin API): the capture settles it,
+     * out of a park included, and a parked order never goes back to
+     * `ArrangingPayment` for it (that is {@link OrdersModule.unpark}, which gives
+     * the reserved stock back). `ORDER_NOT_SETTLEABLE` is the other refusal — a
+     * state a settlement cannot be reached from, which paying more can never fix.
+     *
+     * This is also how staff ACCEPT a paid order held for review — an installed
+     * app refused it after it was paid, or a check an ordinary checkout would have
+     * refused it for (it is `Parked`, or `ArrangingPayment` after an un-park or
+     * when it could not be parked; `admin.orders.status(orderId).hold` gives the
+     * refusal's code, and the app when an app refused). Nothing else settles such an order: money that lands on it meanwhile
+     * is recorded and the order stays where it is. A settled one settles here and
+     * is placed; one that still owes money is accepted WITHOUT settling — the hold
+     * ends and the answer's `order.state` stays where it was (for a parked order,
+     * an ordinary part-paid park the shopper can now pay off). One whose balance
+     * is covered only by an AUTHORIZED payment owes nothing and is refused
+     * `COVERAGE_INSUFFICIENT` with the hold kept: accept it by capturing that
+     * payment with `settlePayment`, which settles and places it. To turn the order
+     * down, refund the payment, then {@link OrdersModule.unpark} and cancel it: a
+     * refund alone leaves it parked, held and holding its stock.
      *
      * Calling this on an order the platform ALREADY settled succeeds rather than
      * refusing. Expect that to be the common case: the engine settles an order as
@@ -98,6 +175,14 @@ export interface OrdersModule {
     settle(orderId: string, options?: Call & {
         fulfil?: boolean;
     }): Promise<OrderSettlement>;
+    /**
+     * The app providers this order is currently running WITHOUT (spec §15.19): a
+     * rates or tax app that could not answer, so the platform's own behaviour was
+     * used instead. Empty when none. Needs `ReadOrder`; `ORDER_NOT_FOUND` for an
+     * order this store does not have. {@link OrderStatusModule.status} answers
+     * the same list beside everything else about the order.
+     */
+    providerFallbacks(orderId: string, options?: Call): Promise<OrderProviderFallback[]>;
 }
 export declare const PARK_ORDER_MUTATION = "\n  mutation ParkOrder($orderId: ID!, $reason: String, $idempotencyKey: String) {\n    parkOrder(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";
 export declare const UNPARK_ORDER_MUTATION = "\n  mutation UnparkOrder($orderId: ID!, $idempotencyKey: String) {\n    unparkOrder(orderId: $orderId, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";