@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/reports/index.d.ts

@@ -0,0 +1,199 @@
+import { type OrderScope, type Page, type Transport } from '@sixtyninecommerce/core';
+import type { BulkModule, BulkOperation } from '../bulk/index.js';
+import type { JobHandle, JobsModule } from '../jobs/index.js';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * A report period (spec §9.3).
+ *
+ * Each bound is EITHER a date, `YYYY-MM-DD`, read as a whole day in the
+ * STORE's time zone (`Channel.customFields.timezone`, else Europe/Amsterdam) —
+ * never yours, never the server's — OR an ISO-8601 instant WITH an explicit
+ * offset (`2026-09-01T00:00:00+02:00`, `…Z`); a time without an offset is
+ * refused (`INVALID_REPORT_PERIOD`, a `ValidationError`).
+ *
+ * `from` is inclusive. `to` is inclusive as a DATE (`{ from: '2026-09-01',
+ * to: '2026-09-30' }` is all of September) and exclusive as an instant. At most
+ * 366 days.
+ */
+export interface ReportPeriod {
+    from: string;
+    to: string;
+}
+export interface ReportOverviewInput {
+    period: ReportPeriod;
+    /**
+     * One stock location of this store (`stockLocationId`). Keeps the orders whose
+     * stock was allocated or sold there, or that stated it at entry; an order
+     * touching two locations counts at both. A location of another store is
+     * refused with `LOCATION_NOT_IN_CHANNEL` (`ValidationError`). Omitted, the
+     * client's `tenant.location` (`x-location`) applies, as on every
+     * location-taking read. A credential restricted to some locations
+     * (`locationIds`) is refused elsewhere with `LOCATION_NOT_ALLOWED`
+     * (`PermissionDeniedError`) and, naming none, reads only its own locations'
+     * orders.
+     */
+    locationId?: string;
+    /** One storefront's orders: `CONSUMER` (retail) or `TRADE` (B2B). */
+    orderScope?: OrderScope;
+}
+/** The money of one period. Every `…Minor` is an integer in minor units of `currencyCode`. */
+export interface ReportTotals {
+    /** Placed, uncancelled orders — every currency. Carts never count. */
+    orderCount: number;
+    cancelledCount: number;
+    /**
+     * What those orders BILLED: the sum of each order's total with its goodwill
+     * rounding folded in — the same figure its invoice and its payment position
+     * read — for the orders in `currencyCode`.
+     */
+    revenueMinor: number;
+    /** The same orders' billable net totals, the rounding split at each order's own VAT rate. */
+    revenueNetMinor: number;
+    /** `revenueMinor` ÷ the orders in `currencyCode`, rounded half up. */
+    averageOrderValueMinor: number;
+    averageOrderValueNetMinor: number;
+    /** Orders placed in another currency: in `orderCount`, in no `…Minor` figure. */
+    ordersInOtherCurrencies: number;
+}
+/** One day of the store's calendar. */
+export interface ReportDay {
+    /** The instant the day begins in the store's zone, ISO-8601 UTC. A DST day is 23 or 25 hours long. */
+    startsAt: string;
+    orderCount: number;
+    revenueMinor: number;
+    revenueNetMinor: number;
+}
+export interface ReportOverview {
+    /** ISO 4217. The store's default currency; every `…Minor` value is in it. */
+    currencyCode: string;
+    /** IANA zone the days are cut in — the store's. */
+    timeZone: string;
+    /** The resolved period, ISO-8601 UTC: `from` inclusive, `to` exclusive. */
+    from: string;
+    to: string;
+    /** The comparison window immediately before, same length. */
+    previousFrom: string;
+    previousTo: string;
+    current: ReportTotals;
+    previous: ReportTotals;
+    days: ReportDay[];
+    newCustomers: number;
+    previousNewCustomers: number;
+    /** Live, not period-scoped: placed orders whose goods have not all been handed off. */
+    awaitingFulfillment: number;
+    /** Placed orders of the period by lifecycle (`open`, `completed`, `cancelled`). */
+    statusBreakdown: Array<{
+        status: string;
+        count: number;
+    }>;
+    topProducts: Array<{
+        productVariantId: string;
+        productId: string;
+        name: string;
+        sku: string;
+        unitsSold: number;
+    }>;
+}
+export interface PopularVariantsInput {
+    /** 1–50, default 8. */
+    take?: number;
+    /** 1–3650, default 90. */
+    sinceDays?: number;
+}
+export interface PopularVariant {
+    id: string;
+    productId: string;
+    name: string;
+    sku: string;
+}
+export interface LowStockInput extends ListOptions {
+    /** Rows whose `available` is at or below this; a whole number, 0–1,000,000. */
+    threshold: number;
+    /**
+     * One stock location of this store. Omitted: the client's `tenant.location`
+     * (`x-location`), else every location this credential may act at.
+     */
+    locationId?: string;
+}
+/** One variant at one stock location. */
+export interface LowStockVariant {
+    productVariantId: string;
+    productId: string;
+    sku: string;
+    name: string;
+    stockLocationId: string;
+    stockLocationName: string;
+    stockOnHand: number;
+    stockAllocated: number;
+    /** Units the out-of-stock threshold holds back from sale: `max(0, threshold)`. */
+    reserved: number;
+    /**
+     * `stockOnHand − stockAllocated − threshold` — the same figure `admin.stock`
+     * reports; negative when more is allocated than can be sold.
+     */
+    available: number;
+}
+/** The reports `export` can produce. */
+export type ReportExportKind = 'overview';
+export interface ReportExportFilter {
+    period: ReportPeriod;
+    /**
+     * Omitted, the client's (or the call's) `tenant.location` is used — the same
+     * fallback `overview` gets from `x-location` — so a file and the screen it
+     * mirrors cover the same place.
+     */
+    locationId?: string;
+    orderScope?: OrderScope;
+}
+/**
+ * A finished export: a bulk operation whose `resultUrl` is a short-lived
+ * signed link to the JSONL — one line per store day:
+ * `{ date, startsAt, timeZone, currencyCode, orderCount, revenueMinor, revenueNetMinor }`.
+ * Read `status` before the file: a failed run carries `error.code`.
+ */
+export type ReportExport = Omit<BulkOperation, 'entity'> & {
+    /** Export-only report entities are not among the importable `BulkEntity` values. */
+    entity: 'report_overview';
+};
+/**
+ * Tenant reporting (spec §9.2 `reports`): the order-analytics surface the
+ * dashboard reads, with money in integer minor units + `currencyCode` and time
+ * as ISO-8601 UTC (§9.3).
+ *
+ * Everything is scoped to the client's store; nothing here reads another.
+ * `overview` needs `ReadOrder`, `lowStock` `ReadCatalog` or `ReadProduct`,
+ * `popularVariants` `ReadOrder`, `export` `ReadOrder`. The cross-store fleet is
+ * `admin.platform.reports.fleet` (SuperAdmin session only).
+ */
+export interface ReportsModule {
+    /** Orders, revenue and customers of a period, by the store's own days. */
+    overview(input: ReportOverviewInput, options?: Call): Promise<ReportOverview>;
+    /**
+     * Variants ranked by units sold in placed orders of the last `sinceDays`
+     * days, most first. A `Page` because every list is one; it is always a
+     * single, final page.
+     */
+    popularVariants(input?: PopularVariantsInput, options?: Call): Promise<Page<PopularVariant>>;
+    /**
+     * Variants at or below `threshold` available units, per stock location,
+     * lowest first. Untracked variants are never low.
+     */
+    lowStock(input: LowStockInput): Promise<Page<LowStockVariant>>;
+    /**
+     * Write a report to a file, as a job (`kind: report.export`). `wait()`
+     * resolves with the operation and a freshly signed `resultUrl`. The filter's
+     * shape is checked when you call; its meaning (a real period, a location of
+     * this store) when the job runs, so a bad location fails the JOB. A
+     * location-restricted credential must name one of its own locations
+     * (`LOCATION_NOT_ALLOWED` otherwise) — a store-wide file is what its
+     * restriction withholds.
+     */
+    export(kind: ReportExportKind, filter: ReportExportFilter, options?: Call): Promise<JobHandle<ReportExport>>;
+}
+/** Only the §9.3 generation is selected — never the deprecated Float/String fields. */
+export declare const REPORT_OVERVIEW_QUERY = "\n  query ReportOverview($range: ReportPeriodInput!, $locationId: ID, $orderScope: OrderScope) {\n    commerceOverviewMetrics(range: $range, locationId: $locationId, orderScope: $orderScope) {\n      currencyCode\n      timeZone\n      from\n      to\n      previousFrom\n      previousTo\n      current { \n  orderCount\n  cancelledCount\n  revenueMinor\n  revenueNetMinor\n  averageOrderValueMinor\n  averageOrderValueNetMinor\n  ordersInOtherCurrencies\n }\n      previous { \n  orderCount\n  cancelledCount\n  revenueMinor\n  revenueNetMinor\n  averageOrderValueMinor\n  averageOrderValueNetMinor\n  ordersInOtherCurrencies\n }\n      revenueSeries { startsAt valueMinor valueNetMinor }\n      orderSeries { startsAt value }\n      newCustomers\n      previousNewCustomers\n      awaitingFulfillment\n      statusBreakdown { state count }\n      topProducts { productVariantId productId name sku unitsSold }\n    }\n  }\n";
+export declare const POPULAR_VARIANTS_QUERY = "\n  query ReportPopularVariants($take: Int, $sinceDays: Int) {\n    popularProductVariantsInChannel(take: $take, sinceDays: $sinceDays) {\n      id\n      productId\n      name\n      sku\n    }\n  }\n";
+export declare const LOW_STOCK_QUERY = "\n  query ReportLowStock($threshold: Int!, $locationId: ID, $options: LowStockVariantListOptions) {\n    lowStockVariants(threshold: $threshold, locationId: $locationId, options: $options) {\n      items {\n        productVariantId\n        productId\n        sku\n        name\n        stockLocationId\n        stockLocationName\n        stockOnHand\n        stockAllocated\n        reserved\n        available\n      }\n      totalItems\n    }\n  }\n";
+export declare function createReportsModule(transport: Transport, bulk: BulkModule, jobs: JobsModule, 
+/** The client's `tenant.location`, read per call (a derived client has its own). */
+clientLocation?: () => string | undefined): ReportsModule;

