@fire-spark/payments-payphone-checkout 0.0.0-stage → 0.15.0

package/dist/index.d.ts

@@ -0,0 +1,141 @@
+import { PaymentAdapter, PaymentContext, PaymentPolicy } from "@fire-spark/payments";
+//#region src/types.d.ts
+/** Answer of the Spark Payphone operations (no token, no card data). */
+type PayphoneOutcome = {
+  status: "PAID" | "FAILED" | "PENDING";
+  status_code: number | null;
+  transaction_id: number | null;
+  client_transaction_id: string | null;
+  authorization_code: string | null;
+  amount: number | null;
+  card_brand: string | null;
+  card_type: string | null;
+  last_digits: string | null;
+  deferred: boolean | null;
+  message: string | null;
+  message_code: number | null;
+  error_code: number | null;
+};
+/** `prepare` answer: the Payphone form URLs for this attempt. */
+type PayphonePrepared = {
+  payment_id: string | number | null;
+  pay_with_card: string | null;
+  pay_with_payphone: string | null;
+};
+/** Query string Payphone sends to `responseUrl` after the form. */
+type PayphoneReturn = {
+  id: number;
+  clientTransactionId: string;
+};
+type PayphoneRedirectInput = {
+  /** Payphone form to open in the browser (never in an iframe/WebView). */
+  url: string;
+  attemptReference: string;
+  responseUrl: string;
+  /** Aborted on timeout or cancel: close the tab, resolve `cancelled`. */
+  signal: AbortSignal;
+};
+/**
+ * How the redirect ended. A popup or new tab resolves `returned` with the
+ * query of the `responseUrl` page (e.g. sent by `postMessage`); a full
+ * page navigation resolves `redirected` and the return page resumes with
+ * `takeReturn`.
+ */
+type PayphoneRedirectOutcome = ({
+  type: "returned";
+} & PayphoneReturn) | {
+  type: "cancelled";
+} | {
+  type: "redirected";
+};
+/**
+ * Implemented once per web template. Payphone only accepts its form opened
+ * from the domain registered in Payphone Developer, in a browser tab.
+ */
+type PayphoneRedirectBridge = {
+  open(input: PayphoneRedirectInput): Promise<PayphoneRedirectOutcome>;
+  /**
+   * After a full page redirect: the return of `attemptReference` read from
+   * the `responseUrl` page (see `parsePayphoneReturn`), once; else `null`.
+   */
+  takeReturn?(attemptReference: string): Promise<PayphoneReturn | null>;
+};
+//#endregion
+//#region src/card.d.ts
+type PayphoneCardOptions = {
+  /** Opens the Payphone form in a browser tab and reports the return. */
+  bridge: PayphoneRedirectBridge;
+  /** https page of the registered domain that reads `id` and `clientTransactionId`. */
+  responseUrl: string;
+  cancellationUrl?: string;
+  /** `card` (default) or `payphone` (balance, inside Payphone's form). */
+  payWith?: "card" | "payphone";
+  language?: "es" | "en";
+};
+/**
+ * `id` and `clientTransactionId` of a Payphone return URL (the page at
+ * `responseUrl`); `null` if it is not one.
+ */
+declare const parsePayphoneReturn: (url: string) => PayphoneReturn | null;
+/**
+ * Payphone card on the web: Botón de Pago por redirección. Spark prepares
+ * the form with the token (`prepare`), the template opens it in a browser
+ * tab (`bridge`), and Spark confirms the return (`confirm`) within the 5
+ * minutes Payphone allows before it reverses. A paid charge is reversed by
+ * Spark with the order cancel or refund, the same day only. Web only:
+ * Payphone forbids its form in apps, iframes and WebViews.
+ */
+declare const payphoneCardPayments: (options: PayphoneCardOptions) => PaymentAdapter;
+//#endregion
+//#region src/constants.d.ts
+declare const PAYPHONE_PROVIDER = "payphone";
+/** API Sale: the customer has 5 minutes to approve in the Payphone app. */
+declare const PAYPHONE_SALE_TTL_MS = 300000;
+/**
+ * Card: the Payphone form lives 10 minutes and an unconfirmed charge is
+ * reversed after 5. One automatic attempt: a retry is a new charge.
+ */
+declare const PAYPHONE_CARD_POLICY: Partial<PaymentPolicy>;
+/** Wallet push: 5 minutes to approve, status read every 3 seconds. */
+declare const PAYPHONE_WALLET_POLICY: Partial<PaymentPolicy>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Payphone `errorCode` values seen in the official docs; the full catalog
+ * is pending (ficha §13). Unknown codes fall back per method.
+ */
+declare const payphoneErrors: Readonly<Record<string, import("@fire-spark/payments").PaymentErrorEntry>> & {
+  "20": {
+    code: "AMBIGUOUS";
+    source: string;
+  };
+  "25": {
+    code: "AMBIGUOUS";
+    source: string;
+  };
+  "2029": {
+    code: "INVALID_REQUEST";
+    source: string;
+  };
+};
+//#endregion
+//#region src/wallet.d.ts
+type PayphoneWalletOptions = {
+  /**
+   * Phone registered in Payphone. Default: the order customer phone, else
+   * asked with `ui.input`.
+   */
+  phone?: (ctx: PaymentContext) => Promise<string | null>;
+  phoneLabel?: string;
+};
+/**
+ * Payphone app push (API Sale) for kiosks and mobile apps: Spark sends
+ * the charge to the customer's Payphone app, the customer approves it
+ * there (balance or a card saved in the app) within 5 minutes, and the
+ * adapter reads the status. A push nobody approves is withdrawn. A paid
+ * charge is reversed by Spark with the order cancel or refund, the same
+ * day only.
+ */
+declare const payphoneWalletPayments: (options?: PayphoneWalletOptions) => PaymentAdapter;
+//#endregion
+export { PAYPHONE_CARD_POLICY, PAYPHONE_PROVIDER, PAYPHONE_SALE_TTL_MS, PAYPHONE_WALLET_POLICY, PayphoneCardOptions, type PayphoneOutcome, type PayphonePrepared, type PayphoneRedirectBridge, type PayphoneRedirectInput, type PayphoneRedirectOutcome, type PayphoneReturn, PayphoneWalletOptions, parsePayphoneReturn, payphoneCardPayments, payphoneErrors, payphoneWalletPayments };

