@tallyui/connector-vendure 3.7.1 → 3.9.0

package/dist/index.d.ts

@@ -128,6 +128,186 @@ declare function searchVendureCustomers(context: SyncContext, query: string, opt
 declare function createVendureCustomer(context: SyncContext, input: CustomerInput): Promise<Customer>;
 declare function getVendureCustomer(context: SyncContext, id: string): Promise<Customer | null>;
 
+interface VendureOrderListOptions {
+    /** Offset, default 0; negative or fractional values are truncated and floored to 0. */
+    skip?: number;
+    /** Page size, default 25, clamped to 1..100. */
+    take?: number;
+    /** Vendure's DateOperators on orderPlacedAt; only these three keys are sent. */
+    orderPlacedAt?: {
+        after?: string;
+        before?: string;
+        between?: {
+            start: string;
+            end: string;
+        };
+    };
+    /** Order states, sent as `state: { in }` when non-empty. */
+    state?: string[];
+    /** The plugin's register id custom field, sent as `tallyRegisterId: { eq }` when non-empty. */
+    tallyRegisterId?: string;
+    /** The plugin's cashier custom field, sent as `tallyCashierRef: { eq }` when non-empty. */
+    tallyCashierRef?: string;
+    /** Lists through `customer(id) { orders }` when non-empty. */
+    customerId?: string;
+    /** Trimmed; when non-empty, matches order code or customer last name with `contains`. */
+    search?: string;
+    /** Select the vendurepos plugin's custom fields; default true. False for a server without the plugin. */
+    tallyFields?: boolean;
+}
+interface VendureOrderList<T> {
+    items: T[];
+    totalItems: number;
+}
+interface VendureOrderSummary {
+    id: string;
+    code: string;
+    state: string;
+    orderPlacedAt: string | null;
+    updatedAt: string;
+    currencyCode: string;
+    totalQuantity: number;
+    total: number;
+    totalWithTax: number;
+    customer: {
+        id: string;
+        firstName: string;
+        lastName: string;
+        emailAddress: string;
+    } | null;
+    customFields?: {
+        tallyClientOrderId: string | null;
+        tallySaleAt: string | null;
+        tallyRegisterId: string | null;
+        tallySessionId: string | null;
+        tallyCashierRef: string | null;
+        tallyRejected: boolean | null;
+        tallyRejectedClientOrderId: string | null;
+    };
+}
+interface VendureOrder extends VendureOrderSummary {
+    active: boolean;
+    lines: {
+        id: string;
+        quantity: number;
+        orderPlacedQuantity: number;
+        proratedUnitPrice: number;
+        /** Vendure's per-unit value used in refund calculations, which the till sums for `order.refund`'s `totalMinor` (ADR-080). */
+        proratedUnitPriceWithTax: number;
+        taxRate: number;
+        productVariant: {
+            id: string;
+            name: string;
+            sku: string;
+        };
+        unitPrice: number;
+        unitPriceWithTax: number;
+        linePrice: number;
+        linePriceWithTax: number;
+        discountedLinePrice: number;
+        discountedLinePriceWithTax: number;
+        discounts: {
+            description: string;
+            amount: number;
+            amountWithTax: number;
+        }[];
+        customFields?: {
+            tallyCustomName: string | null;
+            tallyCustomSku: string | null;
+            tallyUnitPrice: number | null;
+            tallyPriceIncludesTax: boolean | null;
+            tallyClientLineId: string | null;
+        };
+    }[];
+    shippingLines: {
+        shippingMethod: {
+            name: string;
+        };
+        price: number;
+        priceWithTax: number;
+    }[];
+    surcharges: {
+        description: string;
+        sku: string;
+        price: number;
+        priceWithTax: number;
+    }[];
+    subTotal: number;
+    subTotalWithTax: number;
+    shipping: number;
+    shippingWithTax: number;
+    taxSummary: {
+        description: string;
+        taxRate: number;
+        taxBase: number;
+        taxTotal: number;
+    }[];
+    discounts: {
+        description: string;
+        amount: number;
+        amountWithTax: number;
+    }[];
+    couponCodes: string[];
+    payments?: {
+        id: string;
+        method: string;
+        amount: number;
+        state: string;
+        transactionId: string;
+        createdAt: string;
+        metadata: unknown;
+        refunds: {
+            id: string;
+            total: number;
+            items: number;
+            shipping: number;
+            adjustment: number;
+            state: string;
+            reason: string;
+            metadata: unknown;
+            lines: {
+                orderLineId: string;
+                quantity: number;
+            }[];
+        }[];
+    }[];
+    fulfillments?: {
+        id: string;
+        state: string;
+        method: string;
+        trackingCode: string;
+    }[];
+    customFields?: VendureOrderSummary['customFields'] & {
+        tallyPayments: string | null;
+        tallySnapshot: string | null;
+        tallyShipping: string | null;
+    };
+}
+declare function listVendureOrders(context: SyncContext, options?: VendureOrderListOptions): Promise<VendureOrderList<VendureOrderSummary>>;
+declare function getVendureOrder(context: SyncContext, id: string, options?: {
+    tallyFields?: boolean;
+}): Promise<VendureOrder | null>;
+
+interface VendureRefundableLine {
+    orderLineId: string;
+    quantity: number;
+    refundedQuantity: number;
+    cancelledQuantity: number;
+    refundableQuantity: number;
+    unitRefundWithTax: number;
+}
+interface VendureRefundable {
+    lines: VendureRefundableLine[];
+    shippingWithTax: number;
+    moneyWithTax: number;
+}
+/**
+ * What the form may offer, from the order alone. Pending refunds count as refunded.
+ * The plugin is authoritative (`quantity_exceeds`, `amount_mismatch`).
+ * Amounts are Vendure's minor units with tax.
+ */
+declare function vendureRefundable(order: Pick<VendureOrder, 'lines' | 'shippingWithTax' | 'payments'>): VendureRefundable;
+
 /**
  * Vendure connector for Tally UI. Build one per store session, anew on each sign-in or store change:
  * each instance owns its reconcile feed, whose queued work must never reach another store's database (#307).
@@ -165,4 +345,4 @@ declare const createVendureConnector: (options?: {
  */
 declare const vendureConnector: TallyConnector;
 
-export { type VendureCredentialKind, type VendureCredentials, VendureTimezoneConfigError, createVendureConnector, createVendureCustomer, createVendureProductReplication, createVendureVariantFeedReplication, getVendureCustomer, searchVendureCustomers, toVendureCustomer, vendureAuth, vendureAuthFieldSets, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureSignIn, vendureStockReconcile, vendureStoreSettings };
+export { type VendureCredentialKind, type VendureCredentials, type VendureOrder, type VendureOrderList, type VendureOrderListOptions, type VendureOrderSummary, type VendureRefundable, type VendureRefundableLine, VendureTimezoneConfigError, createVendureConnector, createVendureCustomer, createVendureProductReplication, createVendureVariantFeedReplication, getVendureCustomer, getVendureOrder, listVendureOrders, searchVendureCustomers, toVendureCustomer, vendureAuth, vendureAuthFieldSets, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureRefundable, vendureSignIn, vendureStockReconcile, vendureStoreSettings };

package/dist/index.js

@@ -966,6 +966,126 @@ async function vendureGlobalStockSettings(context) {
   return res.data.globalSettings;
 }
 
+// src/orders.ts
+var ORDER_ROW_FIELDS = `
+  id code state orderPlacedAt updatedAt currencyCode totalQuantity total totalWithTax
+  customer { id firstName lastName emailAddress }
+`;
+var ORDER_CUSTOM_FIELDS = "tallyClientOrderId tallySaleAt tallyRegisterId tallySessionId tallyCashierRef tallyRejected tallyRejectedClientOrderId";
+var TALLY_ORDER_ROW_FIELDS = `${ORDER_ROW_FIELDS} customFields { ${ORDER_CUSTOM_FIELDS} }`;
+var ORDER_DETAIL_FIELDS_START = `
+  id code state active orderPlacedAt updatedAt currencyCode totalQuantity
+  customer { id firstName lastName emailAddress }
+  lines {`;
+var ORDER_DETAIL_FIELDS_END = `
+    id quantity orderPlacedQuantity proratedUnitPrice proratedUnitPriceWithTax taxRate productVariant { id name sku }
+    unitPrice unitPriceWithTax linePrice linePriceWithTax discountedLinePrice discountedLinePriceWithTax
+    discounts { description amount amountWithTax }
+  }
+  shippingLines { shippingMethod { name } price priceWithTax }
+  surcharges { description sku price priceWithTax }
+  subTotal subTotalWithTax shipping shippingWithTax total totalWithTax
+  taxSummary { description taxRate taxBase taxTotal }
+  discounts { description amount amountWithTax }
+  couponCodes
+  payments { id method amount state transactionId createdAt metadata refunds { id total items shipping adjustment state reason metadata lines { orderLineId quantity } } }
+  fulfillments { id state method trackingCode }
+`;
+var ORDER_DETAIL_FIELDS = `${ORDER_DETAIL_FIELDS_START}${ORDER_DETAIL_FIELDS_END}`;
+var TALLY_ORDER_DETAIL_FIELDS = `${ORDER_DETAIL_FIELDS_START}
+  customFields { tallyCustomName tallyCustomSku tallyUnitPrice tallyPriceIncludesTax tallyClientLineId }
+${ORDER_DETAIL_FIELDS_END} customFields { ${ORDER_CUSTOM_FIELDS} tallyPayments tallySnapshot tallyShipping }`;
+var LIST_QUERY = `query Orders($options: OrderListOptions) {
+  orders(options: $options) { items { ${ORDER_ROW_FIELDS} } totalItems }
+}`;
+var TALLY_LIST_QUERY = LIST_QUERY.replace(ORDER_ROW_FIELDS, TALLY_ORDER_ROW_FIELDS);
+var CUSTOMER_LIST_QUERY = `query CustomerOrders($customerId: ID!, $options: OrderListOptions) {
+  customer(id: $customerId) { orders(options: $options) { items { ${ORDER_ROW_FIELDS} } totalItems } }
+}`;
+var TALLY_CUSTOMER_LIST_QUERY = CUSTOMER_LIST_QUERY.replace(ORDER_ROW_FIELDS, TALLY_ORDER_ROW_FIELDS);
+var DETAIL_QUERY = `query Order($id: ID!) {
+  order(id: $id) { ${ORDER_DETAIL_FIELDS} }
+}`;
+var TALLY_DETAIL_QUERY = `query Order($id: ID!) {
+  order(id: $id) { ${TALLY_ORDER_DETAIL_FIELDS} }
+}`;
+async function listVendureOrders(context, options = {}) {
+  const skip = Math.max(0, Math.trunc(Number.isFinite(options.skip) ? options.skip : 0));
+  const take = Math.max(1, Math.min(100, Math.trunc(Number.isFinite(options.take) ? options.take : 25)));
+  const date = options.orderPlacedAt;
+  const orderPlacedAt = {
+    ...date?.after !== void 0 ? { after: date.after } : {},
+    ...date?.before !== void 0 ? { before: date.before } : {},
+    ...date?.between !== void 0 ? { between: date.between } : {}
+  };
+  const q = options.search?.trim();
+  const filter = {
+    orderPlacedAt: Object.keys(orderPlacedAt).length ? orderPlacedAt : { isNull: false },
+    ...options.state?.length ? { state: { in: options.state } } : {},
+    ...options.tallyRegisterId ? { tallyRegisterId: { eq: options.tallyRegisterId } } : {},
+    ...options.tallyCashierRef ? { tallyCashierRef: { eq: options.tallyCashierRef } } : {},
+    ...q ? { _or: [{ code: { contains: q } }, { customerLastName: { contains: q } }] } : {}
+  };
+  const variables = {
+    options: { skip, take, sort: { orderPlacedAt: "DESC", id: "DESC" }, filter },
+    ...options.customerId ? { customerId: options.customerId } : {}
+  };
+  const query2 = options.customerId ? options.tallyFields === false ? CUSTOMER_LIST_QUERY : TALLY_CUSTOMER_LIST_QUERY : options.tallyFields === false ? LIST_QUERY : TALLY_LIST_QUERY;
+  const body = await gql2(context, query2, variables);
+  if (options.customerId && body?.data?.customer === null) return { items: [], totalItems: 0 };
+  const result = options.customerId ? body?.data?.customer?.orders : body?.data?.orders;
+  if (!result || typeof result !== "object" || !Array.isArray(result.items) || typeof result.totalItems !== "number") {
+    throw new Error("Vendure sent an unexpected orders response");
+  }
+  return { items: result.items, totalItems: result.totalItems };
+}
+async function getVendureOrder(context, id, options) {
+  const body = await gql2(context, options?.tallyFields === false ? DETAIL_QUERY : TALLY_DETAIL_QUERY, { id });
+  const order = body?.data?.order;
+  if (order === null) return null;
+  if (typeof order !== "object" || typeof order?.id !== "string") {
+    throw new Error("Vendure sent an unexpected order response");
+  }
+  return order;
+}
+
+// src/refunds.ts
+function vendureRefundable(order) {
+  const refundedQuantities = /* @__PURE__ */ new Map();
+  let refundedShipping = 0;
+  let moneyWithTax = 0;
+  for (const payment of order.payments ?? []) {
+    let refundedTotal = 0;
+    for (const refund of payment.refunds ?? []) {
+      if (refund.state === "Failed") continue;
+      refundedTotal += Number.isFinite(refund.total) ? refund.total : 0;
+      refundedShipping += Number.isFinite(refund.shipping) ? refund.shipping : 0;
+      for (const line of refund.lines ?? []) {
+        refundedQuantities.set(line.orderLineId, (refundedQuantities.get(line.orderLineId) ?? 0) + (Number.isFinite(line.quantity) ? line.quantity : 0));
+      }
+    }
+    if (payment.state === "Settled") {
+      moneyWithTax += Math.max(0, (Number.isFinite(payment.amount) ? payment.amount : 0) - refundedTotal);
+    }
+  }
+  return {
+    lines: (order.lines ?? []).map((line) => {
+      const quantity = Number.isFinite(line.quantity) ? line.quantity : 0;
+      const refundedQuantity = refundedQuantities.get(line.id) ?? 0;
+      return {
+        orderLineId: line.id,
+        quantity,
+        refundedQuantity,
+        cancelledQuantity: Number.isFinite(line.orderPlacedQuantity) ? Math.max(0, line.orderPlacedQuantity - quantity) : 0,
+        refundableQuantity: Math.max(0, quantity - refundedQuantity),
+        unitRefundWithTax: Number.isFinite(line.proratedUnitPriceWithTax) ? line.proratedUnitPriceWithTax : 0
+      };
+    }),
+    shippingWithTax: Math.max(0, (Number.isFinite(order.shippingWithTax) ? order.shippingWithTax : 0) - refundedShipping),
+    moneyWithTax
+  };
+}
+
 // src/index.ts
 import { ConnectorUnauthorizedError as ConnectorUnauthorizedError6 } from "@tallyui/core";
 var VENDURE_IDS_PER_REQUEST = 1e3;
@@ -1024,6 +1144,8 @@ export {
   createVendureProductReplication,
   createVendureVariantFeedReplication,
   getVendureCustomer,
+  getVendureOrder,
+  listVendureOrders,
   searchVendureCustomers,
   toVendureCustomer,
   vendureAuth,
@@ -1034,6 +1156,7 @@ export {
   vendureProductSchema,
   vendureProductSync,
   vendureProductTraits,
+  vendureRefundable,
   vendureSignIn,
   vendureStockReconcile,
   vendureStoreSettings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-vendure",
-  "version": "3.7.1",
+  "version": "3.9.0",
   "type": "module",
   "description": "Vendure connector for Tally UI",
   "main": "./dist/index.js",
@@ -10,7 +10,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "source": "./src/index.ts"
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -26,11 +27,11 @@
     "directory": "connectors/vendure"
   },
   "peerDependencies": {
-    "@tallyui/core": "^3.7.1"
+    "@tallyui/core": "^3.9.0"
   },
   "devDependencies": {
-    "@tallyui/database": "3.7.1",
-    "@tallyui/pos": "3.7.1",
+    "@tallyui/database": "3.9.0",
+    "@tallyui/pos": "3.9.0",
     "rxdb": "17.5.0"
   },
   "scripts": {

package/src/index.ts

@@ -114,6 +114,8 @@ export { vendureStockReconcile } from './reconcile/stock';
 export { vendureStoreSettings } from './store-settings';
 export { vendureGlobalStockSettings } from './global-settings';
 export { searchVendureCustomers, createVendureCustomer, getVendureCustomer, toVendureCustomer } from './customers';
+export { listVendureOrders, getVendureOrder, type VendureOrderListOptions, type VendureOrderList, type VendureOrderSummary, type VendureOrder } from './orders';
+export { vendureRefundable, type VendureRefundableLine, type VendureRefundable } from './refunds';
 
 export { ConnectorUnauthorizedError } from '@tallyui/core';
 export { VendureTimezoneConfigError } from './replication/products';

package/src/orders.ts

@@ -0,0 +1,187 @@
+import type { SyncContext } from '@tallyui/core';
+import { gql } from './replication/products';
+
+export interface VendureOrderListOptions {
+  /** Offset, default 0; negative or fractional values are truncated and floored to 0. */
+  skip?: number;
+  /** Page size, default 25, clamped to 1..100. */
+  take?: number;
+  /** Vendure's DateOperators on orderPlacedAt; only these three keys are sent. */
+  orderPlacedAt?: { after?: string; before?: string; between?: { start: string; end: string } };
+  /** Order states, sent as `state: { in }` when non-empty. */
+  state?: string[];
+  /** The plugin's register id custom field, sent as `tallyRegisterId: { eq }` when non-empty. */
+  tallyRegisterId?: string;
+  /** The plugin's cashier custom field, sent as `tallyCashierRef: { eq }` when non-empty. */
+  tallyCashierRef?: string;
+  /** Lists through `customer(id) { orders }` when non-empty. */
+  customerId?: string;
+  /** Trimmed; when non-empty, matches order code or customer last name with `contains`. */
+  search?: string;
+  /** Select the vendurepos plugin's custom fields; default true. False for a server without the plugin. */
+  tallyFields?: boolean;
+}
+
+export interface VendureOrderList<T> { items: T[]; totalItems: number }
+
+export interface VendureOrderSummary {
+  id: string;
+  code: string;
+  state: string;
+  orderPlacedAt: string | null;
+  updatedAt: string;
+  currencyCode: string;
+  totalQuantity: number;
+  total: number;
+  totalWithTax: number;
+  customer: { id: string; firstName: string; lastName: string; emailAddress: string } | null;
+  customFields?: {
+    tallyClientOrderId: string | null;
+    tallySaleAt: string | null;
+    tallyRegisterId: string | null;
+    tallySessionId: string | null;
+    tallyCashierRef: string | null;
+    tallyRejected: boolean | null;
+    tallyRejectedClientOrderId: string | null;
+  };
+}
+
+export interface VendureOrder extends VendureOrderSummary {
+  active: boolean;
+  lines: {
+    id: string;
+    quantity: number;
+    orderPlacedQuantity: number;
+    proratedUnitPrice: number;
+    /** Vendure's per-unit value used in refund calculations, which the till sums for `order.refund`'s `totalMinor` (ADR-080). */
+    proratedUnitPriceWithTax: number;
+    taxRate: number;
+    productVariant: { id: string; name: string; sku: string };
+    unitPrice: number;
+    unitPriceWithTax: number;
+    linePrice: number;
+    linePriceWithTax: number;
+    discountedLinePrice: number;
+    discountedLinePriceWithTax: number;
+    discounts: { description: string; amount: number; amountWithTax: number }[];
+    customFields?: {
+      tallyCustomName: string | null;
+      tallyCustomSku: string | null;
+      tallyUnitPrice: number | null;
+      tallyPriceIncludesTax: boolean | null;
+      tallyClientLineId: string | null;
+    };
+  }[];
+  shippingLines: { shippingMethod: { name: string }; price: number; priceWithTax: number }[];
+  surcharges: { description: string; sku: string; price: number; priceWithTax: number }[];
+  subTotal: number;
+  subTotalWithTax: number;
+  shipping: number;
+  shippingWithTax: number;
+  taxSummary: { description: string; taxRate: number; taxBase: number; taxTotal: number }[];
+  discounts: { description: string; amount: number; amountWithTax: number }[];
+  couponCodes: string[];
+  payments?: {
+    id: string;
+    method: string;
+    amount: number;
+    state: string;
+    transactionId: string;
+    createdAt: string;
+    metadata: unknown;
+    refunds: { id: string; total: number; items: number; shipping: number; adjustment: number; state: string; reason: string; metadata: unknown; lines: { orderLineId: string; quantity: number }[] }[];
+  }[];
+  fulfillments?: { id: string; state: string; method: string; trackingCode: string }[];
+  customFields?: VendureOrderSummary['customFields'] & {
+    tallyPayments: string | null;
+    tallySnapshot: string | null;
+    tallyShipping: string | null;
+  };
+}
+
+const ORDER_ROW_FIELDS = `
+  id code state orderPlacedAt updatedAt currencyCode totalQuantity total totalWithTax
+  customer { id firstName lastName emailAddress }
+`;
+const ORDER_CUSTOM_FIELDS = 'tallyClientOrderId tallySaleAt tallyRegisterId tallySessionId tallyCashierRef tallyRejected tallyRejectedClientOrderId';
+const TALLY_ORDER_ROW_FIELDS = `${ORDER_ROW_FIELDS} customFields { ${ORDER_CUSTOM_FIELDS} }`;
+const ORDER_DETAIL_FIELDS_START = `
+  id code state active orderPlacedAt updatedAt currencyCode totalQuantity
+  customer { id firstName lastName emailAddress }
+  lines {`;
+const ORDER_DETAIL_FIELDS_END = `
+    id quantity orderPlacedQuantity proratedUnitPrice proratedUnitPriceWithTax taxRate productVariant { id name sku }
+    unitPrice unitPriceWithTax linePrice linePriceWithTax discountedLinePrice discountedLinePriceWithTax
+    discounts { description amount amountWithTax }
+  }
+  shippingLines { shippingMethod { name } price priceWithTax }
+  surcharges { description sku price priceWithTax }
+  subTotal subTotalWithTax shipping shippingWithTax total totalWithTax
+  taxSummary { description taxRate taxBase taxTotal }
+  discounts { description amount amountWithTax }
+  couponCodes
+  payments { id method amount state transactionId createdAt metadata refunds { id total items shipping adjustment state reason metadata lines { orderLineId quantity } } }
+  fulfillments { id state method trackingCode }
+`;
+const ORDER_DETAIL_FIELDS = `${ORDER_DETAIL_FIELDS_START}${ORDER_DETAIL_FIELDS_END}`;
+const TALLY_ORDER_DETAIL_FIELDS = `${ORDER_DETAIL_FIELDS_START}
+  customFields { tallyCustomName tallyCustomSku tallyUnitPrice tallyPriceIncludesTax tallyClientLineId }
+${ORDER_DETAIL_FIELDS_END} customFields { ${ORDER_CUSTOM_FIELDS} tallyPayments tallySnapshot tallyShipping }`;
+
+const LIST_QUERY = `query Orders($options: OrderListOptions) {
+  orders(options: $options) { items { ${ORDER_ROW_FIELDS} } totalItems }
+}`;
+const TALLY_LIST_QUERY = LIST_QUERY.replace(ORDER_ROW_FIELDS, TALLY_ORDER_ROW_FIELDS);
+const CUSTOMER_LIST_QUERY = `query CustomerOrders($customerId: ID!, $options: OrderListOptions) {
+  customer(id: $customerId) { orders(options: $options) { items { ${ORDER_ROW_FIELDS} } totalItems } }
+}`;
+const TALLY_CUSTOMER_LIST_QUERY = CUSTOMER_LIST_QUERY.replace(ORDER_ROW_FIELDS, TALLY_ORDER_ROW_FIELDS);
+const DETAIL_QUERY = `query Order($id: ID!) {
+  order(id: $id) { ${ORDER_DETAIL_FIELDS} }
+}`;
+const TALLY_DETAIL_QUERY = `query Order($id: ID!) {
+  order(id: $id) { ${TALLY_ORDER_DETAIL_FIELDS} }
+}`;
+
+export async function listVendureOrders(context: SyncContext, options: VendureOrderListOptions = {}): Promise<VendureOrderList<VendureOrderSummary>> {
+  const skip = Math.max(0, Math.trunc(Number.isFinite(options.skip) ? options.skip! : 0));
+  const take = Math.max(1, Math.min(100, Math.trunc(Number.isFinite(options.take) ? options.take! : 25)));
+  const date = options.orderPlacedAt;
+  const orderPlacedAt = {
+    ...(date?.after !== undefined ? { after: date.after } : {}),
+    ...(date?.before !== undefined ? { before: date.before } : {}),
+    ...(date?.between !== undefined ? { between: date.between } : {}),
+  };
+  const q = options.search?.trim();
+  const filter = {
+    orderPlacedAt: Object.keys(orderPlacedAt).length ? orderPlacedAt : { isNull: false },
+    ...(options.state?.length ? { state: { in: options.state } } : {}),
+    ...(options.tallyRegisterId ? { tallyRegisterId: { eq: options.tallyRegisterId } } : {}),
+    ...(options.tallyCashierRef ? { tallyCashierRef: { eq: options.tallyCashierRef } } : {}),
+    ...(q ? { _or: [{ code: { contains: q } }, { customerLastName: { contains: q } }] } : {}),
+  };
+  const variables = {
+    options: { skip, take, sort: { orderPlacedAt: 'DESC', id: 'DESC' }, filter },
+    ...(options.customerId ? { customerId: options.customerId } : {}),
+  };
+  const query = options.customerId
+    ? (options.tallyFields === false ? CUSTOMER_LIST_QUERY : TALLY_CUSTOMER_LIST_QUERY)
+    : (options.tallyFields === false ? LIST_QUERY : TALLY_LIST_QUERY);
+  const body = await gql(context, query, variables);
+  if (options.customerId && body?.data?.customer === null) return { items: [], totalItems: 0 };
+  const result = options.customerId ? body?.data?.customer?.orders : body?.data?.orders;
+  if (!result || typeof result !== 'object' || !Array.isArray(result.items) || typeof result.totalItems !== 'number') {
+    throw new Error('Vendure sent an unexpected orders response');
+  }
+  return { items: result.items, totalItems: result.totalItems };
+}
+
+export async function getVendureOrder(context: SyncContext, id: string, options?: { tallyFields?: boolean }): Promise<VendureOrder | null> {
+  const body = await gql(context, options?.tallyFields === false ? DETAIL_QUERY : TALLY_DETAIL_QUERY, { id });
+  const order = body?.data?.order;
+  if (order === null) return null;
+  if (typeof order !== 'object' || typeof order?.id !== 'string') {
+    throw new Error('Vendure sent an unexpected order response');
+  }
+  return order;
+}

package/src/refunds.ts

@@ -0,0 +1,58 @@
+import type { VendureOrder } from './orders';
+
+export interface VendureRefundableLine {
+  orderLineId: string;
+  quantity: number; // The line's current quantity.
+  refundedQuantity: number; // Sum of its refund lines over refunds not Failed.
+  cancelledQuantity: number; // max(0, orderPlacedQuantity - quantity).
+  refundableQuantity: number; // max(0, quantity - refundedQuantity).
+  unitRefundWithTax: number; // The line's proratedUnitPriceWithTax.
+}
+
+export interface VendureRefundable {
+  lines: VendureRefundableLine[]; // In the order's line order, one per line.
+  shippingWithTax: number; // max(0, order.shippingWithTax - shipping refunded over refunds not Failed).
+  moneyWithTax: number; // Sum over Settled payments of max(0, amount - refunds' total not Failed).
+}
+
+/**
+ * What the form may offer, from the order alone. Pending refunds count as refunded.
+ * The plugin is authoritative (`quantity_exceeds`, `amount_mismatch`).
+ * Amounts are Vendure's minor units with tax.
+ */
+export function vendureRefundable(order: Pick<VendureOrder, 'lines' | 'shippingWithTax' | 'payments'>): VendureRefundable {
+  const refundedQuantities = new Map<string, number>();
+  let refundedShipping = 0;
+  let moneyWithTax = 0;
+  for (const payment of order.payments ?? []) {
+    let refundedTotal = 0;
+    for (const refund of payment.refunds ?? []) {
+      if (refund.state === 'Failed') continue;
+      refundedTotal += Number.isFinite(refund.total) ? refund.total : 0;
+      refundedShipping += Number.isFinite(refund.shipping) ? refund.shipping : 0;
+      for (const line of refund.lines ?? []) {
+        refundedQuantities.set(line.orderLineId, (refundedQuantities.get(line.orderLineId) ?? 0)
+          + (Number.isFinite(line.quantity) ? line.quantity : 0));
+      }
+    }
+    if (payment.state === 'Settled') {
+      moneyWithTax += Math.max(0, (Number.isFinite(payment.amount) ? payment.amount : 0) - refundedTotal);
+    }
+  }
+  return {
+    lines: (order.lines ?? []).map(line => {
+      const quantity = Number.isFinite(line.quantity) ? line.quantity : 0;
+      const refundedQuantity = refundedQuantities.get(line.id) ?? 0;
+      return {
+        orderLineId: line.id,
+        quantity,
+        refundedQuantity,
+        cancelledQuantity: Number.isFinite(line.orderPlacedQuantity) ? Math.max(0, line.orderPlacedQuantity - quantity) : 0,
+        refundableQuantity: Math.max(0, quantity - refundedQuantity),
+        unitRefundWithTax: Number.isFinite(line.proratedUnitPriceWithTax) ? line.proratedUnitPriceWithTax : 0,
+      };
+    }),
+    shippingWithTax: Math.max(0, (Number.isFinite(order.shippingWithTax) ? order.shippingWithTax : 0) - refundedShipping),
+    moneyWithTax,
+  };
+}