@kybernesis/payments 0.1.0 → 0.2.0

package/README.md

@@ -7,6 +7,7 @@ friends: the agent names a merchant and a total, the person approves it in the
 Link app, and Link issues a one-time card for exactly that purchase. This
 package adds the two pieces that make it usable by a Kybernesis agent:
 
+- **`linkTool(name)`** — Link's tool catalog (`@stripe/link-sdk/tools`) as eve tools, one per file. `create_spend_request` asks the person in eve before Link asks them again; every result is stripped of card fields.
 - **`linkCliAuth()`** — the owner's `link-cli` sign-in as the agent's wallet
   credential. The owner runs `npx link-cli auth login --client-name <agent>` on
   the agent's host once (a device-code flow approved in the Link app); the CLI
@@ -18,9 +19,9 @@ package adds the two pieces that make it usable by a Kybernesis agent:
   own browser via `@kybernesis/computer`'s fill primitive. The model supplies CSS
   selectors; the card goes Link → page and comes back only as brand + last four.
 
-```ts title="agent/extensions/link.ts"
-import { linkWallet } from "@kybernesis/payments";
-export default linkWallet();
+```ts title="agent/tools/create_spend_request.ts"
+import { linkTool } from "@kybernesis/payments";
+export default linkTool("create_spend_request"); // one file per Link tool; see LINK_TOOL_NAMES
 ```
 
 ```ts title="agent/tools/pay_on_computer.ts"
@@ -42,9 +43,7 @@ approval link, wait, fill, screenshot, submit, report with `link__create_report`
 
 ## Gotchas
 
-- `@stripe/link-integrations-eve` is built against an older eve; the tools mount
-  as a plain extension and have been exercised on eve 0.68, but a Link API change
-  shows up there first.
+- Stripe's own eve extension (`@stripe/link-integrations-eve`, built with eve 0.66) does not mount on eve 0.68 — that is why the tools are wrapped here from the SDK instead.
 - Link may require 3-D Secure or a verification step the agent cannot complete.
   The instructions tell it to stop and describe the screen; the person can take
   over the computer.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { linkCliAuth, linkCliAuthFile, readStoredAuth, NOT_SIGNED_IN, type LinkCliAuthOptions } from "./link-cli-auth.js";
 export { payOnComputerTool } from "./pay-on-computer.js";
 export { PAYMENTS_INSTRUCTIONS } from "./instructions.js";
-export { linkWallet } from "./extension.js";
+export { linkTool, linkClient, sanitizeLinkOutput, LINK_TOOL_NAMES, type LinkToolName } from "./link-tools.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { linkCliAuth, linkCliAuthFile, readStoredAuth, NOT_SIGNED_IN } from "./link-cli-auth.js";
 export { payOnComputerTool } from "./pay-on-computer.js";
 export { PAYMENTS_INSTRUCTIONS } from "./instructions.js";
-export { linkWallet } from "./extension.js";
+export { linkTool, linkClient, sanitizeLinkOutput, LINK_TOOL_NAMES } from "./link-tools.js";

package/dist/instructions.d.ts

