@phala/pay 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `@phala/pay` are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-27
+
+### Added
+
+- `PhalaPay({ apiBase })`: `retrieveQuote(clientSecret)` reads a quote's public view
+  (`GET /v1/quotes/{id}?client_secret=…`) and `checkout(clientSecret)` follows it, exposing the
+  payer-facing status (also `createCheckout` and `retrieveQuote`).
+- `watchWallets` (EIP-6963, `window.ethereum` fallback) and `payWithWallet`: pay a quote's EIP-681
+  ERC-20 transfer from a browser wallet, switching or adding the chain.
+- `@phala/pay/react`: `<Checkout>` with wallet ("Pay with crypto", `buttonText`), QR code, and
+  manual payment, live status, and Stripe-style `appearance`; `useCheckout`.
+- `formatTokenAmount(quote, locale?)` shows the exact token amount grouped for the locale and
+  without trailing zeros (`1,273.9185`); `tokenAmount(quote)` is the plain decimal a wallet
+  accepts, which `<Checkout>`'s "Exact amount" copies.
+
+[unreleased]: https://github.com/Phala-Network/phala-pay/compare/sdk-js-v0.1.0...HEAD
+[0.1.0]: https://github.com/Phala-Network/phala-pay/releases/tag/sdk-js-v0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,142 @@
+# @phala/pay
+
+Browser checkout for Phala Pay: a framework-agnostic client for a quote's public
+view, and a React component that lets the payer pay from a browser wallet, by QR code, or manually,
+with live status. It is the browser half of the flow; your backend creates the quote with the
+Python SDK (`phala-pay`) and fulfils from the signed `deposit.credited` webhook.
+
+## Install
+
+```sh
+npm install @phala/pay viem
+```
+
+Peer dependencies: `viem` 2, and `react` 18 or 19 for `@phala/pay/react`. Nothing else:
+wallets are found with EIP-6963 (with a `window.ethereum` fallback), not wagmi or WalletConnect.
+
+Until the first npm release, install from the repository with pnpm. The package builds itself
+on install, which pnpm allows only for listed git dependencies: the first `pnpm add` stops and
+prints an `allowBuilds` entry naming the exact commit; add it to `pnpm-workspace.yaml` and run the
+same command again.
+
+```sh
+pnpm add "github:Phala-Network/phala-pay#main&path:/sdk/js"
+```
+
+```yaml
+# pnpm-workspace.yaml: the entry pnpm printed
+allowBuilds:
+  "@phala/pay@https://codeload.github.com/Phala-Network/phala-pay/tar.gz/<commit>#path:/sdk/js": true
+```
+
+## Quickstart
+
+1. Your backend creates a quote (`POST /v1/quotes`, signed with the product key) and returns only its
+   `client_secret` to the signed-in user's browser.
+2. Render the checkout with it:
+
+```tsx
+"use client";
+import { Checkout } from "@phala/pay/react";
+
+export function TopUp(props: { clientSecret: string; onPaid: () => void; onRetry: () => void }) {
+  return (
+    <Checkout
+      clientSecret={props.clientSecret}
+      apiBase="https://pay.example.com"
+      onSuccess={props.onPaid}
+      onExpire={props.onRetry}
+      buttonText="Pay with crypto"
+    />
+  );
+}
+```
+
+3. Credit the account when your webhook endpoint receives `deposit.credited`. `onSuccess` is for the
+   UI only: the browser is not a trusted source of payment.
+
+The component reads `GET /v1/quotes/{id}?client_secret=…` every three seconds. That endpoint is
+public (`Access-Control-Allow-Origin: *`) and shows only what the payer needs: the amount, the
+token, the chain, the deposit address, the EIP-681 payment request, the expiry, and the payment
+status. Keep the client secret out of logs and URLs you share; anyone holding it can see that view.
+
+### Statuses
+
+| `status` | Shown |
+|---|---|
+| `loading` | Loading payment details |
+| `waiting` | Payment options, the exact amount, and the time left |
+| `seen` | Payment in a block, with its confirmations (a reorg can still remove it) |
+| `confirming` | Payment final, being valued and screened |
+| `credited` | Credited; `onSuccess` is called once |
+| `rejected` | Final but will not be credited; the payer contacts support |
+| `expired`, `canceled` | The address is hidden; `onExpire` is called once |
+| `error` | The client secret is not valid |
+
+The payment options disappear once a payment is seen, and at `expires_at`. A payment of a different
+amount, or after expiry, is still credited, at the market price instead of the quote's.
+
+## Appearance
+
+```tsx
+<Checkout
+  clientSecret={clientSecret}
+  apiBase={apiBase}
+  appearance={{
+    theme: "dark",
+    variables: { colorPrimary: "#cdfa50", borderRadius: "12px", fontFamily: "Inter, sans-serif" },
+  }}
+/>
+```
+
+Variables: `colorPrimary`, `colorBackground`, `colorText`, `colorTextSecondary`, `colorBorder`,
+`colorDanger`, `colorSuccess`, `fontFamily`, `borderRadius`. Each is also a CSS custom property on
+`.pp-root` (`--pp-color-primary`, …), so a stylesheet can set them too.
+
+## Without React
+
+```ts
+import { PhalaPay, payWithWallet, watchWallets, type Wallet } from "@phala/pay";
+
+const pay = new PhalaPay({ apiBase: "https://pay.example.com" });
+const quote = await pay.retrieveQuote(clientSecret); // one read of the public view
+const checkout = pay.checkout(clientSecret); // or follow it until it settles
+const unsubscribe = checkout.subscribe(({ status, quote, error }) => render(status, quote, error));
+
+const stop = watchWallets((wallets) => showWalletButtons(wallets));
+
+async function onWalletClick(wallet: Wallet) {
+  const { quote } = checkout.getState();
+  if (quote !== null) {
+    // Resolves with the transaction hash once the wallet broadcast the transfer.
+    showTransaction(await payWithWallet(wallet.provider, quote));
+    await checkout.refresh();
+  }
+}
+
+// When leaving the page:
+stop();
+unsubscribe();
+checkout.destroy();
+```
+
+`payWithWallet` connects, switches the wallet to the quote's chain (adding Ethereum, Sepolia,
+Base, or Base Sepolia when the wallet lacks it), and sends the ERC-20 `transfer` stated by the
+quote's `payment_uri`, after checking that it pays exactly `amount_atomic` to `address`.
+
+## Development
+
+```sh
+pnpm install
+pnpm run check   # typecheck, lint, unit tests, build
+pnpm run e2e     # Playwright against Anvil; needs Foundry (anvil, forge) on PATH
+pnpm run e2e:docker  # the same, with Chromium from Playwright's image (as CI runs it)
+```
+
+The end-to-end tests start Anvil as Sepolia, deploy a test token, and pay a quote from a mocked
+EIP-6963 wallet backed by the node, then decode the QR code and exercise the manual details.
+
+## Releases
+
+A tag `sdk-js-v<version>` matching `package.json` publishes to npm from the `release` workflow
+with trusted publishing and provenance. See [CHANGELOG.md](CHANGELOG.md).

