@fire-spark/core 0.9.1 → 0.11.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Money, PaymentAdapter, PaymentCollectAt, PaymentContext, PaymentResult, PaymentStorage, PaymentUI, RedeemLike, RedeemSource, isRealPaymentMethod, orderRedeems } from "@fire-spark/payments";
-import { AndConditions, CheckoutMode, CheckoutResolved, CmsBlock, Condition, Customer, CustomerIdentifyInput, CustomerRegisterInput, CustomerUpdateInput, Fulfillment, FulfillmentListInput, GroupDisplayType, KioskDeviceConfig, KioskDeviceOverrides, KioskHealthBatchInput, KioskHealthBatchResult, KioskHeartbeatInput, KioskHeartbeatResult, KioskRealtimeToken, MatchResult, MatchableRule, Menu, Menu as Menu$1, MenuLookup, MenuLookup as MenuLookup$1, MerchantPayment, ModifierControlType, ModifierGroup, OrConditions, Order as Order$1, Order as Order$2, OrderDeviceListInput, OrderDeviceListResult, OrderFulfillment, OrderInsertInput, OrderLine, OrderListInput, OrderRecordPaymentInput, OrderRedeem, OrderRedemptionStep, OrderReorderInput, OrderTotals, OrderUpdateInput, OrderValidateInput, OrderValidateOutput, PaymentCollectAt as PaymentCollectAt$1, PaymentIntentPutInput, PaymentMethod, PaymentProvider, PaymentTender, PaymentTenderInput, PlaceOrderResult, PosCatalog, PosFloorInput, PosFloorOccupancy, PosFloorPlan, PosFloorRealtimeToken, PosHealthBatchInput, PosHealthBatchResult, PosHeartbeatInput, PosHeartbeatResult, PosKioskOrder, PosKioskSettleInput, PosKioskSettleResult, PosOrderInput, PosOrderResult, PosTableAttachOrderInput, PosTableCloseInput, PosTableJoinInput, PosTableSeatInput, PosTableSeatReservationInput, PosTableSplitInput, PricingModifier, Product, Product as Product$1, Recommendation, RecurringDateCronResult, RecurringDateCronValues, RulesEngineOrderLine, RulesEngineParams, RulesEngineRuntime, Schedule, SdkLogContext, SdkLogErrorInfo, SdkLogLevel, SdkLogOptions, Store, StoreGetInput, StoreListInput, StoreNearbyInput, StorefrontAvailability, StorefrontMenu, StorefrontMenuScope, StorefrontMenuStreamOptions, StorefrontPaymentsListInput, StorefrontPreferences, TenderRefundInput, TenderReplaceInput, TenderVoidInput, Variant, VariantGroup } from "@fire-spark/types";
+import { AndConditions, CheckoutMode, CheckoutResolved, CmsBlock, Condition, Customer, CustomerIdentifyInput, CustomerRegisterInput, CustomerUpdateInput, Fulfillment, FulfillmentListInput, GroupDisplayType, KioskDeviceConfig, KioskDeviceOverrides, KioskHealthBatchInput, KioskHealthBatchResult, KioskHeartbeatInput, KioskHeartbeatResult, KioskRealtimeToken, MatchResult, MatchableRule, Menu, Menu as Menu$1, MenuLookup, MenuLookup as MenuLookup$1, MerchantPayment, ModifierControlType, ModifierGroup, OrConditions, Order as Order$1, Order as Order$2, OrderCancelInput, OrderCancelInput as OrderCancelInput$1, OrderCancelType, OrderCancelType as OrderCancelType$1, OrderDeviceListInput, OrderDeviceListResult, OrderFulfillment, OrderInsertInput, OrderLine, OrderListInput, OrderRecordPaymentInput, OrderRedeem, OrderRedemptionStep, OrderReorderInput, OrderTotals, OrderUpdateInput, OrderValidateInput, OrderValidateOutput, PaymentCollectAt as PaymentCollectAt$1, PaymentIntentPutInput, PaymentMethod, PaymentProvider, PaymentTender, PaymentTenderInput, PlaceOrderResult, PosCatalog, PosFloorInput, PosFloorOccupancy, PosFloorPlan, PosFloorRealtimeToken, PosHealthBatchInput, PosHealthBatchResult, PosHeartbeatInput, PosHeartbeatResult, PosKioskOrder, PosKioskSettleInput, PosKioskSettleResult, PosOrderInput, PosOrderResult, PosTableAttachOrderInput, PosTableCloseInput, PosTableJoinInput, PosTableSeatInput, PosTableSeatReservationInput, PosTableSplitInput, PricingModifier, Product, Product as Product$1, Recommendation, RecurringDateCronResult, RecurringDateCronValues, RulesEngineOrderLine, RulesEngineParams, RulesEngineRuntime, Schedule, SdkLogContext, SdkLogErrorInfo, SdkLogLevel, SdkLogOptions, Store, StoreGetInput, StoreListInput, StoreNearbyInput, StorefrontAvailability, StorefrontMenu, StorefrontMenuScope, StorefrontMenuStreamOptions, StorefrontPaymentsListInput, StorefrontPreferences, TenderRefundInput, TenderReplaceInput, TenderVoidInput, Variant, VariantGroup } from "@fire-spark/types";
 import { Big } from "big.js";
 //#region src/productCustomization/catalog.utils.d.ts
 /** Image for a product inside one modifier group, else the product image. */
