openclaw-skill-pinti 0.1.0

package/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: pinti-spend-policy
+version: 0.1.0
+description: Spend policy enforcement for AI agents. Evaluate every payment against PINTI policies before executing.
+author: pinti
+category: policy
+tags:
+  - spend
+  - policy
+  - guard
+  - payments
+  - compliance
+env:
+  - name: PINTI_API_KEY
+    required: true
+    description: Your PINTI API key (starts with pinti_)
+  - name: PINTI_URL
+    required: false
+    description: PINTI API base URL (defaults to https://pinti.ai)
+---
+
+# PINTI Spend Policy Skill
+
+Add spend policy enforcement to any OpenClaw agent. PINTI evaluates every payment against your configured policies and returns one of three decisions:
+
+- **ALLOW** — proceed with the payment (includes a Spend Authorization Token)
+- **DENY** — block the payment
+- **REQUIRE_APPROVAL** — pause and wait for human approval
+
+## Why Use This
+
+AI agents that spend money need guardrails. PINTI sits between your agent's intent to pay and the actual payment execution:
+
+```
+Agent → PINTI (policy check) → Payment rail (Stripe, Privacy.com, crypto, etc.)
+```
+
+Works with **any payment method** — PINTI doesn't handle payments, it decides whether they should happen.
+
+## Quick Start
+
+```typescript
+import { beforeSpendAction } from "openclaw-skill-pinti";
+
+const check = await beforeSpendAction({
+  agentId: "my-agent",
+  amountMinor: 5000, // $50.00
+  unit: "USD",
+  merchant: "openai.com",
+  category: "api",
+  reason: "API credits top-up",
+});
+
+if (check.action === "continue") {
+  await executePayment(); // your payment logic
+} else {
+  console.log("Blocked or paused:", check.reason);
+}
+```
+
+## API
+
+### beforeSpendAction(input) → SpendActionResult
+
+Hook pattern. Call before any spend action. Returns an action directive.
+
+| Action     | PINTI Decision     | What to Do                           |
+|------------|--------------------|--------------------------------------|
+| `continue` | ALLOW              | Proceed with the spend action        |
+| `block`    | DENY (or error)    | Stop. Do not execute.                |
+| `pause`    | REQUIRE_APPROVAL   | Wait for human approval.             |
+
+### guardedExecutor(input, executeFn) → GuardedExecutorResult
+
+Wraps an action function with a PINTI check. The function only runs if PINTI allows it.
+
+```typescript
+import { guardedExecutor } from "openclaw-skill-pinti";
+
+const result = await guardedExecutor(
+  { agentId: "my-agent", amountMinor: 3000, unit: "USD", merchant: "openai.com", category: "api", reason: "Credits" },
+  async () => {
+    return await stripe.paymentIntents.create({ amount: 3000, currency: "usd" });
+  }
+);
+
+if (result.executed) {
+  console.log("Payment created:", result.result);
+}
+```
+
+### checkSpend(input) → CheckSpendResult
+
+Direct evaluation. Returns status without throwing.
+
+```typescript
+import { checkSpend } from "openclaw-skill-pinti";
+
+const result = await checkSpend({ agentId: "agent-1", amountMinor: 10000, unit: "USD", merchant: "aws.amazon.com", category: "infra", reason: "Compute" });
+// result.status: "allowed" | "denied" | "needs_approval"
+```
+
+## Fail-Closed
+
+On API errors or network failures, all functions default to **block/denied**. Agents never spend money when the policy check fails.

package/dist/before-spend-action.d.ts

@@ -0,0 +1,10 @@
+import type { SpendInput, SpendActionResult } from "./types";
+/**
+ * Call before any spend action. Returns an action directive:
+ * - "continue" — PINTI says ALLOW. Proceed with the payment.
+ * - "block"    — PINTI says DENY (or an error occurred). Stop.
+ * - "pause"    — PINTI says REQUIRE_APPROVAL. Wait for human approval.
+ *
+ * On API errors, defaults to "block" (fail-closed).
+ */
+export declare function beforeSpendAction(input: SpendInput): Promise<SpendActionResult>;

package/dist/before-spend-action.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.beforeSpendAction = beforeSpendAction;
+const guard_1 = require("@pinti/guard");
+const client_1 = require("./client");
+/**
+ * Call before any spend action. Returns an action directive:
+ * - "continue" — PINTI says ALLOW. Proceed with the payment.
+ * - "block"    — PINTI says DENY (or an error occurred). Stop.
+ * - "pause"    — PINTI says REQUIRE_APPROVAL. Wait for human approval.
+ *
+ * On API errors, defaults to "block" (fail-closed).
+ */
+async function beforeSpendAction(input) {
+    try {
+        const client = (0, client_1.getClient)();
+        const result = await client.authorize({
+            agentId: input.agentId,
+            amountMinor: input.amountMinor,
+            currency: input.unit,
+            merchant: input.merchant,
+            category: input.category,
+            reason: input.reason,
+            metadata: input.metadata,
+        });
+        return {
+            action: "continue",
+            reason: result.decisionReason,
+            spendRequestId: result.spendRequestId,
+            sat: result.sat,
+        };
+    }
+    catch (err) {
+        if (err instanceof guard_1.SpendDeniedError) {
+            return {
+                action: "block",
+                reason: err.decisionReason,
+                spendRequestId: err.spendRequestId,
+            };
+        }
+        if (err instanceof guard_1.ApprovalRequiredError) {
+            return {
+                action: "pause",
+                reason: err.decisionReason,
+                spendRequestId: err.spendRequestId,
+            };
+        }
+        // Unknown error — fail closed
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+            action: "block",
+            reason: `Policy check failed: ${message}`,
+        };
+    }
+}