@@ -1 +1 @@
-export declare const PAYMENTS_INSTRUCTIONS = "## Paying for things\n\nYou can buy things with the person's Link wallet. Every purchase is their decision twice over: creating a spend request asks them here, and Link asks them again in their Link app before any card exists. Never work around either step.\n\nThe order, every time:\n1. Agree the exact purchase first: merchant, items, final total including tax and shipping, in the right currency. Get these from the actual checkout page in your own browser (open_browser, then look), not from memory.\n2. `link__create_spend_request` with that merchant, those line items and that total. Send the person the approval link it returns, as a plain link, and wait. Do not create a second request for the same purchase.\n3. When `link__retrieve_spend_request` says approved, use `pay_on_computer` to type the one-time card into the checkout. You give it the selectors of the card fields you can see; the card itself never comes to you. Check the filled form in a screenshot, confirm the total still matches, then submit.\n4. Report the outcome with `link__create_report`: succeeded, failed, or what the merchant said. If the merchant needs more (3-D Secure, a code), stop and tell the person exactly what is on the screen; they can take over your screen.\n\nNever read card numbers or CVCs aloud, never paste them into chat or a file, never guess a total. If Link asks for verification you cannot complete, say so.\n";
+export declare const PAYMENTS_INSTRUCTIONS = "## Paying for things\n\nYou can buy things with the person's Link wallet. Every purchase is their decision twice over: creating a spend request asks them here, and Link asks them again in their Link app before any card exists. Never work around either step.\n\nThe order, every time:\n1. Agree the exact purchase first: merchant, items, final total including tax and shipping, in the right currency. Get these from the actual checkout page in your own browser (open_browser, then look), not from memory.\n2. `create_spend_request` with that merchant, those line items and that total. If it comes back without an approval link, call `request_spend_approval`. Send the person the approval link as a plain link, and wait. Do not create a second request for the same purchase.\n3. When `retrieve_spend_request` says approved, use `pay_on_computer` to type the one-time card into the checkout. You give it the selectors of the card fields you can see; the card itself never comes to you. Check the filled form in a screenshot, confirm the total still matches, then submit.\n4. Report the outcome with `create_report`: succeeded, failed, or what the merchant said. If the merchant needs more (3-D Secure, a code), stop and tell the person exactly what is on the screen; they can take over your screen.\n\nNever read card numbers or CVCs aloud, never paste them into chat or a file, never guess a total. If Link asks for verification you cannot complete, say so.\n";

package/dist/instructions.js

@@ -4,9 +4,9 @@ You can buy things with the person's Link wallet. Every purchase is their decisi
 
 The order, every time:
 1. Agree the exact purchase first: merchant, items, final total including tax and shipping, in the right currency. Get these from the actual checkout page in your own browser (open_browser, then look), not from memory.
-2. \`link__create_spend_request\` with that merchant, those line items and that total. Send the person the approval link it returns, as a plain link, and wait. Do not create a second request for the same purchase.
-3. When \`link__retrieve_spend_request\` says approved, use \`pay_on_computer\` to type the one-time card into the checkout. You give it the selectors of the card fields you can see; the card itself never comes to you. Check the filled form in a screenshot, confirm the total still matches, then submit.
-4. Report the outcome with \`link__create_report\`: succeeded, failed, or what the merchant said. If the merchant needs more (3-D Secure, a code), stop and tell the person exactly what is on the screen; they can take over your screen.
+2. \`create_spend_request\` with that merchant, those line items and that total. If it comes back without an approval link, call \`request_spend_approval\`. Send the person the approval link as a plain link, and wait. Do not create a second request for the same purchase.
+3. When \`retrieve_spend_request\` says approved, use \`pay_on_computer\` to type the one-time card into the checkout. You give it the selectors of the card fields you can see; the card itself never comes to you. Check the filled form in a screenshot, confirm the total still matches, then submit.
+4. Report the outcome with \`create_report\`: succeeded, failed, or what the merchant said. If the merchant needs more (3-D Secure, a code), stop and tell the person exactly what is on the screen; they can take over your screen.
 
 Never read card numbers or CVCs aloud, never paste them into chat or a file, never guess a total. If Link asks for verification you cannot complete, say so.
 `;

package/dist/link-tools.d.ts

