@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/orders/order-entry.d.ts

@@ -0,0 +1,566 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { MetafieldAttachment } from '../metafields/index.js';
+import type { Call } from '../types.js';
+/**
+ * How a caller states a price (spec §8.1).
+ *
+ * There is NO default and there never will be: a vertical's €121 is either the
+ * net or the gross of a 21 % line, and the two differ by a whole VAT rate. The
+ * platform refuses rather than guesses, so every input that carries a price
+ * carries its basis beside it.
+ */
+export type ExternalLinePriceBasis = 'net' | 'gross';
+/**
+ * What is going to happen to the goods.
+ *
+ * A fact the vertical STATES about the order rather than an instruction
+ * commerce acts on in this release: nothing here creates a fulfilment or picks
+ * a shipping method. It is recorded as the order's `platform.fulfilment`
+ * metafield so a document, a WMS push or a later fulfilment flow can read back
+ * what the caller actually asked for.
+ *
+ * - `pickup` — collected at a location. Needs no shipping method and no
+ *   address.
+ * - `ship` — shipped. The order still needs a shipping method before it can
+ *   leave `Draft`, and `transitionTo: 'ArrangingPayment'` on an order that has
+ *   none is refused by the platform's own placement gate, not by this call.
+ * - `none` — neither shipped nor collected: a service, a subscription set-up,
+ *   a fee.
+ */
+export type ExternalOrderFulfilment = 'pickup' | 'ship' | 'none';
+/**
+ * Where the composed order should end up.
+ *
+ * `Draft` is the default and the only state that needs nothing else to be true.
+ * `ArrangingPayment` runs the platform's ordinary placement gate — a shipping
+ * method for a shipped order, a customer, stock — and a refusal there is
+ * `ORDER_TRANSITION_REFUSED` carrying the state machine's own reason, with the
+ * whole order rolled back.
+ *
+ * `Parked` is accepted by the type and REFUSED by the engine, deliberately and
+ * always. Every deposit rule — whether the store has deposits on at all, the
+ * minimum, whether a zero-deposit park is allowed — lives in {@link
+ * OrdersModule.park}, and a direct transition would walk past all of them while
+ * taking the stock-allocation sweeper's park exemption for good. A freshly
+ * composed order has no payment on it to be a deposit either. Compose the order
+ * here, record the deposit with `payments.record`, then call `orders.park`.
+ */
+export type ExternalOrderTargetState = 'Draft' | 'ArrangingPayment' | 'Parked';
+/**
+ * A line the STORE prices: the catalogue decides what it costs.
+ *
+ * `kind` is the SDK's discriminant, not a wire field — see
+ * {@link ExternalOrderLineInput} for what goes over the wire.
+ */
+export interface ExternalOrderCatalogLine {
+    kind: 'catalog';
+    /** A product variant of this channel. */
+    productVariantId: string;
+    /** A whole number of at least 1. */
+    quantity: number;
+    /**
+     * What the caller believes one unit costs INCLUDING tax, in minor units.
+     *
+     * Optional, and a mismatch is `LINE_MISPRICED` with the line's position —
+     * NEVER a silent re-price, and never a "close enough" comparison either, since
+     * both sides are integers of the same currency. A vertical that quoted a price
+     * to a customer an hour ago has to learn that the catalogue moved now, not
+     * discover it on the invoice; and because the whole call is atomic, the order
+     * is not created at all when one line is off.
+     *
+     * Send it whenever the caller showed a price to somebody. Omit it and the
+     * store's current price is accepted without question.
+     */
+    expectedUnitPriceWithTax?: number | null;
+    /** Written to this LINE's `platform.attachments` metafield. */
+    attachments?: MetafieldAttachment[] | null;
+}
+/**
+ * A line the VERTICAL prices: it has no catalogue entry at all, so the label,
+ * the price, the basis and the tax class all come from the caller.
+ *
+ * Needs the `ImportExternalLines` permission on top of `CreateOrder`. An order
+ * of nothing but catalog lines does not, which is why the check is per request
+ * rather than on the mutation: an integration that never prices a line should
+ * not have to ask for the permission that lets one.
+ *
+ * The line lands on a hidden carrier variant, and price lists and line-level
+ * promotions never re-price it (spec §8.3). An ORDER-level promotion — a
+ * percentage or fixed discount on the whole order, including the pay-now
+ * discount — is shared across every line of an order by the engine itself, with
+ * no way to leave one out, so an order that ends up with one on an externally
+ * priced line is REFUSED with `EXTERNAL_LINE_PROMOTION_UNSUPPORTED` rather than
+ * invoiced with your stated price quietly reduced.
+ */
+export interface ExternalOrderExternalLine {
+    kind: 'external';
+    /**
+     * What the customer reads on the invoice — the vertical's own words, 1 to 255
+     * characters. It is the line's name everywhere the platform prints one; the
+     * carrier variant behind it is an implementation detail nobody sees.
+     */
+    label: string;
+    /** A whole number of at least 1. */
+    quantity: number;
+    /**
+     * Unit price in minor units (`1999` is 19.99), stated in
+     * {@link ExternalOrderExternalLine.priceBasis}.
+     *
+     * Zero is refused as `LINE_ZERO_PRICE`, separately from a negative price and
+     * for a different reason: a caller that means "free" is usually missing a
+     * price it failed to compute, and a zero line silently widens every total, tax
+     * summary and document by something nobody is charged for. A line given away
+     * is a discount on a priced line.
+     *
+     * Negative is refused too — money coming back off an order is a surcharge or a
+     * refund, not a line.
+     */
+    unitPrice: number;
+    /**
+     * Required. The platform will not guess whether the price is net or gross —
+     * and the side you state is the side that is held FIXED.
+     *
+     * A line stated `net: 10000` is invoiced at 100.00 net whatever the order's
+     * tax situation turns out to be: 100.00 plus 21.00 VAT at the standard rate,
+     * 100.00 at 0% under an EU intra-community reverse charge, 100.00 at 0% on a
+     * tax-removed order. A line stated `gross: 12100` is 121.00 to the customer in
+     * all three, so at 0% its NET rises to 121.00 — the platform's own behaviour
+     * for gross-priced money, not a rounding artefact.
+     *
+     * The stated side survives every later edit of the order. A merchant may
+     * re-price the line in the back office, and their number is then charged in
+     * the basis you stated; they cannot UN-price it. An edit that would leave the
+     * line with no price at all is refused with `EXTERNAL_LINE_UNPRICED`, because
+     * the line has no catalogue price to fall back to and the alternative is
+     * invoicing your line at zero.
+     */
+    priceBasis: ExternalLinePriceBasis;
+    /**
+     * A `taxClass.key` of this store (spec §8.6), resolved PER ORDER: the order's
+     * shipping COUNTRY picks the class's mapping, the order's tax ZONE picks the
+     * rate. A class that says nothing about this order's country is
+     * `TAX_CLASS_UNMAPPED`, and one mapped to a category with no rate in the
+     * order's zone is `TAX_CLASS_RATE_MISSING` — the merchant's own configuration
+     * gap, refused rather than priced at a rate nobody chose.
+     */
+    taxClass: string;
+    /**
+     * The vertical's own JSON for this line — a configurator's answers, a
+     * measurement sheet, a booking's parameters.
+     *
+     * Opaque: never interpreted, never indexed, never searched, size-capped, and
+     * stored verbatim as the line's `platform.configuration` metafield. Its keys
+     * are the CALLER's, and they travel BYTE-FOR-BYTE — this SDK's GraphQL path
+     * does no case conversion whatsoever, so `serial_number`, `SKU_REF` and
+     * `größe` come back spelled exactly as they were sent. (The SDK's
+     * `preserveKeys` option is a REST-only concern and has no bearing here.)
+     *
+     * `undefined` and `null` are NOT the same: omit the field for "no
+     * configuration", and note that an explicit JSON `null` is refused by the
+     * metafield writer as a value. Omitting it also keeps it out of the request
+     * fingerprint in the same way the engine's own recovery check does.
+     */
+    configuration?: unknown;
+    /** Written to this LINE's `platform.attachments` metafield. */
+    attachments?: MetafieldAttachment[] | null;
+    /** The caller's own article code for the line, when it has one. */
+    sku?: string | null;
+}
+/**
+ * One line of the order: a catalog line or an externally priced one.
+ *
+ * **This is a nicer shape than the wire's.** GraphQL has no input union, so the
+ * Admin API models a line as `ExternalOrderLineInput { catalog, external }` with
+ * exactly one member set — a shape in which "both" and "neither" are
+ * representable and have to be refused at runtime. The SDK takes a real
+ * discriminated union on `kind` instead, so neither mistake type-checks, and
+ * {@link toWireLine} wraps it back into the member the engine expects. The
+ * engine's own service layer holds the identical `kind`-tagged union behind its
+ * resolver, so the two ends agree and only the transport hop is wrapped.
+ */
+export type ExternalOrderLineInput = ExternalOrderCatalogLine | ExternalOrderExternalLine;
+/**
+ * An order-level adjustment that is not a line: a delivery charge, a negotiated
+ * discount, a handling fee.
+ *
+ * Priced by the caller like an external line, so it needs `ImportExternalLines`
+ * too. Its tax lines are written ONCE, through the store's configured tax-line
+ * strategy, so a tax-removed or reverse-charged order gets the right answer
+ * rather than the class's raw rate frozen onto the order for good.
+ */
+export interface ExternalOrderSurchargeInput {
+    /** What the customer reads, 1 to 255 characters. */
+    label: string;
+    /**
+     * Minor units, stated in {@link ExternalOrderSurchargeInput.priceBasis}.
+     * NEGATIVE for a deduction. Zero is refused (`LINE_ZERO_PRICE`): an
+     * adjustment that moves no money is almost always an amount that failed to
+     * compute.
+     */
+    amount: number;
+    /** Required, for the same reason it is required on a line. */
+    priceBasis: ExternalLinePriceBasis;
+    /** A `taxClass.key` of this store, resolved per order exactly as a line's is. */
+    taxClass: string;
+    /**
+     * The caller's own classification of the charge, stored as the surcharge's
+     * SKU. Unrelated to the `kind` discriminant on {@link ExternalOrderLineInput}
+     * — this one is the SDL's field name and carries the caller's data.
+     */
+    kind?: string | null;
+}
+/**
+ * A whole order, composed in one call.
+ *
+ * Every money figure in and out of this surface is an INTEGER of MINOR UNITS in
+ * the order's currency (`1999` is 19.99). There are no decimals anywhere on this
+ * API and a fractional value is refused rather than rounded.
+ */
+export interface ExternalOrderInput {
+    /**
+     * The vertical's own aggregate id for this order — an ERP number, a booking
+     * reference, a contract id. 1 to 255 characters, unique per store, trimmed but
+     * NOT case-folded: two systems that disagree about case disagree about
+     * identity.
+     *
+     * It is the handle {@link OrdersModule.byExternalRef} recovers by, and it
+     * never expires. See {@link OrdersModule.createOrRecover} for what happens
+     * when the same ref arrives twice.
+     */
+    externalRef: string;
+    /**
+     * An EXISTING customer of this channel. A customer of another store reads as
+     * absent, which is the same answer a bad id gets.
+     *
+     * There is no "create the customer too" here on purpose: core's
+     * customer-creation path reuses a row with the same email from ANY channel,
+     * which would hand a second tenant a handle on the first tenant's customer.
+     * Create the customer with `admin.customers.create` first.
+     */
+    customerId?: string | null;
+    /**
+     * A stock location of THIS channel, recorded as the order's
+     * `platform.location` metafield. A location id belonging to another store is
+     * `LOCATION_NOT_IN_CHANNEL` — the same code the `x-location` header gate and
+     * the API-token restriction writer answer with, because it is one rule
+     * enforced at three boundaries.
+     */
+    location?: string | null;
+    /**
+     * The order's billing address. Written to the order, and the first step of
+     * the country that selects each tax class's category mapping.
+     *
+     * Send it whenever your store maps a tax class differently per country. A
+     * composed order has no shipping address of its own, so the country is
+     * resolved in this order and stops at the first answer:
+     *
+     * 1. the order's shipping address, if something else has already set one;
+     * 2. this billing address;
+     * 3. for `fulfilment: 'pickup'`, the country of the `location` you named;
+     * 4. the store's default tax zone, when that zone names exactly ONE country
+     *    (an "EU" zone names 27 and therefore names none);
+     * 5. otherwise no country, which resolves through the class's `*` mapping.
+     *
+     * A class that says nothing about the resolved country and has no `*` mapping
+     * is `TAX_CLASS_UNMAPPED`.
+     */
+    billingAddress?: ExternalOrderAddressInput | null;
+    /**
+     * At least one line, at most 500. An empty order is refused rather than
+     * created: nothing on this API can add to an order afterwards, so an order
+     * with no lines is not a draft to fill in later.
+     *
+     * ORDER IS SIGNIFICANT. The position of a line in this array is what every
+     * refusal about a line names (`extensions.details.position`), and it is what
+     * each returned line carries back as `customFields.externalEntryPosition` —
+     * the handle to map a response line onto the request line that produced it,
+     * since a line has no id until it exists. Match on that FIELD rather than on
+     * array order; the response is sorted by it, but the field is the contract.
+     *
+     * ONE REQUEST LINE IS ONE ORDER LINE. Two externally priced lines that differ
+     * only in their `configuration` stay two lines, and two byte-identical ones
+     * stay two lines of quantity 1 rather than becoming one of quantity 2. If you
+     * mean two of something, send a quantity — which is also why two CATALOG
+     * lines naming the same variant are refused with `LINE_DUPLICATE_VARIANT`.
+     */
+    lines: ExternalOrderLineInput[];
+    /** Order-level adjustments. Refusals about one carry `collection: 'surcharges'`. */
+    surcharges?: ExternalOrderSurchargeInput[] | null;
+    /** Required: what is going to happen to the goods. */
+    fulfilment: ExternalOrderFulfilment;
+    /** Defaults to `Draft`. `Parked` is always refused — see {@link ExternalOrderTargetState}. */
+    transitionTo?: ExternalOrderTargetState | null;
+    /** Written to the ORDER's `platform.attachments` metafield. At most 50. */
+    attachments?: MetafieldAttachment[] | null;
+}
+/**
+ * A postal address, as the platform spells one.
+ *
+ * `countryCode` is required whenever an address is given at all: it is what
+ * selects this order's tax-class mapping, and the platform will not infer it
+ * from the rest of the address.
+ */
+export interface ExternalOrderAddressInput {
+    fullName?: string | null;
+    company?: string | null;
+    streetLine1?: string | null;
+    streetLine2?: string | null;
+    city?: string | null;
+    province?: string | null;
+    postalCode?: string | null;
+    /** ISO 3166-1 alpha-2. */
+    countryCode: string;
+    phoneNumber?: string | null;
+}
+/** One rate applied to a line, as the order's tax strategy resolved it. */
+export interface ExternalOrderTaxLine {
+    /** The store's own words for the rate, printed on documents. */
+    description: string;
+    /** Whole-number percent: `21` is 21 %. */
+    taxRate: number;
+}
+/**
+ * A line of the composed order.
+ *
+ * `productVariant` is present on EVERY line, including an externally priced one
+ * — that one names the hidden per-tax-class carrier variant it landed on, whose
+ * `name` and `sku` are platform bookkeeping and not what the customer reads. The
+ * customer reads the label the caller sent, which is what the platform prints.
+ */
+export interface ExternalOrderLine {
+    /** The handle every later call about this line uses. */
+    id: string;
+    quantity: number;
+    /** Minor units, excluding tax. */
+    unitPrice: number;
+    /** Minor units, including tax. */
+    unitPriceWithTax: number;
+    /** Minor units, excluding tax, for the whole line. */
+    linePrice: number;
+    /** Minor units, including tax, for the whole line. */
+    linePriceWithTax: number;
+    taxLines: ExternalOrderTaxLine[];
+    productVariant: {
+        id: string;
+        sku: string;
+        name: string;
+    };
+    /**
+     * `externalEntryPosition` is the zero-based index of the REQUEST line that
+     * produced this order line — the handle to map the response back onto what
+     * you sent. `externalEntryKey` is a hash of that request line's content, for a
+     * caller that would rather match on content than on position.
+     * `externalLineLabel` is your own words for an externally priced line, and is
+     * null on a catalog line.
+     */
+    customFields: {
+        externalEntryPosition: number | null;
+        externalEntryKey: string | null;
+        externalLineLabel: string | null;
+    } | null;
+}
+/** A surcharge as it sits on the composed order. */
+export interface ExternalOrderSurcharge {
+    id: string;
+    description: string;
+    /** The caller's `kind`, or null. */
+    sku: string | null;
+    /** Minor units, excluding tax. Negative for a deduction. */
+    price: number;
+    /** Minor units, including tax. */
+    priceWithTax: number;
+    /** Whole-number percent. */
+    taxRate: number;
+}
+/**
+ * The composed order, as much of it as this surface projects.
+ *
+ * The figures are the order's own persisted state after composition, not a
+ * projection of the request: an external line's price has been through the
+ * store's tax-line strategy, and a catalog line's through the catalogue.
+ */
+export interface ExternalOrder {
+    id: string;
+    /** The store's human-readable order code. */
+    code: string;
+    /** The order's state, `Draft` unless `transitionTo` asked for another. */
+    state: string;
+    currencyCode: string;
+    /** Minor units: all lines, excluding tax. */
+    subTotal: number;
+    subTotalWithTax: number;
+    /** Minor units: `subTotal` plus shipping. */
+    total: number;
+    /** Minor units: the final payable amount. */
+    totalWithTax: number;
+    lines: ExternalOrderLine[];
+    surcharges: ExternalOrderSurcharge[];
+    /**
+     * `externalRef` is on the ADMIN schema although the custom field is declared
+     * `public: false` — that flag withholds it from the SHOP API, where another
+     * system's order id has no business being, and says nothing about this one.
+     * Null on an order that was never composed through this surface.
+     */
+    customFields: {
+        externalRef: string | null;
+    } | null;
+}
+/**
+ * Options for {@link OrdersModule.createOrRecover}.
+ *
+ * `idempotencyKey` is REQUIRED, unlike everywhere else in this SDK: the engine
+ * declares it `String!`, so a caller that omitted it would be refused by GraphQL
+ * validation with the whole document 400ing rather than by anything actionable.
+ * Making it required here turns that into a compile error.
+ */
+export interface ExternalOrderCall extends Call {
+    /**
+     * A key the CALLER generates, valid for 24 hours. A UUIDv7 is ideal. Reuse it
+     * only when retrying that exact request — see {@link
+     * OrdersModule.createOrRecover} for how it differs from `externalRef`.
+     */
+    idempotencyKey: string;
+}
+/**
+ * External order entry (spec §8.1, §8.3, §8.4).
+ *
+ * One call composes a whole order — catalog lines at the store's prices,
+ * externally priced lines at the vertical's, surcharges, attachments — or
+ * composes nothing at all. The atomicity is the point: the caller is a
+ * vertical's trading system, and an order that exists with half its lines is
+ * worse for it than an order that does not exist.
+ */
+export interface OrderEntryModule {
+    /**
+     * Compose an order, or hand back the one this `externalRef` already names.
+     * Needs `CreateOrder`, plus `ImportExternalLines` when any line or surcharge
+     * is priced by the caller.
+     *
+     * ## Two different questions, two different keys
+     *
+     * `idempotencyKey` answers **"is this the same REQUEST I already made?"** — a
+     * key the caller generated, valid for 24 hours, replaying the first call's
+     * order on a repeat and refused with a `ConflictError` coded
+     * `IDEMPOTENCY_CONFLICT` when the same key arrives with a different body.
+     *
+     * `externalRef` answers **"is this the same ORDER?"** — the vertical's own
+     * aggregate id, valid for ever. A caller that lost its response, restarted and
+     * generated a fresh key still must not create a second order for the same
+     * trade, which is why recovery is keyed on the ref as well.
+     *
+     * **Recovery by ref is CONDITIONAL on the request being the same one.** The
+     * engine fingerprints the composed order against the ref, so re-posting a ref
+     * with different lines is a `ConflictError` coded `EXTERNAL_REF_CONFLICT`
+     * rather than a silent hand-back of an order that no longer matches what the
+     * caller thinks it sent.
+     * Read the existing one with {@link OrdersModule.byExternalRef}, or post the
+     * new order under its own reference. The same code answers a ref claimed by a
+     * concurrent call while this one was composing — the remedy is identical.
+     *
+     * ## What it refuses, and why none of it is a silent correction
+     *
+     * Everything below rolls the whole order back; there is never a half-composed
+     * order to clean up. Each refusal about a line or a surcharge carries the
+     * caller's own zero-based INDEX on `extensions.details`
+     * (`{ position, collection }`), because a vertical posting a basket of ten
+     * lines cannot act on "one of them is mispriced", and a line has no id yet to
+     * be named by.
+     *
+     * - `LINE_MISPRICED` — a catalog line's `expectedUnitPriceWithTax` is not what
+     *   the store charges. Never re-priced, never rounded to.
+     * - `LINE_ZERO_PRICE` — an external line or a surcharge priced at zero.
+     * - `LINE_NOT_SALEABLE` — the catalogue refused the line: no stock, not
+     *   orderable, an order that cannot take items. The engine's own message rides
+     *   along.
+     * - `INVALID_EXTERNAL_LINE` / `INVALID_EXTERNAL_REF` — structurally bad input:
+     *   a quantity below 1, a blank label, a missing basis, a line carrying both
+     *   `catalog` and `external` data or neither, a ref over 255 characters.
+     * - `LINE_DUPLICATE_VARIANT` — two catalog lines name the same variant.
+     *   `details` carries the second one's `position` and the first one's
+     *   `firstPosition`. Send one line with the quantity you want.
+     * - `EXTERNAL_LINE_PROMOTION_UNSUPPORTED` — a promotion discounted one of your
+     *   externally priced lines. An order-level promotion is shared across every
+     *   line of an order by the engine, so the platform refuses rather than
+     *   invoicing a price you did not state.
+     * - `LOCATION_NOT_IN_CHANNEL` — the location belongs to another store.
+     * - `TAX_CLASS_UNMAPPED` / `TAX_CLASS_RATE_MISSING` — the store's tax setup
+     *   cannot price this line for this order's country and zone.
+     * - `ORDER_TRANSITION_REFUSED` — `transitionTo` could not be reached, with the
+     *   state machine's own reason; also the answer to `Parked`, which is what
+     *   {@link OrdersModule.park} is for.
+     * - `HOOK_REJECTED` (`HookRejectedError`) — an app the store installed refused
+     *   the order through its `order.validate` hook, whatever `transitionTo` is
+     *   (a Draft is asked too). `appSlug`, `appCode` and `customerMessage` (the
+     *   app's own sentence) are typed on the error; `details` names the lines or
+     *   fields it pointed at. Nothing is created.
+     * - `HOOK_UNAVAILABLE` (`HookUnavailableError`) — such an app could not be
+     *   asked (timeout, failure, or suspended after repeated failures), and the
+     *   order is refused rather than placed unchecked. Not retried automatically;
+     *   the same `idempotencyKey` may be retried once the app answers again. With
+     *   `transitionTo: 'ArrangingPayment'` the store's tax provider app answers it
+     *   too when it cannot be asked (`details[1]` is `kind` / `tax.calculate`).
+     * - `TAX_CHANGED` (`ConflictError`) — with `transitionTo: 'ArrangingPayment'`,
+     *   the store's tax provider app answered different tax while the order was
+     *   being placed. Nothing is created; repeat the same call (same
+     *   `idempotencyKey`): the repeat composes the order afresh at the provider's
+     *   current tax.
+     *
+     * @param input the whole order. Money is integer minor units throughout.
+     * @param options must carry `idempotencyKey`; the engine declares it non-null.
+     */
+    createOrRecover(input: ExternalOrderInput, options: ExternalOrderCall): Promise<ExternalOrder>;
+    /**
+     * The order this store filed under `externalRef`, or null. Needs `ReadOrder`.
+     *
+     * The recovery read that never expires, and the one to reach for after an
+     * `EXTERNAL_REF_CONFLICT` or a lost response. Channel-scoped twice over, so a
+     * ref that names another store's order reads as null rather than leaking that
+     * it exists.
+     *
+     * Null means this store has nothing under that ref — it is not an error, and a
+     * caller that treats it as one will retry a ref it never successfully posted.
+     */
+    byExternalRef(externalRef: string, options?: Call): Promise<ExternalOrder | null>;
+    /**
+     * The order a previous {@link OrderEntryModule.createOrRecover} created under
+     * this idempotency key, or null. Needs `ReadOrder`.
+     *
+     * Null once the key's 24-hour window has passed and the record is swept — a
+     * caller that waited that long has the `externalRef`, which does not expire.
+     * Null is also what another tenant's or another principal's key gets: the key
+     * is scoped to `(channel, principal, key)`, never global.
+     *
+     * So null here is NEVER proof that no order was created. Fall back to
+     * {@link OrderEntryModule.byExternalRef} before deciding to post again.
+     */
+    byIdempotencyKey(key: string, options?: Call): Promise<ExternalOrder | null>;
+}
+export declare const CREATE_OR_RECOVER_ORDER_MUTATION = "\n  mutation CreateOrRecoverOrder($input: ExternalOrderInput!, $idempotencyKey: String!) {\n    createOrRecoverOrder(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  code\n  state\n  currencyCode\n  subTotal\n  subTotalWithTax\n  total\n  totalWithTax\n  lines {\n    id\n    quantity\n    unitPrice\n    unitPriceWithTax\n    linePrice\n    linePriceWithTax\n    taxLines {\n      description\n      taxRate\n    }\n    productVariant {\n      id\n      sku\n      name\n    }\n    customFields {\n      externalEntryPosition\n      externalEntryKey\n      externalLineLabel\n    }\n  }\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n  customFields {\n    externalRef\n  }\n\n    }\n  }\n";
+export declare const ORDER_BY_EXTERNAL_REF_QUERY = "\n  query OrderByExternalRef($externalRef: String!) {\n    orderByExternalRef(externalRef: $externalRef) {\n      \n  id\n  code\n  state\n  currencyCode\n  subTotal\n  subTotalWithTax\n  total\n  totalWithTax\n  lines {\n    id\n    quantity\n    unitPrice\n    unitPriceWithTax\n    linePrice\n    linePriceWithTax\n    taxLines {\n      description\n      taxRate\n    }\n    productVariant {\n      id\n      sku\n      name\n    }\n    customFields {\n      externalEntryPosition\n      externalEntryKey\n      externalLineLabel\n    }\n  }\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n  customFields {\n    externalRef\n  }\n\n    }\n  }\n";
+export declare const ORDER_BY_IDEMPOTENCY_KEY_QUERY = "\n  query OrderByIdempotencyKey($key: String!) {\n    orderByIdempotencyKey(key: $key) {\n      \n  id\n  code\n  state\n  currencyCode\n  subTotal\n  subTotalWithTax\n  total\n  totalWithTax\n  lines {\n    id\n    quantity\n    unitPrice\n    unitPriceWithTax\n    linePrice\n    linePriceWithTax\n    taxLines {\n      description\n      taxRate\n    }\n    productVariant {\n      id\n      sku\n      name\n    }\n    customFields {\n      externalEntryPosition\n      externalEntryKey\n      externalLineLabel\n    }\n  }\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n  customFields {\n    externalRef\n  }\n\n    }\n  }\n";
+/** The wire shape of one line: exactly one of the two members set. */
+interface WireLine {
+    catalog?: Omit<ExternalOrderCatalogLine, 'kind'>;
+    external?: Omit<ExternalOrderExternalLine, 'kind'>;
+}
+/**
+ * The SDK's discriminated line → the wrapper member the SDL declares.
+ *
+ * `kind` is stripped rather than sent: it is not a field of either input type,
+ * and the Admin API runs `forbidNonWhitelisted`-equivalent GraphQL input
+ * coercion, so leaving it on would 400 the whole document.
+ *
+ * Every other key is copied ACROSS, never rebuilt field by field: `configuration`
+ * is the caller's own JSON and must reach the engine byte-for-byte, and a
+ * hand-written field list would also silently drop a field added to the input
+ * type later. Nothing on this path converts case — see
+ * {@link ExternalOrderExternalLine.configuration}.
+ *
+ * An absent optional stays ABSENT rather than becoming an explicit null:
+ * `JSON.stringify` drops `undefined`, and the engine's request fingerprint is
+ * taken from the raw wire arguments, so coercing one to null here would make two
+ * identical requests look different to the idempotency store.
+ */
+export declare function toWireLine(line: ExternalOrderLineInput): WireLine;
+export declare function createOrderEntryModule(transport: Transport): OrderEntryModule;
+export {};