@mysten-incubation/suipay 0.0.0-stage → 0.2.0-dev.0

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @mysten-incubation/suipay
 
-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.
+Embeddable SuiPay client for app developers. Quote a 402 resource and pay it
+from a spend-account grant. This package does **not** bake hosted gateway URLs
+— pass `gatewayUrl` yourself.
+
+## 30-second quickstart
+
+```ts
+import { createClient } from '@mysten-incubation/suipay';
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+
+const keypair = Ed25519Keypair.fromSecretKey(/* 32-byte seed */);
+
+const client = await createClient({
+  gatewayUrl: process.env.SUIPAY_GATEWAY_URL!,
+  keypair,
+});
+
+const url = 'https://gateway.example/v1/image/generate';
+const result = await client.pay(url, {
+  json: { prompt: 'a small red circle' },
+});
+```
+
+`pay` quotes that POST, then pays the quoted price. You do not pass atomic
+units. `result.quote` is the price it agreed to, and `result.paid` says whether
+settlement finished.
+
+`createClient` throws if `gatewayUrl` or `keypair` is missing. The key must
+already have a live spend-account grant on that gateway. A body makes the
+request POST; a GET resource is `pay(url, { method: 'GET' })`. To show the
+price before spending, call `quote` first and pass it back:
+
+```ts
+const quote = await client.quote(url, { body: JSON.stringify({ prompt: '...' }) });
+const result = await client.pay(url, { quote });
+```
+
+Passing `quote` pins `payTo` and replays that quote's method, body, and
+content type. A later offer cannot swap the recipient or the coin. `maxAmount`
+can only tighten the quoted price, not raise it. A different body or content
+type is refused before anything is signed.
+
+## Errors — branch on `code`
+
+A caller mistake caught before anything is quoted or signed (a missing
+`gatewayUrl`, a URL off the gateway origin, `json` and `body` together) is
+**thrown** as a `SuiPayError`. A failed quote throws one too. Once a payment
+is attempted, `pay` **returns** the result instead: a failed or ambiguous
+`PayResult` carries `code`, `paymentState`, `retryable`, `nextAction`,
+`detail`, and `txDigest` / `paymentId` / `challengeId` when known.
+
+```ts
+import { SuiPayError, toErrorFields } from '@mysten-incubation/suipay';
+
+try {
+  const result = await client.pay(url, { json: { prompt: 'a small red circle' } });
+  if (result.status !== 'ok') {
+    // Money first: `paymentState` always agrees with `paid`.
+    if (result.paymentState !== 'not_charged') {
+      console.log('do not pay again; reconcile', result.paymentId);
+    } else if (result.retryable) {
+      console.log('safe to retry');
+    } else {
+      console.log(result.code, result.nextAction); // branch on code, never on detail
+    }
+  }
+} catch (err) {
+  const fields = err instanceof SuiPayError ? err : toErrorFields(err);
+  console.log(fields.code, fields.nextAction);
+}
+```
+
+`status` keeps its meaning: `failed` only when nothing was charged,
+`ambiguous` when money moved or may have. `ErrorCode`, `PaymentState` and
+`NextAction` are exported, so a `switch` over `ErrorCode` can be exhaustive.
+
+## Which package?
+
+| Install | Use it when |
+| --- | --- |
+| `@mysten-incubation/suipay` | An app needs `quote` + `pay` against a 402. This barrel. |
+| `@mysten-incubation/suipay-buyer` | You need the typed `/v1` control plane, connection manifests, or `createPayer` directly. |
+| `@mysten-incubation/suipay-mcp` | An MCP host (Claude, Codex, …) should log in, discover, and pay. |
+
+Sellers copy `apps/seller-template` (and `@suipay/seller-runtime` inside the
+repo). There is **no** published seller SDK.
+
+Do not publish or depend on `@cmdoss/suipay-core` or `@cmdoss/suipay-sdk`.
+Those stay private; this tarball bundles what it needs.
+
+## Build (this repo)
+
+```bash
+pnpm --filter @mysten-incubation/suipay test
+pnpm --filter @mysten-incubation/suipay build
+```
+
+Publishing is the `release-npm` workflow: merge to `dev` publishes
+`@mysten-incubation/suipay@<version>-dev.N` with dist-tag `dev` (OIDC, pack gate,
+provenance). `latest` is a gated dispatch from `main` (`dry_run` default
+true). Do not `npm publish` from a laptop. See
+[`docs/guide/npm-release.md`](../../docs/guide/npm-release.md).