@paybond/kit 0.12.0 → 0.12.2

package/templates/paybond-stripe-agent-demo/package-lock.json

@@ -0,0 +1,223 @@
+{
+  "name": "paybond-stripe-agent-demo",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "paybond-stripe-agent-demo",
+      "dependencies": {
+        "@paybond/kit": "^0.12.1"
+      },
+      "devDependencies": {
+        "@types/node": "^22.10.1",
+        "typescript": "^5.7.2"
+      },
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "node_modules/@noble/ed25519": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/@noble/ed25519/-/ed25519-2.3.0.tgz",
+      "integrity": "sha512-M7dvXL2B92/M7dw9+gzuydL8qn/jiqNHaoR3Q+cb1q1GHV7uwE17WCyFMG+Y+TZb5izcaXk5TdJRrDUxHXL78A==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@noble/secp256k1": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/@noble/secp256k1/-/secp256k1-2.3.0.tgz",
+      "integrity": "sha512-0TQed2gcBbIrh7Ccyw+y/uZQvbJwm7Ao4scBUxqpBCcsOlZG0O4KGfjtNAy/li4W8n1xt3dxrwJ0beZ2h2G6Kw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@paybond/kit": {
+      "version": "0.12.1",
+      "resolved": "https://registry.npmjs.org/@paybond/kit/-/kit-0.12.1.tgz",
+      "integrity": "sha512-dwLMq8MkuLiuWQrXy1AtFR++tom14hkpKYGe4koiPyGKu2LQyOHtresZQ6IDoC7HAUSyDWEilg0maAPslKnm+Q==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@noble/ed25519": "^2.2.1",
+        "@noble/hashes": "^1.7.1",
+        "@noble/secp256k1": "^2.2.3",
+        "ajv": "^8.17.1",
+        "blake3": "^2.1.7",
+        "uuid": "^14.0.0",
+        "zod": "^3.25.32 || ^4.2.0"
+      },
+      "bin": {
+        "paybond": "dist/cli.js",
+        "paybond-init": "dist/init.js",
+        "paybond-kit-login": "dist/login.js",
+        "paybond-mcp-server": "dist/mcp-server.js"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "@anthropic-ai/claude-agent-sdk": ">=0.2.100",
+        "@langchain/core": ">=0.3.0",
+        "@langchain/langgraph": ">=0.2.50",
+        "@mastra/core": ">=1.0.0",
+        "@openai/agents": ">=0.12.0",
+        "agents": ">=0.10.0",
+        "ai": ">=4.0.0",
+        "zod": "^3.25.32 || ^4.2.0"
+      },
+      "peerDependenciesMeta": {
+        "@anthropic-ai/claude-agent-sdk": {
+          "optional": true
+        },
+        "@langchain/core": {
+          "optional": true
+        },
+        "@langchain/langgraph": {
+          "optional": true
+        },
+        "@mastra/core": {
+          "optional": true
+        },
+        "@openai/agents": {
+          "optional": true
+        },
+        "agents": {
+          "optional": true
+        },
+        "ai": {
+          "optional": true
+        },
+        "zod": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "22.20.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.0.tgz",
+      "integrity": "sha512-QWlFW2wf3nTjC13/DqRnBpR4ZO36VJH/JVBkA/vcnmbTBNQIlnObqyqZE1tUR7+Ni23Lda8R1BxMfbXRpCUx5g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/blake3": {
+      "version": "2.1.7",
+      "resolved": "https://registry.npmjs.org/blake3/-/blake3-2.1.7.tgz",
+      "integrity": "sha512-5d+TdKJvju96IyEaGJ0eO6CHbckWi+NBrCezGYM/WsnI3R03aLL2TWfsuZSh1rs0fTv/L3ps/r0vykjYurcIwA==",
+      "hasInstallScript": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.3.tgz",
+      "integrity": "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "license": "MIT"
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/uuid": {
+      "version": "14.0.1",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-14.0.1.tgz",
+      "integrity": "sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew==",
+      "funding": [
+        "https://github.com/sponsors/broofa",
+        "https://github.com/sponsors/ctavan"
+      ],
+      "license": "MIT",
+      "bin": {
+        "uuid": "dist-node/bin/uuid"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/templates/paybond-stripe-agent-demo/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "paybond-stripe-agent-demo",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "smoke": "paybond agent sandbox smoke --policy-file paybond.policy.yaml --operation payments.charge_customer --requested-spend-cents 2500 --result-body '{\"payment_intent_id\":\"pi_smoke\",\"charge_id\":\"ch_smoke\",\"cost_cents\":2500,\"status\":\"succeeded\"}' --format json"
+  },
+  "dependencies": {
+    "@paybond/kit": "^0.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/paybond-stripe-agent-demo/paybond.policy.yaml

@@ -0,0 +1,22 @@
+# Reference implementation — edit freely. Regenerate with:
+# paybond policy init --preset stripe-commerce --out paybond.policy.yaml
+
+version: 1
+name: stripe-commerce-agent-v1
+default_deny: true
+
+tools:
+  payments.charge_customer:
+    side_effecting: true
+    max_spend_cents: 50000
+    evidence_preset: stripe_charge
+
+  payments.list_invoices:
+    side_effecting: false
+
+intent:
+  allowed_tools:
+    - payments.charge_customer
+  budget:
+    currency: usd
+    max_spend_usd: 500

package/templates/paybond-stripe-agent-demo/src/charge-customer.ts

@@ -0,0 +1,237 @@
+import {
+  buildPaybondStripeMetadata,
+  mapStripeToolResultToEvidence,
+  type PaybondEnvironment,
+  type PaybondStripeSettlementRail,
+  type StripeCommerceEvidencePreset,
+  type StripeToolResultInput,
+} from "@paybond/kit";
+
+/**
+ * Resolved Paybond session environment used to gate the optional Stripe test-mode charge.
+ * `"unknown"` when the gateway did not report one — treated as non-sandbox (fail closed).
+ */
+export type PaybondSessionEnvironment = PaybondEnvironment | "unknown";
+
+/**
+ * Paybond session binding for Stripe metadata — never sourced from client input.
+ *
+ * Tenant isolation + sandbox-only invariant: `tenantId`/`intentId` come from the authenticated
+ * Paybond session (populated after sandbox bind), and `environment` is the server-derived session
+ * environment. The optional Stripe test-mode charge is a per-tenant capability that is only valid
+ * when `environment === "sandbox"` — a live session must never forward a template-held secret to
+ * Stripe.
+ */
+export type PaybondSessionBinding = {
+  tenantId: string;
+  intentId: string;
+  environment: PaybondSessionEnvironment;
+};
+
+export type ChargeCustomerArgs = {
+  amountCents: number;
+  customerId?: string;
+  rail?: PaybondStripeSettlementRail;
+};
+
+export type ChargeCustomerResult = StripeToolResultInput & {
+  payment_intent_id: string;
+  charge_id: string;
+  cost_cents: number;
+  status: string;
+  metadata: Record<string, string>;
+  mode: "mock" | "stripe_test";
+};
+
+function assertPositiveIntegerAmount(amountCents: number): void {
+  if (!Number.isInteger(amountCents) || amountCents <= 0) {
+    throw new Error("amountCents must be a positive integer");
+  }
+}
+
+function mockSuffix(intentId: string): string {
+  return intentId.replace(/-/g, "").slice(0, 12) || "demo";
+}
+
+/**
+ * Offline mock charge — no Stripe secret required.
+ */
+export function mockChargeCustomer(
+  metadata: Record<string, string>,
+  args: ChargeCustomerArgs,
+  intentId: string,
+): ChargeCustomerResult {
+  assertPositiveIntegerAmount(args.amountCents);
+  const suffix = mockSuffix(intentId);
+  return {
+    payment_intent_id: `pi_mock_${suffix}`,
+    charge_id: `ch_mock_${suffix}`,
+    cost_cents: args.amountCents,
+    status: "succeeded",
+    metadata,
+    mode: "mock",
+  };
+}
+
+function stripeMetadataParams(metadata: Record<string, string>): URLSearchParams {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(metadata)) {
+    params.set(`metadata[${key}]`, value);
+  }
+  return params;
+}
+
+/**
+ * Optional Stripe test-mode PaymentIntent create + confirm via REST (requires `STRIPE_SECRET_KEY`).
+ */
+export async function stripeTestChargeCustomer(
+  secretKey: string,
+  metadata: Record<string, string>,
+  args: ChargeCustomerArgs,
+): Promise<ChargeCustomerResult> {
+  assertPositiveIntegerAmount(args.amountCents);
+
+  const body = stripeMetadataParams(metadata);
+  body.set("amount", String(args.amountCents));
+  body.set("currency", "usd");
+  body.set("confirm", "true");
+  body.set("payment_method", "pm_card_visa");
+  if (args.customerId?.trim()) {
+    body.set("customer", args.customerId.trim());
+  }
+
+  const response = await fetch("https://api.stripe.com/v1/payment_intents", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${secretKey}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body,
+  });
+
+  const payload = (await response.json()) as Record<string, unknown>;
+  if (!response.ok) {
+    const message =
+      typeof payload.error === "object" &&
+      payload.error !== null &&
+      "message" in payload.error &&
+      typeof payload.error.message === "string"
+        ? payload.error.message
+        : `Stripe API error (${response.status})`;
+    throw new Error(message);
+  }
+
+  const paymentIntentId =
+    typeof payload.id === "string" && payload.id.startsWith("pi_") ? payload.id : undefined;
+  if (!paymentIntentId) {
+    throw new Error("Stripe response missing payment_intent id");
+  }
+
+  let chargeId: string | undefined;
+  const latestCharge = payload.latest_charge;
+  if (typeof latestCharge === "string" && latestCharge.startsWith("ch_")) {
+    chargeId = latestCharge;
+  } else if (
+    typeof latestCharge === "object" &&
+    latestCharge !== null &&
+    "id" in latestCharge &&
+    typeof latestCharge.id === "string"
+  ) {
+    chargeId = latestCharge.id;
+  }
+  if (!chargeId) {
+    throw new Error("Stripe response missing charge id");
+  }
+
+  const status = typeof payload.status === "string" ? payload.status : "succeeded";
+  return {
+    payment_intent_id: paymentIntentId,
+    charge_id: chargeId,
+    cost_cents: args.amountCents,
+    status,
+    metadata,
+    mode: "stripe_test",
+  };
+}
+
+/**
+ * Resolve the sandbox-only Stripe test key, enforcing the per-tenant + sandbox-only invariant.
+ *
+ * Returns the validated `sk_test_...` secret only when a secret is present AND the bound Paybond
+ * session environment is `sandbox`. Returns `undefined` when no secret is configured (the default
+ * offline mock path). Fails closed with an explanatory message when:
+ *   - a secret is set but the session is not sandbox (live or unknown environment), or
+ *   - the secret is not a Stripe TEST key (e.g. a live `sk_live_...` key).
+ *
+ * This guarantees a live tenant can never forward a template-held secret to Stripe.
+ *
+ * @param environment Server-derived Paybond session environment (preferred over client hints).
+ * @returns The validated Stripe test secret, or `undefined` to use the offline mock.
+ */
+export function resolveSandboxStripeTestKey(
+  environment: PaybondSessionEnvironment,
+): string | undefined {
+  const stripeSecretKey = process.env.STRIPE_SECRET_KEY?.trim();
+  if (!stripeSecretKey) {
+    // Default offline path: no secret required, so `paybond dev loop --offline` and the sandbox
+    // smoke run with zero secrets.
+    return undefined;
+  }
+
+  if (environment !== "sandbox") {
+    throw new Error(
+      `STRIPE_SECRET_KEY is set but the Paybond session environment is "${environment}". ` +
+        "The Stripe test-mode charge is a per-tenant, sandbox-only capability; unset " +
+        "STRIPE_SECRET_KEY for live (or unconfirmed) sessions — the mock path needs no secret.",
+    );
+  }
+
+  if (!stripeSecretKey.startsWith("sk_test_")) {
+    throw new Error(
+      "STRIPE_SECRET_KEY must be a Stripe TEST key (sk_test_...). " +
+        "Live keys (sk_live_...) are refused: this sandbox-only demo never charges live Stripe.",
+    );
+  }
+
+  return stripeSecretKey;
+}
+
+/**
+ * Instrumented `payments.charge_customer` handler: binds Harbor metadata, then charges (mock or Stripe test).
+ *
+ * `tenantId` and `intentId` must come from Paybond session context after sandbox bind — never from
+ * unauthenticated client input. The Stripe test-mode charge is per-tenant + sandbox-only: it is used
+ * only when a `sk_test_...` secret is configured AND `binding.environment === "sandbox"`; otherwise
+ * this falls back to the offline mock (and fails closed if a secret is misconfigured for live).
+ */
+export async function chargeCustomer(
+  binding: PaybondSessionBinding,
+  args: ChargeCustomerArgs,
+): Promise<ChargeCustomerResult> {
+  if (!binding.tenantId.trim() || !binding.intentId.trim()) {
+    throw new Error("Paybond session binding is required before charging");
+  }
+
+  const metadata = buildPaybondStripeMetadata({
+    tenantId: binding.tenantId,
+    intentId: binding.intentId,
+    rail: args.rail ?? "stripe_connect",
+  });
+
+  const sandboxStripeTestKey = resolveSandboxStripeTestKey(binding.environment);
+  if (sandboxStripeTestKey) {
+    return stripeTestChargeCustomer(sandboxStripeTestKey, metadata, args);
+  }
+
+  return mockChargeCustomer(metadata, args, binding.intentId);
+}
+
+/**
+ * Maps a charge tool result into completion-catalog evidence for the configured preset.
+ */
+export function mapChargeEvidence(
+  toolResult: Record<string, unknown>,
+  preset: StripeCommerceEvidencePreset = "stripe_charge",
+): ReturnType<typeof mapStripeToolResultToEvidence> {
+  return mapStripeToolResultToEvidence(toolResult, { preset });
+}

package/templates/paybond-stripe-agent-demo/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Stripe commerce agent (generic TypeScript) — instrumented mock `payments.charge_customer`.
+ * Uses `buildPaybondStripeMetadata` + `mapStripeToolResultToEvidence` from @paybond/kit.
+ * No live LLM required for the sandbox smoke path.
+ */
+import { createPaybondClient } from "./paybond.config.js";
+import {
+  chargeCustomer,
+  mapChargeEvidence,
+  type PaybondSessionBinding,
+} from "./charge-customer.js";
+
+const PRIMARY_OPERATION = "payments.charge_customer";
+const REQUESTED_SPEND_CENTS = 2500;
+
+async function main(): Promise<void> {
+  const paybond = await createPaybondClient();
+  try {
+    // tenant_id and paybond_intent_id are populated after sandbox bind — never from client input.
+    // environment is server-derived (gateway principal); the Stripe test key is sandbox-only.
+    const bindingRef: PaybondSessionBinding = {
+      tenantId: "",
+      intentId: "",
+      environment: paybond.environment ?? "unknown",
+    };
+
+    const agent = await paybond.agent({
+      policy: "./paybond.policy.yaml",
+      framework: "generic",
+      tools: {
+        [PRIMARY_OPERATION]: async (args: { amountCents: number; customerId?: string }) =>
+          chargeCustomer(bindingRef, args),
+      },
+      sandbox: true,
+    });
+
+    bindingRef.tenantId = agent.run.tenantId;
+    bindingRef.intentId = agent.run.intentId;
+
+    const tool = agent.tools.find((entry) => entry.name === PRIMARY_OPERATION);
+    if (!tool) {
+      throw new Error(`missing tool ${PRIMARY_OPERATION}`);
+    }
+
+    const result = await tool.execute({
+      toolName: PRIMARY_OPERATION,
+      toolCallId: "demo-1",
+      arguments: { amountCents: REQUESTED_SPEND_CENTS },
+    });
+
+    const toolResult =
+      typeof result.toolResult === "object" && result.toolResult !== null
+        ? (result.toolResult as Record<string, unknown>)
+        : {};
+
+    const mappedEvidence = mapChargeEvidence(toolResult, "stripe_charge");
+
+    console.log(
+      JSON.stringify(
+        {
+          runId: agent.run.runId,
+          intentId: agent.run.intentId,
+          tenantId: agent.run.tenantId,
+          authorization: result.authorization,
+          evidence: result.evidence,
+          mappedEvidence,
+          toolResult: result.toolResult,
+        },
+        null,
+        2,
+      ),
+    );
+  } finally {
+    await paybond.aclose();
+  }
+}
+
+void main();

package/templates/paybond-stripe-agent-demo/src/paybond.config.ts

@@ -0,0 +1,51 @@
+import { Paybond } from "@paybond/kit";
+
+declare const process: {
+  env: Record<string, string | undefined>;
+};
+
+function readEnvValue(body: string, key: string): string | undefined {
+  const pattern = new RegExp("^\\s*(?:export\\s+)?" + key + "\\s*=\\s*(.*)$", "m");
+  const match = body.match(pattern);
+  if (!match) return undefined;
+  let value = (match[1] ?? "").trim();
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      value = value.slice(1, -1);
+    }
+  } else if (value.startsWith("'") && value.endsWith("'")) {
+    value = value.slice(1, -1);
+  }
+  return value.trim() || undefined;
+}
+
+export async function loadPaybondEnvFile(envFile = ".env.local"): Promise<void> {
+  if (process.env.PAYBOND_API_KEY?.trim()) return;
+  let body: string;
+  try {
+    const { readFile } = await import("node:fs/promises");
+    body = await readFile(envFile, "utf8");
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") return;
+    throw err;
+  }
+  const apiKey = readEnvValue(body, "PAYBOND_API_KEY");
+  if (apiKey) {
+    process.env.PAYBOND_API_KEY = apiKey;
+  }
+}
+
+export async function createPaybondClient(): Promise<Paybond> {
+  await loadPaybondEnvFile(".env.local");
+  const apiKey = process.env.PAYBOND_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("PAYBOND_API_KEY is required; run paybond login");
+  }
+  return Paybond.open({
+    apiKey,
+    gatewayBaseUrl: process.env.PAYBOND_GATEWAY_URL ?? process.env.PAYBOND_GATEWAY_BASE_URL,
+    expectedEnvironment: "sandbox",
+  });
+}

package/templates/paybond-stripe-agent-demo/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"]
+}