@apicity/cost 0.2.0-alpha.1 → 0.2.0

package/README.md

@@ -149,18 +149,22 @@ The cost package maintains a small, explicit **paid-endpoint registry**.
 Endpoints that are **not** in the registry are assumed free and require no
 caller changes.
 
-Paid endpoints require a **human-minted, single-request OTP** (one-time
-password). Autonomous callers cannot self-approve paid requests by passing
-a numeric `maxSpend` — they must present an OTP that was signed by an
-operator-held Ed25519 key.
+Paid endpoints require a **single-use OTP** (one-time password) minted from a
+shared **HMAC secret**. The gate is fail-closed and does **no** cost
+estimation — it is pure authorization: a paid call cannot fire unless the
+provider was constructed with the secret **and** the caller presents a valid,
+request-bound OTP. The autonomous caller never holds the secret, so it cannot
+self-approve; only the human or the code client that holds the secret can mint.
+
+There are **no environment variables and no key files** — the secret is passed
+in via factory options (or the MCP server's `--paygate-secret-file`).
 
 ### Registry model
 
 - `PAID_ENDPOINTS` is the canonical list. Every entry is an exact triple of
   `(provider, method, dotPath)` — there is no regex, prefix, wildcard, or
   inferred matching.
-- Unlisted endpoints are free. Free endpoints pass through without OTP or
-  pay gate configuration.
+- Unlisted endpoints are free and pass through without OTP or configuration.
 - Listed endpoints block unless a valid OTP is supplied.
 
 ### Token format
@@ -168,69 +172,80 @@ operator-held Ed25519 key.
 OTP tokens are a dependency-free compact envelope:
 
 ```
-<base64url(payloadJson)>.<base64url(signature)>
+<base64url(payloadJson)>.<base64url(HMAC-SHA256(payloadSegment, secret))>
 ```
 
-The payload JSON is canonicalized with sorted object keys before signing.
-Signature is Ed25519 over the exact base64url payload segment bytes.
-
-Payload schema:
+The signature is HMAC-SHA256 over the exact base64url payload segment bytes,
+verified in constant time. Payload schema:
 
 ```ts
 interface PayGateOtpPayload {
-  v: 1;                        // version
-  jti: string;                 // random 128-bit hex (unique token id)
-  provider: string;            // e.g. "kie"
-  method: string;              // e.g. "POST"
-  dotPath: string;             // e.g. "api.v1.jobs.createTask"
+  v: 1; // version
+  jti: string; // random 128-bit hex (unique token id)
+  provider: string; // e.g. "kie"
+  method: string; // e.g. "POST"
+  dotPath: string; // e.g. "api.v1.jobs.createTask"
   requestHash: `sha256:${string}`; // sha256 of canonical request JSON
-  maxSpendUsd: number;         // maximum allowed spend in USD
-  iat: number;                 // issued-at unix seconds
-  exp: number;                 // expiration unix seconds
+  iat: number; // issued-at unix seconds
+  exp: number; // expiration unix seconds
 }
 ```
 
-Request hash is `sha256:` + hex SHA-256 of the canonical JSON for the request
-payload. Object keys are sorted recursively; array order is preserved.
-Non-JSON payload values must fail closed.
+### Configuration
 
-### Key configuration
+The code client supplies a `PayGateConfig` via factory options:
 
-**Runtime (verification):**
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `APICITY_PAYGATE_PUBLIC_KEY_PATH` | Yes | Path to an Ed25519 public key PEM file. Without this, the pay gate is disabled and all paid endpoints throw `PayGateError`. |
+```ts
+interface PayGateConfig {
+  secret: string; // shared HMAC secret (the code client holds it)
+  replayStore?: ReplayStore; // defaults to an in-process Set, per provider instance
+  now?: () => number; // clock injection for tests; defaults to Date.now
+}
 
-**CLI (minting):**
+interface ReplayStore {
+  has(jti: string): boolean;
+  add(jti: string): void;
+}
+```
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `APICITY_PAYGATE_PRIVATE_KEY_PATH` | Yes | Path to an Ed25519 private key PEM file. Used by the `apicity-paygate` CLI to sign OTPs. |
+```ts
+import { createKie } from "@apicity/kie";
 
-### Request canonicalization
+const provider = createKie({
+  apiKey: process.env.KIE_API_KEY!,
+  paygate: { secret: loadSecret() }, // from your secret manager / config
+});
+```
 
-Before hashing, the request payload is canonicalized:
+### Minting OTPs
 
-1. Serialize to JSON with **sorted object keys** (recursive).
-2. Preserve array order exactly.
-3. Reject non-JSON values (functions, undefined, circular references, etc.).
+`mintOtp` is pure and env-free — the secret is passed explicitly and the OTP
+binds to the exact request via its canonical hash:
 
-The canonical JSON string is then SHA-256 hashed, and the hash is prefixed
-with `sha256:` in the OTP payload.
+```ts
+import { mintOtp } from "@apicity/cost";
 
-### Replay ledger
+const otp = mintOtp(secret, {
+  dotPath: "api.v1.jobs.createTask", // provider/method resolved from the registry
+  request: payload, // bound by canonical hash
+  ttl: "10m", // seconds or "10m" / "1h" / "1d"; defaults to 10m
+});
+```
 
-Consumed OTPs are recorded immediately before dispatch to prevent replay
-attacks. The default ledger path:
+### Request canonicalization
 
-- `$XDG_STATE_HOME/apicity/paygate-used.jsonl`
-- Fallback: `~/.local/state/apicity/paygate-used.jsonl`
+Before hashing, the request payload is canonicalized: serialized to JSON with
+**sorted object keys** (recursive), preserving array order, rejecting non-JSON
+values (functions, undefined, circular references). The canonical string is
+SHA-256 hashed and prefixed with `sha256:`. Change any byte of the request and
+verification fails.
 
-Each line is a JSON object: `{ "jti": "...", "consumedAt": 1234567890 }`.
+### Replay protection
 
-If dispatch later fails (network error, upstream 500, etc.), the OTP remains
-consumed. The operator must mint a new OTP for retry.
+Each OTP `jti` is single-use. The default `ReplayStore` is an in-process Set
+scoped to one provider instance (no files, no `XDG_STATE_HOME`). Pass a custom
+`replayStore` for cross-process or persistent protection. The `jti` is consumed
+**before** dispatch — see [Retry semantics](#retry-semantics).
 
 ### Public interface
 
@@ -245,153 +260,135 @@ async function dispatchWithPaidGate<T>(
   dotPath: string,
   payload: Record<string, unknown>,
   approval: PayGateApproval | undefined,
-  dispatch: () => Promise<T>
+  dispatch: () => Promise<T>,
+  config?: PayGateConfig
 ): Promise<T>;
 ```
 
-Paid endpoint APIs pass the approval as an options object:
+Paid endpoint APIs accept the approval as a second options object:
 
 ```ts
-import { kie } from "@apicity/kie";
-
-const provider = kie({ apiKey: process.env.KIE_API_KEY! });
-
 const task = await provider.post.api.v1.jobs.createTask(
-  {
-    model: "kling-3.0/video",
-    input: { prompt: "...", duration: "5", aspect_ratio: "16:9" },
-  },
-  { otp: "eyJ2IjoxLCJqdGkiOi4uLn0.uK2J9..." }
+  { model: "kling-3.0/video", input: { prompt: "...", duration: "5" } },
+  { otp }
 );
 ```
 
 ### Guard behavior
 
-1. **Preflight** — before any network dispatch, `dispatchWithPaidGate` checks
-   whether the endpoint is paid. If the runtime lacks
-   `APICITY_PAYGATE_PUBLIC_KEY_PATH`, the call throws `PayGateError`.
-2. **OTP presence** — paid endpoints require `approval.otp`. If omitted, the
-   call throws `PayGateError`.
-3. **Signature verification** — the OTP payload segment is verified against
-   the Ed25519 public key. If the signature is invalid or forged, the call
-   throws `PayGateError`.
-4. **Expiration** — if `exp` is in the past, the call throws `PayGateError`.
-5. **Request binding** — the OTP `provider`, `method`, `dotPath`, and
-   `requestHash` must match the actual call. Any mismatch throws
-   `PayGateError`.
-6. **Replay check** — if the OTP `jti` already exists in the ledger, the call
-   throws `PayGateError`.
-7. **Estimate** — the package computes a local cost estimate from the payload.
-8. **Bound check** — if the estimate exceeds `maxSpendUsd`, or if the cost
-   cannot be estimated (unknown model, missing fields), the call throws
-   `SpendBoundError`.
-9. **Consume** — the `jti` is appended to the replay ledger.
-10. **Dispatch** — only when all checks pass does the actual HTTP request fire.
+1. **Preflight** — if the endpoint is not in `PAID_ENDPOINTS`, dispatch runs
+   immediately.
+2. **Configuration** — a paid endpoint with no `paygate.secret` throws
+   `PayGateError` (`paygate-not-configured`).
+3. **OTP presence** — paid endpoints require `approval.otp`; if omitted the call
+   throws `PayGateError` (`otp-missing`).
+4. **Signature** — the payload segment's HMAC is verified (constant-time)
+   against the secret; mismatch throws `PayGateError` (`otp-invalid-signature`).
+5. **Expiration** — `exp` in the past throws `PayGateError` (`otp-expired`).
+6. **Request binding** — `provider`, `method`, `dotPath`, and `requestHash` must
+   match the actual call, else `PayGateError` (`otp-mismatched-request`).
+7. **Replay check** — a `jti` already in the store throws `PayGateError`
+   (`otp-replayed`).
+8. **Consume + dispatch** — the `jti` is recorded, then the HTTP request fires.
 
 ```ts
-import { PayGateError, SpendBoundError } from "@apicity/cost";
+import { PayGateError } from "@apicity/cost";
 
 try {
-  await provider.post.api.v1.jobs.createTask({ ... }, { otp: "..." });
+  await provider.post.api.v1.jobs.createTask({ ... }, { otp });
 } catch (e) {
   if (e instanceof PayGateError) {
-    // OTP missing, invalid, expired, replayed, or mismatched request
-  }
-  if (e instanceof SpendBoundError) {
-    // estimated cost > maxSpendUsd, or cost could not be computed
-  }
+    // e.code: paygate-not-configured | otp-missing | otp-malformed
+    //         | otp-invalid-signature | otp-expired
+    //         | otp-mismatched-request | otp-replayed
+  } else throw e;
 }
 ```
 
 ### Failure modes
 
-| Condition | Error | Notes |
-|-----------|-------|-------|
-| No `APICITY_PAYGATE_PUBLIC_KEY_PATH` | `PayGateError` | Pay gate is not configured |
-| Paid endpoint without OTP | `PayGateError` | Caller must pass `approval.otp` |
-| Invalid signature | `PayGateError` | OTP was not signed by the correct key |
-| Expired OTP (`exp` < now) | `PayGateError` | Operator must mint a fresh OTP |
-| Replayed OTP (`jti` in ledger) | `PayGateError` | Each OTP is single-use |
-| Mismatched provider/method/dotPath | `PayGateError` | OTP is bound to a specific call |
-| Mismatched request hash | `PayGateError` | Payload must match exactly |
-| Estimate > `maxSpendUsd` | `SpendBoundError` | Request is too expensive |
-| Unestimable cost | `SpendBoundError` | Unknown model or missing fields |
+| Condition                          | `PayGateError.code`      |
+| ---------------------------------- | ------------------------ |
+| Provider built without a secret    | `paygate-not-configured` |
+| Paid endpoint without OTP          | `otp-missing`            |
+| Malformed envelope                 | `otp-malformed`          |
+| Invalid HMAC signature             | `otp-invalid-signature`  |
+| Expired OTP (`exp` < now)          | `otp-expired`            |
+| Mismatched provider/method/dotPath | `otp-mismatched-request` |
+| Mismatched request hash            | `otp-mismatched-request` |
+| Replayed OTP (`jti` seen)          | `otp-replayed`           |
 
 ### CLI: minting OTPs
 
-The `apicity-paygate` binary from `@apicity/cost` mints operator-signed OTPs:
+The `apicity-paygate` binary mints OTPs. The secret is read from a **file**
+(never an env var); only the OTP is printed to stdout:
 
 ```bash
-# Mint an OTP for a specific request
 apicity-paygate otp mint \
-  --provider kie \
-  --method POST \
+  --secret-file ./paygate.secret \
   --dot-path api.v1.jobs.createTask \
   --payload-file request.json \
-  --max-spend 5 \
   --ttl 10m
 ```
 
-The CLI requires `APICITY_PAYGATE_PRIVATE_KEY_PATH` and prints only the OTP
-to stdout on success.
+### Wiring the gate into a provider
 
-### Migration from `maxSpend`
+Providers apply the gate once at the bottom of their factory using
+`withPaidGate`. The walker descends the HTTP-method roots (`post`, `get`,
+`delete`, `patch`, `put`) and routes every leaf whose `(provider, method,
+dotPath)` is in `PAID_ENDPOINTS` through `dispatchWithPaidGate`. Free leaves
+pass through unchanged; sub-providers, schema records, and other non-route
+properties are returned by reference. The config is passed once and shared
+(one replay store per provider instance):
 
-The previous numeric `maxSpend` parameter is **deprecated**. It allowed
-autonomous callers to self-approve by passing any positive number, which is
-not a true authority boundary.
+```ts
+import { withPaidGate } from "@apicity/cost";
+
+export function createKie(opts: KieOptions): KieProvider {
+  // ...build endpoint functions...
+  return withPaidGate(
+    "kie",
+    {
+      veo: createVeoProvider(...),     // sub-provider, untouched
+      modelInputSchemas,               // data, untouched
+      post: { api: { v1: { jobs: { createTask: Object.assign(createTask, { schema }) } } } },
+      get:  { api: { v1: { jobs: { recordInfo } } } },
+    },
+    { config: opts.paygate }
+  );
+}
+```
 
-Migration path:
+The gate is generic — `xai` and other providers opt in simply by adding a
+`PAID_ENDPOINTS` entry and threading `{ config: opts.paygate }` through their
+factory.
 
-1. **Operator** generates an Ed25519 key pair:
-   ```bash
-   openssl genpkey -algorithm Ed25519 -out paygate-private.pem
-   openssl pkey -in paygate-private.pem -pubout -out paygate-public.pem
-   ```
-2. **Runtime** sets `APICITY_PAYGATE_PUBLIC_KEY_PATH` to the public key.
-3. **Operator** mints OTPs before each paid call using the CLI or a custom
-   tool that signs the same payload format.
-4. **Caller** passes `{ otp }` instead of a numeric `maxSpend`:
-   ```ts
-   // Before (deprecated)
-   await provider.post.api.v1.jobs.createTask({ ... }, 5);
+### Retry semantics
 
-   // After
-   await provider.post.api.v1.jobs.createTask({ ... }, { otp: "..." });
-   ```
+The OTP `jti` is consumed **before** `dispatch()` runs. If dispatch later fails
+(network error, upstream 5xx, abort), the `jti` stays consumed and the caller
+must mint a fresh OTP to retry. This is intentional — without it, a hostile
+caller could replay a single OTP on every transient failure. Treat each OTP as
+single-use authority for one network attempt.
 
-The old `maxSpendPreflight`, `MaxSpendError`, and `dispatchWithPaidGuard`
-interfaces are retained during the transition but will be removed in a
-future major version.
+### MCP server
+
+The `@apicity/mcp-server` is the code client: start it with
+`--paygate-secret-file <path>` and it holds the secret to **verify** OTPs (it
+never mints). A human mints an OTP out-of-band (same secret) and the caller
+passes it as the paid tool's `otp` argument — so an AI driving the tool cannot
+self-approve.
 
 ### Minimal operator workflow
 
-1. **Set up keys** (one-time):
-   ```bash
-   export APICITY_PAYGATE_PRIVATE_KEY_PATH=./paygate-private.pem
-   export APICITY_PAYGATE_PUBLIC_KEY_PATH=./paygate-public.pem
-   ```
-2. **Prepare a request**:
-   ```bash
-   cat > request.json << 'EOF'
-   {
-     "model": "kling-3.0/video",
-     "input": {
-       "prompt": "A cat playing piano",
-       "duration": "5",
-       "aspect_ratio": "16:9"
-     }
-   }
-   EOF
-   ```
+1. **Generate a secret** (one-time) and store it (secret manager / file).
+2. **Prepare a request** JSON file.
 3. **Mint an OTP**:
    ```bash
    apicity-paygate otp mint \
-     --provider kie \
-     --method POST \
+     --secret-file ./paygate.secret \
      --dot-path api.v1.jobs.createTask \
      --payload-file request.json \
-     --max-spend 5 \
      --ttl 10m
    ```
 4. **Pass the OTP to the caller** (copy-paste, secrets manager, etc.).

package/dist/src/cost.d.ts

@@ -1,3 +1,3 @@
 import type { CostProvider } from "./types";
-export declare function cost(): CostProvider;
+export declare function createCost(): CostProvider;
 //# sourceMappingURL=cost.d.ts.map

package/dist/src/cost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/cost.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,SAAS,CAAC;AAE7D,wBAAgB,IAAI,IAAI,YAAY,CAInC"}
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/cost.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,SAAS,CAAC;AAE7D,wBAAgB,UAAU,IAAI,YAAY,CAIzC"}

package/dist/src/cost.js

@@ -1,5 +1,5 @@
 import { computeEstimate } from "./compute.js";
-export function cost() {
+export function createCost() {
     return {
         estimate: (req) => computeEstimate(req),
     };

package/dist/src/cost.js.map

@@ -1 +1 @@
-{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,MAAM,UAAU,IAAI;IAClB,OAAO;QACL,QAAQ,EAAE,CAAC,GAAoB,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC;KACzD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,QAAQ,EAAE,CAAC,GAAoB,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export { cost } from "./cost";
+export { createCost } from "./cost";
 export { computeEstimate } from "./compute";
 export { PRICING, PRICING_AS_OF } from "./pricing/index";
 export { MODEL_SLUGS, MODEL_DISPLAY, modelSlug, modelDisplay } from "./slugs";
@@ -6,8 +6,10 @@ export type { SlugProviderId, SlugModelId } from "./slugs";
 export type { CostUnit, ModelPricing, PerUnitPricing, PricedProviderId, RateSource, TokenPricing, } from "./pricing/index";
 export type { CostBreakdown, CostEstimate, CostProvider, CostSource, EstimateRequest, } from "./types";
 export type { ExtractResult, TextExtract } from "./extract/types";
-export { PAID_ENDPOINTS, lookupPaidEndpoint, isPaidEndpoint, maxSpendPreflight, MaxSpendError, SpendBoundError, spendBoundCheck, dispatchWithPaidGuard, } from "./paid-endpoints";
+export { PAID_ENDPOINTS, lookupPaidEndpoint, isPaidEndpoint, } from "./paid-endpoints";
 export type { PaidEndpointKey, PaidEndpointInfo, PaidEndpointEntry, } from "./paid-endpoints";
-export { PayGateError, PayGateApproval, dispatchWithPaidGate, canonicalizeJson, canonicalHash, parseOtp, verifyOtpSignature, isJtiConsumed, consumeJti, } from "./paygate";
-export type { PayGateOtpPayload } from "./paygate";
+export { PayGateError, dispatchWithPaidGate, mintOtp, createReplayStore, canonicalizeJson, canonicalHash, parseOtp, parseTtl, verifyOtp, } from "./paygate";
+export type { PayGateApproval, PayGateConfig, ReplayStore, OtpCall, PayGateOtpPayload, VerifyFailureCode, VerifyOtpInput, VerifyResult, } from "./paygate";
+export { withPaidGate } from "./with-paid-gate";
+export type { WithPaidGateOptions } from "./with-paid-gate";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC9E,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3D,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,eAAe,EACf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC9E,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3D,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,OAAO,EACP,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,YAAY,GACb,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/index.js

@@ -1,7 +1,8 @@
-export { cost } from "./cost.js";
+export { createCost } from "./cost.js";
 export { computeEstimate } from "./compute.js";
 export { PRICING, PRICING_AS_OF } from "./pricing/index.js";
 export { MODEL_SLUGS, MODEL_DISPLAY, modelSlug, modelDisplay } from "./slugs.js";
-export { PAID_ENDPOINTS, lookupPaidEndpoint, isPaidEndpoint, maxSpendPreflight, MaxSpendError, SpendBoundError, spendBoundCheck, dispatchWithPaidGuard, } from "./paid-endpoints.js";
-export { PayGateError, dispatchWithPaidGate, canonicalizeJson, canonicalHash, parseOtp, verifyOtpSignature, isJtiConsumed, consumeJti, } from "./paygate.js";
+export { PAID_ENDPOINTS, lookupPaidEndpoint, isPaidEndpoint, } from "./paid-endpoints.js";
+export { PayGateError, dispatchWithPaidGate, mintOtp, createReplayStore, canonicalizeJson, canonicalHash, parseOtp, parseTtl, verifyOtp, } from "./paygate.js";
+export { withPaidGate } from "./with-paid-gate.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsB9E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,eAAe,EACf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,EACL,YAAY,EAEZ,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,UAAU,GACX,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsB9E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAO1B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,SAAS,GACV,MAAM,WAAW,CAAC;AAYnB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/paid-endpoints.d.ts

@@ -43,68 +43,4 @@ export declare function lookupPaidEndpoint(provider: string, method: string, dot
  * Unlisted endpoints return `false` (assumed free).
  */
 export declare function isPaidEndpoint(provider: string, method: string, dotPath: string): boolean;
-/**
- * Error thrown when a paid endpoint is called without an explicit maxSpend.
- */
-export declare class MaxSpendError extends Error {
-    readonly provider: string;
-    readonly method: string;
-    readonly dotPath: string;
-    readonly maxSpend: number;
-    constructor(provider: string, method: string, dotPath: string, maxSpend: number);
-}
-/**
- * Error thrown when the estimated cost of a paid endpoint exceeds the
- * caller's maxSpend or when the cost cannot be safely estimated.
- */
-export declare class SpendBoundError extends Error {
-    readonly provider: string;
-    readonly method: string;
-    readonly dotPath: string;
-    readonly maxSpend: number;
-    readonly estimatedUsd: number;
-    constructor(provider: string, method: string, dotPath: string, maxSpend: number, estimatedUsd: number, message?: string);
-}
-/**
- * Preflight check for paid endpoints.
- *
- * For paid endpoints, maxSpend defaults to 0 when omitted. maxSpend=0 blocks
- * before the network request with a MaxSpendError. maxSpend>0 authorizes the
- * call to proceed.
- *
- * Free/unlisted endpoints are always allowed regardless of maxSpend.
- */
-export declare function maxSpendPreflight(provider: string, method: string, dotPath: string, maxSpend?: number): void;
-/**
- * Verify that a cost estimate is within the caller's maxSpend.
- *
- * If the estimate has warnings (could not be computed safely), the spend
- * cannot be bounded and the call is blocked. If the estimated USD exceeds
- * maxSpend, the call is blocked. Otherwise the call proceeds.
- *
- * This must run AFTER maxSpendPreflight, so maxSpend is known to be > 0.
- */
-export declare function spendBoundCheck(provider: string, method: string, dotPath: string, maxSpend: number | undefined, estimate: {
-    usd: number;
-    warnings: string[];
-}): void;
-/**
- * Wrap a provider network dispatch with the paid-endpoint guard.
- *
- * This is the canonical boundary enforcement: it runs the preflight check
- * and spend-bound check before the actual HTTP request, and only calls the
- * supplied `dispatch` function when the checks pass.
- *
- * Free/unlisted endpoints return `dispatch()` immediately without guard
- * overhead, so callers that omit `maxSpend` on free endpoints see no change.
- *
- * @param provider - Provider identifier (e.g. "kie", "openai")
- * @param method - HTTP method (e.g. "POST", "GET")
- * @param dotPath - Exact endpoint dot-path (e.g. "api.v1.jobs.createTask")
- * @param payload - Request payload for cost estimation
- * @param maxSpend - Maximum spend authorization in USD (undefined for free endpoints)
- * @param dispatch - The actual network dispatch to wrap
- * @returns The result of `dispatch()`
- */
-export declare function dispatchWithPaidGuard<T>(provider: string, method: string, dotPath: string, payload: Record<string, unknown>, maxSpend: number | undefined, dispatch: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=paid-endpoints.d.ts.map

package/dist/src/paid-endpoints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paid-endpoints.d.ts","sourceRoot":"","sources":["../../src/paid-endpoints.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,eAAe,CAAC;IACrB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,iBAAiB,EAetD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,gBAAgB,GAAG,SAAS,CAW9B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAET;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAExB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM;CAanB;AACD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAE5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM;CAcnB;AACD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAU,GACnB,IAAI,CAON;AACD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5C,IAAI,CA0BN;AACD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAcZ"}
+{"version":3,"file":"paid-endpoints.d.ts","sourceRoot":"","sources":["../../src/paid-endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,eAAe,CAAC;IACrB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,iBAAiB,EAetD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,gBAAgB,GAAG,SAAS,CAW9B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAET"}