@escro/plugin-sak 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,91 @@
+import { Keypair } from '@solana/web3.js';
+import { EscroOptions, SpendCap, X402SpendCap } from '@escro/sdk';
+import { z } from 'zod';
+
+/**
+ * Minimal vendored type surface for `solana-agent-kit`, Apache-2.0.
+ *
+ * `solana-agent-kit` is provided by the host agent and declared in no dependency list; this plugin imports no runtime
+ * value from it, and its dependency tree is out of proportion to a handful of erased types. Each declaration below is a consume-only structural subset of the published declarations of:
+ *
+ *   solana-agent-kit@2.0.10  dist/index.d.ts
+ *
+ * The kit spells `any` where this file spells `unknown`. A real `SolanaAgentKit` remains assignable to `SakAgent` and
+ * the plugin to the kit's `Plugin`. If a later kit major changes these shapes, re-verify against its declarations.
+ */
+
+/** The part of `SolanaAgentKit` this plugin reads: `BaseWallet.publicKey`, and no signing method. */
+interface SakAgent {
+    wallet: {
+        publicKey: {
+            toBase58(): string;
+        };
+    };
+}
+type Handler = (agent: SakAgent, input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+interface ActionExample {
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+    explanation: string;
+}
+interface Action {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: ActionExample[][];
+    schema: z.ZodType<unknown>;
+    handler: Handler;
+}
+interface Plugin {
+    name: string;
+    methods: Record<string, unknown>;
+    actions: Action[];
+    initialize(agent: SakAgent): void;
+}
+
+type EscroActionName = "escro_commission" | "escro_claim" | "escro_submit" | "escro_release" | "escro_read_escrow" | "escro_find_workers" | "escro_reputation" | "escro_pay_402";
+
+/** A set-up refusal, or a failure after money may have moved. */
+declare class EscroPluginError extends Error {
+    /** The SDK's code on a failure after money may have moved; absent on a set-up refusal. */
+    readonly code?: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+
+interface EscroSakPluginOptions {
+    /** The agent wallet's own keypair; passed only to the SDK, which alone signs. */
+    wallet: Keypair;
+    /** Required; a missing cluster never defaults to devnet. */
+    cluster: EscroOptions["cluster"];
+    /** Passed through unchanged; the SDK refuses a mainnet commission without it. */
+    spendCap?: SpendCap;
+    /** Passed through unchanged; the SDK refuses a mainnet `exact` payment without it. */
+    x402SpendCap?: X402SpendCap;
+    /** Defaults to the cluster's public Escro API. */
+    apiUrl?: string;
+    /** Defaults to the cluster's public RPC endpoint. */
+    rpcUrl?: string;
+    /**
+     * Lets escro_pay_402 pay a URL whose host is a loopback, link-local or private address (a local
+     * worker). Off by default. On mainnet a public host is still paid only over https:.
+     */
+    allowPrivateHosts?: boolean;
+}
+interface EscroSakPlugin {
+    name: "escro";
+    methods: Record<EscroActionName, Handler>;
+    actions: Action[];
+    initialize(agent: SakAgent): void;
+}
+/**
+ * The Solana Agent Kit plugin: `agent.use(createEscroPlugin({ wallet, cluster, ... }))`.
+ *
+ * The keypair lives only in this closure and the SDK client, so no dump of the plugin can show it.
+ */
+declare function createEscroPlugin(options: EscroSakPluginOptions): EscroSakPlugin;
+
+export { EscroPluginError, createEscroPlugin };
+export type { Action, ActionExample, EscroActionName, EscroSakPlugin, EscroSakPluginOptions, Handler, Plugin, SakAgent };

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { Keypair } from '@solana/web3.js';
+import { EscroOptions, SpendCap, X402SpendCap } from '@escro/sdk';
+import { z } from 'zod';
+
+/**
+ * Minimal vendored type surface for `solana-agent-kit`, Apache-2.0.
+ *
+ * `solana-agent-kit` is provided by the host agent and declared in no dependency list; this plugin imports no runtime
+ * value from it, and its dependency tree is out of proportion to a handful of erased types. Each declaration below is a consume-only structural subset of the published declarations of:
+ *
+ *   solana-agent-kit@2.0.10  dist/index.d.ts
+ *
+ * The kit spells `any` where this file spells `unknown`. A real `SolanaAgentKit` remains assignable to `SakAgent` and
+ * the plugin to the kit's `Plugin`. If a later kit major changes these shapes, re-verify against its declarations.
+ */
+
+/** The part of `SolanaAgentKit` this plugin reads: `BaseWallet.publicKey`, and no signing method. */
+interface SakAgent {
+    wallet: {
+        publicKey: {
+            toBase58(): string;
+        };
+    };
+}
+type Handler = (agent: SakAgent, input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+interface ActionExample {
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+    explanation: string;
+}
+interface Action {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: ActionExample[][];
+    schema: z.ZodType<unknown>;
+    handler: Handler;
+}
+interface Plugin {
+    name: string;
+    methods: Record<string, unknown>;
+    actions: Action[];
+    initialize(agent: SakAgent): void;
+}
+
+type EscroActionName = "escro_commission" | "escro_claim" | "escro_submit" | "escro_release" | "escro_read_escrow" | "escro_find_workers" | "escro_reputation" | "escro_pay_402";
+
+/** A set-up refusal, or a failure after money may have moved. */
+declare class EscroPluginError extends Error {
+    /** The SDK's code on a failure after money may have moved; absent on a set-up refusal. */
+    readonly code?: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+
+interface EscroSakPluginOptions {
+    /** The agent wallet's own keypair; passed only to the SDK, which alone signs. */
+    wallet: Keypair;
+    /** Required; a missing cluster never defaults to devnet. */
+    cluster: EscroOptions["cluster"];
+    /** Passed through unchanged; the SDK refuses a mainnet commission without it. */
+    spendCap?: SpendCap;
+    /** Passed through unchanged; the SDK refuses a mainnet `exact` payment without it. */
+    x402SpendCap?: X402SpendCap;
+    /** Defaults to the cluster's public Escro API. */
+    apiUrl?: string;
+    /** Defaults to the cluster's public RPC endpoint. */
+    rpcUrl?: string;
+    /**
+     * Lets escro_pay_402 pay a URL whose host is a loopback, link-local or private address (a local
+     * worker). Off by default. On mainnet a public host is still paid only over https:.
+     */
+    allowPrivateHosts?: boolean;
+}
+interface EscroSakPlugin {
+    name: "escro";
+    methods: Record<EscroActionName, Handler>;
+    actions: Action[];
+    initialize(agent: SakAgent): void;
+}
+/**
+ * The Solana Agent Kit plugin: `agent.use(createEscroPlugin({ wallet, cluster, ... }))`.
+ *
+ * The keypair lives only in this closure and the SDK client, so no dump of the plugin can show it.
+ */
+declare function createEscroPlugin(options: EscroSakPluginOptions): EscroSakPlugin;
+
+export { EscroPluginError, createEscroPlugin };
+export type { Action, ActionExample, EscroActionName, EscroSakPlugin, EscroSakPluginOptions, Handler, Plugin, SakAgent };