@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/orders/list.d.ts

@@ -0,0 +1,243 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * One order as a list shows it (`admin.orders.list`, `admin.customers.orders`): the totals, the
+ * status dimensions, who it is for, and the three company sources a display name reads
+ * (`billingAddress.company`, `shippingAddress.company`, the customer's address book).
+ *
+ * Money is an integer in minor units of the order's `currencyCode`.
+ */
+export interface OrderSummary {
+    id: string;
+    code: string;
+    state: string;
+    /** Core's total excl. VAT, before a staff rounding. */
+    total: number;
+    /** Core's total incl. VAT, before a staff rounding. Print {@link billableTotals} instead. */
+    totalWithTax: number;
+    /**
+     * What the order bills: `total` incl. VAT is `totalWithTax` with a staff (goodwill) rounding
+     * folded in, the figure the order page (`moneyView.total`), the invoice and the payment carry;
+     * `totalExcludingTax` the same excl. VAT. Print these as the order's total. `null` from an
+     * engine before the field: print `totalWithTax` / `total` then.
+     */
+    billableTotals: OrderBillableTotals | null;
+    currencyCode: string;
+    /** ISO-8601; null for an order not placed yet (a cart, a draft). */
+    orderPlacedAt: string | null;
+    customer: {
+        id: string;
+        firstName: string;
+        lastName: string;
+        emailAddress: string;
+        addresses: Array<{
+            company: string | null;
+            defaultBillingAddress: boolean | null;
+            defaultShippingAddress: boolean | null;
+        }> | null;
+    } | null;
+    billingAddress: {
+        company: string | null;
+    } | null;
+    shippingAddress: {
+        company: string | null;
+    } | null;
+    lines: Array<{
+        quantity: number;
+    }>;
+    payments: Array<{
+        id: string;
+        state: string;
+    }> | null;
+    customFields: {
+        externalOrderId: string | null;
+        externalPlatform: string | null;
+        isGift: boolean | null;
+        /** The status dimensions; null until the engine has set them on an older order. */
+        paymentStatus: string | null;
+        fulfillmentStatus: string | null;
+        returnStatus: string | null;
+        lifecycleStatus: string | null;
+        statusOverrides: {
+            fulfillmentHoldReason: string | null;
+        } | null;
+    } | null;
+    /**
+     * Set when the caller's customer-data level blanked part of the row (an app installation below
+     * `customerData: full`): read an empty name or company as "not granted", never as "none".
+     */
+    redacted?: true;
+}
+/** What an order bills, a staff rounding included (`Order.billableTotals`). Minor units. */
+export interface OrderBillableTotals {
+    /** Incl. VAT; equals the order's `moneyView.total`. */
+    total: number;
+    /** Excl. VAT; equals the order's `moneyView.totalExcludingTax`. */
+    totalExcludingTax: number;
+}
+/**
+ * Which orders a list holds. Every key narrows it; several keys are combined with AND. An empty
+ * list (`state: []`) matches nothing.
+ */
+export interface OrderListFilter {
+    ids?: readonly string[];
+    /** Any of these engine states (`PaymentSettled`, `Draft`, …). */
+    state?: readonly string[];
+    /**
+     * The order code. `startsWith` and `contains` ignore case; `contains` treats `%` and `_` as
+     * wildcards.
+     */
+    code?: {
+        eq?: string;
+        contains?: string;
+        startsWith?: string;
+    };
+    /**
+     * When the order was placed. `isNull: true` keeps the orders never placed (carts, drafts),
+     * `false` the placed ones. `before`/`after` are ISO-8601 instants WITH an offset or `Z`, both
+     * exclusive; an order never placed matches neither.
+     */
+    orderPlacedAt?: {
+        isNull?: boolean;
+        before?: string;
+        after?: string;
+    };
+    /** True for a cart its shopper still has open; a draft, placed or cancelled order is not. */
+    active?: boolean;
+    currencyCode?: string;
+    /**
+     * The platform an imported order came from (`woocommerce`, …); `null` keeps only the orders
+     * that were not imported.
+     */
+    externalPlatform?: string | null;
+    /** Any of these payment dimensions (`paid`, `partially_paid`, …). */
+    paymentStatus?: readonly string[];
+    /** Any of these lifecycles (`open`, `completed`, …). */
+    lifecycleStatus?: readonly string[];
+    /** Part of the customer's last name, ignoring case. */
+    customerLastName?: string;
+}
+/** The fields an order list sorts on. */
+export type OrderListSortField = 'orderPlacedAt' | 'createdAt' | 'updatedAt' | 'code' | 'state' | 'total' | 'totalWithTax' | 'customerLastName';
+export declare const ORDER_LIST_SORT_FIELDS: readonly OrderListSortField[];
+export interface OrderListSort {
+    field: OrderListSortField;
+    direction: 'ASC' | 'DESC';
+}
+export interface OrderListOptions extends Call {
+    filter?: OrderListFilter;
+    sort?: OrderListSort;
+    /** Rows to skip, 0 when omitted. */
+    skip?: number;
+    /** Rows per page, 1 to {@link MAX_ORDER_LIST_TAKE}; 25 when omitted. */
+    take?: number;
+}
+/** The engine's `adminListQueryLimit`: a larger page is refused. */
+export declare const MAX_ORDER_LIST_TAKE = 1000;
+export declare const ORDER_SUMMARY_FIELDS = "\n  \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n  billableTotals {\n    total\n    totalExcludingTax\n  }\n";
+export declare const ORDERS_LIST_QUERY = "\n  query OrdersList($options: OrderListOptions) {\n    orders(options: $options) {\n      items {\n        \n  \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n  billableTotals {\n    total\n    totalExcludingTax\n  }\n\n      }\n      totalItems\n    }\n  }\n";
+export declare const ORDERS_COUNT_QUERY = "\n  query OrdersCount($options: OrderListOptions) {\n    orders(options: $options) {\n      totalItems\n    }\n  }\n";
+export declare const CUSTOMER_ORDERS_QUERY = "\n  query CustomerOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          \n  \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n  billableTotals {\n    total\n    totalExcludingTax\n  }\n\n        }\n        totalItems\n      }\n    }\n  }\n";
+/** The Admin API's `OrderFilterParameter` for a typed filter; unknown keys are refused. */
+export declare function toOrderFilterParameter(filter: OrderListFilter | undefined): Record<string, unknown>;
+export interface OrderListModule {
+    /**
+     * One page of the store's orders, with `total` the exact count of every order the filter
+     * matches. Needs `ReadOrder`.
+     *
+     * - **Carts are orders too.** A cart a shopper never checked out, and a draft staff never placed,
+     *   are listed unless the filter leaves them out (`orderPlacedAt: { isNull: false }`).
+     * - **Sorting by `orderPlacedAt` descending puts the never-placed rows FIRST** (the database
+     *   sorts an empty date above every date). To show the newest placed order first, list the
+     *   placed orders, then continue with `orderPlacedAt: { isNull: true }` sorted by `createdAt`.
+     * - `page.next()` asks for the following page with the same filter and sort; `skip` starts
+     *   somewhere else.
+     *
+     * Refused before anything is asked: `INVALID_ORDER_LIST_OPTIONS` (`ValidationError`, 400) for a
+     * filter key or operator it does not list, a date without an offset, a sort field it does not
+     * list, or `take`/`skip` out of range.
+     *
+     * @effect read
+     */
+    list(options?: OrderListOptions): Promise<Page<OrderSummary>>;
+    /**
+     * How many of the store's orders the filter matches, without reading any. Carts count unless
+     * the filter leaves them out. Needs `ReadOrder`. Refused like {@link list}.
+     *
+     * @effect read
+     */
+    count(filter?: OrderListFilter, options?: Call): Promise<number>;
+}
+export declare function createOrderListModule(transport: Transport): OrderListModule;
+/**
+ * One customer's orders, as `customers.orders` reads them: the same rows, filter, sort and paging
+ * as `orders.list`, or `null` when the store holds no customer with that id.
+ */
+export declare function listCustomerOrders(transport: Transport, customerId: string, options: OrderListOptions | undefined): Promise<Page<OrderSummary> | null>;
+/** The most orders `customers.recentOrders` answers. */
+export declare const MAX_RECENT_ORDERS = 20;
+/**
+ * One line of a customer's earlier order: what was bought, and how many. The members are named
+ * as on every other order line of this SDK (`orders.get`, `orders.drafts`).
+ */
+export interface RecentOrderLine {
+    id: string;
+    /** 0 for a line that was cancelled on the order. */
+    quantity: number;
+    /**
+     * Whether the line is priced gross. `customFields.unitPriceOverride` is stated in this basis,
+     * which follows the customer's tax zone, not the store's setting: a store that prices gross
+     * still holds net lines for a customer in a tax-exclusive country.
+     */
+    listPriceIncludesTax: boolean;
+    /**
+     * The variant as it is NOW (its name and SKU may have changed since the order). A line an
+     * external system priced sits on the platform's hidden carrier variant: read it through
+     * `catalog.variants.find({ ids })`, which leaves such a variant out, before offering it.
+     */
+    productVariant: {
+        id: string;
+        name: string;
+        sku: string;
+        product: {
+            id: string;
+            name: string;
+        };
+    };
+    customFields: {
+        /**
+         * The unit price the line states in place of the catalogue's, in minor units of the
+         * order's currency and in the line's basis (`listPriceIncludesTax`); null for a line the
+         * catalogue priced.
+         */
+        unitPriceOverride: number | null;
+        /** True when that price arrived with the line (an import, a quote, a till price). */
+        unitPriceImported: boolean | null;
+    } | null;
+}
+/** A placed order of a customer, with its lines. */
+export interface RecentOrder {
+    id: string;
+    code: string;
+    /** ISO-8601. */
+    orderPlacedAt: string;
+    /** Minor units of `currencyCode`: core's total, before a staff rounding. */
+    totalWithTax: number;
+    /**
+     * What the order bills (a staff rounding folded in): print `billableTotals.total`. `null` from
+     * an engine before the field: print `totalWithTax` then.
+     */
+    billableTotals: OrderBillableTotals | null;
+    currencyCode: string;
+    lines: RecentOrderLine[];
+}
+export interface RecentOrdersOptions extends Call {
+    /** How many orders, 1 to {@link MAX_RECENT_ORDERS}; 5 when omitted. */
+    take?: number;
+}
+export declare const CUSTOMER_RECENT_ORDERS_QUERY = "\n  query CustomerRecentOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          id\n          code\n          orderPlacedAt\n          totalWithTax\n          billableTotals {\n            total\n            totalExcludingTax\n          }\n          currencyCode\n          lines {\n            id\n            quantity\n            listPriceIncludesTax\n            productVariant {\n              id\n              name\n              sku\n              product {\n                id\n                name\n              }\n            }\n            customFields {\n              unitPriceOverride\n              unitPriceImported\n            }\n          }\n        }\n        totalItems\n      }\n    }\n  }\n";
+/**
+ * A customer's last placed orders, newest first, each with its lines, as `customers.recentOrders`
+ * reads them; `null` when the store holds no customer with that id.
+ */
+export declare function listCustomerRecentOrders(transport: Transport, customerId: string, options: RecentOrdersOptions | undefined): Promise<RecentOrder[] | null>;