package/dist/reports/index.js

@@ -0,0 +1,154 @@
+import { createPage, pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+const TOTALS_FIELDS = /* GraphQL */ `
+  orderCount
+  cancelledCount
+  revenueMinor
+  revenueNetMinor
+  averageOrderValueMinor
+  averageOrderValueNetMinor
+  ordersInOtherCurrencies
+`;
+/** Only the §9.3 generation is selected — never the deprecated Float/String fields. */
+export const REPORT_OVERVIEW_QUERY = /* GraphQL */ `
+  query ReportOverview($range: ReportPeriodInput!, $locationId: ID, $orderScope: OrderScope) {
+    commerceOverviewMetrics(range: $range, locationId: $locationId, orderScope: $orderScope) {
+      currencyCode
+      timeZone
+      from
+      to
+      previousFrom
+      previousTo
+      current { ${TOTALS_FIELDS} }
+      previous { ${TOTALS_FIELDS} }
+      revenueSeries { startsAt valueMinor valueNetMinor }
+      orderSeries { startsAt value }
+      newCustomers
+      previousNewCustomers
+      awaitingFulfillment
+      statusBreakdown { state count }
+      topProducts { productVariantId productId name sku unitsSold }
+    }
+  }
+`;
+export const POPULAR_VARIANTS_QUERY = /* GraphQL */ `
+  query ReportPopularVariants($take: Int, $sinceDays: Int) {
+    popularProductVariantsInChannel(take: $take, sinceDays: $sinceDays) {
+      id
+      productId
+      name
+      sku
+    }
+  }
+`;
+export const LOW_STOCK_QUERY = /* GraphQL */ `
+  query ReportLowStock($threshold: Int!, $locationId: ID, $options: LowStockVariantListOptions) {
+    lowStockVariants(threshold: $threshold, locationId: $locationId, options: $options) {
+      items {
+        productVariantId
+        productId
+        sku
+        name
+        stockLocationId
+        stockLocationName
+        stockOnHand
+        stockAllocated
+        reserved
+        available
+      }
+      totalItems
+    }
+  }
+`;
+const DEFAULT_LOW_STOCK_PAGE = 50;
+/** The bulk entity a report kind is exported as. */
+const EXPORT_ENTITY = { overview: 'report_overview' };
+/** Filter keys travel as the service spells them — see `bulk/index.ts`'s `FILTER_PASSTHROUGH`. */
+const FILTER_PASSTHROUGH = new Set(['filter']);
+export function createReportsModule(transport, bulk, jobs, 
+/** The client's `tenant.location`, read per call (a derived client has its own). */
+clientLocation = () => undefined) {
+    const lowStockPage = async (input, skip, take) => {
+        const data = await transport.graphql({
+            api: 'admin',
+            query: LOW_STOCK_QUERY,
+            variables: {
+                threshold: input.threshold,
+                locationId: input.locationId ?? null,
+                options: { skip, take },
+            },
+        }, input);
+        return pageFromVendureList(data.lowStockVariants, skip, take, (cursor) => lowStockPage(input, readOffsetCursor(cursor), take));
+    };
+    return {
+        async overview(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REPORT_OVERVIEW_QUERY,
+                variables: {
+                    range: { from: input.period.from, to: input.period.to },
+                    locationId: input.locationId ?? null,
+                    orderScope: input.orderScope ?? null,
+                },
+            }, options);
+            const { revenueSeries, orderSeries, statusBreakdown, ...rest } = data.commerceOverviewMetrics;
+            // The two series are the same buckets; joined on the instant rather than
+            // the index so a reordering on the server could never pair two days.
+            const orders = new Map(orderSeries.map((point) => [point.startsAt, point.value]));
+            return {
+                ...rest,
+                days: revenueSeries.map((point) => ({
+                    startsAt: point.startsAt,
+                    orderCount: orders.get(point.startsAt) ?? 0,
+                    revenueMinor: point.valueMinor ?? 0,
+                    revenueNetMinor: point.valueNetMinor ?? 0,
+                })),
+                statusBreakdown: statusBreakdown.map((row) => ({ status: row.state, count: row.count })),
+            };
+        },
+        async popularVariants(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: POPULAR_VARIANTS_QUERY,
+                variables: { take: input?.take ?? null, sinceDays: input?.sinceDays ?? null },
+            }, options);
+            const items = data.popularProductVariantsInChannel;
+            return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+                // Unreachable while `hasNext` is false — `Page.next()` short-circuits.
+                throw new Error('popularVariants returns one ranked list; there is no next page');
+            });
+        },
+        lowStock(input) {
+            const take = input.limit ?? DEFAULT_LOW_STOCK_PAGE;
+            const skip = input.after === undefined ? 0 : readOffsetCursor(input.after);
+            return lowStockPage(input, skip, take);
+        },
+        async export(kind, filter, options) {
+            // The worker runs without the caller's `x-location`, so the fallback
+            // `overview` gets from that header is applied here, explicitly.
+            const locationId = filter.locationId ?? options?.tenant?.location ?? clientLocation();
+            const { jobId } = await transport.rest('plugins', {
+                method: 'POST',
+                path: '/bulk/exports',
+                body: {
+                    entity: EXPORT_ENTITY[kind],
+                    filter: {
+                        from: filter.period.from,
+                        to: filter.period.to,
+                        ...(locationId === undefined ? {} : { location_id: locationId }),
+                        ...(filter.orderScope === undefined ? {} : { order_scope: filter.orderScope }),
+                    },
+                },
+            }, { ...options, preserveKeys: FILTER_PASSTHROUGH });
+            return {
+                runId: jobId,
+                async wait(waitOptions) {
+                    // Wait on the JOB, then read the operation once: its signed link is
+                    // minted per read, so one minted while the run was going would have
+                    // expired by the time the file existed.
+                    await jobs.wait(jobId, { ...options, ...waitOptions });
+                    return (await bulk.get(jobId, options));
+                },
+            };
+        },
+    };
+}

