Restart-safe x402 subscriptions in TypeScript

npm install --save-exact \
  @x402/[email protected] \
  @x402/[email protected] \
  @x402/[email protected] \
  [email protected] \
  @solana/[email protected]

import { x402Client } from "@x402/core/client";
import {
  decodePaymentRequiredHeader,
  decodePaymentResponseHeader,
  encodePaymentSignatureHeader,
} from "@x402/core/http";
import type {
  PaymentPayload,
  PaymentRequired,
  PaymentRequirements,
  SettleResponse,
} from "@x402/core/types";
import { ExactEvmScheme, type ClientEvmSigner } from "@x402/evm";
import { ExactSvmScheme, type ClientSvmSigner } from "@x402/svm";
 
const API_ORIGIN = "https://api.ambient.xyz";
const COMPLETION_URL = `${API_ORIGIN}/billing/x402/subscription-complete`;
 
const SOLANA = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
const SOLANA_USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
const SOLANA_RECIPIENT = "AYYo37bgztqAgP6wp2S9SiYWcijr8gz2o14c8RGWojJZ";
 
const BASE = "eip155:8453";
const BASE_USDC = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
const BASE_RECIPIENT = "0x6992c688c56be442efe1e1ce7d5c95212ed7d59b";
 
type Network = typeof SOLANA | typeof BASE;
type TrustedOffer = PaymentRequirements & { network: Network };
type PlanId = "starter" | "basic" | "power" | "pro";
type Stage =
  | "registered"
  | "approved"
  | "authorized"
  | "attempted"
  | "granted"
  | "completed"
  | "ambiguous";
 
type PaymentOrder = {
  kind: "registration" | "renewal";
  orderId: string;
  planId: PlanId;
  months: number;
  paymentUrl: string;
  bootstrap?: {
    apiKey: string;
    orderExpiresAt: string;
  };
};
 
type Approval = {
  orderId: string;
  planId: PlanId;
  months: number;
  resourceUrl: string;
  scheme: "exact";
  network: Network;
  asset: string;
  recipient: string;
  amountMicroUsdc: string;
  expectedPayer: string;
  approvedAt: string;
};
 
type PaidResponse = {
  status: number;
  headers: Record<string, string>;
  paymentResponse?: string;
  grantToken?: string;
  grantSignature?: string;
  body?: string;
};
 
type Completion = {
  team_id: string;
  plan_id: PlanId;
  months: number;
  current_period_end: string;
  already_completed: boolean;
};
 
type OrderState = {
  stage: Stage;
  order: PaymentOrder;
  paymentRequiredHeader?: string;
  paymentRequired?: PaymentRequired;
  selectedOffer?: PaymentRequirements;
  approval?: Approval;
  paymentPayload?: PaymentPayload;
  paymentSignature?: string;
  transmissionAttemptedAt?: string;
  paidResponse?: PaidResponse;
  settlementReceipt?: SettleResponse;
  completion?: Completion;
  ambiguityReason?: string;
};
 
type StoredState = { revision: number; value: OrderState };
 
interface DurableOrderStore {
  // This lock must exclude writers in every process, not only this Node process.
  withExclusiveLock<T>(orderId: string, fn: () => Promise<T>): Promise<T>;
  read(orderId: string): Promise<StoredState>;
  // Atomically commits and returns the new revision, or throws on a mismatch.
  compareAndSwap(
    orderId: string,
    expectedRevision: number,
    next: OrderState,
  ): Promise<StoredState>;
}
 
type WalletChoice =
  | { network: typeof BASE; signer: ClientEvmSigner }
  | { network: typeof SOLANA; signer: ClientSvmSigner };
 
function assertOrderIdentity(orderId: string, state: OrderState): void {
  if (state.order.orderId !== orderId) {
    throw new Error("Loaded state belongs to a different order");
  }
}

type Preview = {
  paymentRequiredHeader: string;
  paymentRequired: PaymentRequired;
  selectedOffer: TrustedOffer;
};
 