package/dist/check-spend.d.ts

@@ -0,0 +1,8 @@
+import type { SpendInput, CheckSpendResult } from "./types";
+/**
+ * Direct spend evaluation. Returns the policy decision without
+ * throwing errors — useful when the hook pattern doesn't fit.
+ *
+ * On API errors, defaults to "denied" (fail-closed).
+ */
+export declare function checkSpend(input: SpendInput): Promise<CheckSpendResult>;

package/dist/check-spend.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSpend = checkSpend;
+const guard_1 = require("@pinti/guard");
+const client_1 = require("./client");
+/**
+ * Direct spend evaluation. Returns the policy decision without
+ * throwing errors — useful when the hook pattern doesn't fit.
+ *
+ * On API errors, defaults to "denied" (fail-closed).
+ */
+async function checkSpend(input) {
+    try {
+        const client = (0, client_1.getClient)();
+        const result = await client.authorize({
+            agentId: input.agentId,
+            amountMinor: input.amountMinor,
+            currency: input.unit,
+            merchant: input.merchant,
+            category: input.category,
+            reason: input.reason,
+            metadata: input.metadata,
+        });
+        return {
+            status: "allowed",
+            reason: result.decisionReason,
+            spendRequestId: result.spendRequestId,
+            sat: result.sat,
+        };
+    }
+    catch (err) {
+        if (err instanceof guard_1.SpendDeniedError) {
+            return {
+                status: "denied",
+                reason: err.decisionReason,
+                spendRequestId: err.spendRequestId,
+            };
+        }
+        if (err instanceof guard_1.ApprovalRequiredError) {
+            return {
+                status: "needs_approval",
+                reason: err.decisionReason,
+                spendRequestId: err.spendRequestId,
+            };
+        }
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+            status: "denied",
+            reason: `Policy check failed: ${message}`,
+        };
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import { PintiGuard } from "@pinti/guard";
+/**
+ * Returns a singleton PintiGuard instance configured from environment variables.
+ *
+ * Env vars:
+ *   PINTI_API_KEY  — required
+ *   PINTI_URL      — optional, defaults to https://pinti.ai
+ */
+export declare function getClient(): PintiGuard;
+/** @internal Reset client singleton — for testing only. */
+export declare function _resetClient(): void;

package/dist/client.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClient = getClient;
+exports._resetClient = _resetClient;
+const guard_1 = require("@pinti/guard");
+let _client = null;
+/**
+ * Returns a singleton PintiGuard instance configured from environment variables.
+ *
+ * Env vars:
+ *   PINTI_API_KEY  — required
+ *   PINTI_URL      — optional, defaults to https://pinti.ai
+ */
+function getClient() {
+    if (_client)
+        return _client;
+    const apiKey = process.env.PINTI_API_KEY;
+    if (!apiKey) {
+        throw new Error("openclaw-skill-pinti: PINTI_API_KEY environment variable is required");
+    }
+    _client = new guard_1.PintiGuard({
+        apiKey,
+        baseUrl: process.env.PINTI_URL,
+    });
+    return _client;
+}
+/** @internal Reset client singleton — for testing only. */
+function _resetClient() {
+    _client = null;
+}

package/dist/guarded-executor.d.ts

@@ -0,0 +1,8 @@
+import type { SpendInput, GuardedExecutorResult } from "./types";
+/**
+ * Wraps an action function with a PINTI policy check.
+ * The action only executes if PINTI returns ALLOW.
+ *
+ * On API errors, defaults to not executing (fail-closed).
+ */
+export declare function guardedExecutor<T = unknown>(input: SpendInput, execute: () => Promise<T>): Promise<GuardedExecutorResult<T>>;

package/dist/guarded-executor.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guardedExecutor = guardedExecutor;
+const guard_1 = require("@pinti/guard");
+const client_1 = require("./client");
+/**
+ * Wraps an action function with a PINTI policy check.
+ * The action only executes if PINTI returns ALLOW.
+ *
+ * On API errors, defaults to not executing (fail-closed).
+ */
+async function guardedExecutor(input, execute) {
+    try {
+        const client = (0, client_1.getClient)();
+        const auth = await client.authorize({
+            agentId: input.agentId,
+            amountMinor: input.amountMinor,
+            currency: input.unit,
+            merchant: input.merchant,
+            category: input.category,
+            reason: input.reason,
+            metadata: input.metadata,
+        });
+        // ALLOW — execute the action
+        const result = await execute();
+        return {
+            executed: true,
+            result,
+            reason: auth.decisionReason,
+            spendRequestId: auth.spendRequestId,
+        };
+    }
+    catch (err) {
+        if (err instanceof guard_1.SpendDeniedError) {
+            return {
+                executed: false,
+                reason: err.decisionReason,
+                spendRequestId: err.spendRequestId,
+            };
+        }
+        if (err instanceof guard_1.ApprovalRequiredError) {
+            return {
+                executed: false,
+                reason: err.decisionReason,
+                spendRequestId: err.spendRequestId,
+            };
+        }
+        // Unknown error — fail closed
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+            executed: false,
+            reason: `Policy check failed: ${message}`,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { beforeSpendAction } from "./before-spend-action";
+export { guardedExecutor } from "./guarded-executor";
+export { checkSpend } from "./check-spend";
+export type { SpendInput, SpendActionResult, GuardedExecutorResult, CheckSpendResult, } from "./types";

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSpend = exports.guardedExecutor = exports.beforeSpendAction = void 0;
+var before_spend_action_1 = require("./before-spend-action");
+Object.defineProperty(exports, "beforeSpendAction", { enumerable: true, get: function () { return before_spend_action_1.beforeSpendAction; } });
+var guarded_executor_1 = require("./guarded-executor");
+Object.defineProperty(exports, "guardedExecutor", { enumerable: true, get: function () { return guarded_executor_1.guardedExecutor; } });
+var check_spend_1 = require("./check-spend");
+Object.defineProperty(exports, "checkSpend", { enumerable: true, get: function () { return check_spend_1.checkSpend; } });

package/dist/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test.js

@@ -0,0 +1,219 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_http_1 = __importDefault(require("node:http"));
+const before_spend_action_1 = require("./before-spend-action");
+const guarded_executor_1 = require("./guarded-executor");
+const check_spend_1 = require("./check-spend");
+// ----- Mock PINTI API Server -----
+let server;
+let port;
+// Controls what the mock server returns
+let mockResponse = {
+    status: 200,
+    body: {},
+};
+function setMockResponse(status, body) {
+    mockResponse = { status, body };
+}
+(0, node_test_1.before)(async () => {
+    server = node_http_1.default.createServer((req, res) => {
+        let rawBody = "";
+        req.on("data", (chunk) => (rawBody += chunk));
+        req.on("end", () => {
+            // Verify API key header
+            const apiKey = req.headers["x-api-key"];
+            if (apiKey !== "test_key") {
+                res.writeHead(401, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Unauthorized" }));
+                return;
+            }
+            res.writeHead(mockResponse.status, {
+                "Content-Type": "application/json",
+            });
+            res.end(JSON.stringify(mockResponse.body));
+        });
+    });
+    await new Promise((resolve) => {
+        server.listen(0, () => {
+            const addr = server.address();
+            port = typeof addr === "object" && addr ? addr.port : 0;
+            // Configure env vars BEFORE any client is created
+            process.env.PINTI_API_KEY = "test_key";
+            process.env.PINTI_URL = `http://localhost:${port}`;
+            resolve();
+        });
+    });
+});
+(0, node_test_1.after)(() => {
+    server.close();
+});
+// ----- beforeSpendAction tests -----
+(0, node_test_1.describe)("beforeSpendAction", () => {
+    const input = {
+        agentId: "test-agent",
+        amountMinor: 5000,
+        unit: "USD",
+        merchant: "openai.com",
+        category: "api",
+        reason: "Test spend",
+    };
+    (0, node_test_1.it)("returns 'continue' on ALLOW", async () => {
+        setMockResponse(200, {
+            decision: "ALLOW",
+            decisionReason: "Within policy limits",
+            spendRequestId: "sr_123",
+            sat: "eyJhbGciOi...",
+        });
+        const result = await (0, before_spend_action_1.beforeSpendAction)(input);
+        strict_1.default.equal(result.action, "continue");
+        strict_1.default.equal(result.reason, "Within policy limits");
+        strict_1.default.equal(result.spendRequestId, "sr_123");
+        strict_1.default.equal(result.sat, "eyJhbGciOi...");
+    });
+    (0, node_test_1.it)("returns 'block' on DENY", async () => {
+        setMockResponse(200, {
+            decision: "DENY",
+            decisionReason: "Exceeds daily limit",
+            spendRequestId: "sr_456",
+        });
+        const result = await (0, before_spend_action_1.beforeSpendAction)(input);
+        strict_1.default.equal(result.action, "block");
+        strict_1.default.equal(result.reason, "Exceeds daily limit");
+        strict_1.default.equal(result.spendRequestId, "sr_456");
+        strict_1.default.equal(result.sat, undefined);
+    });
+    (0, node_test_1.it)("returns 'pause' on REQUIRE_APPROVAL", async () => {
+        setMockResponse(200, {
+            decision: "REQUIRE_APPROVAL",
+            decisionReason: "Amount exceeds auto-approve threshold",
+            spendRequestId: "sr_789",
+        });
+        const result = await (0, before_spend_action_1.beforeSpendAction)(input);
+        strict_1.default.equal(result.action, "pause");
+        strict_1.default.equal(result.reason, "Amount exceeds auto-approve threshold");
+        strict_1.default.equal(result.spendRequestId, "sr_789");
+    });
+    (0, node_test_1.it)("returns 'block' on network error (fail-closed)", async () => {
+        // Point to a port that doesn't exist
+        const origUrl = process.env.PINTI_URL;
+        process.env.PINTI_URL = "http://localhost:1";
+        // Force new client by clearing the singleton
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const clientModule = require("./client");
+        clientModule._resetClient?.();
+        const result = await (0, before_spend_action_1.beforeSpendAction)(input);
+        strict_1.default.equal(result.action, "block");
+        strict_1.default.ok(result.reason.includes("Policy check failed"));
+        // Restore
+        process.env.PINTI_URL = origUrl;
+        clientModule._resetClient?.();
+    });
+});
+// ----- guardedExecutor tests -----
+(0, node_test_1.describe)("guardedExecutor", () => {
+    const input = {
+        agentId: "test-agent",
+        amountMinor: 3000,
+        unit: "USD",
+        merchant: "stripe.com",
+        category: "api",
+        reason: "Payment processing",
+    };
+    (0, node_test_1.it)("executes callback on ALLOW", async () => {
+        setMockResponse(200, {
+            decision: "ALLOW",
+            decisionReason: "Allowed",
+            spendRequestId: "sr_exec_1",
+            sat: "token123",
+        });
+        let callbackRan = false;
+        const result = await (0, guarded_executor_1.guardedExecutor)(input, async () => {
+            callbackRan = true;
+            return { paymentId: "pi_abc" };
+        });
+        strict_1.default.equal(result.executed, true);
+        strict_1.default.equal(callbackRan, true);
+        strict_1.default.deepEqual(result.result, { paymentId: "pi_abc" });
+        strict_1.default.equal(result.reason, "Allowed");
+        strict_1.default.equal(result.spendRequestId, "sr_exec_1");
+    });
+    (0, node_test_1.it)("does NOT execute callback on DENY", async () => {
+        setMockResponse(200, {
+            decision: "DENY",
+            decisionReason: "Budget exhausted",
+            spendRequestId: "sr_exec_2",
+        });
+        let callbackRan = false;
+        const result = await (0, guarded_executor_1.guardedExecutor)(input, async () => {
+            callbackRan = true;
+            return "should not run";
+        });
+        strict_1.default.equal(result.executed, false);
+        strict_1.default.equal(callbackRan, false);
+        strict_1.default.equal(result.result, undefined);
+        strict_1.default.equal(result.reason, "Budget exhausted");
+    });
+    (0, node_test_1.it)("does NOT execute callback on REQUIRE_APPROVAL", async () => {
+        setMockResponse(200, {
+            decision: "REQUIRE_APPROVAL",
+            decisionReason: "Needs manager sign-off",
+            spendRequestId: "sr_exec_3",
+        });
+        let callbackRan = false;
+        const result = await (0, guarded_executor_1.guardedExecutor)(input, async () => {
+            callbackRan = true;
+            return "nope";
+        });
+        strict_1.default.equal(result.executed, false);
+        strict_1.default.equal(callbackRan, false);
+        strict_1.default.equal(result.reason, "Needs manager sign-off");
+    });
+});
+// ----- checkSpend tests -----
+(0, node_test_1.describe)("checkSpend", () => {
+    const input = {
+        agentId: "agent-1",
+        amountMinor: 10000,
+        unit: "USD",
+        merchant: "aws.amazon.com",
+        category: "infra",
+        reason: "Compute provisioning",
+    };
+    (0, node_test_1.it)("returns 'allowed' on ALLOW", async () => {
+        setMockResponse(200, {
+            decision: "ALLOW",
+            decisionReason: "OK",
+            spendRequestId: "sr_chk_1",
+            sat: "sat_token",
+        });
+        const result = await (0, check_spend_1.checkSpend)(input);
+        strict_1.default.equal(result.status, "allowed");
+        strict_1.default.equal(result.reason, "OK");
+        strict_1.default.equal(result.sat, "sat_token");
+    });
+    (0, node_test_1.it)("returns 'denied' on DENY", async () => {
+        setMockResponse(200, {
+            decision: "DENY",
+            decisionReason: "Blocked by policy",
+            spendRequestId: "sr_chk_2",
+        });
+        const result = await (0, check_spend_1.checkSpend)(input);
+        strict_1.default.equal(result.status, "denied");
+        strict_1.default.equal(result.reason, "Blocked by policy");
+    });
+    (0, node_test_1.it)("returns 'needs_approval' on REQUIRE_APPROVAL", async () => {
+        setMockResponse(200, {
+            decision: "REQUIRE_APPROVAL",
+            decisionReason: "High amount",
+            spendRequestId: "sr_chk_3",
+        });
+        const result = await (0, check_spend_1.checkSpend)(input);
+        strict_1.default.equal(result.status, "needs_approval");
+        strict_1.default.equal(result.reason, "High amount");
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+/** Input for all spend evaluation functions. */
+export interface SpendInput {
+    /** Unique identifier of the agent making the spend request. */
+    agentId: string;
+    /** Amount in minor units (e.g. 4200 = $42.00). */
+    amountMinor: number;
+    /** Currency/unit code (e.g. "USD", "EUR"). */
+    unit: string;
+    /** Merchant or service receiving the payment. */
+    merchant: string;
+    /** Spend category (e.g. "api", "infra", "saas"). */
+    category: string;
+    /** Human-readable reason for the spend. */
+    reason: string;
+    /** Optional metadata key-value pairs. */
+    metadata?: Record<string, string>;
+}
+/** Result of beforeSpendAction(). */
+export interface SpendActionResult {
+    /** Action directive for the agent. */
+    action: "continue" | "block" | "pause";
+    /** Explanation of the decision. */
+    reason: string;
+    /** PINTI spend request ID for tracking. */
+    spendRequestId?: string;
+    /** Spend Authorization Token — present only on "continue". */
+    sat?: string;
+}
+/** Result of guardedExecutor(). */
+export interface GuardedExecutorResult<T = unknown> {
+    /** Whether the action callback was executed. */
+    executed: boolean;
+    /** Return value of the action callback (only if executed). */
+    result?: T;
+    /** Explanation of the decision. */
+    reason: string;
+    /** PINTI spend request ID for tracking. */
+    spendRequestId?: string;
+}
+/** Result of checkSpend(). */
+export interface CheckSpendResult {
+    /** Policy evaluation status. */
+    status: "allowed" | "denied" | "needs_approval";
+    /** Explanation of the decision. */
+    reason: string;
+    /** PINTI spend request ID for tracking. */
+    spendRequestId?: string;
+    /** Spend Authorization Token — present only on "allowed". */
+    sat?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "openclaw-skill-pinti",
+  "version": "0.1.0",
+  "description": "OpenClaw skill for PINTI — spend policy enforcement for AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "SKILL.md"],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "openclaw",
+    "skill",
+    "pinti",
+    "ai",
+    "agent",
+    "spend",
+    "policy",
+    "guard"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@pinti/guard": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@pinti/guard": "^0.1.0",
+    "typescript": "^5.5.0"
+  }
+}