package/dist/chains.d.ts

@@ -0,0 +1,7 @@
+import type { Chain } from "viem";
+export declare function knownChain(chainId: number): Chain | undefined;
+/** A human name for the network, for example `Sepolia`. */
+export declare function networkName(chainId: number): string;
+/** The block explorer link for a transaction, when the chain is known. */
+export declare function transactionUrl(chainId: number, hash: string): string | undefined;
+//# sourceMappingURL=chains.d.ts.map

package/dist/chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAMlC,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAE7D;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhF"}

package/dist/chains.js

@@ -0,0 +1,16 @@
+import { base, baseSepolia, mainnet, sepolia } from "viem/chains";
+/** Chains a wallet can be asked to add; any other chain must already be in the wallet. */
+const CHAINS = [mainnet, sepolia, base, baseSepolia];
+export function knownChain(chainId) {
+    return CHAINS.find((chain) => chain.id === chainId);
+}
+/** A human name for the network, for example `Sepolia`. */
+export function networkName(chainId) {
+    return knownChain(chainId)?.name ?? `Chain ${chainId}`;
+}
+/** The block explorer link for a transaction, when the chain is known. */
+export function transactionUrl(chainId, hash) {
+    const explorer = knownChain(chainId)?.blockExplorers?.default.url;
+    return explorer === undefined ? undefined : `${explorer}/tx/${hash}`;
+}
+//# sourceMappingURL=chains.js.map

package/dist/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAElE,0FAA0F;AAC1F,MAAM,MAAM,GAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AAEvE,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,SAAS,OAAO,EAAE,CAAC;AACzD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,IAAY;IAC1D,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC;IAClE,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,OAAO,IAAI,EAAE,CAAC;AACvE,CAAC"}

package/dist/checkout.d.ts