function positiveAmount(value: unknown): bigint {
  if (typeof value !== "string" || !/^[1-9][0-9]*$/.test(value)) {
    throw new Error("Amount must be a canonical positive decimal integer");
  }
  return BigInt(value);
}
 
function formatMicroUsdc(amount: bigint): string {
  const whole = amount / 1_000_000n;
  const fraction = (amount % 1_000_000n)
    .toString()
    .padStart(6, "0")
    .replace(/0+$/, "");
  return fraction ? `${whole}.${fraction}` : whole.toString();
}
 
function canonicalIdentifier(network: Network, value: string): string {
  const trimmed = value.trim();
  if (!trimmed) throw new Error("Identifier is empty");
  return network === BASE ? trimmed.toLowerCase() : trimmed;
}
 
function isTrustedOffer(offer: PaymentRequirements): offer is TrustedOffer {
  if (offer.scheme !== "exact") return false;
 
  if (offer.network === SOLANA) {
    return offer.asset === SOLANA_USDC && offer.payTo === SOLANA_RECIPIENT;
  }
 
  if (offer.network === BASE) {
    return (
      offer.asset.toLowerCase() === BASE_USDC &&
      offer.payTo.toLowerCase() === BASE_RECIPIENT &&
      offer.extra.assetTransferMethod === "eip3009" &&
      offer.extra.name === "USD Coin" &&
      offer.extra.version === "2" &&
      Number.isInteger(offer.maxTimeoutSeconds) &&
      offer.maxTimeoutSeconds > 0 &&
      offer.maxTimeoutSeconds <= 300
    );
  }
 
  return false;
}
 
function selectTrustedOffer(
  required: PaymentRequired,
  paymentUrl: string,
  preferredNetwork: Network,
): TrustedOffer {
  if (required.x402Version !== 2) throw new Error("Expected x402 v2");
  if (required.resource?.url !== paymentUrl) {
    throw new Error("Challenge resource differs from the saved payment URL");
  }
 
  const amounts = new Set(
    required.accepts.map((offer) => positiveAmount(offer.amount).toString()),
  );
  if (amounts.size !== 1) throw new Error("Offered rails disagree on amount");
 
  const offer = required.accepts
    .filter(isTrustedOffer)
    .find((candidate) => candidate.network === preferredNetwork);
  if (!offer) throw new Error("No trusted offer for the selected network");
  return offer;
}
 
async function previewPayment(
  paymentUrl: string,
  preferredNetwork: Network,
): Promise<Preview> {
  const response = await fetch(paymentUrl, {
    method: "POST",
    redirect: "manual",
  });
  if (response.status !== 402) {
    throw new Error(`Expected unsigned 402, received ${response.status}`);
  }
 
  const header = response.headers.get("Payment-Required");
  if (!header) throw new Error("Payment-Required header is missing");
  const paymentRequired = decodePaymentRequiredHeader(header);
  const selectedOffer = selectTrustedOffer(
    paymentRequired,
    paymentUrl,
    preferredNetwork,
  );
  return {
    paymentRequiredHeader: header,
    paymentRequired,
    selectedOffer,
  };
}
 
