@kybernesis/payments 0.2.0 → 0.3.0

package/dist/approve-ask.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The approval moment of a purchase: the pure half (no Node imports), safe
+ * inside a workflow driver bundle. The Link calls live in ./approve-steps.js.
+ *
+ * Link approves a spend request in the person's Link app. Before this the
+ * agent pasted the approval link as text and asked them to say when they were
+ * done. Now the tool asks through eve's question channel with a marker a
+ * Kybernesis client renders as a card — merchant, total, an "Approve in Link"
+ * button — and parks until they tap "I approved" or "Cancel". Then it checks
+ * with Link and returns the real status. The model sees one result.
+ */
+export declare const SPEND_REQUEST_MARKER = "[kyb:spend-request]";
+export interface SpendRequestAsk {
+    readonly id: string;
+    readonly amount: number;
+    readonly currency: string;
+    readonly merchant?: string;
+    readonly merchant_url?: string;
+    readonly approval_url?: string;
+    readonly status: string;
+}
+export declare function spendRequestPrompt(ask: SpendRequestAsk): string;
+export declare function parseSpendRequestPrompt(prompt: string): {
+    ask: SpendRequestAsk;
+    text: string;
+} | null;
+export interface SpendRequestSnapshot {
+    id: string;
+    status: string;
+    amount: number;
+    currency: string;
+    merchant?: string;
+    merchant_url?: string;
+    approval_url?: string;
+}
+/** What the agent's tool file passes to `ctx.ask` once it has a snapshot. The tool itself is authored in `agent/tools/` — eve compiles `"use workflow"` from source. */
+export declare function spendRequestAsk(current: SpendRequestSnapshot): {
+    prompt: string;
+    display: "confirmation";
+    options: ({
+        id: string;
+        label: string;
+        style: "primary";
+    } | {
+        id: string;
+        label: string;
+        style: "danger";
+    })[];
+};
+export declare const APPROVE_SPEND_REQUEST_DESCRIPTION = "Put a spend request in front of the person for approval and wait for their answer. Call this right after create_spend_request. It shows them the merchant, the total and the Link approval button, pauses until they confirm or cancel, then returns the request's real status from Link. Only proceed to pay_on_computer when it returns approved.";

package/dist/approve-ask.js

@@ -0,0 +1,42 @@
+/**
+ * The approval moment of a purchase: the pure half (no Node imports), safe
+ * inside a workflow driver bundle. The Link calls live in ./approve-steps.js.
+ *
+ * Link approves a spend request in the person's Link app. Before this the
+ * agent pasted the approval link as text and asked them to say when they were
+ * done. Now the tool asks through eve's question channel with a marker a
+ * Kybernesis client renders as a card — merchant, total, an "Approve in Link"
+ * button — and parks until they tap "I approved" or "Cancel". Then it checks
+ * with Link and returns the real status. The model sees one result.
+ */
+export const SPEND_REQUEST_MARKER = "[kyb:spend-request]";
+export function spendRequestPrompt(ask) {
+    const total = `${(ask.amount / 100).toFixed(2)} ${ask.currency.toUpperCase()}`;
+    const at = ask.merchant ? ` at ${ask.merchant}` : "";
+    const link = ask.approval_url ? ` Approve it in Link: ${ask.approval_url}` : "";
+    return `${SPEND_REQUEST_MARKER} ${JSON.stringify(ask)}\nA purchase of ${total}${at} is waiting for your approval.${link}`;
+}
+export function parseSpendRequestPrompt(prompt) {
+    if (!prompt.startsWith(SPEND_REQUEST_MARKER))
+        return null;
+    const nl = prompt.indexOf("\n");
+    const head = nl === -1 ? prompt : prompt.slice(0, nl);
+    try {
+        return { ask: JSON.parse(head.slice(SPEND_REQUEST_MARKER.length).trim()), text: nl === -1 ? "" : prompt.slice(nl + 1) };
+    }
+    catch {
+        return null;
+    }
+}
+/** What the agent's tool file passes to `ctx.ask` once it has a snapshot. The tool itself is authored in `agent/tools/` — eve compiles `"use workflow"` from source. */
+export function spendRequestAsk(current) {
+    return {
+        prompt: spendRequestPrompt(current),
+        display: "confirmation",
+        options: [
+            { id: "approved", label: "I approved it in Link", style: "primary" },
+            { id: "cancel", label: "Cancel this purchase", style: "danger" },
+        ],
+    };
+}
+export const APPROVE_SPEND_REQUEST_DESCRIPTION = "Put a spend request in front of the person for approval and wait for their answer. Call this right after create_spend_request. It shows them the merchant, the total and the Link approval button, pauses until they confirm or cancel, then returns the request's real status from Link. Only proceed to pay_on_computer when it returns approved.";

