@cmdoss/suipay 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @cmdoss/suipay
+
+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 '@cmdoss/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`, so a later offer cannot swap the recipient under
+the same cap. `pay` still refuses to sign more than that quote.
+
+## Which package?
+
+| Install | Use it when |
+| --- | --- |
+| `@cmdoss/suipay` | An app needs `quote` + `pay` against a 402. This barrel. |
+| `@cmdoss/suipay-buyer` | You need the typed `/v1` control plane, connection manifests, or `createPayer` directly. |
+| `@cmdoss/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 @cmdoss/suipay test
+pnpm --filter @cmdoss/suipay build
+```
+
+Publishing is the `release-npm` workflow: merge to `dev` publishes
+`@cmdoss/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).

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+
+/** Price a 402 resource advertised without settling it. */
+interface Quote {
+    amount: string;
+    asset: string;
+    resource: string;
+    network: string;
+    description: string;
+    expiresAt: number;
+    /** Recipient the offer pays. Pin this on `pay` so caps cannot stop substitution. */
+    payTo: string;
+    dialect: 'mpp' | 'x402';
+    decimals: number;
+    /** Method the probe used. `pay` replays it when the caller does not set one. */
+    method: 'GET' | 'POST';
+    /** Exact POST bytes the probe sent. Absent for GET. */
+    body?: string;
+}
+interface QuoteRequest {
+    /** HTTP method the resource is sold at. Defaults to POST, same as the shared pay-flow. */
+    method?: 'GET' | 'POST';
+    /** POST probe body. Ignored for GET. Defaults to `{}`. */
+    body?: string;
+}
+
+interface ClientOptions {
+    /** Gateway origin. Required; this package does not bake hosted URLs. */
+    gatewayUrl: string;
+    /** Delegate keypair that will sign spend-account payments. */
+    keypair: Ed25519Keypair;
+    /** Injectable fetch (tests / custom transports). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+interface PayRequest {
+    /**
+     * JSON object sent as `POST` `application/json`. This is the usual call.
+     * Do not also pass `body`.
+     */
+    json?: Record<string, unknown>;
+    body?: string | Uint8Array;
+    /**
+     * Only `Content-Type` is forwarded (the inner payer has no other header
+     * slot). Any other header throws rather than being dropped.
+     */
+    headers?: Record<string, string>;
+    maxAmount?: string;
+    asset?: string;
+    /**
+     * Defaults to POST when `json` or `body` is set, otherwise GET. A quote
+     * remembers the method it probed, and pay replays that when this is omitted.
+     */
+    method?: 'GET' | 'POST';
+    dialect?: Quote['dialect'];
+    /**
+     * Quote taken for this same URL. Supplies amount/asset/payTo/dialect when
+     * the caller omitted them, and pins `intent.recipient` to the quoted payTo.
+     * When omitted, `pay` quotes the same request first and uses that price as
+     * the ceiling, so a caller does not have to know atomic units.
+     */
+    quote?: Quote;
+}
+/** App-facing pay outcome. Defined here so published `.d.ts` does not name the private SDK. */
+interface PayResult {
+    status: 'ok' | 'failed' | 'ambiguous';
+    paid: boolean | 'unknown';
+    body?: unknown;
+    code?: string;
+    httpStatus?: number;
+    detail?: string;
+    txDigest?: string;
+    paymentId?: string;
+    /** The price this pay agreed to. Present when pay quoted, or when the caller passed one. */
+    quote?: Quote;
+    settlement?: {
+        status: 'success';
+        txDigest: string;
+        amount: string;
+        recipient: string;
+        coinType: string;
+        asset: string;
+    };
+}
+interface Client {
+    quote(url: string, request?: QuoteRequest): Promise<Quote>;
+    pay(url: string, input?: PayRequest): Promise<PayResult>;
+}
+/**
+ * Build a tiny quote/pay client from a gateway origin and a delegate key.
+ *
+ * Fail closed: missing `gatewayUrl` or `keypair` throws. The inner payer is
+ * `createPayer` over a spend-account grant; this barrel does not expose `/v1`.
+ */
+declare function createClient(options: ClientOptions): Promise<Client>;
+
+export { type Client, type ClientOptions, type PayRequest, type PayResult, type Quote, type QuoteRequest, createClient };