async function saveApproval(
  store: DurableOrderStore,
  orderId: string,
  preview: Preview,
  wallet: WalletChoice,
  maximumMicroUsdc: bigint,
): Promise<OrderState> {
  return store.withExclusiveLock(orderId, async () => {
    const stored = await store.read(orderId);
    const state = stored.value;
    assertOrderIdentity(orderId, state);
    if (state.paymentSignature || state.transmissionAttemptedAt) {
      throw new Error("An authorization already exists for this order");
    }
    if (state.stage !== "registered" && state.stage !== "approved") {
      throw new Error(`Cannot approve an order in stage ${state.stage}`);
    }
 
    const offer = selectTrustedOffer(
      preview.paymentRequired,
      state.order.paymentUrl,
      preview.selectedOffer.network,
    );
    const amount = positiveAmount(offer.amount);
    if (amount > maximumMicroUsdc) {
      throw new Error(`Charge ${formatMicroUsdc(amount)} USDC exceeds approval`);
    }
    if (wallet.network !== offer.network) {
      throw new Error("Wallet network differs from the selected offer");
    }
 
    const approval: Approval = {
      orderId: state.order.orderId,
      planId: state.order.planId,
      months: state.order.months,
      resourceUrl: state.order.paymentUrl,
      scheme: "exact",
      network: offer.network,
      asset: canonicalIdentifier(offer.network, offer.asset),
      recipient: canonicalIdentifier(offer.network, offer.payTo),
      amountMicroUsdc: amount.toString(),
      expectedPayer: canonicalIdentifier(
        offer.network,
        wallet.signer.address,
      ),
      approvedAt: new Date().toISOString(),
    };
    const committed = await store.compareAndSwap(orderId, stored.revision, {
      ...state,
      stage: "approved",
      paymentRequiredHeader: preview.paymentRequiredHeader,
      paymentRequired: preview.paymentRequired,
      selectedOffer: offer,
      approval,
    });
    return committed.value;
  });
}

function offerMatchesApproval(
  offer: PaymentRequirements,
  approval: Approval,
): boolean {
  if (!isTrustedOffer(offer) || offer.network !== approval.network) return false;
  return (
    offer.scheme === approval.scheme &&
    canonicalIdentifier(approval.network, offer.asset) === approval.asset &&
    canonicalIdentifier(approval.network, offer.payTo) === approval.recipient &&
    positiveAmount(offer.amount).toString() === approval.amountMicroUsdc
  );
}
 
async function createSavedAuthorization(
  store: DurableOrderStore,
  orderId: string,
  wallet: WalletChoice,
): Promise<OrderState> {
  return store.withExclusiveLock(orderId, async () => {
    const stored = await store.read(orderId);
    const state = stored.value;
    assertOrderIdentity(orderId, state);
    if (state.paymentSignature) return state;
    if (
      state.stage !== "approved" ||
      !state.paymentRequired ||
      !state.selectedOffer ||
      !state.approval
    ) {
      throw new Error("Order does not have a durable approved offer");
    }
    const approval = state.approval;
    const paymentRequired = state.paymentRequired;
    if (
      approval.orderId !== state.order.orderId ||
      approval.planId !== state.order.planId ||
      approval.months !== state.order.months ||
      approval.resourceUrl !== state.order.paymentUrl
    ) {
      throw new Error("Approved terms differ from the saved order");
    }
    if (wallet.network !== approval.network) {
      throw new Error("Wallet network differs from the approved network");
    }
    if (
      canonicalIdentifier(wallet.network, wallet.signer.address) !==
      approval.expectedPayer
    ) {
      throw new Error("Wallet payer differs from the approved payer");
    }
 
    const client = new x402Client((_version, offers) => {
      const selected = offers.find((offer) =>
        offerMatchesApproval(offer, approval),
      );
      if (!selected) throw new Error("Approved offer is no longer selectable");
      return selected;
    });
    if (wallet.network === BASE) {
      client.register(BASE, new ExactEvmScheme(wallet.signer));
    } else {
      client.register(SOLANA, new ExactSvmScheme(wallet.signer));
    }
 
    let saved: OrderState | undefined;
    client.onAfterPaymentCreation(async ({ paymentPayload }) => {
      const committed = await store.compareAndSwap(orderId, stored.revision, {
        ...state,
        stage: "authorized",
        paymentPayload,
        paymentSignature: encodePaymentSignatureHeader(paymentPayload),
      });
      saved = committed.value;
    });
 
    await client.createPaymentPayload(paymentRequired);
    if (!saved?.paymentSignature) {
      throw new Error("Authorization was not durably saved");
    }
    return saved;
  });
}