@@ -0,0 +1,29 @@
+import { Link } from "@stripe/link-sdk";
+import { type ToolDefinition } from "eve/tools";
+import { type LinkCliAuthOptions } from "./link-cli-auth.js";
+/**
+ * Stripe's Link tools, mounted the Kybernesis way.
+ *
+ * Stripe ships an eve extension, but it is built against an older eve and
+ * eve 0.68 refuses to mount it. The same tool catalog is available
+ * framework-free from `@stripe/link-sdk/tools`, so each one is wrapped here as
+ * an eve tool: the owner's link-cli sign-in supplies the token on every call,
+ * creating a spend request asks the person in eve before it asks them in Link,
+ * and anything that could carry a card number is stripped from what the model
+ * sees — the card has exactly one path, `pay_on_computer`.
+ */
+export declare const LINK_TOOL_NAMES: readonly ["retrieve_user_info", "list_payment_methods", "list_shipping_addresses", "list_spend_requests", "create_spend_request", "update_spend_request", "cancel_spend_request", "request_spend_approval", "retrieve_spend_request", "create_report"];
+export type LinkToolName = (typeof LINK_TOOL_NAMES)[number];
+/** A Link client whose token is the owner's current link-cli sign-in, read at call time. */
+export declare function linkClient(options?: LinkCliAuthOptions): Link;
+/** Remove anything that is or contains a card credential before it reaches the model. */
+export declare function sanitizeLinkOutput<T>(value: T): T;
+/**
+ * One Link tool as an eve tool. Mount each in `agent/tools/<name>.ts`:
+ *
+ * ```ts
+ * import { linkTool } from "@kybernesis/payments";
+ * export default linkTool("create_spend_request");
+ * ```
+ */
+export declare function linkTool<N extends LinkToolName>(name: N, options?: LinkCliAuthOptions): ToolDefinition<Record<string, unknown>, unknown>;

package/dist/link-tools.js

