@paybond/kit 0.9.3 → 0.9.5

package/dist/init.js

@@ -11,6 +11,7 @@ const FRAMEWORKS = new Set([
     "langgraph",
     "mcp",
 ]);
+const PRESETS = new Set(["paid-tool-guard"]);
 const FRAMEWORK_NOTES = {
     generic: "Wrap the returned function around any side-effecting tool handler.",
     "provider-agnostic": "Use the guarded handler with OpenAI, Gemini, Claude/Anthropic, local models, or any custom runtime.",
@@ -25,26 +26,36 @@ const FRAMEWORK_NOTES = {
 };
 function usage() {
     return [
-        "Usage: paybond-init [--framework generic|provider-agnostic|openai|claude|anthropic|gemini|google-ai|vercel-ai|langgraph|mcp] [--out paybond-spend-guard.ts] [--force]",
+        "Usage: paybond-init [--preset paid-tool-guard] [--framework generic|provider-agnostic|openai|claude|anthropic|gemini|google-ai|vercel-ai|langgraph|mcp] [--out paybond-paid-tool-guard.ts] [--force]",
         "",
-        "Scaffolds a Paybond spend guard wrapper for delegated agent spend controls.",
+        "Scaffolds a production-shaped Paybond guardrail integration helper.",
     ].join("\n");
 }
 function parseArgs(argv) {
-    let framework = "generic";
-    let out = "paybond-spend-guard.ts";
+    let preset = "paid-tool-guard";
+    let framework = "provider-agnostic";
+    let out = "paybond-paid-tool-guard.ts";
     let force = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--help" || arg === "-h") {
             process.stdout.write(`${usage()}\n`);
             process.exitCode = 0;
-            return { framework, out, force };
+            return { preset, framework, out, force };
         }
         if (arg === "--force") {
             force = true;
             continue;
         }
+        if (arg === "--preset") {
+            const raw = argv[i + 1];
+            i += 1;
+            if (!raw || !PRESETS.has(raw)) {
+                throw new Error("invalid --preset");
+            }
+            preset = raw;
+            continue;
+        }
         if (arg === "--framework") {
             const raw = argv[i + 1];
             i += 1;
@@ -65,71 +76,166 @@ function parseArgs(argv) {
         }
         throw new Error(`unknown argument: ${arg}`);
     }
-    return { framework, out, force };
+    return { preset, framework, out, force };
 }
 function template(framework) {
-    return `import { Paybond, type FundIntentResult } from "@paybond/kit";
+    return `import {
+  Paybond,
+  type SandboxGuardrailBootstrapResult,
+  type SandboxGuardrailEvidenceResult,
+} from "@paybond/kit";
 
-type ToolInput = {
-  city: string;
-  maxPriceCents: number;
+declare const process: {
+  env: Record<string, string | undefined>;
 };
 
-type FundedIntent = {
-  intentId: string;
-  capabilityToken: string;
+// Production integration helpers only. Add your paid-tool handler in
+// application code and pass it to wrapPaidTool(...).
+const DEFAULT_OPERATION = "paid_tool.operation";
+const DEFAULT_REQUESTED_SPEND_CENTS = 500;
+
+export type PaidToolHandler<TInput, TResult> = (input: TInput) => TResult | Promise<TResult>;
+
+export type SandboxGuardrailIntentOptions = {
+  operation?: string;
+  requestedSpendCents?: number;
+  currency?: string;
+  evidenceSchema?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  idempotencyKey?: string;
 };
 
-export async function openPaybond(): Promise<Paybond> {
-  return Paybond.open({
-    apiKey: process.env.PAYBOND_API_KEY!,
-    expectedEnvironment: "sandbox",
-  });
+export type SubmitSandboxEvidenceOptions = {
+  operation?: string;
+  requestedSpendCents?: number;
+  metadata?: Record<string, unknown>;
+  artifacts?: string[];
+  idempotencyKey?: string;
+};
+
+export type OpenPaybondFromEnvOptions = {
+  /**
+   * Load PAYBOND_API_KEY from this local env file when the process environment
+   * does not already provide it. Pass false when your agent host injects secrets.
+   */
+  envFile?: string | false;
+};
+
+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 function fundedIntentFromCreate(created: Record<string, unknown>): FundedIntent {
-  const intentId = String(created["intent_id"] ?? "");
-  const capabilityToken = String(created["capability_token"] ?? "");
-  if (!intentId) {
-    throw new Error("intent create response missing intent_id");
+async function readTextFile(envFile: string): Promise<string | undefined> {
+  // @ts-ignore Node builtins are available in agent and CLI Node runtimes.
+  const fs: { readFile(path: string, encoding: "utf8"): Promise<string> } = await import("node:fs/promises");
+  try {
+    return await fs.readFile(envFile, "utf8");
+  } catch (err) {
+    if ((err as { code?: unknown })?.code === "ENOENT") return undefined;
+    throw err;
   }
-  if (!capabilityToken) {
-    throw new Error("intent is not funded yet; call paybond.intents.fund(...) before guarding tools");
+}
+
+export async function loadPaybondEnvFile(envFile = ".env.local"): Promise<void> {
+  if (process.env.PAYBOND_API_KEY?.trim()) return;
+  const body = await readTextFile(envFile);
+  if (body === undefined) return;
+  const apiKey = readEnvValue(body, "PAYBOND_API_KEY");
+  if (apiKey) {
+    process.env.PAYBOND_API_KEY = apiKey;
   }
-  return { intentId, capabilityToken };
 }
 
-export function fundedIntentFromFund(funded: FundIntentResult): FundedIntent {
-  if (!funded.capabilityToken) {
-    throw new Error("intent funding did not return a capabilityToken yet");
+export async function openPaybondFromEnv(options: OpenPaybondFromEnvOptions = {}): Promise<Paybond> {
+  if (options.envFile !== false) {
+    await loadPaybondEnvFile(options.envFile ?? ".env.local");
   }
-  return { intentId: funded.intentId, capabilityToken: funded.capabilityToken };
+  const apiKey = process.env.PAYBOND_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("PAYBOND_API_KEY is required; run paybond login or configure your agent host to pass it");
+  }
+
+  return Paybond.open({
+    apiKey,
+    gatewayBaseUrl: process.env.PAYBOND_GATEWAY_BASE_URL,
+    expectedEnvironment: "sandbox",
+  });
 }
 
-async function bookHotel(input: ToolInput): Promise<{ confirmation: string }> {
-  // Put the side-effecting tool call here.
-  return { confirmation: \`demo-\${input.city}-\${input.maxPriceCents}\` };
+export async function bootstrapSandboxGuardrailIntent(
+  paybond: Paybond,
+  options: SandboxGuardrailIntentOptions = {},
+): Promise<SandboxGuardrailBootstrapResult> {
+  return paybond.guardrails.bootstrapSandbox({
+    operation: options.operation ?? DEFAULT_OPERATION,
+    requestedSpendCents: options.requestedSpendCents ?? DEFAULT_REQUESTED_SPEND_CENTS,
+    currency: options.currency ?? "usd",
+    evidenceSchema: options.evidenceSchema ?? {
+      type: "object",
+      required: ["confirmation_id", "charged_cents"],
+      properties: {
+        confirmation_id: { type: "string" },
+        charged_cents: { type: "integer" },
+      },
+    },
+    metadata: options.metadata,
+    idempotencyKey: options.idempotencyKey,
+  });
 }
 
-export async function buildGuardedHotelTool(params: {
-  paybond: Paybond;
-  intentId: string;
-  capabilityToken: string;
-}): Promise<(input: ToolInput) => Promise<{ confirmation: string }>> {
-  if (!params.capabilityToken.trim()) {
-    throw new Error("fund the intent before guarding tools");
+export function wrapPaidTool<TInput, TResult>(
+  paybond: Paybond,
+  guardrail: Pick<
+    SandboxGuardrailBootstrapResult,
+    "intent_id" | "capability_token" | "operation" | "requested_spend_cents"
+  >,
+  handler: PaidToolHandler<TInput, TResult>,
+): (input: TInput) => Promise<Awaited<TResult>> {
+  if (!guardrail.capability_token.trim()) {
+    throw new Error("sandbox guardrail bootstrap did not return a capability token");
   }
-  const guard = params.paybond.spendGuard(params.intentId, params.capabilityToken);
+
+  const guard = paybond.spendGuard(guardrail.intent_id, guardrail.capability_token);
 
   // ${FRAMEWORK_NOTES[framework]}
   return guard.guardTool(
     {
-      operation: "travel.book_hotel",
-      requestedSpendCents: 20_000,
+      operation: guardrail.operation,
+      requestedSpendCents: guardrail.requested_spend_cents,
     },
-    bookHotel,
+    handler,
   );
 }
+
+export async function submitSandboxEvidence(
+  paybond: Paybond,
+  guardrail: Pick<SandboxGuardrailBootstrapResult, "intent_id" | "operation" | "requested_spend_cents">,
+  payload: Record<string, unknown>,
+  options: SubmitSandboxEvidenceOptions = {},
+): Promise<SandboxGuardrailEvidenceResult> {
+  return paybond.guardrails.submitSandboxEvidence({
+    intentId: guardrail.intent_id,
+    payload,
+    artifacts: options.artifacts,
+    operation: options.operation ?? guardrail.operation,
+    requestedSpendCents: options.requestedSpendCents ?? guardrail.requested_spend_cents,
+    metadata: options.metadata,
+    idempotencyKey: options.idempotencyKey,
+  });
+}
 `;
 }
 async function writeScaffold(out, body, force) {
@@ -162,13 +268,28 @@ export async function main(argv = process.argv.slice(2)) {
     if (argv.includes("--help") || argv.includes("-h")) {
         return 0;
     }
-    await writeScaffold(parsed.out, template(parsed.framework), parsed.force);
-    process.stdout.write(`Created ${parsed.out}\n`);
+    try {
+        await writeScaffold(parsed.out, template(parsed.framework), parsed.force);
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    process.stdout.write(`Created Paybond guardrail integration: ${parsed.out}\n`);
     return 0;
 }
-main().then((code) => {
-    process.exitCode = code;
-}, (err) => {
-    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-    process.exitCode = 1;
-});
+function normalizeFileURL(url) {
+    return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
+}
+function invokedFromCLI() {
+    const invokedPath = process.argv[1] ? normalizeFileURL(new URL("file://" + process.argv[1]).href) : "";
+    return Boolean(invokedPath && normalizeFileURL(import.meta.url) === invokedPath);
+}
+if (invokedFromCLI()) {
+    main().then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/login.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+type Writable = {
+    write(chunk: string): boolean;
+};
+export type DeviceEnvironment = "sandbox";
+export type LoginOptions = {
+    envFile: string;
+    gateway: string;
+    environment: DeviceEnvironment;
+    noOpen: boolean;
+    force: boolean;
+};
+type FetchInput = string | URL;
+type FetchInit = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+};
+type FetchLike = (input: FetchInput, init?: FetchInit) => Promise<Response>;
+export type LoginDependencies = {
+    cwd?: string;
+    fetch?: FetchLike;
+    sleep?: (ms: number) => Promise<void>;
+    openBrowser?: (url: string) => Promise<boolean>;
+    stdout?: Writable;
+    stderr?: Writable;
+    now?: () => number;
+};
+export declare function parseArgs(argv: string[]): LoginOptions | "help";
+export declare function assertGitIgnored(envPath: string, cwd: string): Promise<void>;
+export declare function assertCanWriteEnvFile(envPath: string, force: boolean): Promise<void>;
+export declare function writeEnvFile(envPath: string, rawKey: string, force: boolean): Promise<void>;
+export declare function runLogin(options: LoginOptions, deps?: LoginDependencies): Promise<number>;
+export declare function main(argv?: string[], deps?: LoginDependencies): Promise<number>;
+export {};