function validateReceipt(state: OrderState): SettleResponse {
  const raw = state.paidResponse?.paymentResponse;
  const approval = state.approval;
  if (!raw || !approval) throw new Error("Settlement receipt is missing");
 
  const receipt = decodePaymentResponseHeader(raw);
  if (receipt.success !== true) throw new Error("Settlement did not succeed");
  if (typeof receipt.network !== "string" || receipt.network !== approval.network) {
    throw new Error("Settlement network differs from approval");
  }
  if (typeof receipt.payer !== "string" || !receipt.payer.trim()) {
    throw new Error("Settlement payer is missing");
  }
  if (typeof receipt.transaction !== "string" || !receipt.transaction.trim()) {
    throw new Error("Settlement transaction is missing");
  }
  if (
    canonicalIdentifier(approval.network, receipt.payer) !==
    approval.expectedPayer
  ) {
    throw new Error("Settlement payer differs from approval");
  }
  if (
    receipt.amount !== undefined &&
    positiveAmount(receipt.amount).toString() !== approval.amountMicroUsdc
  ) {
    throw new Error("Settlement amount differs from approval");
  }
  return receipt;
}
 
function validateSavedGrant(state: OrderState): SettleResponse {
  const receipt = validateReceipt(state);
  if (
    state.paidResponse?.status !== 200 ||
    !state.paidResponse.grantToken ||
    !state.paidResponse.grantSignature
  ) {
    throw new Error("Successful receipt or Ambient grant is incomplete");
  }
  return receipt;
}
 
async function recoverSavedGrant(
  store: DurableOrderStore,
  orderId: string,
): Promise<OrderState> {
  return store.withExclusiveLock(orderId, async () => {
    const stored = await store.read(orderId);
    const state = stored.value;
    assertOrderIdentity(orderId, state);
    if (state.stage === "granted" || state.stage === "completed") return state;
    if (state.stage !== "attempted" || !state.paidResponse) {
      throw new Error("Order has no recoverable saved paid response");
    }
 
    const receipt = validateSavedGrant(state);
    const committed = await store.compareAndSwap(orderId, stored.revision, {
      ...state,
      stage: "granted",
      settlementReceipt: receipt,
    });
    return committed.value;
  });
}
 
async function transmitSavedAuthorization(
  store: DurableOrderStore,
  orderId: string,
): Promise<OrderState> {
  return store.withExclusiveLock(orderId, async () => {
    let stored = await store.read(orderId);
    let state = stored.value;
    assertOrderIdentity(orderId, state);
    if (state.stage === "granted" || state.stage === "completed") return state;
    if (state.stage !== "authorized" || !state.paymentSignature) {
      throw new Error(`Refusing transmission from stage ${state.stage}`);
    }
    const paymentSignature = state.paymentSignature;
 
    stored = await store.compareAndSwap(orderId, stored.revision, {
      ...state,
      stage: "attempted",
      transmissionAttemptedAt: new Date().toISOString(),
    });
    state = stored.value;
 
    let response: Response;
    try {
      response = await fetch(state.order.paymentUrl, {
        method: "POST",
        redirect: "manual",
        headers: { "Payment-Signature": paymentSignature },
        signal: AbortSignal.timeout(125_000),
      });
    } catch {
      const ambiguous = await store.compareAndSwap(orderId, stored.revision, {
        ...state,
        stage: "ambiguous",
        ambiguityReason: "Paid request ended without an HTTP response",
      });
      return ambiguous.value;
    }
 
    const paymentResponse =
      response.headers.get("Payment-Response") ??
      response.headers.get("X-Payment-Response") ??
      undefined;
    const snapshot: PaidResponse = {
      status: response.status,
      headers: Object.fromEntries(response.headers.entries()),
      paymentResponse,
      grantToken: response.headers.get("X-Ambient-X402-Grant") ?? undefined,
      grantSignature:
        response.headers.get("X-Ambient-X402-Grant-Signature") ?? undefined,
    };
    stored = await store.compareAndSwap(orderId, stored.revision, {
      ...state,
      paidResponse: snapshot,
    });
    state = stored.value;
 
    try {
      const body = await response.text();
      stored = await store.compareAndSwap(orderId, stored.revision, {
        ...state,
        paidResponse: { ...snapshot, body },
      });
      state = stored.value;
    } catch {
      // The receipt and grants are already durable; the body is non-authoritative.
    }
 
    try {
      const receipt = validateSavedGrant(state);
      const granted = await store.compareAndSwap(orderId, stored.revision, {
        ...state,
        stage: "granted",
        settlementReceipt: receipt,
      });
      return granted.value;
    } catch (error) {
      const ambiguous = await store.compareAndSwap(orderId, stored.revision, {
        ...state,
        stage: "ambiguous",
        ambiguityReason:
          error instanceof Error ? error.message : "Invalid paid response",
      });
      return ambiguous.value;
    }
  });
}