@@ -0,0 +1,63 @@
+import { type ClientQuote } from "./quote.js";
+/**
+ * What the payer sees:
+ * - `loading` until the quote is first read;
+ * - `waiting` for a payment, until `expires_at`;
+ * - `seen` once a transfer is in a block, `confirming` once it is final and being valued;
+ * - `credited`, or `rejected` for a final payment that will not be credited;
+ * - `expired` or `canceled` without a payment;
+ * - `error` when the client secret is not valid.
+ */
+export type CheckoutStatus = "loading" | "waiting" | "seen" | "confirming" | "credited" | "rejected" | "expired" | "canceled" | "error";
+export type CheckoutErrorCode = "invalid_client_secret" | "rate_limited" | "network_error" | "invalid_response" | "api_error";
+export declare class CheckoutError extends Error {
+    readonly code: CheckoutErrorCode;
+    readonly name = "CheckoutError";
+    constructor(code: CheckoutErrorCode, message: string, options?: ErrorOptions);
+}
+export interface CheckoutState {
+    status: CheckoutStatus;
+    quote: ClientQuote | null;
+    /** The last failed refresh; polling continues after every error but `invalid_client_secret`. */
+    error: CheckoutError | null;
+}
+export interface CheckoutOptions {
+    /** The quote's `client_secret`, from your backend's `POST /v1/quotes`. */
+    clientSecret: string;
+    /** The service origin, for example `https://topup.example.com`. */
+    apiBase: string;
+    /** Milliseconds between status reads; default 3000. */
+    pollInterval?: number;
+    fetch?: typeof globalThis.fetch;
+    /** Current time in milliseconds; for tests. */
+    now?: () => number;
+}
+export interface CheckoutSession {
+    getState(): CheckoutState;
+    /** Calls `listener` on every state change; returns the unsubscribe function. */
+    subscribe(listener: (state: CheckoutState) => void): () => void;
+    /** Reads the quote now instead of at the next poll. */
+    refresh(): Promise<void>;
+    /** Stops polling. */
+    destroy(): void;
+}
+export interface RetrieveQuoteOptions {
+    clientSecret: string;
+    apiBase: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Reads a quote's public view once, as Stripe.js's `retrievePaymentIntent(clientSecret)` does.
+ * Rejects with a `CheckoutError`: `invalid_client_secret` for an unknown quote or secret.
+ */
+export declare function retrieveQuote(options: RetrieveQuoteOptions): Promise<ClientQuote>;
+/** The payer-facing status of a quote at `nowSeconds`. */
+export declare function checkoutStatus(quote: ClientQuote, nowSeconds: number): CheckoutStatus;
+/**
+ * Follows a quote from the browser by polling its public view until it is credited, rejected,
+ * canceled, or expired by the service. The status turns `expired` at `expires_at` even while the
+ * service, which expires quotes by chain time, still reports the quote open; polling continues
+ * until then, so a payment sent just before expiry still shows.
+ */
+export declare function createCheckout(options: CheckoutOptions): CheckoutSession;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6C,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,SAAS,GACT,MAAM,GACN,YAAY,GACZ,UAAU,GACV,UAAU,GACV,SAAS,GACT,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GACzB,uBAAuB,GACvB,cAAc,GACd,eAAe,GACf,kBAAkB,GAClB,WAAW,CAAC;AAEhB,qBAAa,aAAc,SAAQ,KAAK;IAIpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB;IAHlC,SAAkB,IAAI,mBAAmB;gBAG9B,IAAI,EAAE,iBAAiB,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAIzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,gGAAgG;IAChG,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,IAAI,aAAa,CAAC;IAC1B,gFAAgF;IAChF,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,qBAAqB;IACrB,OAAO,IAAI,IAAI,CAAC;CACjB;AAKD,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuBvF;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAWrF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAgGxE"}

package/dist/checkout.js

@@ -0,0 +1,146 @@
+import { parseClientQuote, quoteIdFromClientSecret } from "./quote.js";
+export class CheckoutError extends Error {
+    code;
+    name = "CheckoutError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+const DEFAULT_POLL_INTERVAL = 3000;
+const MAX_BACKOFF = 30_000;
+/**
+ * Reads a quote's public view once, as Stripe.js's `retrievePaymentIntent(clientSecret)` does.
+ * Rejects with a `CheckoutError`: `invalid_client_secret` for an unknown quote or secret.
+ */
+export async function retrieveQuote(options) {
+    const quoteId = quoteIdFromClientSecret(options.clientSecret);
+    const base = options.apiBase.replace(/\/+$/, "");
+    const url = `${base}/v1/quotes/${quoteId}?client_secret=${encodeURIComponent(options.clientSecret)}`;
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    // A simple GET with no custom headers, so the browser sends no CORS preflight.
+    const response = await fetchImpl(url, { cache: "no-store", credentials: "omit" });
+    if (response.status === 404) {
+        throw new CheckoutError("invalid_client_secret", "the quote or its client secret is unknown");
+    }
+    if (response.status === 429) {
+        throw new CheckoutError("rate_limited", "too many status requests");
+    }
+    if (!response.ok) {
+        throw new CheckoutError("api_error", `the payment service answered ${response.status}`);
+    }
+    try {
+        return parseClientQuote(await response.json());
+    }
+    catch (cause) {
+        throw new CheckoutError("invalid_response", "unexpected response from the payment service", {
+            cause,
+        });
+    }
+}
+/** The payer-facing status of a quote at `nowSeconds`. */
+export function checkoutStatus(quote, nowSeconds) {
+    if (quote.payment_status !== "none") {
+        return quote.payment_status;
+    }
+    if (quote.status === "canceled") {
+        return "canceled";
+    }
+    if (quote.status === "expired" || nowSeconds >= quote.expires_at) {
+        return "expired";
+    }
+    return quote.status === "open" ? "waiting" : "confirming";
+}
+/**
+ * Follows a quote from the browser by polling its public view until it is credited, rejected,
+ * canceled, or expired by the service. The status turns `expired` at `expires_at` even while the
+ * service, which expires quotes by chain time, still reports the quote open; polling continues
+ * until then, so a payment sent just before expiry still shows.
+ */
+export function createCheckout(options) {
+    quoteIdFromClientSecret(options.clientSecret);
+    const now = options.now ?? Date.now;
+    const interval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
+    const listeners = new Set();
+    let state = { status: "loading", quote: null, error: null };
+    let timer;
+    let failures = 0;
+    let destroyed = false;
+    let inFlight;
+    function setState(next) {
+        if (next.status === state.status &&
+            next.error === state.error &&
+            JSON.stringify(next.quote) === JSON.stringify(state.quote)) {
+            return;
+        }
+        state = next;
+        for (const listener of listeners) {
+            listener(state);
+        }
+    }
+    function finished() {
+        const { status, quote } = state;
+        return (destroyed ||
+            status === "error" ||
+            status === "credited" ||
+            status === "rejected" ||
+            status === "canceled" ||
+            (status === "expired" && quote?.status === "expired"));
+    }
+    async function load() {
+        try {
+            const quote = await retrieveQuote(options);
+            failures = 0;
+            setState({ status: checkoutStatus(quote, now() / 1000), quote, error: null });
+        }
+        catch (cause) {
+            const error = cause instanceof CheckoutError
+                ? cause
+                : new CheckoutError("network_error", "could not reach the payment service", { cause });
+            failures += 1;
+            const quote = state.quote;
+            if (error.code === "invalid_client_secret") {
+                setState({ status: "error", quote, error });
+            }
+            else {
+                setState({
+                    status: quote === null ? state.status : checkoutStatus(quote, now() / 1000),
+                    quote,
+                    error,
+                });
+            }
+        }
+    }
+    function refresh() {
+        inFlight ??= load().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    }
+    function schedule() {
+        if (finished()) {
+            return;
+        }
+        const delay = failures === 0 ? interval : Math.min(interval * 2 ** failures, MAX_BACKOFF);
+        timer = setTimeout(() => {
+            void refresh().then(schedule);
+        }, delay);
+    }
+    void refresh().then(schedule);
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        destroy() {
+            destroyed = true;
+            clearTimeout(timer);
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=checkout.js.map

package/dist/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { type CheckoutOptions, type CheckoutSession } from "./checkout.js";
+import type { ClientQuote } from "./quote.js";
+export interface PhalaPayOptions {
+    /** The service origin, for example `https://pay.example.com`. */
+    apiBase: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The browser client, in the shape of Stripe.js: it holds no key, only the service origin, and
+ * works with the `client_secret` your backend got from `POST /v1/quotes`.
+ *
+ *     const pay = new PhalaPay({ apiBase: "https://pay.example.com" });
+ *     const quote = await pay.retrieveQuote(clientSecret);
+ *     const session = pay.checkout(clientSecret);
+ *     session.subscribe(({ status }) => render(status));
+ */
+export declare class PhalaPay {
+    #private;
+    readonly apiBase: string;
+    constructor(options: PhalaPayOptions);
+    /** Reads the quote's public view once. */
+    retrieveQuote(clientSecret: string): Promise<ClientQuote>;
+    /** Follows the quote until it is credited, rejected, canceled, or expired. */
+    checkout(clientSecret: string, options?: Pick<CheckoutOptions, "pollInterval">): CheckoutSession;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGb,OAAO,EAAE,eAAe;IAKpC,0CAA0C;IAC1C,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAIzD,8EAA8E;IAC9E,QAAQ,CACN,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,cAAc,CAAM,GAClD,eAAe;CAYnB"}