caelum0x ae448fe158 feat(checkout): subscribe to recurring products with onchain billing
Recurring checkouts (/c and /l links) offer Subscribe on the session's network:
smart-wallet spend permission, Permit2 capped allowance, Solana SPL delegate or
renewal invoices by email (HyperCore / Zcash). The page states the per-period
price, total cap and expiry before signing; the buyer's wallet (EIP-6963 /
Wallet Standard) sends prerequisite calls and signs the server-built grant,
and the API activates it, charges the first period and delivers access.
Buyers get a signed /s/<token> manage page with status, next charge, charges
with explorer links, cancel and an on-chain revoke. All billing calls go
server-side through /v1/onchain-billing with the service token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:24:52 +03:00

311 lines
10 KiB
TypeScript

/**
* Real fetch client for the SettleKit checkout API.
*
* Talks HTTP to the route handlers under /api/v1. Works in three contexts:
* - Server Components (absolute URL derived from request/env, no-store cache)
* - Client Components (relative URL, browser fetch)
*
* Every method returns parsed JSON or throws an `ApiClientError` carrying the
* HTTP status + server message, so callers can branch on 404 (not found) /
* 410 (expired) without string matching.
*/
import type { PaymentNetwork } from "@settlekit/common";
import type { AnyTokenOptionsResponse, RouteQuoteView, RouteStatusView } from "./any-token";
import type { EvmPaymentParams } from "./evm-checkout";
import type { HyperCorePaymentParams, HyperCoreStatusResponse } from "./hypercore-checkout";
import type {
CheckoutSessionView,
ConfirmPaymentRequest,
NetworkSelectResponse,
ReceiptView,
SolanaPayUrlResponse,
SolanaStatusResponse,
SolanaTxResponse,
} from "./types";
import type { ZcashStatusResponse, ZcashUriResponse } from "./zcash-checkout";
import type { CompleteSubscriptionResult, StartSubscriptionResult, SubscriptionOffer } from "./subscription-checkout";
import type { CancelManagedResult } from "./manage-subscription";
export class ApiClientError extends Error {
constructor(
public readonly status: number,
message: string,
/** Machine-readable checkout error code, when the server sent one. */
public readonly code?: string,
) {
super(message);
this.name = "ApiClientError";
}
/** Found on-chain but not final yet: poll again. */
get pending(): boolean {
return this.code === "payment_pending";
}
/** Paid after the quote expired: held for manual review. */
get underReview(): boolean {
return this.code === "payment_under_review";
}
get notFound(): boolean {
return this.status === 404;
}
get expired(): boolean {
return this.status === 410;
}
}
/**
* Resolve the API base URL.
* - Browser: relative (empty base) so it hits the same origin.
* - Server: CHECKOUT_API_BASE_URL or a localhost fallback for the dev port.
*/
export function resolveBaseUrl(): string {
if (typeof window !== "undefined") return "";
const explicit = process.env.CHECKOUT_API_BASE_URL;
if (explicit) return explicit.replace(/\/$/, "");
const port = process.env.PORT ?? "3000";
return `http://localhost:${port}`;
}
async function request<T>(
path: string,
init?: RequestInit,
): Promise<T> {
const base = resolveBaseUrl();
const res = await fetch(`${base}${path}`, {
...init,
headers: {
"content-type": "application/json",
accept: "application/json",
...(init?.headers ?? {}),
},
// Checkout state is dynamic; never serve a cached body.
cache: "no-store",
});
const text = await res.text();
const body = text.length > 0 ? safeJson(text) : undefined;
if (!res.ok) {
const message =
body && typeof body === "object" && "error" in body
? String((body as { error: unknown }).error)
: `Request failed with status ${res.status}`;
const code =
body && typeof body === "object" && "code" in body ? String((body as { code: unknown }).code) : undefined;
throw new ApiClientError(res.status, message, code);
}
return body as T;
}
function safeJson(text: string): unknown {
try {
return JSON.parse(text);
} catch {
return undefined;
}
}
/** Fetch a checkout session view by id. */
export function getCheckoutSession(
sessionId: string,
): Promise<CheckoutSessionView> {
return request<CheckoutSessionView>(
`/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}`,
);
}
/** Confirm payment: submit tx hash + collected fields. */
export function confirmCheckoutPayment(
sessionId: string,
payload: ConfirmPaymentRequest,
): Promise<ReceiptView> {
return request<ReceiptView>(
`/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}/confirm`,
{
method: "POST",
body: JSON.stringify(payload),
},
);
}
/** Fetch the receipt + delivered access for a completed session. */
export function getReceipt(sessionId: string): Promise<ReceiptView> {
return request<ReceiptView>(
`/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}/receipt`,
);
}
/** Mark a session expired (used by the expired flow). */
export function expireCheckoutSession(
sessionId: string,
): Promise<{ ok: true }> {
return request<{ ok: true }>(
`/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}/expire`,
{ method: "POST" },
);
}
function solanaPath(sessionId: string, leaf: "pay-url" | "tx" | "status"): string {
return `/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}/solana/${leaf}`;
}
/** Save buyer fields and get the Solana Pay request (QR + reference) for a session. */
export function requestSolanaPayUrl(
sessionId: string,
fields: Record<string, string>,
): Promise<SolanaPayUrlResponse> {
return request<SolanaPayUrlResponse>(solanaPath(sessionId, "pay-url"), {
method: "POST",
body: JSON.stringify({ fields }),
});
}
/** Ask the server to build the unsigned USDC payment tx for `account`. */
export function requestSolanaTransaction(
sessionId: string,
account: string,
): Promise<SolanaTxResponse> {
return request<SolanaTxResponse>(solanaPath(sessionId, "tx"), {
method: "POST",
body: JSON.stringify({ account }),
});
}
/** Poll whether the session's Solana payment has landed (confirms it if so). */
export function getSolanaStatus(sessionId: string): Promise<SolanaStatusResponse> {
return request<SolanaStatusResponse>(solanaPath(sessionId, "status"));
}
function sessionPath(sessionId: string, leaf: string): string {
return `/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}/${leaf}`;
}
/** Switch the session to another accepted network (locks a ZEC quote for Zcash). */
export function selectCheckoutNetwork(sessionId: string, network: PaymentNetwork): Promise<NetworkSelectResponse> {
return request<NetworkSelectResponse>(sessionPath(sessionId, "network"), {
method: "POST",
body: JSON.stringify({ network }),
});
}
/** Wallet parameters for paying on the session's EVM network. */
export function getEvmParams(sessionId: string): Promise<EvmPaymentParams> {
return request<EvmPaymentParams>(sessionPath(sessionId, "evm/params"));
}
/** Save delivery fields and bind the connected wallet as payer. */
export function declareEvmPayer(
sessionId: string,
proof: { payer: string; signature: string; expiresAt: string },
fields: Record<string, string>,
): Promise<{ payerAddress: string }> {
return request<{ payerAddress: string }>(sessionPath(sessionId, "evm/payer"), {
method: "POST",
body: JSON.stringify({ ...proof, fields }),
});
}
/** Save delivery fields and get the ZIP-321 request for the locked quote. */
export function requestZcashUri(sessionId: string, fields: Record<string, string>): Promise<ZcashUriResponse> {
return request<ZcashUriResponse>(sessionPath(sessionId, "zcash/uri"), {
method: "POST",
body: JSON.stringify({ fields }),
});
}
/** Poll the session's Zcash payment status. */
export function getZcashStatus(sessionId: string): Promise<ZcashStatusResponse> {
return request<ZcashStatusResponse>(sessionPath(sessionId, "zcash/status"));
}
/** What the buyer's wallet signs to pay on HyperCore. */
export function getHyperCoreParams(sessionId: string): Promise<HyperCorePaymentParams> {
return request<HyperCorePaymentParams>(sessionPath(sessionId, "hypercore/params"));
}
/** Submit the buyer-signed usdSend (binds the signer, saves fields). */
export function submitHyperCoreTransfer(
sessionId: string,
payload: { action: unknown; signature: string; fields: Record<string, string> },
): Promise<HyperCoreStatusResponse> {
return request<HyperCoreStatusResponse>(sessionPath(sessionId, "hypercore/submit"), {
method: "POST",
body: JSON.stringify(payload),
});
}
/** Poll the submitted HyperCore transfer (settles it once it is in the ledger). */
export function getHyperCoreStatus(sessionId: string, nonce: number): Promise<HyperCoreStatusResponse> {
return request<HyperCoreStatusResponse>(sessionPath(sessionId, "hypercore/status"), {
method: "POST",
body: JSON.stringify({ nonce }),
});
}
/** Origin chains/tokens the buyer can pay from (any-token routing). */
export function getAnyTokenOptions(sessionId: string): Promise<AnyTokenOptionsResponse> {
return request<AnyTokenOptionsResponse>(sessionPath(sessionId, "route/quote"));
}
/** Quote an any-token route to the session's network (saves fields). */
export function requestRouteQuote(
sessionId: string,
payload: {
originChainId: number;
originToken: string;
originAddress: string;
depositAddress: boolean;
fields: Record<string, string>;
},
): Promise<RouteQuoteView> {
return request<RouteQuoteView>(sessionPath(sessionId, "route/quote"), {
method: "POST",
body: JSON.stringify(payload),
});
}
/** Poll the route; settles the session once the destination transfer verifies. */
export function getRouteStatus(sessionId: string, originTxHash?: string): Promise<RouteStatusView> {
return request<RouteStatusView>(sessionPath(sessionId, "route/status"), {
method: "POST",
body: JSON.stringify(originTxHash ? { originTxHash } : {}),
});
}
/** Subscription options for a recurring checkout on its current network. */
export function getSubscriptionOffer(sessionId: string): Promise<SubscriptionOffer> {
return request<SubscriptionOffer>(sessionPath(sessionId, "subscription"));
}
/** Save fields and create the subscription intent the wallet signs. */
export function startSubscription(
sessionId: string,
payload: { method: string; payer?: string; fields: Record<string, string> },
): Promise<StartSubscriptionResult> {
return request<StartSubscriptionResult>(sessionPath(sessionId, "subscription"), {
method: "POST",
body: JSON.stringify(payload),
});
}
/** Submit the signed grant; activates, charges period 1 and delivers access. */
export function completeSubscription(
sessionId: string,
payload: { subscriptionId: string; signature?: string; approveSignature?: string },
): Promise<CompleteSubscriptionResult> {
return request<CompleteSubscriptionResult>(sessionPath(sessionId, "subscription/grant"), {
method: "POST",
body: JSON.stringify(payload),
});
}
/** Buyer cancel from the manage page; returns the wallet revoke action. */
export function cancelManagedSubscription(token: string): Promise<CancelManagedResult> {
return request<CancelManagedResult>(`/api/subscriptions/${encodeURIComponent(token)}/cancel`, { method: "POST" });
}