@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.1

package/dist/esm/registries/builder.d.ts

@@ -0,0 +1,340 @@
+/**
+ * @module registries/builder
+ * @description Fluent agent registration builder.
+ *
+ * Provides a chainable API for registering a fully-configured agent
+ * in a single flow — identity, capabilities, pricing tiers, tools,
+ * x402 endpoint, and discovery indexes.
+ *
+ * Instead of calling 5+ separate instructions manually, developers
+ * use a single builder chain that validates inputs and batches
+ * the registration cleanly.
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const result = await client.builder
+ *   .agent("SwapBot")
+ *   .description("AI-powered Jupiter swap agent")
+ *   .x402Endpoint("https://swapbot.example.com/x402")
+ *   .addCapability("jupiter:swap", { protocol: "jupiter", version: "6.0" })
+ *   .addCapability("jupiter:quote", { protocol: "jupiter", version: "6.0" })
+ *   .addPricingTier({
+ *     tierId: "standard",
+ *     pricePerCall: 1000,
+ *     rateLimit: 60,
+ *     tokenType: "sol",
+ *     settlementMode: "x402",
+ *   })
+ *   .addProtocol("jupiter")
+ *   .register();
+ *
+ * // Or register with tools:
+ * const result = await client.builder
+ *   .agent("DataBot")
+ *   .description("Real-time DeFi data feeds")
+ *   .addTool({ name: "getPrice", protocol: "pyth", category: "data", ... })
+ *   .registerWithTools();
+ * ```
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import type { SapProgram } from "../modules/base";
+import { TOOL_CATEGORY_VALUES } from "../constants";
+/**
+ * @interface CapabilityInput
+ * @name CapabilityInput
+ * @description Simplified capability input for the builder.
+ * Defines the protocol, version, and description of a capability
+ * to register with the agent.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface CapabilityInput {
+    readonly protocol?: string;
+    readonly version?: string;
+    readonly description?: string;
+}
+/**
+ * @interface PricingTierInput
+ * @name PricingTierInput
+ * @description Simplified pricing tier input for the builder.
+ * Supports flat-rate, tiered, and volume-curve pricing with
+ * configurable token types and settlement modes.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface PricingTierInput {
+    readonly tierId: string;
+    readonly pricePerCall: number | string | BN;
+    readonly rateLimit: number;
+    readonly maxCallsPerSession?: number;
+    readonly burstLimit?: number;
+    readonly tokenType?: "sol" | "usdc" | "spl";
+    readonly tokenMint?: PublicKey;
+    readonly tokenDecimals?: number;
+    readonly settlementMode?: "instant" | "escrow" | "batched" | "x402";
+    readonly minEscrowDeposit?: number | string | BN;
+    readonly batchIntervalSec?: number;
+    readonly minPricePerCall?: number | string | BN;
+    readonly maxPricePerCall?: number | string | BN;
+    readonly volumeCurve?: Array<{
+        afterCalls: number;
+        pricePerCall: number | string | BN;
+    }>;
+}
+/**
+ * @interface ToolInput
+ * @name ToolInput
+ * @description Simplified tool input for batch registration via {@link AgentBuilder.registerWithTools}.
+ * Defines the tool’s name, protocol, schemas, HTTP method, and category.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface ToolInput {
+    readonly name: string;
+    readonly protocol: string;
+    readonly description: string;
+    readonly inputSchema: string;
+    readonly outputSchema: string;
+    readonly httpMethod?: "get" | "post" | "put" | "delete" | "compound";
+    readonly category?: keyof typeof TOOL_CATEGORY_VALUES;
+    readonly paramsCount: number;
+    readonly requiredParams: number;
+    readonly isCompound?: boolean;
+}
+/**
+ * @interface RegisterResult
+ * @name RegisterResult
+ * @description Result of a successful agent registration.
+ * Contains the transaction signature and derived PDA addresses.
+ * Returned by {@link AgentBuilder.register}.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface RegisterResult {
+    /** Transaction signature for agent registration. */
+    readonly txSignature: TransactionSignature;
+    /** Derived agent PDA. */
+    readonly agentPda: PublicKey;
+    /** Derived agent stats PDA. */
+    readonly statsPda: PublicKey;
+}
+/**
+ * @interface RegisterWithToolsResult
+ * @name RegisterWithToolsResult
+ * @description Result of agent + tools registration.
+ * Extends {@link RegisterResult} with tool publication transaction signatures.
+ * Returned by {@link AgentBuilder.registerWithTools}.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface RegisterWithToolsResult extends RegisterResult {
+    /** Transaction signatures for tool publications. */
+    readonly toolSignatures: Array<{
+        readonly name: string;
+        readonly txSignature: TransactionSignature;
+    }>;
+}
+/**
+ * @name AgentBuilder
+ * @description Fluent builder for registering a fully-configured agent on-chain.
+ *
+ * Chains identity setters, capability/pricing/protocol adders, and tool
+ * definitions into a single validated registration flow. Validates all
+ * inputs against on-chain limits before sending transactions.
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const result = await client.builder
+ *   .agent("SwapBot")
+ *   .description("AI-powered Jupiter swap agent")
+ *   .x402Endpoint("https://swapbot.example.com/x402")
+ *   .addCapability("jupiter:swap", { protocol: "jupiter", version: "6.0" })
+ *   .addPricingTier({ tierId: "standard", pricePerCall: 1000, rateLimit: 60 })
+ *   .register();
+ * ```
+ */
+export declare class AgentBuilder {
+    private readonly program;
+    private readonly wallet;
+    private _name;
+    private _description;
+    private _agentId;
+    private _agentUri;
+    private _x402Endpoint;
+    private _capabilities;
+    private _pricing;
+    private _protocols;
+    private _tools;
+    constructor(program: SapProgram);
+    /**
+     * @name agent
+     * @description Set the agent display name.
+     * @param name - Display name (max 64 characters).
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    agent(name: string): this;
+    /**
+     * @name description
+     * @description Set the agent description.
+     * @param desc - Description text (max 256 characters).
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    description(desc: string): this;
+    /**
+     * @name agentId
+     * @description Set a DID-style agent identifier.
+     * @param id - Agent identifier string.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    agentId(id: string): this;
+    /**
+     * @name agentUri
+     * @description Set an agent metadata URI.
+     * @param uri - Metadata URI string.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    agentUri(uri: string): this;
+    /**
+     * @name x402Endpoint
+     * @description Set the x402 payment endpoint URL.
+     * @param url - The x402 endpoint URL for the agent.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    x402Endpoint(url: string): this;
+    /**
+     * @name addCapability
+     * @description Add a capability to the agent.
+     *
+     * @param id - Capability identifier string (e.g. `"jupiter:swap"`).
+     * @param opts - Optional capability metadata.
+     * @param opts.protocol - Protocol the capability belongs to.
+     * @param opts.version - Capability version string.
+     * @param opts.description - Human-readable capability description.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * builder.addCapability("jupiter:swap", { protocol: "jupiter", version: "6.0" })
+     * ```
+     */
+    addCapability(id: string, opts?: CapabilityInput): this;
+    /**
+     * @name addPricingTier
+     * @description Add a pricing tier for the agent's services.
+     * Supports flat-rate, volume-curve, and configurable settlement modes.
+     *
+     * @param input - Pricing tier configuration.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * builder.addPricingTier({
+     *   tierId: "standard",
+     *   pricePerCall: 1000,
+     *   rateLimit: 60,
+     *   tokenType: "sol",
+     *   settlementMode: "x402",
+     * })
+     * ```
+     */
+    addPricingTier(input: PricingTierInput): this;
+    /**
+     * @name addProtocol
+     * @description Add a protocol the agent supports.
+     * Duplicates are silently ignored.
+     *
+     * @param protocolId - Protocol identifier string (e.g. `"jupiter"`).
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * builder.addProtocol("jupiter")
+     * ```
+     */
+    addProtocol(protocolId: string): this;
+    /**
+     * @name addTool
+     * @description Add a tool to be published after registration.
+     * Only used with {@link AgentBuilder.registerWithTools}.
+     *
+     * @param tool - Tool configuration.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    addTool(tool: ToolInput): this;
+    /**
+     * @name register
+     * @description Register the agent on-chain.
+     * Validates all inputs before sending the transaction.
+     *
+     * @returns A {@link RegisterResult} with the transaction signature and derived PDAs.
+     * @throws If validation fails (missing name, description, or limit exceeded).
+     * @since v0.1.0
+     */
+    register(): Promise<RegisterResult>;
+    /**
+     * @name registerWithTools
+     * @description Register the agent AND publish all configured tools.
+     * Sends agent registration first, then tool publications sequentially.
+     *
+     * @returns A {@link RegisterWithToolsResult} with agent and tool transaction signatures.
+     * @throws If validation fails or any tool publication fails.
+     * @since v0.1.0
+     */
+    registerWithTools(): Promise<RegisterWithToolsResult>;
+    /**
+     * @name reset
+     * @description Reset the builder to its initial state.
+     * Clears all configured values so the builder can be reused.
+     *
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    reset(): this;
+    /**
+     * @name validate
+     * @description Validate all builder inputs against on-chain limits.
+     * @throws If any required field is missing or any limit is exceeded.
+     * @private
+     */
+    private validate;
+    /**
+     * @name resolveTokenType
+     * @description Resolve a token type string to the on-chain enum variant.
+     * @param t - Token type string (`"sol"`, `"usdc"`, or `"spl"`).
+     * @returns The corresponding {@link TokenTypeKind} enum value.
+     * @private
+     */
+    private resolveTokenType;
+    /**
+     * @name resolveSettlementMode
+     * @description Resolve a settlement mode string to the on-chain enum variant.
+     * @param m - Settlement mode string (`"instant"`, `"escrow"`, `"batched"`, or `"x402"`).
+     * @returns The corresponding {@link SettlementModeKind} enum value.
+     * @private
+     */
+    private resolveSettlementMode;
+    /**
+     * @name methods
+     * @description Accessor for the Anchor program methods namespace.
+     * @returns The program methods object for building RPC calls.
+     * @private
+     */
+    private get methods();
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/esm/registries/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/registries/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAuB,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQlD,OAAO,EAAU,oBAAoB,EAAsB,MAAM,cAAc,CAAC;AAchF;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IACpE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC;IACjD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC;IAChD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC;IAChD,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;CAC1F;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAC;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,oBAAoB,CAAC;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D,oDAAoD;IACpD,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;KAC5C,CAAC,CAAC;CACJ;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IAYX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAXpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,aAAa,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,MAAM,CAAmB;gBAEJ,OAAO,EAAE,UAAU;IAMhD;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMzB;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM/B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMzB;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM3B;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM/B;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI;IAcvD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IA0C7C;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAWrC;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAO9B;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IA8BzC;;;;;;;;OAQG;IACG,iBAAiB,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAiD3D;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IAeb;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAmBhB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;;;;OAKG;IAEH,OAAO,KAAK,OAAO,GAGlB;CACF"}