package/dist/approve-steps.d.ts

@@ -0,0 +1,8 @@
+import type { LinkCliAuthOptions } from "./link-cli-auth.js";
+import type { SpendRequestSnapshot } from "./approve-ask.js";
+/** The Link calls behind approve_spend_request. Import only from "use step" functions: this touches the filesystem and the network. */
+export declare function spendRequestSnapshot(id: string, options?: LinkCliAuthOptions): Promise<SpendRequestSnapshot | null>;
+export declare function spendRequestApprovalLink(id: string, options?: LinkCliAuthOptions): Promise<string | undefined>;
+/** Link settles a moment after the tap; look a few times before giving up. */
+export declare function spendRequestSettledStatus(id: string, options?: LinkCliAuthOptions): Promise<string>;
+export declare function cancelSpendRequest(id: string, options?: LinkCliAuthOptions): Promise<void>;

package/dist/approve-steps.js

@@ -0,0 +1,39 @@
+import { linkClient } from "./link-tools.js";
+/** The Link calls behind approve_spend_request. Import only from "use step" functions: this touches the filesystem and the network. */
+export async function spendRequestSnapshot(id, options = {}) {
+    const link = linkClient(options);
+    const r = (await link.spendRequests.retrieve(id));
+    if (!r)
+        return null;
+    return { id: r.id, status: r.status, amount: r.amount, currency: r.currency, merchant: r.merchant_name ?? r.merchant, merchant_url: r.merchant_url, approval_url: r.approval_url };
+}
+export async function spendRequestApprovalLink(id, options = {}) {
+    const link = linkClient(options);
+    try {
+        const r = await link.spendRequests.requestApproval(id);
+        return r.approval_url;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Link settles a moment after the tap; look a few times before giving up. */
+export async function spendRequestSettledStatus(id, options = {}) {
+    const link = linkClient(options);
+    for (let i = 0; i < 6; i++) {
+        const r = await link.spendRequests.retrieve(id);
+        if (r && r.status !== "pending_approval" && r.status !== "created")
+            return r.status;
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+    const r = await link.spendRequests.retrieve(id);
+    return r?.status ?? "unknown";
+}
+export async function cancelSpendRequest(id, options = {}) {
+    try {
+        await linkClient(options).spendRequests.cancel(id);
+    }
+    catch {
+        /* already terminal */
+    }
+}

package/dist/approve.d.ts

@@ -0,0 +1,55 @@
+import type { LinkCliAuthOptions } from "./link-cli-auth.js";
+/**
+ * The approval moment of a purchase, as one durable tool call.
+ *
+ * Link approves a spend request in the person's Link app. Before this the
+ * agent pasted the approval link as text and asked them to say when they were
+ * done. Now the tool asks through eve's question channel with a marker a
+ * Kybernesis client renders as a card — merchant, total, an "Approve in Link"
+ * button — and parks until they tap "I approved" or "Cancel". Then it checks
+ * with Link and returns the real status. The model sees one result.
+ */
+export declare const SPEND_REQUEST_MARKER = "[kyb:spend-request]";
+export interface SpendRequestAsk {
+    readonly id: string;
+    readonly amount: number;
+    readonly currency: string;
+    readonly merchant?: string;
+    readonly merchant_url?: string;
+    readonly approval_url?: string;
+    readonly status: string;
+}
+export declare function spendRequestPrompt(ask: SpendRequestAsk): string;
+export declare function parseSpendRequestPrompt(prompt: string): {
+    ask: SpendRequestAsk;
+    text: string;
+} | null;
+export interface SpendRequestSnapshot {
+    id: string;
+    status: string;
+    amount: number;
+    currency: string;
+    merchant?: string;
+    merchant_url?: string;
+    approval_url?: string;
+}
+export declare function spendRequestSnapshot(id: string, options?: LinkCliAuthOptions): Promise<SpendRequestSnapshot | null>;
+export declare function spendRequestApprovalLink(id: string, options?: LinkCliAuthOptions): Promise<string | undefined>;
+/** Link settles a moment after the tap; look a few times before giving up. */
+export declare function spendRequestSettledStatus(id: string, options?: LinkCliAuthOptions): Promise<string>;
+export declare function cancelSpendRequest(id: string, options?: LinkCliAuthOptions): Promise<void>;
+/** What the agent's tool file passes to `ctx.ask` once it has a snapshot. The tool itself is authored in `agent/tools/` — eve compiles `"use workflow"` from source. */
+export declare function spendRequestAsk(current: SpendRequestSnapshot): {
+    prompt: string;
+    display: "confirmation";
+    options: ({
+        id: string;
+        label: string;
+        style: "primary";
+    } | {
+        id: string;
+        label: string;
+        style: "danger";
+    })[];
+};
+export declare const APPROVE_SPEND_REQUEST_DESCRIPTION = "Put a spend request in front of the person for approval and wait for their answer. Call this right after create_spend_request. It shows them the merchant, the total and the Link approval button, pauses until they confirm or cancel, then returns the request's real status from Link. Only proceed to pay_on_computer when it returns approved.";

package/dist/approve.js

@@ -0,0 +1,79 @@
+import { linkClient } from "./link-tools.js";
+/**
+ * The approval moment of a purchase, as one durable tool call.
+ *
+ * Link approves a spend request in the person's Link app. Before this the
+ * agent pasted the approval link as text and asked them to say when they were
+ * done. Now the tool asks through eve's question channel with a marker a
+ * Kybernesis client renders as a card — merchant, total, an "Approve in Link"
+ * button — and parks until they tap "I approved" or "Cancel". Then it checks
+ * with Link and returns the real status. The model sees one result.
+ */
+export const SPEND_REQUEST_MARKER = "[kyb:spend-request]";
+export function spendRequestPrompt(ask) {
+    const total = `${(ask.amount / 100).toFixed(2)} ${ask.currency.toUpperCase()}`;
+    const at = ask.merchant ? ` at ${ask.merchant}` : "";
+    const link = ask.approval_url ? ` Approve it in Link: ${ask.approval_url}` : "";
+    return `${SPEND_REQUEST_MARKER} ${JSON.stringify(ask)}\nA purchase of ${total}${at} is waiting for your approval.${link}`;
+}
+export function parseSpendRequestPrompt(prompt) {
+    if (!prompt.startsWith(SPEND_REQUEST_MARKER))
+        return null;
+    const nl = prompt.indexOf("\n");
+    const head = nl === -1 ? prompt : prompt.slice(0, nl);
+    try {
+        return { ask: JSON.parse(head.slice(SPEND_REQUEST_MARKER.length).trim()), text: nl === -1 ? "" : prompt.slice(nl + 1) };
+    }
+    catch {
+        return null;
+    }
+}
+export async function spendRequestSnapshot(id, options = {}) {
+    const link = linkClient(options);
+    const r = (await link.spendRequests.retrieve(id));
+    if (!r)
+        return null;
+    return { id: r.id, status: r.status, amount: r.amount, currency: r.currency, merchant: r.merchant_name ?? r.merchant, merchant_url: r.merchant_url, approval_url: r.approval_url };
+}
+export async function spendRequestApprovalLink(id, options = {}) {
+    const link = linkClient(options);
+    try {
+        const r = await link.spendRequests.requestApproval(id);
+        return r.approval_url;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Link settles a moment after the tap; look a few times before giving up. */
+export async function spendRequestSettledStatus(id, options = {}) {
+    const link = linkClient(options);
+    for (let i = 0; i < 6; i++) {
+        const r = await link.spendRequests.retrieve(id);
+        if (r && r.status !== "pending_approval" && r.status !== "created")
+            return r.status;
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+    const r = await link.spendRequests.retrieve(id);
+    return r?.status ?? "unknown";
+}
+export async function cancelSpendRequest(id, options = {}) {
+    try {
+        await linkClient(options).spendRequests.cancel(id);
+    }
+    catch {
+        /* already terminal */
+    }
+}
+/** What the agent's tool file passes to `ctx.ask` once it has a snapshot. The tool itself is authored in `agent/tools/` — eve compiles `"use workflow"` from source. */
+export function spendRequestAsk(current) {
+    return {
+        prompt: spendRequestPrompt(current),
+        display: "confirmation",
+        options: [
+            { id: "approved", label: "I approved it in Link", style: "primary" },
+            { id: "cancel", label: "Cancel this purchase", style: "danger" },
+        ],
+    };
+}
+export const APPROVE_SPEND_REQUEST_DESCRIPTION = "Put a spend request in front of the person for approval and wait for their answer. Call this right after create_spend_request. It shows them the merchant, the total and the Link approval button, pauses until they confirm or cancel, then returns the request's real status from Link. Only proceed to pay_on_computer when it returns approved.";

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export { linkCliAuth, linkCliAuthFile, readStoredAuth, NOT_SIGNED_IN, type LinkC
 export { payOnComputerTool } from "./pay-on-computer.js";
 export { PAYMENTS_INSTRUCTIONS } from "./instructions.js";
 export { linkTool, linkClient, sanitizeLinkOutput, LINK_TOOL_NAMES, type LinkToolName } from "./link-tools.js";
+export { spendRequestAsk, spendRequestPrompt, parseSpendRequestPrompt, APPROVE_SPEND_REQUEST_DESCRIPTION, SPEND_REQUEST_MARKER, type SpendRequestAsk, type SpendRequestSnapshot } from "./approve-ask.js";
+export { spendRequestSnapshot, spendRequestApprovalLink, spendRequestSettledStatus, cancelSpendRequest } from "./approve-steps.js";

package/dist/index.js

@@ -2,3 +2,5 @@ export { linkCliAuth, linkCliAuthFile, readStoredAuth, NOT_SIGNED_IN } from "./l
 export { payOnComputerTool } from "./pay-on-computer.js";
 export { PAYMENTS_INSTRUCTIONS } from "./instructions.js";
 export { linkTool, linkClient, sanitizeLinkOutput, LINK_TOOL_NAMES } from "./link-tools.js";
+export { spendRequestAsk, spendRequestPrompt, parseSpendRequestPrompt, APPROVE_SPEND_REQUEST_DESCRIPTION, SPEND_REQUEST_MARKER } from "./approve-ask.js";
+export { spendRequestSnapshot, spendRequestApprovalLink, spendRequestSettledStatus, cancelSpendRequest } from "./approve-steps.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. `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";
+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, then immediately `approve_spend_request` with its id. That shows the person the purchase with an approval button and waits for them; do not paste the approval link yourself and do not create a second request for the same purchase.\n3. When `approve_spend_request` returns 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,8 +4,8 @@ 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. \`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.
+2. \`create_spend_request\` with that merchant, those line items and that total, then immediately \`approve_spend_request\` with its id. That shows the person the purchase with an approval button and waits for them; do not paste the approval link yourself and do not create a second request for the same purchase.
+3. When \`approve_spend_request\` returns 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/payments",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -15,7 +15,17 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./ask": {
+      "types": "./dist/approve-ask.d.ts",
+      "import": "./dist/approve-ask.js",
+      "default": "./dist/approve-ask.js"
+    },
+    "./steps": {
+      "types": "./dist/approve-steps.d.ts",
+      "import": "./dist/approve-steps.js",
+      "default": "./dist/approve-steps.js"
+    }
   },
   "files": [
     "dist",