@@ -0,0 +1,71 @@
+import { Link } from "@stripe/link-sdk";
+import { createLinkTools } from "@stripe/link-sdk/tools";
+import { defineTool } from "eve/tools";
+import { always, never } from "eve/tools/approval";
+import { linkCliAuth } from "./link-cli-auth.js";
+/**
+ * Stripe's Link tools, mounted the Kybernesis way.
+ *
+ * Stripe ships an eve extension, but it is built against an older eve and
+ * eve 0.68 refuses to mount it. The same tool catalog is available
+ * framework-free from `@stripe/link-sdk/tools`, so each one is wrapped here as
+ * an eve tool: the owner's link-cli sign-in supplies the token on every call,
+ * creating a spend request asks the person in eve before it asks them in Link,
+ * and anything that could carry a card number is stripped from what the model
+ * sees — the card has exactly one path, `pay_on_computer`.
+ */
+export const LINK_TOOL_NAMES = [
+    "retrieve_user_info",
+    "list_payment_methods",
+    "list_shipping_addresses",
+    "list_spend_requests",
+    "create_spend_request",
+    "update_spend_request",
+    "cancel_spend_request",
+    "request_spend_approval",
+    "retrieve_spend_request",
+    "create_report",
+];
+/** A Link client whose token is the owner's current link-cli sign-in, read at call time. */
+export function linkClient(options = {}) {
+    const auth = linkCliAuth(options);
+    return new Link({ getAccessToken: async () => (await auth.getToken({})).token });
+}
+/** Remove anything that is or contains a card credential before it reaches the model. */
+export function sanitizeLinkOutput(value) {
+    if (Array.isArray(value))
+        return value.map((v) => sanitizeLinkOutput(v));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (k === "card" || k === "credential" || k === "number" || k === "cvc" || k === "payment_token" || k === "shared_payment_token")
+                continue;
+            out[k] = sanitizeLinkOutput(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * One Link tool as an eve tool. Mount each in `agent/tools/<name>.ts`:
+ *
+ * ```ts
+ * import { linkTool } from "@kybernesis/payments";
+ * export default linkTool("create_spend_request");
+ * ```
+ */
+export function linkTool(name, options = {}) {
+    const catalog = createLinkTools(linkClient(options));
+    const tool = catalog[name];
+    return defineTool({
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        // Asking Link for money starts with asking the person here. Reading and
+        // reporting do not; Link's own approval step still gates every card.
+        approval: name === "create_spend_request" ? always() : never(),
+        async execute(input, ctx) {
+            const result = await tool.execute(input, ctx);
+            return sanitizeLinkOutput(result);
+        },
+    });
+}

package/dist/pay-on-computer.d.ts

@@ -1,4 +1,4 @@
-import { type LinkCliAuthOptions } from "./link-cli-auth.js";
+import type { LinkCliAuthOptions } from "./link-cli-auth.js";
 /**
  * Type the one-time card of an APPROVED Link spend request into a checkout
  * form on the agent's own computer. The card number and CVC go from Link to
@@ -14,7 +14,7 @@ export declare function payOnComputerTool(options?: LinkCliAuthOptions): import(
     spend_request_id: string;
     page_url: string;
     fields: {
-        field: "number" | "name" | "exp_month" | "exp_year" | "expiration" | "cvc" | "postal_code";
+        field: "number" | "cvc" | "name" | "exp_month" | "exp_year" | "expiration" | "postal_code";
         selector: string;
         frameUrl?: string | undefined;
         format?: "MM/YY" | "MM/YYYY" | undefined;
@@ -33,7 +33,7 @@ export declare function payOnComputerTool(options?: LinkCliAuthOptions): import(
         spend_request_id: string;
         page_url: string;
         fields: {
-            field: "number" | "name" | "exp_month" | "exp_year" | "expiration" | "cvc" | "postal_code";
+            field: "number" | "cvc" | "name" | "exp_month" | "exp_year" | "expiration" | "postal_code";
             selector: string;
             frameUrl?: string | undefined;
             format?: "MM/YY" | "MM/YYYY" | undefined;

package/dist/pay-on-computer.js

@@ -1,9 +1,8 @@
-import { Link } from "@stripe/link-sdk";
 import { fillOnComputer } from "@kybernesis/computer";
 import { defineTool } from "eve/tools";
 import { never } from "eve/tools/approval";
 import { z } from "zod";
-import { linkCliAuth } from "./link-cli-auth.js";
+import { linkClient } from "./link-tools.js";
 const fieldSchema = z.object({
     field: z.enum(["name", "number", "exp_month", "exp_year", "expiration", "cvc", "postal_code"]),
     selector: z.string().min(1).max(500).describe("CSS selector of that input on the checkout page."),
@@ -22,7 +21,7 @@ const fieldSchema = z.object({
  * a request that is not approved is refused.
  */
 export function payOnComputerTool(options = {}) {
-    const auth = linkCliAuth(options);
+    const link = linkClient(options);
     return defineTool({
         description: "Type the one-time card from an APPROVED Link spend request into the checkout form open in your own browser. Give the CSS selector of each card field you can see (name, number, expiration or exp_month/exp_year, cvc, postal code). The card details never come back to you; the result says which fields were filled. Open the checkout with open_browser first and look at it.",
         inputSchema: z.object({
@@ -32,8 +31,6 @@ export function payOnComputerTool(options = {}) {
         }),
         approval: never(),
         async execute(input, ctx) {
-            const { token } = await auth.getToken({});
-            const link = new Link({ accessToken: token });
             const request = await link.spendRequests.retrieve(input.spend_request_id, { include: ["card"] });
             if (!request)
                 throw new Error("That spend request does not exist.");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kybernesis/payments",
-  "version": "0.1.0",
-  "description": "A Link wallet for an eve agent on its owner's behalf: Stripe's Link tools behind the owner's link-cli sign-in, approval on every purchase, and a one-time card typed into a checkout on the agent's own computer without the model ever seeing it.",
+  "version": "0.2.0",
+  "description": "Stripe Link as an eve agent's wallet, on its owner's behalf: Link's tool catalog mounted as eve tools behind the owner's link-cli sign-in, the person's approval on every purchase, and a one-time card typed into a checkout on the agent's own computer without the model ever seeing it.",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -30,7 +30,6 @@
   },
   "dependencies": {
     "@stripe/link-cli": "^0.26.0",
-    "@stripe/link-integrations-eve": "^0.2.4",
     "@stripe/link-sdk": "^0.11.0"
   },
   "peerDependencies": {