package/dist/returns/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * `admin.returns`: the single-return reads of the returns (RMA) plugin, and the
+ * plan for settling one (headless plan W9-47).
+ *
+ * A first, minimal module: the reads the order and return pages need. The list
+ * (`orderReturns`) and the writes (create, approve, reject, cancel, receipt,
+ * settle, notes, numbering) are phase 7. Money is in MINOR UNITS throughout,
+ * as everywhere in this SDK.
+ *
+ * Every value set below is the engine's own and grows over time, so each field
+ * that carries one also accepts a string this version does not name: treat an
+ * unknown value as "not available".
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** A return's state: the latest row of its status log. */
+export declare const RETURN_STATES: readonly ["requested", "approved", "rejected", "cancelled", "items_received", "settlement_pending", "settlement_failed", "settled"];
+export type ReturnState = (typeof RETURN_STATES)[number];
+/**
+ * How a return is settled. `refund` gives money back to an original payment.
+ * `store_credit` issues a credit note: on a store with an accounts-receivable
+ * ledger it credits the customer's account, elsewhere it credits the order's
+ * invoice and moves no money.
+ */
+export declare const RETURN_SETTLEMENT_METHODS: readonly ["refund", "store_credit"];
+export type ReturnSettlementMethod = (typeof RETURN_SETTLEMENT_METHODS)[number];
+export interface OrderReturnLine {
+    id: string;
+    returnId: string;
+    orderLineId: string;
+    productVariantId: string;
+    productVariantName: string;
+    productVariantSku: string;
+    requestedQty: number;
+    /** Null until approval; 0 means the line was declined. */
+    approvedQty: number | null;
+    /** Units received back, across every receipt. */
+    receivedQty: number;
+    restockQty: number;
+    writeOffQty: number;
+    restockLocationId: string | null;
+    /** `damaged`, `defective`, `wrong_item`, `not_as_described`, `arrived_late`, `no_longer_needed`, `order_error`, `other`. */
+    reasonCode: string;
+    reasonNote: string | null;
+    /** The order line's prorated unit price incl. tax, rounded per unit. Display only. */
+    unitPriceWithTax: number;
+    /**
+     * The same price before per-unit rounding; null for returns requested before
+     * it was recorded. Multiply by a quantity and round ONCE to estimate a line.
+     */
+    unitPriceWithTaxUnrounded: number | null;
+    /** What the line refunds; null until approved. */
+    refundAmount: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One row of a return's status log. */
+export interface OrderReturnStatusLogEntry {
+    state: ReturnState | (string & {});
+    /** `customer`, `admin` or `system`. */
+    actor: string;
+    actorUserId: string | null;
+    reason: string | null;
+    createdAt: string;
+}
+export interface OrderReturn {
+    id: string;
+    /** The human-facing RMA code, e.g. `RMA-000042`. */
+    code: string;
+    channelId: string;
+    orderId: string;
+    orderCode: string;
+    customerId: string;
+    currencyCode: string;
+    state: ReturnState | (string & {});
+    /** `customer` or `admin`. */
+    initiator: string;
+    customerNote: string | null;
+    adminNote: string | null;
+    preferredSettlementMethod: ReturnSettlementMethod | (string & {}) | null;
+    /** The method it was settled with; null until settled. */
+    settlementMethod: ReturnSettlementMethod | (string & {}) | null;
+    /** Shipping refunded on top of the lines. */
+    shippingRefundAmount: number;
+    /** What was settled; null until settled. */
+    settledAmount: number | null;
+    refundId: string | null;
+    creditNoteId: string | null;
+    creditNoteNumber: string | null;
+    requestedAt: string;
+    resolvedAt: string | null;
+    lines: OrderReturnLine[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** {@link OrderReturn} with its status log, newest first: what `get` answers. */
+export interface OrderReturnDetail extends OrderReturn {
+    history: OrderReturnStatusLogEntry[];
+}
+/** One order line and what of it can still be returned. */
+export interface ReturnableOrderLine {
+    orderLineId: string;
+    productVariantId: string;
+    productVariantName: string;
+    productVariantSku: string;
+    /** Units shipped or delivered. */
+    fulfilledQty: number;
+    /** `fulfilledQty` less the units other open returns already claim. */
+    returnableQty: number;
+    unitPriceWithTax: number;
+    unitPriceWithTaxUnrounded: number;
+}
+export interface ReturnEligibility {
+    orderId: string;
+    /** False only when nothing is returnable: an admin may return outside the window. */
+    eligible: boolean;
+    /** Why not, when not eligible. */
+    reason: string | null;
+    /** ISO-8601 with offset; null when the store sets no window. */
+    returnWindowEndsAt: string | null;
+    /** Lines with a fulfilled quantity only. */
+    lines: ReturnableOrderLine[];
+}
+/** Why a return cannot be settled now, in the order the engine checks them. */
+export declare const RETURN_SETTLEMENT_BLOCKERS: readonly ["OUTCOME_UNKNOWN", "ALREADY_SETTLED", "IN_PROGRESS", "RECEIPT_REQUIRED", "STATE"];
+/**
+ * - `OUTCOME_UNKNOWN`: the refund it waits on reached the provider and was never
+ *   confirmed. Record the provider's answer first (`reconcileRefundOutcome`):
+ *   made completes the return, not made lets it be settled again.
+ * - `ALREADY_SETTLED`: settled, or settled by a credit note.
+ * - `IN_PROGRESS`: a refund is on its way and settles the return when the
+ *   provider confirms it.
+ * - `RECEIPT_REQUIRED`: approved, and the store requires the goods received first.
+ * - `STATE`: requested, rejected or cancelled.
+ */
+export type ReturnSettlementBlocker = (typeof RETURN_SETTLEMENT_BLOCKERS)[number];
+/**
+ * - `NO_REFUNDABLE_PAYMENT`: no settled payment can still give money back (net
+ *   terms, everything refunded, reserved by a refund of unknown outcome, or
+ *   moved to the customer's account).
+ * - `REFUND_ORPHAN_EXISTS`: a refund of the invoiced order stands that no credit
+ *   note names; another refund could pay the same money back twice.
+ */
+export type ReturnRefundUnavailableReason = 'NO_REFUNDABLE_PAYMENT' | 'REFUND_ORPHAN_EXISTS';
+/**
+ * - `AR`: the store keeps an accounts-receivable ledger; the credit note credits
+ *   the customer's account, which is money.
+ * - `RETAIL`: the credit note credits the order's invoice and moves no money.
+ */
+export type ReturnCreditNoteLedger = 'AR' | 'RETAIL';
+/**
+ * - `ISSUER_UNAVAILABLE`: the server runs without the plugin that issues it.
+ * - `CURRENCY_MISMATCH` (`AR`): the order is not in the store's default currency.
+ * - `NO_CREDITABLE_INVOICE` (`RETAIL`): the order has no live invoice to credit.
+ * - `REFUND_ORPHAN_EXISTS` (`AR`): as for the refund.
+ */
+export type ReturnCreditNoteUnavailableReason = 'ISSUER_UNAVAILABLE' | 'CURRENCY_MISMATCH' | 'NO_CREDITABLE_INVOICE' | 'REFUND_ORPHAN_EXISTS';
+/** A settled payment a refund may name, with what it can still give back. */
+export interface ReturnSettlementPayment {
+    paymentId: string;
+    method: string;
+    /** As the platform's refund position counts it. */
+    refundable: number;
+}
+export interface ReturnSettlementOptions {
+    returnId: string;
+    currencyCode: string;
+    settleable: boolean;
+    /** Null exactly when `settleable`. */
+    blockedBy: ReturnSettlementBlocker | (string & {}) | null;
+    refund: {
+        available: boolean;
+        /** Null exactly when `available`. */
+        reasonCode: ReturnRefundUnavailableReason | (string & {}) | null;
+        /** Empty when not available. */
+        payments: ReturnSettlementPayment[];
+    };
+    creditNote: {
+        available: boolean;
+        ledger: ReturnCreditNoteLedger | (string & {});
+        /** Null exactly when `available`. */
+        reasonCode: ReturnCreditNoteUnavailableReason | (string & {}) | null;
+        /** `RETAIL` only: the invoice it would credit, when known. */
+        invoiceNumber: string | null;
+    };
+    /** The credit note when asked for or when no refund is possible, and it is available; else `refund`. */
+    initialMethod: ReturnSettlementMethod | (string & {});
+    /** The approved line total: what a settlement without an override settles, before shipping. */
+    defaultAmount: number;
+}
+export declare const RETURN_QUERY = "\n  query SdkOrderReturn($id: ID!) {\n    orderReturn(id: $id) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n    }\n  }\n";
+export declare const RETURNS_FOR_ORDER_QUERY = "\n  query SdkReturnsForOrder($orderId: ID!) {\n    returnsForOrder(orderId: $orderId) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const RETURN_ELIGIBILITY_QUERY = "\n  query SdkReturnEligibility($orderId: ID!) {\n    returnEligibilityForOrder(orderId: $orderId) {\n      orderId\n      eligible\n      reason\n      returnWindowEndsAt\n      lines {\n        orderLineId\n        productVariantId\n        productVariantName\n        productVariantSku\n        fulfilledQty\n        returnableQty\n        unitPriceWithTax\n        unitPriceWithTaxUnrounded\n      }\n    }\n  }\n";
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY = "\n  query SdkReturnSettlementOptions($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      initialMethod\n      defaultAmount\n    }\n  }\n";
+export interface ReturnsModule {
+    /**
+     * One return with its lines and its status log (newest first), or `null`
+     * when this store holds no return with that id. Needs `ReadOrderReturn`.
+     */
+    get(id: string, options?: Call): Promise<OrderReturnDetail | null>;
+    /** Every return of one order, newest first. Needs `ReadOrderReturn`. */
+    forOrder(orderId: string, options?: Call): Promise<OrderReturn[]>;
+    /**
+     * What of an order can still be returned, line by line, and the return
+     * window. The window is reported, never enforced here: an admin may return
+     * outside it. Needs `ReadOrderReturn`.
+     */
+    eligibility(orderId: string, options?: Call): Promise<ReturnEligibility>;
+    /**
+     * How a return can be settled now: whether it is settleable (and why not),
+     * which methods are open (with the payments a refund may name and what each
+     * can still give back), and which method to preselect. Needs
+     * `ReadOrderReturn` AND `ReadOrder`: it names the order's payments.
+     *
+     * This is the PLAN. The write (`settleReturn`) loads its own facts and judges
+     * again, so settling can still be refused when something changed in between,
+     * and an `amountOverride` above a payment's headroom is refused there. A
+     * return this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`).
+     *
+     * Needs an engine that serves `returnSettlementOptions`; against an older one
+     * this call fails validation and nothing else does.
+     */
+    settlementOptions(returnId: string, options?: Call): Promise<ReturnSettlementOptions>;
+}
+export declare function createReturnsModule(transport: Transport): ReturnsModule;