@fire-spark/payments-cash 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,11 +1,23 @@
-import { PaymentAdapter } from "@fire-spark/payments";
+import { PaymentAdapter, PaymentAdapterCapabilities, PaymentContext } from "@fire-spark/payments";
+import { TenderDetails } from "@fire-spark/types";
 //#region src/index.d.ts
 /** Cash has no provider: nothing can fail remotely. */
 declare const cashErrors: Readonly<Record<string, import("@fire-spark/payments").PaymentErrorEntry>>;
+/** Cash is collected by a person and never captured later. */
+declare const cashCapabilities: PaymentAdapterCapabilities;
+type CashDetails = Extract<TenderDetails, {
+  method: "CASH";
+}>;
+/** `details` of a CASH tender; `tendered` below the amount is clamped. */
+declare const cashDetails: (amount: number, tendered: number | null | undefined, currency: string) => CashDetails;
+type CashPaymentsOptions = {
+  /** Cash the customer hands over (e.g. typed by the cashier). */
+  tendered?: (ctx: PaymentContext) => number | null | Promise<number | null>;
+};
 /**
  * Cash collected by staff at the counter (kiosk) or at the door (delivery).
- * The intent stays IDLE until the store marks the order as paid.
+ * The tender stays IDLE until the store marks the order as paid.
  */
-declare const cashPayments: () => PaymentAdapter;
+declare const cashPayments: (options?: CashPaymentsOptions) => PaymentAdapter;
 //#endregion
-export { cashErrors, cashPayments };
+export { CashDetails, CashPaymentsOptions, cashCapabilities, cashDetails, cashErrors, cashPayments };

package/dist/index.js

@@ -1,25 +1,44 @@
-import { definePaymentErrors } from "@fire-spark/payments";
+import { currencyDecimals, definePaymentErrors, roundTo } from "@fire-spark/payments";
 //#region src/index.ts
 /** Cash has no provider: nothing can fail remotely. */
 const cashErrors = definePaymentErrors({});
-const idle = (ctx) => {
-	const metadata = { attempt_reference: ctx.attemptReference };
+/** Cash is collected by a person and never captured later. */
+const cashCapabilities = {
+	deferredCapture: false,
+	inPerson: true
+};
+/** `details` of a CASH tender; `tendered` below the amount is clamped. */
+const cashDetails = (amount, tendered, currency) => {
+	const decimals = currencyDecimals(currency);
+	const given = roundTo(Math.max(tendered ?? amount, amount), decimals);
 	return {
-		status: "IDLE",
-		amount: ctx.amount.value,
-		metadata
+		method: "CASH",
+		tendered: given,
+		change: roundTo(given - amount, decimals)
 	};
 };
 /**
 * Cash collected by staff at the counter (kiosk) or at the door (delivery).
-* The intent stays IDLE until the store marks the order as paid.
+* The tender stays IDLE until the store marks the order as paid.
 */
-const cashPayments = () => {
+const cashPayments = (options = {}) => {
+	const start = async (ctx) => {
+		const metadata = { attempt_reference: ctx.attemptReference };
+		const amount = ctx.amount.value;
+		const tendered = await options.tendered?.(ctx) ?? null;
+		return {
+			status: "IDLE",
+			amount,
+			metadata,
+			details: cashDetails(amount, tendered, ctx.amount.currency)
+		};
+	};
 	return {
 		provider: "firespark",
 		method: "CASH",
 		errors: cashErrors,
-		start: async (ctx) => idle(ctx),
+		capabilities: cashCapabilities,
+		start,
 		cancel: async (_ctx, result) => ({
 			...result,
 			status: "CANCELLED"
@@ -27,4 +46,4 @@ const cashPayments = () => {
 	};
 };
 //#endregion
-export { cashErrors, cashPayments };
+export { cashCapabilities, cashDetails, cashErrors, cashPayments };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/payments-cash",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Fire Spark cash payments adapter (collected at the counter or the door)",
   "type": "module",
   "sideEffects": false,
@@ -17,8 +17,8 @@
     }
   },
   "dependencies": {
-    "@fire-spark/types": "^0.2.0",
-    "@fire-spark/payments": "^0.2.0"
+    "@fire-spark/payments": "^0.3.0",
+    "@fire-spark/types": "^0.3.0"
   },
   "devDependencies": {
     "tsdown": "^0.22.14",