@@ -272,8 +272,13 @@ declare const refundTender: (id: string, tenderId: string, body: TenderRefundInp
 declare const getOrderFulfillment: (id: string, options?: ServiceHttpOptions) => Promise<OrderFulfillment>;
 declare const listOrderFulfillments: (ids: string[], options?: ServiceHttpOptions) => Promise<OrderFulfillment[]>;
 declare const updateOrder: (id: string, body: OrderUpdateInput, options?: ServiceHttpOptions) => Promise<Order$1>;
-declare const cancelOrder: (id: string, options?: ServiceHttpOptions) => Promise<Order$1>;
-declare const refundOrder: (id: string, options?: ServiceHttpOptions) => Promise<Order$1>;
+/**
+ * `body` is optional: `device` (checked only when sent), `type`
+ * (`VOID` / `REVERSE`) and what the device reversed (`tenders`).
+ */
+declare const cancelOrder: (id: string, options?: ServiceHttpOptions, body?: OrderCancelInput$1) => Promise<Order$1>;
+/** Refunds the tenders only; the order status stays. `type` is `REFUND`. */
+declare const refundOrder: (id: string, options?: ServiceHttpOptions, body?: OrderCancelInput$1) => Promise<Order$1>;
 declare const reorderOrder: (id: string, body?: OrderReorderInput, options?: ServiceHttpOptions) => Promise<Order$1>;
 /**
  * `POST /storefront/v1/orders/:id/reopen`: voids every payment of a placed,
@@ -327,7 +332,10 @@ type PaymentSessionOptions = {
    * SDK charges are always saved with `collect_at: DEVICE` (§7.3).
    */
   collectAt?: PaymentCollectAt;
-  /** Where cash is collected: `COUNTER` on a kiosk, `DOOR` on delivery. */
+  /**
+   * Where cash and the Fire Spark card terminal are collected: `COUNTER` on
+   * a kiosk, `DOOR` on delivery.
+   */
   cashCollectAt?: PaymentCollectAt;
   /** `settings_overrides.payment_settings` of this device, by payment id. */
   deviceSettings?: Record<string, Record<string, unknown>>;
@@ -399,6 +407,25 @@ type ReverseAllOptions = {
 declare const coveredAmount: (intents: Intents) => number;
 declare const remainingAmount: (order: Order$1) => number;
 //#endregion
+//#region src/order/cancel.d.ts
+/**
+ * The operation an order takes: `VOID` (nothing charged), `REVERSE`
+ * (charged, not delivered) or `REFUND` (delivered). An order already
+ * cancelled keeps its operation, so a replay stays idempotent.
+ */
+declare const cancelTypeOf: (order: Order$1) => OrderCancelType$1;
+type OrderCancelResult = {
+  /** The order the server answered. */
+  order: Order$1;
+  type: OrderCancelType$1;
+  /** Endpoint called: `cancel()` → `cancel`, `refund()` → `refund`. */
+  path: "cancel" | "refund";
+  /** What the device did with each charge it voided. */
+  outcomes: ReversalOutcome[];
+  /** Tender ids the device could not void yet (`reversal_pending`). */
+  pending: string[];
+};
+//#endregion
 //#region src/order/recommendations.d.ts
 type RecommendationType = Recommendation["type"];
 declare const DEFAULT_RECOMMENDATION_TYPES: RecommendationType[];
@@ -415,6 +442,13 @@ type OrderDeviceCredential = {
   uid: string;
   secret: string;
 };
+type OrderCancelOptions = {
+  /** `cancel()` only: forces VOID / REVERSE; omitted, it follows the order. */
+  type?: Exclude<OrderCancelType, "REFUND">;
+  reason?: string;
+  /** Only these charged tenders are voided on the device. */
+  tenderIds?: readonly string[];
+};
 type CreateOrderOptions = {
   scope?: OrderScope;
   customer?: OrderCustomerSource;
@@ -495,6 +529,8 @@ declare class Order {
    */
   private requestedRedeem;
   private readonly device?;
+  /** Device voids a failed cancel / refund call did not report yet. */
+  private unreported;
   private constructor();
   /**
    * Opens a cart session: reuses an existing OPEN order for the scope, or a
@@ -511,6 +547,8 @@ declare class Order {
     debounceMs?: number;
     persisted?: boolean;
     sleep?: (ms: number) => Promise<void>;
+    /** Sent by `cancel()` (and `placeOrder`) when present. */
+    device?: CreateOrderOptions["device"];
   }, notify?: () => void): Order;
   /** Whether this session has a server row yet. */
   isPersisted(): boolean;
@@ -645,6 +683,25 @@ declare class Order {
   replaceTender(tenderId: string, payment: MerchantPayment, collectAt?: PaymentCollectAt$1): Promise<Order$1>;
   /** "Cancel and refund": reverses device charges, then cancels the order. */
   cancelAndRefund(options?: ReverseAllOptions): Promise<ReversalOutcome[]>;
+  /**
+   * Cancels this placed, not delivered order with one call to `/cancel`:
+   * `VOID` (nothing charged) or `REVERSE` (charged), decided from the
+   * fresh order. Device charges are voided first and their results go in
+   * the same body (never `/payments`). The device credential of
+   * `createOrder({ device })` / `fromExisting({ device })` is sent when
+   * present. A delivered order throws before touching the device: use
+   * `refund()`. A forced `type` that does not match throws too.
+   */
+  cancel(options?: OrderCancelOptions): Promise<OrderCancelResult>;
+  /**
+   * Refunds this delivered order with one call to `/refund`
+   * (`type: REFUND`): device charges are voided first and reported in the
+   * body. Only the tenders change; the order status stays. An order not
+   * delivered throws before touching the device: use `cancel()`.
+   */
+  refund(options?: Omit<OrderCancelOptions, "type">): Promise<OrderCancelResult>;
+  private freshCancelType;
+  private runCancel;
   /** Voids one tender (operator flow); idempotent per call. */
   voidTender(tenderId: string, reason?: string): Promise<Order$1>;
   /** Refunds one tender: all of it, an amount, or some units. */
@@ -1058,6 +1115,45 @@ type PaymentOperationBody = {
 };
 /** Server half of an adapter (`POST /payments/:id/operations/:operation`). */
 declare const callPaymentOperation: <T>(paymentId: string, operation: string, body: PaymentOperationBody, options?: ServiceHttpOptions) => Promise<T>;
+type DeunaCallbackUrls = Partial<Record<"on_success" | "on_pending" | "on_failed" | "on_canceled" | "on_reject", string>>;
+type DeunaTokenizeBody = {
+  order_id: string;
+  attempt_reference: string;
+  callback_urls?: DeunaCallbackUrls;
+};
+type DeunaTokenizeResult = {
+  order_token: string;
+  order_id: string;
+};
+type DeunaOrderStatus = {
+  order_token: string;
+  status: string;
+  transaction_id: string | null;
+  error: {
+    code: string | null;
+    message: string | null;
+  } | null;
+};
+/** DEUNA order for the Payment Widget (`POST .../deuna/:id/tokenize`). */
+declare const tokenizeDeunaOrder: (paymentId: string, body: DeunaTokenizeBody, options?: ServiceHttpOptions) => Promise<DeunaTokenizeResult>;
+/** Payment status of a DEUNA order (`GET .../deuna/:id/orders/:token`). */
+declare const getDeunaOrder: (paymentId: string, orderToken: string, options?: ServiceHttpOptions) => Promise<DeunaOrderStatus>;
+/**
+ * `api` option of `deunaWidgetPayments` (`@fire-spark/payments-deuna-widget`)
+ * bound to the storefront HTTP options of the template.
+ */
+declare const createDeunaWidgetApi: (options?: ServiceHttpOptions) => {
+  tokenize: (input: {
+    paymentId: string;
+    orderId: string;
+    attemptReference: string;
+    callbackUrls?: DeunaCallbackUrls;
+  }) => Promise<DeunaTokenizeResult>;
+  order: (input: {
+    paymentId: string;
+    orderToken: string;
+  }) => Promise<DeunaOrderStatus>;
+};
 type TerminalFailureBody = {
   operation: string;
   device_id?: string | null;
@@ -1208,6 +1304,11 @@ declare const services: {
     list: typeof listPayments;
     operation: typeof callPaymentOperation;
     terminalFailure: typeof reportTerminalFailure;
+    deuna: {
+      tokenize: typeof tokenizeDeunaOrder;
+      order: typeof getDeunaOrder;
+      widgetApi: typeof createDeunaWidgetApi;
+    };
   };
   stores: {
     list: typeof listStores;
@@ -1554,4 +1655,4 @@ declare const validateCardholderName: (value: string) => CardholderNameError | n
  */
 declare const cardPreviewGroups: (value: string) => CardPreviewSlot[][];
 //#endregion
-export { type ApplyRedeemInput, type AuthConfigureOptions, CARD_BRANDS, type CardBrand, type CardBrandSpec, type CardCvcError, type CardExpiry, type CardExpiryError, type CardNumberError, type CardPreviewSlot, type CardholderNameError, type CreateOrderOptions, type CreateSessionOptions, type CustomizationPath, type CustomizationSession, DEFAULT_RECOMMENDATION_TYPES, type ExchangeOptions, type FailedCharge, type FlatMenuCategory, type GenOrderIdOptions, type GroupDisplayType, ID_HASH_FORMATS, type IdBuilder, type IdHashFormat, type ListMenusStreamOptions, type ListPaymentsOptions, type Menu, type MenuCategoryNode, type MenuLookup, type MilestoneSteps, type MilestoneTrackItem, type ModifierControlType, type ModifierCtx, type ModifierGroupCtx, type NestedMenuCategory, Order, type OrderCustomerSource, type OrderDeviceCredential, type OrderDraft, type OrderIssue, type OrderIssueCode, type OrderLineDiff, type OrderLineIssue, type OrderLineIssueCode, OrderPaymentRequiredError, type OrderScope, OrderSyncPendingError, OrderSyncRejectedError, OrderValidationError, type OrderValidationResult, type PayIntentOptions, type PayIntentResult, type PayOptions, type PaymentCardBrand, type PaymentProgressEvent, type PaymentProgressListener, type PaymentRunOptions, type PaymentSessionOptions, type PricingModifier, type Product, type ProductCtx, type QuantitiesByPath, type RecommendationType, RecurringDateCron, type RedeemPaymentRow, type RemoveRedeemInput, type ReorderOrderOptions, type ResetOptions, type ReversalOutcome, type ReverseAllOptions, RulesEngine, type ScheduleWindow, type SelectionStatus, type SelectionsByPath, type SerializedError, type ServiceHttpOptions, type SimpleTenderPayment, type Snapshot, type StorefrontAccessToken, type StorefrontErrorDetails, StorefrontHttpError, type TrackWorkflow, type ValidateOptions, type ValidateOrderAgainstMenuInput, type Variant, type VariantGroup, type VariantGroupCtx, type VariantOptionCtx, type VariantSelection, type VerifyWebhookSignatureInput, type VisitedState, addLines, auth, buildCustomerSnapshot, capRedeems, cappedRedeems, cardBrandSpec, cardDigits, cardNumberGaps, cardNumberMaxLength, cardPreviewGroups, caretAfterDigits, collectOrderLineDiffs, computeStartingPrice, countCartProducts, coveredAmount, createSession, currentNodes, cvcMaxLength, defaultConditionError, detectCardBrand, fitRedeems, flattenMenuCategories, flushLogs, formatCardNumber, formatCvc, formatExpiry, fromOrderLines, genId, genOrderId, getLogContext, getScheduleWindow, indexMenu, isCardNumberComplete, isCardNumberDefinitelyInvalid, isCheckoutFieldFilled, isCvcComplete, isDeviceCharged, isDeviceNotLinked, isExpiryComplete, isGenId, isKioskUnauthorized, isMilestoneStepDone, isOnSchedule, isOrderPaymentRequiredError, isOrderValidationError, isPosDeviceNotLinked, isPosUnauthorized, isRealPaymentMethod, isStorefrontNotFound, isVariantBase, linePayableTotal, listMenusStream, localizePosError, log, logError, luhnCheck, matchAbsoluteDateOperator, matchBooleanOperator, matchCurrencyOperator, matchEnumOperator, matchNumberOperator, matchRecurringDateOperator, matchRelativeDateOperator, matchStringOperator, milestoneSteps, milestoneTrack, nestMenuCategories, normalizeCardholderName, orderPayableTotal, orderRedeemedTotal, orderRedeems, parseExpiry, paymentMatchesClientConditions, rebuildRootGroups, recomputeTotals, redeemedTotal, redemptionCap, redemptionSteps, remainingAmount, removeLine, replaceLine, resolveCheckout, resolveModifierImageUrl, reversePayment, runPaymentAttempt, selectablePayments, serializeError, services, setLineQuantity, storefrontJson, toOrderLines, toPaymentCardBrand, validateCardNumber, validateCardholderName, validateCvc, validateExpiry, validateOrderAgainstMenu, verifyWebhookSignature, visitedStates };
+export { type ApplyRedeemInput, type AuthConfigureOptions, CARD_BRANDS, type CardBrand, type CardBrandSpec, type CardCvcError, type CardExpiry, type CardExpiryError, type CardNumberError, type CardPreviewSlot, type CardholderNameError, type CreateOrderOptions, type CreateSessionOptions, type CustomizationPath, type CustomizationSession, DEFAULT_RECOMMENDATION_TYPES, type DeunaCallbackUrls, type DeunaOrderStatus, type ExchangeOptions, type FailedCharge, type FlatMenuCategory, type GenOrderIdOptions, type GroupDisplayType, ID_HASH_FORMATS, type IdBuilder, type IdHashFormat, type ListMenusStreamOptions, type ListPaymentsOptions, type Menu, type MenuCategoryNode, type MenuLookup, type MilestoneSteps, type MilestoneTrackItem, type ModifierControlType, type ModifierCtx, type ModifierGroupCtx, type NestedMenuCategory, Order, type OrderCancelInput, type OrderCancelOptions, type OrderCancelResult, type OrderCancelType, type OrderCustomerSource, type OrderDeviceCredential, type OrderDraft, type OrderIssue, type OrderIssueCode, type OrderLineDiff, type OrderLineIssue, type OrderLineIssueCode, OrderPaymentRequiredError, type OrderScope, OrderSyncPendingError, OrderSyncRejectedError, OrderValidationError, type OrderValidationResult, type PayIntentOptions, type PayIntentResult, type PayOptions, type PaymentCardBrand, type PaymentProgressEvent, type PaymentProgressListener, type PaymentRunOptions, type PaymentSessionOptions, type PricingModifier, type Product, type ProductCtx, type QuantitiesByPath, type RecommendationType, RecurringDateCron, type RedeemPaymentRow, type RemoveRedeemInput, type ReorderOrderOptions, type ResetOptions, type ReversalOutcome, type ReverseAllOptions, RulesEngine, type ScheduleWindow, type SelectionStatus, type SelectionsByPath, type SerializedError, type ServiceHttpOptions, type SimpleTenderPayment, type Snapshot, type StorefrontAccessToken, type StorefrontErrorDetails, StorefrontHttpError, type TrackWorkflow, type ValidateOptions, type ValidateOrderAgainstMenuInput, type Variant, type VariantGroup, type VariantGroupCtx, type VariantOptionCtx, type VariantSelection, type VerifyWebhookSignatureInput, type VisitedState, addLines, auth, buildCustomerSnapshot, cancelTypeOf, capRedeems, cappedRedeems, cardBrandSpec, cardDigits, cardNumberGaps, cardNumberMaxLength, cardPreviewGroups, caretAfterDigits, collectOrderLineDiffs, computeStartingPrice, countCartProducts, coveredAmount, createDeunaWidgetApi, createSession, currentNodes, cvcMaxLength, defaultConditionError, detectCardBrand, fitRedeems, flattenMenuCategories, flushLogs, formatCardNumber, formatCvc, formatExpiry, fromOrderLines, genId, genOrderId, getLogContext, getScheduleWindow, indexMenu, isCardNumberComplete, isCardNumberDefinitelyInvalid, isCheckoutFieldFilled, isCvcComplete, isDeviceCharged, isDeviceNotLinked, isExpiryComplete, isGenId, isKioskUnauthorized, isMilestoneStepDone, isOnSchedule, isOrderPaymentRequiredError, isOrderValidationError, isPosDeviceNotLinked, isPosUnauthorized, isRealPaymentMethod, isStorefrontNotFound, isVariantBase, linePayableTotal, listMenusStream, localizePosError, log, logError, luhnCheck, matchAbsoluteDateOperator, matchBooleanOperator, matchCurrencyOperator, matchEnumOperator, matchNumberOperator, matchRecurringDateOperator, matchRelativeDateOperator, matchStringOperator, milestoneSteps, milestoneTrack, nestMenuCategories, normalizeCardholderName, orderPayableTotal, orderRedeemedTotal, orderRedeems, parseExpiry, paymentMatchesClientConditions, rebuildRootGroups, recomputeTotals, redeemedTotal, redemptionCap, redemptionSteps, remainingAmount, removeLine, replaceLine, resolveCheckout, resolveModifierImageUrl, reversePayment, runPaymentAttempt, selectablePayments, serializeError, services, setLineQuantity, storefrontJson, toOrderLines, toPaymentCardBrand, validateCardNumber, validateCardholderName, validateCvc, validateExpiry, validateOrderAgainstMenu, verifyWebhookSignature, visitedStates };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DIGITAL_COLLECT_AT, PARTIAL_APPROVAL_ERROR, REDEMPTION_METHOD, activeIntent, createAttemptReference, createPaymentError, currentIntent, defaultReversalFor, groupRedeems, hasRedeemPayment, isDeliveryFee, isPaymentError, isRealPaymentMethod, isRealPaymentMethod as isRealPaymentMethod$1, isTenderSettled, isTipFee, liveTenders, memoryPaymentStorage, missingDeviceFields, money, moneyMin, moneyNumber, moneyZero, orderRedeems, orderRedeems as orderRedeems$1, redeemsCoverTotal, resolvePaymentPolicy, resolveProviderEnvironment, scopedPaymentStorage, taxBreakdown, toChargeAmount, withTerminalLock } from "@fire-spark/payments";
+import { DIGITAL_COLLECT_AT, PARTIAL_APPROVAL_ERROR, REDEMPTION_METHOD, activeIntent, createAttemptReference, createPaymentError, currentIntent, defaultReversalFor, groupRedeems, hasRedeemPayment, isDeliveryFee, isManualPayment, isPaymentError, isRealPaymentMethod, isRealPaymentMethod as isRealPaymentMethod$1, isTenderSettled, isTipFee, liveTenders, memoryPaymentStorage, missingDeviceFields, money, moneyMin, moneyNumber, moneyZero, orderRedeems, orderRedeems as orderRedeems$1, redeemsCoverTotal, resolvePaymentPolicy, resolveProviderEnvironment, scopedPaymentStorage, taxBreakdown, toChargeAmount, withTerminalLock } from "@fire-spark/payments";
 import advancedFormat from "dayjs/plugin/advancedFormat.js";
 import isBetween from "dayjs/plugin/isBetween.js";
 import isSameOrAfter from "dayjs/plugin/isSameOrAfter.js";
@@ -2625,11 +2625,24 @@ const updateOrder = (id, body, options) => {
 		options
 	]);
 };
-const cancelOrder = (id, options) => {
-	return storefrontJson(`${orderPath(id)}/cancel`, { method: "POST" }, options);
+const postCancel = (path, options, body) => {
+	const method = "POST";
+	if (!body) return storefrontJson(path, { method }, options);
+	return storefrontJson(path, {
+		method,
+		body: JSON.stringify(body)
+	}, options);
 };
-const refundOrder = (id, options) => {
-	return storefrontJson(`${orderPath(id)}/refund`, { method: "POST" }, options);
+/**
+* `body` is optional: `device` (checked only when sent), `type`
+* (`VOID` / `REVERSE`) and what the device reversed (`tenders`).
+*/
+const cancelOrder = (id, options, body) => {
+	return postCancel(`${orderPath(id)}/cancel`, options, body);
+};
+/** Refunds the tenders only; the order status stays. `type` is `REFUND`. */
+const refundOrder = (id, options, body) => {
+	return postCancel(`${orderPath(id)}/refund`, options, body);
 };
 const reorderOrder = (id, body = {}, options) => {
 	return storefrontJson(`${orderPath(id)}/reorder`, {
@@ -2722,6 +2735,42 @@ const callPaymentOperation = (paymentId, operation, body, options) => {
 		body: JSON.stringify(body)
 	}, options);
 };
+const deunaPath = (paymentId) => {
+	return `/api/storefront/v1/payments/deuna/${encodeURIComponent(paymentId)}`;
+};
+/** DEUNA order for the Payment Widget (`POST .../deuna/:id/tokenize`). */
+const tokenizeDeunaOrder = (paymentId, body, options) => {
+	return storefrontJson(`${deunaPath(paymentId)}/tokenize`, {
+		method: "POST",
+		body: JSON.stringify(body)
+	}, options);
+};
+/** Payment status of a DEUNA order (`GET .../deuna/:id/orders/:token`). */
+const getDeunaOrder = (paymentId, orderToken, options) => {
+	const token = encodeURIComponent(orderToken);
+	return storefrontJson(`${deunaPath(paymentId)}/orders/${token}`, {}, options);
+};
+/**
+* `api` option of `deunaWidgetPayments` (`@fire-spark/payments-deuna-widget`)
+* bound to the storefront HTTP options of the template.
+*/
+const createDeunaWidgetApi = (options) => {
+	return {
+		tokenize: (input) => {
+			const b1 = { order_id: input.orderId };
+			const b2 = { attempt_reference: input.attemptReference };
+			const b3 = input.callbackUrls ? { callback_urls: input.callbackUrls } : {};
+			return tokenizeDeunaOrder(input.paymentId, {
+				...b1,
+				...b2,
+				...b3
+			}, options);
+		},
+		order: (input) => {
+			return getDeunaOrder(input.paymentId, input.orderToken, options);
+		}
+	};
+};
 /** Reports a failed terminal operation (`payment.terminal_failed`). */
 const reportTerminalFailure = (paymentId, body, options) => {
 	return storefrontJson(`/api/storefront/v1/payments/${encodeURIComponent(paymentId)}/terminal-failures`, {
@@ -3089,7 +3138,12 @@ const services = {
 	payments: {
 		list: listPayments,
 		operation: callPaymentOperation,
-		terminalFailure: reportTerminalFailure
+		terminalFailure: reportTerminalFailure,
+		deuna: {
+			tokenize: tokenizeDeunaOrder,
+			order: getDeunaOrder,
+			widgetApi: createDeunaWidgetApi
+		}
 	},
 	stores: {
 		list: listStores,
@@ -3304,6 +3358,63 @@ const isOrderPaymentRequiredError = (error) => {
 	return error instanceof OrderPaymentRequiredError;
 };
 //#endregion
+//#region src/order/cancel.ts
+const FULFILLED = ["COMPLETED", "FULFILLED"];
+/** Same rule as the server: `status` or `fulfillment_status` delivered. */
+const isOrderFulfilled = (order) => {
+	if (FULFILLED.includes(order.status)) return true;
+	return FULFILLED.includes(String(order.fulfillment_status ?? ""));
+};
+/** Money was charged at some point (paid, or already given back). */
+const isOrderCharged = (order) => {
+	if (order.payment_status === "PAID") return true;
+	if (order.payment_status === "REFUNDED") return true;
+	return liveTenders(currentIntent(order.payment_intents)).some((tender) => {
+		if (tender.status === "PAID" || tender.status === "REFUNDED") return true;
+		return (tender.refunded_total ?? 0) > 0;
+	});
+};
+/**
+* The operation an order takes: `VOID` (nothing charged), `REVERSE`
+* (charged, not delivered) or `REFUND` (delivered). An order already
+* cancelled keeps its operation, so a replay stays idempotent.
+*/
+const cancelTypeOf = (order) => {
+	if (order.status === "VOIDED") return "VOID";
+	if (order.status === "REVERSED") return "REVERSE";
+	if (isOrderFulfilled(order)) return "REFUND";
+	return isOrderCharged(order) ? "REVERSE" : "VOID";
+};
+const REVERSED_RESULTS = ["REFUNDED", "CANCELLED"];
+/** The device gave the money back. */
+const isDeviceReversed = (reversal) => {
+	return REVERSED_RESULTS.includes(reversal.outcome.result.status);
+};
+/** Body `tenders` entry for one device reversal. */
+const toReportedTender = (reversal) => {
+	const { tender, outcome } = reversal;
+	const { status, metadata: m1, error } = outcome.result;
+	const payment = m1?.payment ?? null;
+	const metadata = { reversal: {
+		kind: outcome.kind,
+		status,
+		payment,
+		error: error ?? null
+	} };
+	const reference = payment?.provider_transaction_id ?? null;
+	const b1 = { tender_id: tender.id };
+	const b2 = { attempt_reference: tender.attempt_reference };
+	const result = isDeviceReversed(reversal) ? "REVERSED" : "NOT_REVERSED";
+	const provider_reference = reference;
+	return {
+		...b1,
+		...b2,
+		result,
+		provider_reference,
+		metadata
+	};
+};
+//#endregion
 //#region src/order/retry.ts
 const defaultSleep$1 = (ms) => {
 	return new Promise((resolve) => {
@@ -3834,10 +3945,10 @@ const simpleTenderInput = (payment) => {
 /**
 * Charge order of §6.1: deferred capture (authorize only), immediate
 * capture reversible with cancel/refund, manual reversal only, then cash /
-* IDLE last.
+* card terminal (IDLE) last.
 */
 const chargeRank = (tender, adapter) => {
-	if (tender.method === "CASH") return 3;
+	if (isManualPayment(tender.provider, tender.method)) return 3;
 	if (adapter.capabilities?.deferredCapture) return 0;
 	if (adapter.cancel || adapter.refund) return 1;
 	return 2;
@@ -4164,6 +4275,10 @@ const reversePayment = async (adapter, ctx, result, options = {}) => {
 };
 //#endregion
 //#region src/order/payments/session.ts
+/** Cash or the Fire Spark card terminal: staff collects, no adapter call. */
+const isManual = (payment) => {
+	return isManualPayment(payment.provider.provider_id, payment.method.method);
+};
 const noopUI = {
 	message: () => void 0,
 	action: () => void 0,
@@ -4389,12 +4504,12 @@ var PaymentSession = class {
 		};
 	}
 	collectAt(payment) {
-		if (payment.method.method === "CASH") return this.options.cashCollectAt ?? "DOOR";
+		if (isManual(payment)) return this.options.cashCollectAt ?? "DOOR";
 		return this.options.collectAt ?? "DEVICE";
 	}
-	/** `collect_at` of a new tender: cash in person, the rest digital. */
+	/** `collect_at` of a new tender: manual in person, the rest digital. */
 	tenderCollectAt(payment) {
-		if (payment.method.method === "CASH") return this.options.cashCollectAt ?? "DOOR";
+		if (isManual(payment)) return this.options.cashCollectAt ?? "DOOR";
 		return "DEVICE";
 	}
 	toRecord(tender, result) {
@@ -4509,7 +4624,7 @@ var PaymentSession = class {
 		const amount = tender.amount.total;
 		const attemptReference = tender.attempt_reference;
 		const metadata = { attempt_reference: attemptReference };
-		if (!(payment.method.method === "CASH") && tender.status !== "PENDING") {
+		if (!isManual(payment) && tender.status !== "PENDING") {
 			const pending = {
 				status: "PENDING",
 				amount,
@@ -4743,6 +4858,34 @@ var PaymentSession = class {
 		}
 		return outcomes;
 	}
+	/**
+	* Voids the `PAID` device charges of this order without reporting them:
+	* the caller sends the results with one cancel / refund call
+	* (`order.cancel()`), never through `/payments`.
+	*/
+	async reverseOnDevice(options = {}) {
+		const intents = this.deps.getOrder().payment_intents;
+		const reversals = [];
+		const only = options.tenderIds ? new Set(options.tenderIds) : null;
+		for (const tender of chargedTenders(intents)) {
+			if (only && !only.has(tender.id)) continue;
+			if (options.skip?.has(tender.id)) continue;
+			if (tender.status !== "PAID") continue;
+			const found = await this.contextFor(tender);
+			if (!found) continue;
+			await options.onProgress?.({
+				type: "reversing",
+				tender
+			});
+			const { adapter, result, ctx } = found;
+			const outcome = await reversePayment(adapter, ctx, result);
+			reversals.push({
+				tender,
+				outcome
+			});
+		}
+		return reversals;
+	}
 	/** Runs a terminal operation (init, test, closeBatch, status, extra). */
 	async runTerminal(payment, key) {
 		const terminal = this.adapterFor(payment)?.terminal;
@@ -5483,6 +5626,8 @@ var Order = class Order {
 	*/
 	requestedRedeem = null;
 	device;
+	/** Device voids a failed cancel / refund call did not report yet. */
+	unreported = [];
 	constructor(config, notify) {
 		this.draft = cloneOrder(config.order);
 		this.synced = cloneOrder(config.order);
@@ -5625,7 +5770,10 @@ var Order = class Order {
 			debounceMs,
 			persisted
 		};
-		const d2 = { sleep: config.sleep };
+		const d2 = {
+			sleep: config.sleep,
+			device: config.device
+		};
 		return new Order({
 			...d1,
 			...d2
@@ -6093,6 +6241,80 @@ var Order = class Order {
 		await this.cancelOrder();
 		return outcomes;
 	}
+	/**
+	* Cancels this placed, not delivered order with one call to `/cancel`:
+	* `VOID` (nothing charged) or `REVERSE` (charged), decided from the
+	* fresh order. Device charges are voided first and their results go in
+	* the same body (never `/payments`). The device credential of
+	* `createOrder({ device })` / `fromExisting({ device })` is sent when
+	* present. A delivered order throws before touching the device: use
+	* `refund()`. A forced `type` that does not match throws too.
+	*/
+	async cancel(options = {}) {
+		const decided = await this.freshCancelType();
+		if (decided === "REFUND") throw new Error("Order is already delivered; use refund()");
+		if (options.type && options.type !== decided) throw new Error(`Order takes ${decided}, not ${options.type}`);
+		return this.runCancel("cancel", decided, options);
+	}
+	/**
+	* Refunds this delivered order with one call to `/refund`
+	* (`type: REFUND`): device charges are voided first and reported in the
+	* body. Only the tenders change; the order status stays. An order not
+	* delivered throws before touching the device: use `cancel()`.
+	*/
+	async refund(options = {}) {
+		if (await this.freshCancelType() !== "REFUND") throw new Error("Order is not delivered; use cancel()");
+		return this.runCancel("refund", "REFUND", options);
+	}
+	async freshCancelType() {
+		if (!this.persisted) throw new Error("Only a placed order is cancelled");
+		this.flush.cancel();
+		this.applyServerOrder(await services.orders.get(this.draft.id, this.http));
+		return cancelTypeOf(this.draft);
+	}
+	async runCancel(path, type, options) {
+		const earlier = this.unreported;
+		const done = new Set(earlier.map((reversal) => reversal.tender.id));
+		const r1 = {
+			tenderIds: options.tenderIds?.filter((id) => !done.has(id)),
+			skip: done
+		};
+		const fresh = type === "VOID" ? [] : await this.payments.reverseOnDevice(r1);
+		const reversals = [...earlier, ...fresh];
+		const b1 = {
+			type,
+			tenders: reversals.map(toReportedTender),
+			idempotency_key: createAttemptReference()
+		};
+		const b2 = options.reason ? { reason: options.reason } : {};
+		const b3 = this.device ? { device: this.device } : {};
+		const body = {
+			...b1,
+			...b2,
+			...b3
+		};
+		const call = path === "refund" ? services.orders.refund : services.orders.cancel;
+		let next;
+		try {
+			next = await call(this.draft.id, this.http, body);
+		} catch (error) {
+			this.unreported = reversals.filter(isDeviceReversed);
+			throw error;
+		}
+		this.unreported = [];
+		this.applyServerOrder(next);
+		this.deleted = true;
+		this.notify();
+		const outcomes = reversals.map((reversal) => reversal.outcome);
+		const pending = reversals.filter((reversal) => !isDeviceReversed(reversal)).map((reversal) => reversal.tender.id);
+		return {
+			order: this.getOrder(),
+			type,
+			path,
+			outcomes,
+			pending
+		};
+	}
 	/** Voids one tender (operator flow); idempotent per call. */
 	async voidTender(tenderId, reason) {
 		const idempotency_key = createAttemptReference();
@@ -8937,4 +9159,4 @@ const cardPreviewGroups = (value) => {
 	return groups;
 };
 //#endregion
-export { CARD_BRANDS, DEFAULT_RECOMMENDATION_TYPES, ID_HASH_FORMATS, Order, OrderPaymentRequiredError, OrderSyncPendingError, OrderSyncRejectedError, OrderValidationError, RecurringDateCron, RulesEngine, StorefrontHttpError, addLines, auth, buildCustomerSnapshot, capRedeems, cappedRedeems, cardBrandSpec, cardDigits, cardNumberGaps, cardNumberMaxLength, cardPreviewGroups, caretAfterDigits, collectOrderLineDiffs, computeStartingPrice, countCartProducts, coveredAmount, createSession, currentNodes, cvcMaxLength, defaultConditionError, detectCardBrand, fitRedeems, flattenMenuCategories, flushLogs, formatCardNumber, formatCvc, formatExpiry, fromOrderLines, genId, genOrderId, getLogContext, getScheduleWindow, indexMenu, isCardNumberComplete, isCardNumberDefinitelyInvalid, isCheckoutFieldFilled, isCvcComplete, isDeviceCharged, isDeviceNotLinked, isExpiryComplete, isGenId, isKioskUnauthorized, isMilestoneStepDone, isOnSchedule, isOrderPaymentRequiredError, isOrderValidationError, isPosDeviceNotLinked, isPosUnauthorized, isRealPaymentMethod, isStorefrontNotFound, isVariantBase, linePayableTotal, listMenusStream, localizePosError, log, logError, luhnCheck, matchAbsoluteDateOperator, matchBooleanOperator, matchCurrencyOperator, matchEnumOperator, matchNumberOperator, matchRecurringDateOperator, matchRelativeDateOperator, matchStringOperator, milestoneSteps, milestoneTrack, nestMenuCategories, normalizeCardholderName, orderPayableTotal, orderRedeemedTotal, orderRedeems, parseExpiry, paymentMatchesClientConditions, rebuildRootGroups, recomputeTotals, redeemedTotal, redemptionCap, redemptionSteps, remainingAmount, removeLine, replaceLine, resolveCheckout, resolveModifierImageUrl, reversePayment, runPaymentAttempt, selectablePayments, serializeError, services, setLineQuantity, storefrontJson, toOrderLines, toPaymentCardBrand, validateCardNumber, validateCardholderName, validateCvc, validateExpiry, validateOrderAgainstMenu, verifyWebhookSignature, visitedStates };
+export { CARD_BRANDS, DEFAULT_RECOMMENDATION_TYPES, ID_HASH_FORMATS, Order, OrderPaymentRequiredError, OrderSyncPendingError, OrderSyncRejectedError, OrderValidationError, RecurringDateCron, RulesEngine, StorefrontHttpError, addLines, auth, buildCustomerSnapshot, cancelTypeOf, capRedeems, cappedRedeems, cardBrandSpec, cardDigits, cardNumberGaps, cardNumberMaxLength, cardPreviewGroups, caretAfterDigits, collectOrderLineDiffs, computeStartingPrice, countCartProducts, coveredAmount, createDeunaWidgetApi, createSession, currentNodes, cvcMaxLength, defaultConditionError, detectCardBrand, fitRedeems, flattenMenuCategories, flushLogs, formatCardNumber, formatCvc, formatExpiry, fromOrderLines, genId, genOrderId, getLogContext, getScheduleWindow, indexMenu, isCardNumberComplete, isCardNumberDefinitelyInvalid, isCheckoutFieldFilled, isCvcComplete, isDeviceCharged, isDeviceNotLinked, isExpiryComplete, isGenId, isKioskUnauthorized, isMilestoneStepDone, isOnSchedule, isOrderPaymentRequiredError, isOrderValidationError, isPosDeviceNotLinked, isPosUnauthorized, isRealPaymentMethod, isStorefrontNotFound, isVariantBase, linePayableTotal, listMenusStream, localizePosError, log, logError, luhnCheck, matchAbsoluteDateOperator, matchBooleanOperator, matchCurrencyOperator, matchEnumOperator, matchNumberOperator, matchRecurringDateOperator, matchRelativeDateOperator, matchStringOperator, milestoneSteps, milestoneTrack, nestMenuCategories, normalizeCardholderName, orderPayableTotal, orderRedeemedTotal, orderRedeems, parseExpiry, paymentMatchesClientConditions, rebuildRootGroups, recomputeTotals, redeemedTotal, redemptionCap, redemptionSteps, remainingAmount, removeLine, replaceLine, resolveCheckout, resolveModifierImageUrl, reversePayment, runPaymentAttempt, selectablePayments, serializeError, services, setLineQuantity, storefrontJson, toOrderLines, toPaymentCardBrand, validateCardNumber, validateCardholderName, validateCvc, validateExpiry, validateOrderAgainstMenu, verifyWebhookSignature, visitedStates };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/core",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Fire Spark headless SDK",
   "type": "module",
   "sideEffects": false,
@@ -20,8 +20,8 @@
     "big.js": "6.2.1",
     "dayjs": "1.11.9",
     "@types/big.js": "6.2.2",
-    "@fire-spark/payments": "^0.9.1",
-    "@fire-spark/types": "^0.9.1"
+    "@fire-spark/payments": "^0.11.0",
+    "@fire-spark/types": "^0.11.0"
   },
   "devDependencies": {
     "tsdown": "^0.22.14",