const sleep = (milliseconds: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
 
function parseCompletion(value: unknown, order: PaymentOrder): Completion {
  if (!value || typeof value !== "object") {
    throw new Error("Completion response is not an object");
  }
  const body = value as Record<string, unknown>;
  if (typeof body.team_id !== "string" || !body.team_id.trim()) {
    throw new Error("Completion team_id is missing");
  }
  if (body.plan_id !== order.planId || body.months !== order.months) {
    throw new Error("Completion does not match the saved order");
  }
  if (
    typeof body.current_period_end !== "string" ||
    Number.isNaN(Date.parse(body.current_period_end))
  ) {
    throw new Error("Completion current_period_end is invalid");
  }
  if (typeof body.already_completed !== "boolean") {
    throw new Error("Completion already_completed is invalid");
  }
  return body as Completion;
}
 
function retryableCompletionStatus(status: number): boolean {
  return status === 408 || status === 429 || status >= 500;
}
 
async function completeProvisioning(
  store: DurableOrderStore,
  orderId: string,
): Promise<OrderState> {
  return store.withExclusiveLock(orderId, async () => {
    let stored = await store.read(orderId);
    const state = stored.value;
    assertOrderIdentity(orderId, state);
    if (state.stage === "completed") return state;
    if (
      state.stage !== "granted" ||
      !state.paidResponse?.grantToken ||
      !state.paidResponse.grantSignature
    ) {
      throw new Error("Order does not have a saved grant");
    }
 
    const requestBody = JSON.stringify({
      grantToken: state.paidResponse.grantToken,
      signature: state.paidResponse.grantSignature,
    });
    const backoffs = [0, 250, 1_000] as const;
 
    for (let attempt = 0; attempt < backoffs.length; attempt += 1) {
      if (backoffs[attempt]) await sleep(backoffs[attempt]);
      let response: Response;
      try {
        response = await fetch(COMPLETION_URL, {
          method: "POST",
          redirect: "manual",
          headers: { "Content-Type": "application/json" },
          body: requestBody,
          signal: AbortSignal.timeout(10_000),
        });
      } catch {
        if (attempt + 1 < backoffs.length) continue;
        throw new Error("Completion not confirmed; retry this same grant later");
      }
 
      if (retryableCompletionStatus(response.status)) {
        if (attempt + 1 < backoffs.length) continue;
        throw new Error("Completion not confirmed; retry this same grant later");
      }
      if (!response.ok) {
        throw new Error(
          `Completion rejected with HTTP ${response.status}; reconcile without paying again`,
        );
      }
 
      let completion: Completion;
      try {
        completion = parseCompletion(await response.json(), state.order);
      } catch {
        if (attempt + 1 < backoffs.length) continue;
        throw new Error("Completion response invalid; retry this same grant later");
      }
      stored = await store.compareAndSwap(orderId, stored.revision, {
        ...state,
        stage: "completed",
        completion,
      });
      return stored.value;
    }
    throw new Error("Unreachable completion state");
  });
}