package/dist/index.js

@@ -0,0 +1,384 @@
+import { PaymentError, createPaymentError, definePaymentErrors, toPaymentError } from "@fire-spark/payments";
+//#region src/constants.ts
+const PAYPHONE_PROVIDER = "payphone";
+/** API Sale: the customer has 5 minutes to approve in the Payphone app. */
+const PAYPHONE_SALE_TTL_MS = 3e5;
+/**
+* Card: the Payphone form lives 10 minutes and an unconfirmed charge is
+* reversed after 5. One automatic attempt: a retry is a new charge.
+*/
+const PAYPHONE_CARD_POLICY = {
+	timeout_ms: 9e5,
+	max_attempts: 1
+};
+/** Wallet push: 5 minutes to approve, status read every 3 seconds. */
+const PAYPHONE_WALLET_POLICY = {
+	timeout_ms: 36e4,
+	poll_interval_ms: 3e3,
+	max_attempts: 1
+};
+//#endregion
+//#region src/errors.ts
+const source = "docs/payments/payphone/checkout.md#11-errores";
+/**
+* Payphone `errorCode` values seen in the official docs; the full catalog
+* is pending (ficha §13). Unknown codes fall back per method.
+*/
+const payphoneErrors = definePaymentErrors({
+	"20": {
+		code: "AMBIGUOUS",
+		source
+	},
+	"25": {
+		code: "AMBIGUOUS",
+		source
+	},
+	"2029": {
+		code: "INVALID_REQUEST",
+		source
+	}
+});
+//#endregion
+//#region src/result.ts
+const CARD_TYPES = {
+	credit: "CREDIT",
+	debit: "DEBIT",
+	prepaid: "PREPAID"
+};
+const last4Of = (digits) => {
+	const clean = (digits ?? "").replace(/\D/g, "");
+	return clean.length >= 4 ? clean.slice(-4) : null;
+};
+/** Ids and card data of a Payphone outcome; nothing sensitive. */
+const payphoneMetadataOf = (ctx, outcome) => {
+	const type = outcome.card_type ? CARD_TYPES[outcome.card_type.toLowerCase()] ?? null : null;
+	const reference = outcome.authorization_code ?? (outcome.transaction_id != null ? String(outcome.transaction_id) : null);
+	const p1 = { provider_transaction_id: outcome.transaction_id != null ? String(outcome.transaction_id) : null };
+	const p2 = {
+		authorization_code: outcome.authorization_code,
+		reference
+	};
+	const p3 = {
+		brand: outcome.card_brand,
+		card_type: type
+	};
+	const p4 = { last4: last4Of(outcome.last_digits) };
+	const payment = {
+		...p1,
+		...p2,
+		...p3,
+		...p4
+	};
+	const r1 = { transaction_id: outcome.transaction_id };
+	const r2 = { client_transaction_id: outcome.client_transaction_id };
+	const r3 = { status_code: outcome.status_code };
+	const provider = {
+		...r1,
+		...r2,
+		...r3,
+		deferred: outcome.deferred
+	};
+	return {
+		attempt_reference: ctx.attemptReference,
+		payment,
+		provider
+	};
+};
+const cardDetailsOf = (outcome) => {
+	const brand = outcome.card_brand;
+	const last4 = last4Of(outcome.last_digits);
+	if (!brand || !last4) return null;
+	const auth = outcome.authorization_code;
+	return {
+		method: "CARD",
+		brand,
+		last4,
+		...auth ? { auth_code: auth } : {}
+	};
+};
+/** Paid with the Payphone balance (no card) or a card inside the app. */
+const walletDetailsOf = (outcome) => {
+	return {
+		method: "WALLET",
+		wallet: "payphone",
+		reference: outcome.authorization_code ?? String(outcome.transaction_id ?? "")
+	};
+};
+/** Spark error of a failed outcome: dictionary code, else `fallback`. */
+const payphoneErrorOf = (ctx, outcome, fallback) => {
+	return toPaymentError(payphoneErrors, {
+		code: outcome.error_code ?? outcome.message_code,
+		message: outcome.message,
+		attempt: ctx.attempt,
+		fallback
+	});
+};
+const failedResult = (ctx, error, metadata) => {
+	const base = metadata ?? { attempt_reference: ctx.attemptReference };
+	const review = error.code === "AMBIGUOUS" ? { needs_review: true } : {};
+	const m = {
+		...base,
+		...review,
+		error
+	};
+	return {
+		status: "FAILED",
+		amount: ctx.amount.value,
+		metadata: m,
+		error
+	};
+};
+/** PAID / FAILED / PENDING result of a Payphone outcome. */
+const payphoneResultOf = (ctx, outcome, kind) => {
+	const metadata = payphoneMetadataOf(ctx, outcome);
+	const amount = ctx.amount.value;
+	if (outcome.status === "PAID") return {
+		status: "PAID",
+		amount,
+		metadata,
+		details: kind === "CARD" ? cardDetailsOf(outcome) ?? walletDetailsOf(outcome) : walletDetailsOf(outcome)
+	};
+	if (outcome.status === "PENDING") return {
+		status: "PENDING",
+		amount,
+		metadata
+	};
+	return failedResult(ctx, payphoneErrorOf(ctx, outcome, kind === "CARD" ? "CARD_DECLINED" : "WALLET_REJECTED"), metadata);
+};
+/** Spark operation failures: a missing answer may still have charged. */
+const serverErrorOf = (ctx, cause) => {
+	const e = cause;
+	const extra = {
+		provider_message: e?.message ?? "Payphone request failed",
+		attempt: ctx.attempt
+	};
+	if (e?.code === "AMBIGUOUS" || e?.status === 504) return createPaymentError("AMBIGUOUS", extra);
+	if (e?.status === 409) return createPaymentError("INVALID_CREDENTIALS", extra);
+	if (e?.status === 400) return createPaymentError("INVALID_REQUEST", extra);
+	return createPaymentError("PROVIDER_UNAVAILABLE", extra);
+};
+//#endregion
+//#region src/card.ts
+/**
+* `id` and `clientTransactionId` of a Payphone return URL (the page at
+* `responseUrl`); `null` if it is not one.
+*/
+const parsePayphoneReturn = (url) => {
+	try {
+		const params = new URL(url).searchParams;
+		const id = Number(params.get("id"));
+		const clientTransactionId = params.get("clientTransactionId") ?? params.get("clientTxId");
+		if (!Number.isInteger(id) || id <= 0 || !clientTransactionId) return null;
+		return {
+			id,
+			clientTransactionId
+		};
+	} catch {
+		return null;
+	}
+};
+const storageKey = (attemptReference) => {
+	return `payphone:prepared:${attemptReference}`;
+};
+/**
+* Payphone card on the web: Botón de Pago por redirección. Spark prepares
+* the form with the token (`prepare`), the template opens it in a browser
+* tab (`bridge`), and Spark confirms the return (`confirm`) within the 5
+* minutes Payphone allows before it reverses. A paid charge is reversed by
+* Spark with the order cancel or refund, the same day only. Web only:
+* Payphone forbids its form in apps, iframes and WebViews.
+*/
+const payphoneCardPayments = (options) => {
+	const { bridge } = options;
+	const confirm = async (ctx, back) => {
+		if (back.clientTransactionId !== ctx.attemptReference) return failedResult(ctx, createPaymentError("INVALID_REQUEST", {
+			provider_message: "Payphone returned another attempt",
+			attempt: ctx.attempt
+		}));
+		ctx.ui.message({
+			text: "Confirmando pago…",
+			kind: "waiting"
+		});
+		const input = {
+			id: back.id,
+			client_transaction_id: back.clientTransactionId
+		};
+		return payphoneResultOf(ctx, await ctx.server.call("confirm", input), "CARD");
+	};
+	const pending = (ctx) => {
+		const metadata = { attempt_reference: ctx.attemptReference };
+		return {
+			status: "PENDING",
+			amount: ctx.amount.value,
+			metadata
+		};
+	};
+	const start = async (ctx) => {
+		try {
+			const r1 = { response_url: options.responseUrl };
+			const r2 = options.cancellationUrl ? { cancellation_url: options.cancellationUrl } : {};
+			const lang = options.language ?? "es";
+			const input = {
+				...r1,
+				...r2,
+				lang
+			};
+			const prepared = await ctx.server.call("prepare", input);
+			const url = options.payWith === "payphone" ? prepared.pay_with_payphone ?? prepared.pay_with_card : prepared.pay_with_card;
+			if (!url) return failedResult(ctx, createPaymentError("PROVIDER_UNAVAILABLE", {
+				provider_message: "Payphone returned no form",
+				attempt: ctx.attempt
+			}));
+			await ctx.storage.set(storageKey(ctx.attemptReference), url);
+			const b1 = {
+				url,
+				attemptReference: ctx.attemptReference
+			};
+			const b2 = {
+				responseUrl: options.responseUrl,
+				signal: ctx.signal
+			};
+			const outcome = await bridge.open({
+				...b1,
+				...b2
+			});
+			if (outcome.type === "redirected") return pending(ctx);
+			if (outcome.type === "cancelled") return failedResult(ctx, createPaymentError("CANCELLED_BY_USER", { attempt: ctx.attempt }));
+			return await confirm(ctx, outcome);
+		} catch (cause) {
+			if (cause instanceof PaymentError) return failedResult(ctx, cause.error);
+			return failedResult(ctx, serverErrorOf(ctx, cause));
+		}
+	};
+	/** After a full page redirect: confirms the return once it is there. */
+	const query = async (ctx, result) => {
+		if (result.status !== "PENDING") return result;
+		const back = await bridge.takeReturn?.(ctx.attemptReference) ?? null;
+		if (!back) return result;
+		try {
+			return await confirm(ctx, back);
+		} catch (cause) {
+			return failedResult(ctx, serverErrorOf(ctx, cause));
+		}
+	};
+	/** An unconfirmed charge is reversed by Payphone itself after 5 minutes. */
+	const cancel = async (_ctx, result) => {
+		return {
+			...result,
+			status: "CANCELLED"
+		};
+	};
+	const reversalFor = (result) => {
+		return result.status === "PAID" ? "server" : "cancel";
+	};
+	return {
+		provider: PAYPHONE_PROVIDER,
+		method: "CARD",
+		errors: payphoneErrors,
+		policy: PAYPHONE_CARD_POLICY,
+		start,
+		query,
+		cancel,
+		reversalFor
+	};
+};
+//#endregion
+//#region src/wallet.ts
+/** Sleeps `ms`, or less when `signal` aborts. */
+const wait = (ms, signal) => {
+	return new Promise((resolve) => {
+		if (signal.aborted) return resolve();
+		const timer = setTimeout(done, ms);
+		function done() {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", done);
+			resolve();
+		}
+		signal.addEventListener("abort", done);
+	});
+};
+/**
+* Payphone app push (API Sale) for kiosks and mobile apps: Spark sends
+* the charge to the customer's Payphone app, the customer approves it
+* there (balance or a card saved in the app) within 5 minutes, and the
+* adapter reads the status. A push nobody approves is withdrawn. A paid
+* charge is reversed by Spark with the order cancel or refund, the same
+* day only.
+*/
+const payphoneWalletPayments = (options = {}) => {
+	const label = options.phoneLabel ?? "Celular registrado en Payphone";
+	const phoneOf = async (ctx) => {
+		if (options.phone) return options.phone(ctx);
+		if (ctx.customer.phone) return ctx.customer.phone;
+		return ctx.ui.input({
+			label,
+			type: "number",
+			maxLength: 15
+		});
+	};
+	const status = (ctx) => {
+		return ctx.server.call("sale_status", {});
+	};
+	/** Withdraws the push; a refused cancel means it already settled. */
+	const withdraw = async (ctx) => {
+		await ctx.server.call("sale_cancel", {}).catch(() => null);
+		return status(ctx).catch(() => null);
+	};
+	const poll = async (ctx) => {
+		const deadline = Date.now() + PAYPHONE_SALE_TTL_MS;
+		const every = ctx.policy.poll_interval_ms || 3e3;
+		while (Date.now() < deadline && !ctx.signal.aborted) {
+			await wait(every, ctx.signal);
+			if (ctx.signal.aborted) break;
+			const outcome = await status(ctx).catch(() => null);
+			if (outcome && outcome.status !== "PENDING") return payphoneResultOf(ctx, outcome, "WALLET");
+		}
+		const last = await withdraw(ctx);
+		if (last && last.status !== "PENDING") return payphoneResultOf(ctx, last, "WALLET");
+		return failedResult(ctx, createPaymentError(ctx.signal.aborted ? "CANCELLED_BY_USER" : "WALLET_EXPIRED", { attempt: ctx.attempt }));
+	};
+	const start = async (ctx) => {
+		try {
+			const phone = (await phoneOf(ctx))?.trim();
+			if (!phone) return failedResult(ctx, createPaymentError("CANCELLED_BY_USER", { attempt: ctx.attempt }));
+			const sent = await ctx.server.call("sale", { phone_number: phone }).catch((cause) => {
+				if (serverErrorOf(ctx, cause).code === "AMBIGUOUS") return null;
+				throw cause;
+			});
+			if (sent?.status === "FAILED") return payphoneResultOf(ctx, sent, "WALLET");
+			ctx.ui.message({
+				text: "Aprueba el pago en tu app Payphone",
+				kind: "waiting"
+			});
+			return await poll(ctx);
+		} catch (cause) {
+			if (cause instanceof PaymentError) return failedResult(ctx, cause.error);
+			return failedResult(ctx, serverErrorOf(ctx, cause));
+		}
+	};
+	const query = async (ctx) => {
+		return payphoneResultOf(ctx, await status(ctx), "WALLET");
+	};
+	const cancel = async (ctx, result) => {
+		await ctx.server.call("sale_cancel", {}).catch(() => null);
+		return {
+			...result,
+			status: "CANCELLED"
+		};
+	};
+	const reversalFor = (result) => {
+		return result.status === "PAID" ? "server" : "cancel";
+	};
+	return {
+		provider: PAYPHONE_PROVIDER,
+		method: "WALLET",
+		errors: payphoneErrors,
+		policy: PAYPHONE_WALLET_POLICY,
+		start,
+		query,
+		cancel,
+		reversalFor
+	};
+};
+//#endregion
+export { PAYPHONE_CARD_POLICY, PAYPHONE_PROVIDER, PAYPHONE_SALE_TTL_MS, PAYPHONE_WALLET_POLICY, parsePayphoneReturn, payphoneCardPayments, payphoneErrors, payphoneWalletPayments };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@fire-spark/payments-payphone-checkout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.15.0",
+  "description": "Fire Spark Payphone adapters (Ecuador): card through the Botón de Pago redirect on the web, and the Payphone app push (API Sale) for kiosks and mobile apps",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@fire-spark/types": "^0.15.0",
+    "@fire-spark/payments": "^0.15.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "tsdown": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "platform": "neutral",
+    "dts": {
+      "tsconfig": "tsconfig.build.json"
+    },
+    "clean": true,
+    "deps": {
+      "neverBundle": [
+        "@fire-spark/payments",
+        "@fire-spark/types"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit",
+    "test:utils": "vitest run",
+    "lint": "oxlint ./src --max-warnings=0",
+    "format": "oxfmt ./src",
+    "check-format": "oxfmt --check ./src"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.