@apicity/cost 0.2.0-alpha.0 → 0.2.0

package/README.md

@@ -142,6 +142,261 @@ Maintenance is manual: re-fetch each upstream's pricing page, edit `pricing.ts`,
 | `kie`        | `per-unit-table`         | priced per second of video / per image                                |
 | `free`       | `free`                   | always $0                                                             |
 
+## Paid endpoint guard (OTP pay gate)
+
+Some endpoints have a direct marginal compute cost (e.g. video generation).
+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 **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 and pass through without OTP or configuration.
+- Listed endpoints block unless a valid OTP is supplied.
+
+### Token format
+
+OTP tokens are a dependency-free compact envelope:
+
+```
+<base64url(payloadJson)>.<base64url(HMAC-SHA256(payloadSegment, secret))>
+```
+
+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"
+  requestHash: `sha256:${string}`; // sha256 of canonical request JSON
+  iat: number; // issued-at unix seconds
+  exp: number; // expiration unix seconds
+}
+```
+
+### Configuration
+
+The code client supplies a `PayGateConfig` via factory options:
+
+```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
+}
+
+interface ReplayStore {
+  has(jti: string): boolean;
+  add(jti: string): void;
+}
+```
+
+```ts
+import { createKie } from "@apicity/kie";
+
+const provider = createKie({
+  apiKey: process.env.KIE_API_KEY!,
+  paygate: { secret: loadSecret() }, // from your secret manager / config
+});
+```
+
+### Minting OTPs
+
+`mintOtp` is pure and env-free — the secret is passed explicitly and the OTP
+binds to the exact request via its canonical hash:
+
+```ts
+import { mintOtp } from "@apicity/cost";
+
+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
+});
+```
+
+### Request canonicalization
+
+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.
+
+### Replay protection
+
+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
+
+```ts
+interface PayGateApproval {
+  otp: string;
+}
+
+async function dispatchWithPaidGate<T>(
+  provider: string,
+  method: string,
+  dotPath: string,
+  payload: Record<string, unknown>,
+  approval: PayGateApproval | undefined,
+  dispatch: () => Promise<T>,
+  config?: PayGateConfig
+): Promise<T>;
+```
+
+Paid endpoint APIs accept the approval as a second options object:
+
+```ts
+const task = await provider.post.api.v1.jobs.createTask(
+  { model: "kling-3.0/video", input: { prompt: "...", duration: "5" } },
+  { otp }
+);
+```
+
+### Guard behavior
+
+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 } from "@apicity/cost";
+
+try {
+  await provider.post.api.v1.jobs.createTask({ ... }, { otp });
+} catch (e) {
+  if (e instanceof PayGateError) {
+    // 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                          | `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 mints OTPs. The secret is read from a **file**
+(never an env var); only the OTP is printed to stdout:
+
+```bash
+apicity-paygate otp mint \
+  --secret-file ./paygate.secret \
+  --dot-path api.v1.jobs.createTask \
+  --payload-file request.json \
+  --ttl 10m
+```
+
+### Wiring the gate into a provider
+
+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):
+
+```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 }
+  );
+}
+```
+
+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.
+
+### Retry semantics
+
+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.
+
+### 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. **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 \
+     --secret-file ./paygate.secret \
+     --dot-path api.v1.jobs.createTask \
+     --payload-file request.json \
+     --ttl 10m
+   ```
+4. **Pass the OTP to the caller** (copy-paste, secrets manager, etc.).
+5. **Caller uses the OTP**:
+   ```ts
+   await provider.post.api.v1.jobs.createTask({ ... }, { otp: "<paste>" });
+   ```
+
 ## Out of scope
 
 - Anthropic prompt-cache pricing (rates are in the table but `estimate()` ignores them — assumes no caching)

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,4 +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, } from "./paid-endpoints";
+export type { PaidEndpointKey, PaidEndpointInfo, PaidEndpointEntry, } from "./paid-endpoints";
+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"}
+{"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,5 +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, } 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"}
+{"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

@@ -0,0 +1,46 @@
+/**
+ * Exact paid-endpoint registry.
+ *
+ * Only endpoints listed here are considered paid. All unlisted endpoints
+ * are assumed free and must preserve current behavior with no caller changes.
+ *
+ * Matching is exact: provider + method + dotPath. No regex, prefix,
+ * wildcard, path-family, generated broad match, or fallback-by-method logic.
+ */
+export interface PaidEndpointKey {
+    provider: string;
+    method: string;
+    dotPath: string;
+}
+export interface PaidEndpointInfo {
+    /** Human-readable reason why this endpoint is paid. */
+    reason: string;
+    /** Optional estimator identifier for cost computation. */
+    estimatorId?: string;
+    /** Optional known cost notes (e.g. per-unit billing details). */
+    costNotes?: string;
+}
+export interface PaidEndpointEntry {
+    key: PaidEndpointKey;
+    info: PaidEndpointInfo;
+}
+/**
+ * The canonical list of paid endpoints. Add new entries here only after
+ * review. Keep the list small and explicit.
+ */
+export declare const PAID_ENDPOINTS: readonly PaidEndpointEntry[];
+/**
+ * Look up a paid endpoint by exact key match.
+ *
+ * Returns `PaidEndpointInfo` only when provider, method, and dotPath all match
+ * an entry in `PAID_ENDPOINTS` exactly. Returns `undefined` for every
+ * unlisted endpoint, which callers must treat as free.
+ */
+export declare function lookupPaidEndpoint(provider: string, method: string, dotPath: string): PaidEndpointInfo | undefined;
+/**
+ * Predicate: is this exact endpoint paid?
+ *
+ * Unlisted endpoints return `false` (assumed free).
+ */
+export declare function isPaidEndpoint(provider: string, method: string, dotPath: string): boolean;
+//# sourceMappingURL=paid-endpoints.d.ts.map

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

@@ -0,0 +1 @@
+{"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"}

package/dist/src/paid-endpoints.js

@@ -0,0 +1,53 @@
+/**
+ * Exact paid-endpoint registry.
+ *
+ * Only endpoints listed here are considered paid. All unlisted endpoints
+ * are assumed free and must preserve current behavior with no caller changes.
+ *
+ * Matching is exact: provider + method + dotPath. No regex, prefix,
+ * wildcard, path-family, generated broad match, or fallback-by-method logic.
+ */
+/**
+ * The canonical list of paid endpoints. Add new entries here only after
+ * review. Keep the list small and explicit.
+ */
+export const PAID_ENDPOINTS = [
+    {
+        key: {
+            provider: "kie",
+            method: "POST",
+            dotPath: "api.v1.jobs.createTask",
+        },
+        info: {
+            reason: "Media generation task that incurs direct marginal compute cost per job",
+            estimatorId: "kie-per-unit",
+            costNotes: "Billed per unit (seconds/images/songs) based on model and resolution",
+        },
+    },
+];
+/**
+ * Look up a paid endpoint by exact key match.
+ *
+ * Returns `PaidEndpointInfo` only when provider, method, and dotPath all match
+ * an entry in `PAID_ENDPOINTS` exactly. Returns `undefined` for every
+ * unlisted endpoint, which callers must treat as free.
+ */
+export function lookupPaidEndpoint(provider, method, dotPath) {
+    for (const entry of PAID_ENDPOINTS) {
+        if (entry.key.provider === provider &&
+            entry.key.method === method &&
+            entry.key.dotPath === dotPath) {
+            return entry.info;
+        }
+    }
+    return undefined;
+}
+/**
+ * Predicate: is this exact endpoint paid?
+ *
+ * Unlisted endpoints return `false` (assumed free).
+ */
+export function isPaidEndpoint(provider, method, dotPath) {
+    return lookupPaidEndpoint(provider, method, dotPath) !== undefined;
+}
+//# sourceMappingURL=paid-endpoints.js.map

package/dist/src/paid-endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paid-endpoints.js","sourceRoot":"","sources":["../../src/paid-endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsBH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiC;IAC1D;QACE,GAAG,EAAE;YACH,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,wBAAwB;SAClC;QACD,IAAI,EAAE;YACJ,MAAM,EACJ,wEAAwE;YAC1E,WAAW,EAAE,cAAc;YAC3B,SAAS,EACP,sEAAsE;SACzE;KACF;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,MAAc,EACd,OAAe;IAEf,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,IACE,KAAK,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAC/B,KAAK,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;YAC3B,KAAK,CAAC,GAAG,CAAC,OAAO,KAAK,OAAO,EAC7B,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,MAAc,EACd,OAAe;IAEf,OAAO,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,SAAS,CAAC;AACrE,CAAC"}

package/dist/src/paygate-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=paygate-cli.d.ts.map

package/dist/src/paygate-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paygate-cli.d.ts","sourceRoot":"","sources":["../../src/paygate-cli.ts"],"names":[],"mappings":""}

package/dist/src/paygate-cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { mintOtp } from "./paygate.js";
+function parseMintArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--provider")
+            out.provider = argv[++i];
+        else if (a.startsWith("--provider="))
+            out.provider = a.slice(11);
+        else if (a === "--method")
+            out.method = argv[++i];
+        else if (a.startsWith("--method="))
+            out.method = a.slice(9);
+        else if (a === "--dot-path")
+            out.dotPath = argv[++i];
+        else if (a.startsWith("--dot-path="))
+            out.dotPath = a.slice(11);
+        else if (a === "--payload-file")
+            out.payloadFile = argv[++i];
+        else if (a.startsWith("--payload-file="))
+            out.payloadFile = a.slice(15);
+        else if (a === "--secret-file")
+            out.secretFile = argv[++i];
+        else if (a.startsWith("--secret-file="))
+            out.secretFile = a.slice(14);
+        else if (a === "--ttl")
+            out.ttl = argv[++i];
+        else if (a.startsWith("--ttl="))
+            out.ttl = a.slice(6);
+        else {
+            console.error(`[apicity-paygate] unknown arg: ${a}`);
+        }
+    }
+    const required = ["dotPath", "payloadFile", "secretFile"];
+    for (const key of required) {
+        if (out[key] === undefined || out[key] === null) {
+            throw new Error(`Missing required argument: --${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`);
+        }
+    }
+    return out;
+}
+function printHelp() {
+    console.error([
+        "apicity-paygate — Mint OTPs for paid @apicity endpoints.",
+        "",
+        "Usage:",
+        "  apicity-paygate otp mint \\",
+        "    --secret-file <path> \\",
+        "    --dot-path <api.path> \\",
+        "    --payload-file <path> \\",
+        "    [--provider <provider>] \\",
+        "    [--method <HTTP method>] \\",
+        "    [--ttl <duration>]",
+        "",
+        "Options:",
+        "  --secret-file  Path to a file containing the shared HMAC secret",
+        "  --dot-path     API dot-path (e.g. api.v1.jobs.createTask)",
+        "  --payload-file Path to JSON request payload file",
+        "  --provider     Provider name (optional; resolved from the dot-path)",
+        "  --method       HTTP method (optional; resolved from the dot-path)",
+        "  --ttl          Time-to-live: 10m, 1h, 30s, 1d (default 10m)",
+    ].join("\n"));
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+        printHelp();
+        process.exit(0);
+    }
+    if (argv[0] !== "otp" || argv[1] !== "mint") {
+        console.error("[apicity-paygate] only 'otp mint' is supported.");
+        printHelp();
+        process.exit(1);
+    }
+    const args = parseMintArgs(argv.slice(2));
+    const secret = readFileSync(args.secretFile, "utf8").trim();
+    const request = JSON.parse(readFileSync(args.payloadFile, "utf8"));
+    const otp = mintOtp(secret, {
+        provider: args.provider,
+        method: args.method,
+        dotPath: args.dotPath,
+        request,
+        ttl: args.ttl,
+    });
+    console.log(otp);
+}
+const __filename = fileURLToPath(import.meta.url);
+if (process.argv[1] === __filename) {
+    main().catch((err) => {
+        console.error("[apicity-paygate] fatal:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=paygate-cli.js.map

package/dist/src/paygate-cli.js.map

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