@t2000/serve 10.1.0

package/dist/index.js

@@ -0,0 +1,568 @@
+import { isValidSuiAddress, normalizeSuiAddress } from '@mysten/sui/utils';
+import { USDC_TESTNET, USDC, InMemoryDigestStore } from '@suimpp/mpp/server';
+export { InMemoryDigestStore } from '@suimpp/mpp/server';
+import { X402_PAYMENT_HEADER, isX402EscrowHeader, parseX402Header, verifyX402Payment, settleX402Payment, X402_PAYMENT_RESPONSE_HEADER, encodeX402Response, createX402Requirements, X402_VERSION } from '@suimpp/mpp/x402';
+import { SuiGrpcClient } from '@mysten/sui/grpc';
+
+// src/serve.ts
+function buildOpenApiDocument(serve, origin) {
+  const base = serve.baseUrl ?? origin;
+  const paths = {};
+  for (const route of serve.routes.values()) {
+    const { path, priceUsdc, description, inputSchema } = route.meta;
+    const operation = {
+      operationId: path.replace(/[^a-zA-Z0-9]+/g, "_"),
+      summary: description ?? path,
+      responses: {
+        "200": { description: "Success" },
+        ...priceUsdc ? {
+          "402": {
+            description: 'Payment required \u2014 the body carries an x402 accepts[] envelope (scheme "exact", network sui). Sign it and retry with the X-PAYMENT header.'
+          }
+        } : {},
+        "422": { description: "Invalid request body \u2014 never charged" }
+      }
+    };
+    if (priceUsdc) {
+      operation["x-payment-info"] = {
+        pricingMode: "fixed",
+        price: priceUsdc,
+        currency: "USDC",
+        protocols: ["mpp", "x402"],
+        x402: {
+          scheme: "exact",
+          network: `sui:${serve.network}`,
+          asset: (serve.network === "testnet" ? USDC_TESTNET : USDC).type,
+          payTo: serve.payTo
+        }
+      };
+    }
+    if (inputSchema) {
+      operation.requestBody = {
+        required: true,
+        content: { "application/json": { schema: inputSchema } }
+      };
+    }
+    paths[`/${path}`] = { post: operation };
+  }
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: serve.name ?? "Paid API",
+      version: "1.0.0",
+      description: serve.description ?? "Agent-payable API. Every paid endpoint answers 402 with an x402 accepts[] envelope; payment settles in USDC on Sui."
+    },
+    ...base ? { servers: [{ url: base }] } : {},
+    paths
+  };
+}
+function buildLlmsTxt(serve, origin) {
+  const base = serve.baseUrl ?? origin ?? "";
+  const lines = [];
+  lines.push(`# ${serve.name ?? "Paid API"}`);
+  lines.push("");
+  if (serve.description) {
+    lines.push(serve.description);
+    lines.push("");
+  }
+  lines.push("## How to pay");
+  lines.push("");
+  lines.push(
+    "Endpoints below are paid per call in USDC on Sui (x402). An unpaid request returns",
+    "HTTP 402 with an `accepts[]` envelope; sign it and retry with the `X-PAYMENT` header.",
+    "Invalid input returns 422 before any payment is taken. A failed call is never charged.",
+    "",
+    "Easiest client: `npm i -g @t2000/cli` then `t2 pay <url> --method POST --body '{...}'`,",
+    "or the t2000 MCP server (`t2000_pay`), or `@t2000/sdk` `pay()`.",
+    ""
+  );
+  lines.push("## Endpoints");
+  lines.push("");
+  for (const route of serve.routes.values()) {
+    const { path, priceUsdc, description, inputSchema } = route.meta;
+    const price = priceUsdc ? `${priceUsdc} USDC per call` : "free";
+    lines.push(`### POST ${base}/${path} \u2014 ${price}`);
+    if (description) lines.push(description);
+    if (inputSchema) {
+      lines.push("Request body (JSON Schema):");
+      lines.push("```json");
+      lines.push(JSON.stringify(inputSchema, null, 2));
+      lines.push("```");
+    }
+    lines.push("");
+  }
+  lines.push(`Discovery: ${base}/openapi.json`);
+  return lines.join("\n");
+}
+var FULLNODE_URLS = {
+  mainnet: "https://fullnode.mainnet.sui.io:443",
+  testnet: "https://fullnode.testnet.sui.io:443"
+};
+var EPOCH_TTL_MS = 10 * 60 * 1e3;
+var state = {};
+function getGrpcClient(network, rpcUrl) {
+  const s = state[network] ??= {};
+  if (!s.client) {
+    s.client = new SuiGrpcClient({
+      baseUrl: rpcUrl ?? FULLNODE_URLS[network],
+      network
+    });
+  }
+  return s.client;
+}
+async function getChainInfo(network, rpcUrl) {
+  const client = getGrpcClient(network, rpcUrl);
+  const s = state[network] ??= {};
+  if (!s.chainId) {
+    const res = await client.core.getChainIdentifier();
+    s.chainId = res.chainIdentifier;
+  }
+  if (!s.epoch || Date.now() - s.epoch.fetchedAt > EPOCH_TTL_MS) {
+    const res = await client.core.getCurrentSystemState();
+    s.epoch = { value: String(res.systemState.epoch), fetchedAt: Date.now() };
+  }
+  return { chain: s.chainId, epoch: s.epoch.value };
+}
+function __resetChainCaches() {
+  delete state.mainnet;
+  delete state.testnet;
+}
+function __seedChainInfo(network, chain, epoch) {
+  const s = state[network] ??= {};
+  s.chainId = chain;
+  s.epoch = { value: epoch, fetchedAt: Date.now() };
+}
+
+// src/route.ts
+var MPP_REPORT_URL = "https://mpp.t2000.ai/api/mpp/report";
+var REPORT_TIMEOUT_MS = 2e3;
+var CATALOG_PRICE_CAP_USDC = 5;
+var CORS_HEADERS = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "GET, POST, PUT, DELETE, OPTIONS",
+  "access-control-allow-headers": `content-type, ${X402_PAYMENT_HEADER}`,
+  "access-control-expose-headers": `${X402_PAYMENT_RESPONSE_HEADER}, WWW-Authenticate`
+};
+function withCors(response) {
+  const headers = new Headers(response.headers);
+  for (const [k, v] of Object.entries(CORS_HEADERS)) headers.set(k, v);
+  return new Response(response.body, { status: response.status, headers });
+}
+function json(status, body, headers) {
+  return withCors(
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { "content-type": "application/json", ...headers }
+    })
+  );
+}
+function isStandardSchema(schema) {
+  return typeof schema === "object" && schema !== null && "~standard" in schema;
+}
+async function validateBody(schema, value) {
+  if (isStandardSchema(schema)) {
+    const result2 = await schema["~standard"].validate(value);
+    if (result2.issues) {
+      return { ok: false, message: result2.issues.map((i) => i.message).join("; ") };
+    }
+    return { ok: true, data: result2.value };
+  }
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    return { ok: false, message: result.error.message ?? "invalid body" };
+  }
+  return { ok: true, data: result.data };
+}
+function assertValidPrice(price, path) {
+  if (!/^\d+(\.\d{1,6})?$/.test(price) || Number(price) <= 0) {
+    throw new Error(
+      `[serve] Route "${path}": price must be a positive decimal USDC string with up to 6 decimals, got "${price}"`
+    );
+  }
+  if (Number(price) > CATALOG_PRICE_CAP_USDC) {
+    console.warn(
+      `[serve] Route "${path}": price ${price} USDC is above the ${CATALOG_PRICE_CAP_USDC} USDC listing cap \u2014 the route works, but it will not list on mpp.t2000.ai. Job-class work belongs in \`t2 service create\` (escrow).`
+    );
+  }
+}
+var RouteBuilder = class {
+  constructor(runtime, options, register) {
+    this.runtime = runtime;
+    this.options = options;
+    this.register = register;
+  }
+  priceUsdc;
+  bodySchema;
+  inputSchema;
+  isFree = false;
+  /** Charge this many USDC per call (human units, e.g. "0.01"). */
+  paid(priceUsdc) {
+    assertValidPrice(priceUsdc, this.options.path);
+    this.priceUsdc = priceUsdc;
+    this.isFree = false;
+    return this;
+  }
+  /** Serve without payment (health checks, previews, docs). */
+  unprotected() {
+    this.isFree = true;
+    this.priceUsdc = void 0;
+    return this;
+  }
+  /**
+   * Validate the JSON request body. zod v4 / valibot / arktype / anything
+   * Standard-Schema, or anything with a zod-style safeParse.
+   *
+   * Pass the JSON Schema as the second argument to publish it in
+   * /openapi.json + /llms.txt (zod v4: `z.toJSONSchema(schema)`) — buyers'
+   * agents build request bodies from it, and the catalog grades listings
+   * without one.
+   */
+  body(schema, jsonSchema) {
+    this.bodySchema = schema;
+    this.inputSchema = jsonSchema;
+    return this;
+  }
+  handler(fn) {
+    if (!this.isFree && !this.priceUsdc) {
+      throw new Error(
+        `[serve] Route "${this.options.path}": call .paid('<usdc>') or .unprotected() before .handler()`
+      );
+    }
+    const runtime = this.runtime;
+    const { path, description } = this.options;
+    const priceUsdc = this.priceUsdc;
+    const bodySchema = this.bodySchema;
+    const route = (async (req) => {
+      if (req.method === "OPTIONS") {
+        return withCors(new Response(null, { status: 204 }));
+      }
+      let parsedBody;
+      let bodyParseError;
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        const text = await req.text();
+        if (text.trim().length > 0) {
+          try {
+            parsedBody = JSON.parse(text);
+          } catch {
+            bodyParseError = "request body is not valid JSON";
+          }
+        }
+      }
+      const resource = (runtime.baseUrl ?? new URL(req.url).origin).replace(/\/$/, "") + `/${path}`;
+      const runHandler = async (payer) => {
+        let validated = parsedBody;
+        if (bodySchema) {
+          if (bodyParseError) return json(422, { error: bodyParseError });
+          const result = await validateBody(bodySchema, parsedBody ?? {});
+          if (!result.ok) return json(422, { error: result.message });
+          validated = result.data;
+        }
+        const out = await fn({ body: validated, req, payer });
+        if (out instanceof Response) return withCors(out);
+        return json(200, out);
+      };
+      if (!priceUsdc) {
+        try {
+          return await runHandler();
+        } catch (err) {
+          console.error(`[serve] Route "${path}" handler failed:`, err);
+          return json(500, { error: "internal error" });
+        }
+      }
+      const paymentHeader = req.headers.get(X402_PAYMENT_HEADER);
+      if (!paymentHeader) {
+        return await respond402(runtime, { resource, priceUsdc });
+      }
+      if (isX402EscrowHeader(paymentHeader)) {
+        return await respond402(runtime, {
+          resource,
+          priceUsdc,
+          error: "this endpoint sells instant per-call work (settle-then-serve), not escrow jobs \u2014 retry with a signed x402 payment"
+        });
+      }
+      let payment;
+      try {
+        payment = parseX402Header(paymentHeader);
+        verifyX402Payment({
+          payment,
+          expected: {
+            challengeId: payment.payload.challengeId,
+            amount: priceUsdc,
+            currency: runtime.currency,
+            recipient: runtime.payTo,
+            network: runtime.network
+          }
+        });
+      } catch (err) {
+        return await respond402(runtime, {
+          resource,
+          priceUsdc,
+          error: `invalid payment: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      const challengeKey = `challenge:${payment.payload.challengeId}`;
+      if (await runtime.store.has(challengeKey)) {
+        return await respond402(runtime, {
+          resource,
+          priceUsdc,
+          error: "payment challenge already used \u2014 sign a fresh payment"
+        });
+      }
+      let served;
+      try {
+        served = await runHandler(payment.payload.senderAddress);
+      } catch (err) {
+        console.error(`[serve] Route "${path}" handler failed (payment NOT settled):`, err);
+        return json(500, { error: "internal error \u2014 you were not charged" });
+      }
+      if (served.status >= 400) return served;
+      let settle;
+      try {
+        settle = await settleX402Payment({
+          payment,
+          client: getGrpcClient(runtime.network, runtime.rpcUrl),
+          store: runtime.store,
+          expected: {
+            challengeId: payment.payload.challengeId,
+            amount: priceUsdc,
+            currency: runtime.currency,
+            recipient: runtime.payTo,
+            network: runtime.network
+          }
+        });
+      } catch (err) {
+        return await respond402(runtime, {
+          resource,
+          priceUsdc,
+          error: `settlement failed: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      try {
+        await runtime.store.set(challengeKey);
+      } catch {
+      }
+      if (runtime.report) {
+        reportPayment(settle.transaction, resource);
+      }
+      const headers = new Headers(served.headers);
+      headers.set(X402_PAYMENT_RESPONSE_HEADER, encodeX402Response(settle));
+      return new Response(served.body, { status: served.status, headers });
+    });
+    route.meta = { path, priceUsdc, description, bodySchema, inputSchema: this.inputSchema };
+    this.register(route);
+    return route;
+  }
+};
+async function respond402(runtime, args) {
+  try {
+    const { chain, epoch } = await getChainInfo(runtime.network, runtime.rpcUrl);
+    const requirements = createX402Requirements({
+      challengeId: crypto.randomUUID(),
+      amount: args.priceUsdc,
+      currency: runtime.currency,
+      recipient: runtime.payTo,
+      resource: args.resource,
+      network: runtime.network,
+      chain,
+      currentEpoch: epoch
+    });
+    return json(402, {
+      x402Version: X402_VERSION,
+      error: args.error ?? "Payment required",
+      accepts: [requirements]
+    });
+  } catch (err) {
+    console.error("[serve] failed to build 402 challenge:", err);
+    return json(503, { error: "payment challenge temporarily unavailable" });
+  }
+}
+function reportPayment(digest, url) {
+  void fetch(MPP_REPORT_URL, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ digest, url }),
+    signal: AbortSignal.timeout(REPORT_TIMEOUT_MS)
+  }).catch(() => {
+  });
+}
+var DEFAULT_TTL_SECONDS = 72 * 60 * 60;
+var PREFIX = "serve:digest:";
+var UpstashDigestStore = class {
+  url;
+  token;
+  ttlSeconds;
+  constructor(options) {
+    this.url = options.url.replace(/\/$/, "");
+    this.token = options.token;
+    this.ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+  }
+  async command(segments) {
+    const res = await fetch(`${this.url}/${segments.map(encodeURIComponent).join("/")}`, {
+      headers: { authorization: `Bearer ${this.token}` }
+    });
+    if (!res.ok) {
+      throw new Error(`Upstash command failed: ${res.status} ${await res.text()}`);
+    }
+    const body = await res.json();
+    if (body.error) throw new Error(`Upstash error: ${body.error}`);
+    return body.result;
+  }
+  async has(digest) {
+    const result = await this.command(["GET", PREFIX + digest]);
+    return result !== null && result !== void 0;
+  }
+  async set(digest) {
+    const result = await this.command([
+      "SET",
+      PREFIX + digest,
+      "1",
+      "EX",
+      String(this.ttlSeconds),
+      "NX"
+    ]);
+    if (result === null || result === void 0) {
+      throw new Error(`Digest already used: ${digest}`);
+    }
+  }
+};
+
+// src/serve.ts
+var Serve = class {
+  runtime;
+  /** Every route built through this instance, keyed by path (discovery). */
+  routes = /* @__PURE__ */ new Map();
+  payTo;
+  network;
+  name;
+  description;
+  baseUrl;
+  constructor(config) {
+    if (!config.payTo || !isValidSuiAddress(config.payTo)) {
+      throw new Error(
+        `[serve] payTo must be a valid Sui address (the wallet your payments settle to), got "${config.payTo}"`
+      );
+    }
+    this.payTo = normalizeSuiAddress(config.payTo);
+    this.network = config.network ?? "mainnet";
+    this.name = config.name;
+    this.description = config.description;
+    this.baseUrl = config.baseUrl?.replace(/\/$/, "");
+    const currency = this.network === "testnet" ? USDC_TESTNET : USDC;
+    this.runtime = {
+      payTo: this.payTo,
+      network: this.network,
+      currency,
+      store: config.store ?? new InMemoryDigestStore(),
+      baseUrl: this.baseUrl,
+      rpcUrl: config.rpcUrl,
+      report: config.report ?? true
+    };
+  }
+  /** Start building a route. Chain `.paid()` / `.body()` / `.handler()`. */
+  route(options) {
+    const path = options.path.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!path) throw new Error("[serve] route path must be non-empty");
+    return new RouteBuilder({ ...this.runtime }, { ...options, path }, (route) => {
+      this.routes.set(path, route);
+    });
+  }
+  /**
+   * Discovery: GET handler for /openapi.json. OpenAPI 3.1 with the
+   * `x-payment-info` pricing extension on every paid operation — the shape
+   * the mpp.t2000.ai catalog (and x402 tooling generally) indexes.
+   *
+   *   export const GET = serve.openapi();   // app/openapi.json/route.ts
+   */
+  openapi() {
+    return (req) => new Response(JSON.stringify(buildOpenApiDocument(this, new URL(req.url).origin), null, 2), {
+      headers: { "content-type": "application/json", "access-control-allow-origin": "*" }
+    });
+  }
+  /**
+   * Discovery: GET handler for /llms.txt — plain-text guidance agents read
+   * to understand what the API sells, what it costs, and how to pay.
+   *
+   *   export const GET = serve.llms();      // app/llms.txt/route.ts
+   */
+  llms() {
+    return (req) => new Response(buildLlmsTxt(this, new URL(req.url).origin), {
+      headers: { "content-type": "text/plain; charset=utf-8", "access-control-allow-origin": "*" }
+    });
+  }
+  /**
+   * One fetch handler for the whole app — routes + discovery docs. For
+   * fetch-native runtimes (Bun.serve, Deno.serve, Hono, Cloudflare Workers):
+   *
+   *   Bun.serve({ fetch: serve.fetch });
+   *   app.all('*', (c) => serve.fetch(c.req.raw));   // Hono
+   *
+   * Next.js apps can skip this and export route handlers directly.
+   */
+  fetch = async (req) => {
+    const pathname = new URL(req.url).pathname.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (pathname === "openapi.json") return this.openapi()(req);
+    if (pathname === "llms.txt") return this.llms()(req);
+    const route = this.routes.get(pathname);
+    if (route) return route(req);
+    return new Response(
+      JSON.stringify({ error: "not found", discovery: ["/openapi.json", "/llms.txt"] }),
+      { status: 404, headers: { "content-type": "application/json" } }
+    );
+  };
+  /**
+   * The curl that lists this API on mpp.t2000.ai / agents.t2000.ai once it
+   * is deployed. Listing is a separate, explicit step — the catalog gates
+   * (url · probe · dialect · price-cap), not this package, decide outcomes.
+   * Dry-run first with /api/catalog/preview.
+   */
+  catalogSubmitCommand(deployedUrl) {
+    const base = (deployedUrl ?? this.baseUrl ?? "https://<your-deployed-app>").replace(/\/$/, "");
+    const paidPaths = [...this.routes.values()].filter((r) => r.meta.priceUsdc);
+    const example = paidPaths[0]?.meta.path ?? "<route>";
+    return [
+      "# Dry-run (shows gate results, changes nothing):",
+      `curl -X POST https://mpp.t2000.ai/api/catalog/preview -H 'content-type: application/json' -d '{"url":"${base}/${example}"}'`,
+      "# List for real:",
+      `curl -X POST https://mpp.t2000.ai/api/catalog/submit -H 'content-type: application/json' -d '{"url":"${base}/${example}"}'`
+    ].join("\n");
+  }
+};
+function createServe(config) {
+  return new Serve(config);
+}
+function createServeFromEnv(env = process.env) {
+  const read = (key) => {
+    const v = env[key]?.trim();
+    return v && v.length > 0 ? v : void 0;
+  };
+  const payTo = read("T2000_PAY_TO");
+  if (!payTo) {
+    throw new Error(
+      "[serve] T2000_PAY_TO is not set (or is empty). Set it to the Sui address your payments should settle to \u2014 `t2 address` prints yours."
+    );
+  }
+  const network = read("T2000_NETWORK");
+  if (network && network !== "mainnet" && network !== "testnet") {
+    throw new Error(`[serve] T2000_NETWORK must be 'mainnet' or 'testnet', got "${network}"`);
+  }
+  const kvUrl = read("KV_REST_API_URL");
+  const kvToken = read("KV_REST_API_TOKEN");
+  const store = kvUrl && kvToken ? new UpstashDigestStore({ url: kvUrl, token: kvToken }) : void 0;
+  if (!store) {
+    console.warn(
+      "[serve] No KV_REST_API_URL/KV_REST_API_TOKEN \u2014 using the in-memory replay store. Fine for a single long-lived process; on serverless hosts set both so replay protection is durable."
+    );
+  }
+  return new Serve({
+    payTo,
+    network: network ?? "mainnet",
+    baseUrl: read("T2000_BASE_URL"),
+    name: read("T2000_NAME"),
+    description: read("T2000_DESCRIPTION"),
+    store
+  });
+}
+
+export { RouteBuilder, Serve, UpstashDigestStore, __resetChainCaches, __seedChainInfo, buildLlmsTxt, buildOpenApiDocument, createServe, createServeFromEnv };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map