@oobe-protocol-labs/sap-mcp-server 0.9.1 → 0.9.3

package/dist/sap/sap-client-manager.d.ts

@@ -1,13 +1,29 @@
 /**
- * SAP Client Manager
+ * @name sap/sap-client-manager
+ * @description Creates and manages the SAP SDK client (`SapClient`) as a singleton with
+ * connection, wallet, and program ID configuration.
  *
- * Creates and manages SapClient from @oobe-protocol-labs/synapse-sap-sdk
- * with proper connection, wallet, and program ID configuration.
+ * @flow
+ *   1. `SapClientManager.getInstance()` returns the singleton manager.
+ *   2. `initialize(config)` creates a `SapClient` from the SDK, loading a wallet when needed.
+ *   3. If config hasn't changed, the existing client is reused.
+ *   4. `createSapClient`, `getSapClient`, and `isSapClientInitialized` are convenience wrappers.
+ *
+ * @module sap/sap-client-manager
  */
 import type { SapMcpConfig } from '../core/types.js';
 import type { SapClient } from '@oobe-protocol-labs/synapse-sap-sdk';
 /**
- * SAP Client Manager
+ * @name SapClientManager
+ * @description Singleton manager for the SAP SDK client with config-aware reinitialization.
+ *
+ * @method getInstance     — Returns the singleton `SapClientManager` instance.
+ * @method initialize      — Creates or reuses the `SapClient` based on config changes.
+ * @method getClient       — Returns the initialized client (throws if not initialized).
+ * @method getClientOrNull — Returns the initialized client or `null`.
+ * @method reset           — Resets the client and config (for testing).
+ *
+ * @usedBy `createSapClient`, `getSapClient`, `isSapClientInitialized`, `create-server.ts`
  */
 export declare class SapClientManager {
     private static instance;
@@ -15,40 +31,91 @@ export declare class SapClientManager {
     private config;
     private constructor();
     /**
-     * Compares the connection and wallet fields that affect SapClient construction.
+     * @name SapClientManager.isSameClientConfig
+     * @description Compares connection and wallet fields that affect SapClient construction.
+     *
+     * @param current — Current stored config.
+     * @param next    — New config to compare against.
+     * @returns `true` if the relevant config fields match, `false` otherwise.
+     *
+     * @internal
      */
     private isSameClientConfig;
     /**
-     * Get singleton instance
+     * @name SapClientManager.getInstance
+     * @description Returns the singleton `SapClientManager` instance, creating it if necessary.
+     *
+     * @returns The singleton `SapClientManager`.
+     *
+     * @usedBy `createSapClient`, `getSapClient`, `isSapClientInitialized`.
      */
     static getInstance(): SapClientManager;
     /**
-     * Initialize SAP client from config
+     * @name SapClientManager.initialize
+     * @description Initializes the SAP client from config, reusing the existing client if config hasn't changed.
+     *
+     * @param config — SAP MCP configuration with RPC URL, program ID, mode, and wallet path.
+     * @returns The initialized `SapClient` instance.
+     * @throws `SapClientError` if client creation fails.
+     *
+     * @usedBy `createSapClient`, `create-server.ts:createSapMcpServer`.
      */
     initialize(config: SapMcpConfig): Promise<SapClient>;
     /**
-     * Get SAP client instance
+     * @name SapClientManager.getClient
+     * @description Returns the initialized SAP client.
+     *
+     * @returns The `SapClient` instance.
+     * @throws `SapClientError` if the client has not been initialized.
+     *
+     * @usedBy `getSapClient`.
      */
     getClient(): SapClient;
     /**
-     * Get client or null if not initialized
+     * @name SapClientManager.getClientOrNull
+     * @description Returns the initialized SAP client or `null` if not yet initialized.
+     *
+     * @returns The `SapClient` instance or `null`.
+     *
+     * @usedBy `isSapClientInitialized`.
      */
     getClientOrNull(): SapClient | null;
     /**
-     * Reset client (for testing)
+     * @name SapClientManager.reset
+     * @description Resets the client and config to `null` (for testing purposes).
+     *
+     * @usedBy Test setup and teardown.
      */
     reset(): void;
 }
 /**
- * Create SAP client from config
+ * @name createSapClient
+ * @description Creates or reuses the SAP client from the given configuration.
+ *
+ * @param config — SAP MCP configuration.
+ * @returns The initialized `SapClient` instance.
+ * @throws `SapClientError` if initialization fails.
+ *
+ * @usedBy `create-server.ts:createSapMcpServer`.
  */
 export declare function createSapClient(config: SapMcpConfig): Promise<SapClient>;
 /**
- * Get existing SAP client
+ * @name getSapClient
+ * @description Returns the currently initialized SAP client.
+ *
+ * @returns The `SapClient` instance.
+ * @throws `SapClientError` if the client has not been initialized.
+ *
+ * @usedBy Tool handlers across the SAP MCP runtime.
  */
 export declare function getSapClient(): SapClient;
 /**
- * Check if SAP client is initialized
+ * @name isSapClientInitialized
+ * @description Checks whether the SAP client has been initialized.
+ *
+ * @returns `true` if the client is initialized, `false` otherwise.
+ *
+ * @usedBy Health checks and startup validation.
  */
 export declare function isSapClientInitialized(): boolean;
 //# sourceMappingURL=sap-client-manager.d.ts.map

package/dist/sap/sap-client-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sap-client-manager.d.ts","sourceRoot":"","sources":["../../src/sap/sap-client-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAErE;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IACxD,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,MAAM,CAA6B;IAE3C,OAAO;IAEP;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAOtC;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;IAqD1D;;OAEG;IACH,SAAS,IAAI,SAAS;IAOtB;;OAEG;IACH,eAAe,IAAI,SAAS,GAAG,IAAI;IAInC;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAG9E;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAGxC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD"}
+{"version":3,"file":"sap-client-manager.d.ts","sourceRoot":"","sources":["../../src/sap/sap-client-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IACxD,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,MAAM,CAA6B;IAE3C,OAAO;IAEP;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAOtC;;;;;;;;;OASG;IACG,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;IAqD1D;;;;;;;;OAQG;IACH,SAAS,IAAI,SAAS;IAOtB;;;;;;;OAOG;IACH,eAAe,IAAI,SAAS,GAAG,IAAI;IAInC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAKd;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAG9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAGxC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD"}

package/dist/sap/sap-client-manager.js

@@ -1,15 +1,31 @@
 /**
- * SAP Client Manager
+ * @name sap/sap-client-manager
+ * @description Creates and manages the SAP SDK client (`SapClient`) as a singleton with
+ * connection, wallet, and program ID configuration.
  *
- * Creates and manages SapClient from @oobe-protocol-labs/synapse-sap-sdk
- * with proper connection, wallet, and program ID configuration.
+ * @flow
+ *   1. `SapClientManager.getInstance()` returns the singleton manager.
+ *   2. `initialize(config)` creates a `SapClient` from the SDK, loading a wallet when needed.
+ *   3. If config hasn't changed, the existing client is reused.
+ *   4. `createSapClient`, `getSapClient`, and `isSapClientInitialized` are convenience wrappers.
+ *
+ * @module sap/sap-client-manager
  */
 import { createSapClient as createSdkClient } from '@oobe-protocol-labs/synapse-sap-sdk';
 import { Wallet } from '@coral-xyz/anchor';
 import { logger } from '../core/logger.js';
 import { SapClientError } from '../core/errors.js';
 /**
- * SAP Client Manager
+ * @name SapClientManager
+ * @description Singleton manager for the SAP SDK client with config-aware reinitialization.
+ *
+ * @method getInstance     — Returns the singleton `SapClientManager` instance.
+ * @method initialize      — Creates or reuses the `SapClient` based on config changes.
+ * @method getClient       — Returns the initialized client (throws if not initialized).
+ * @method getClientOrNull — Returns the initialized client or `null`.
+ * @method reset           — Resets the client and config (for testing).
+ *
+ * @usedBy `createSapClient`, `getSapClient`, `isSapClientInitialized`, `create-server.ts`
  */
 export class SapClientManager {
     static instance = null;
@@ -17,7 +33,14 @@ export class SapClientManager {
     config = null;
     constructor() { }
     /**
-     * Compares the connection and wallet fields that affect SapClient construction.
+     * @name SapClientManager.isSameClientConfig
+     * @description Compares connection and wallet fields that affect SapClient construction.
+     *
+     * @param current — Current stored config.
+     * @param next    — New config to compare against.
+     * @returns `true` if the relevant config fields match, `false` otherwise.
+     *
+     * @internal
      */
     isSameClientConfig(current, next) {
         return current.rpcUrl === next.rpcUrl
@@ -27,7 +50,12 @@ export class SapClientManager {
             && current.walletPath === next.walletPath;
     }
     /**
-     * Get singleton instance
+     * @name SapClientManager.getInstance
+     * @description Returns the singleton `SapClientManager` instance, creating it if necessary.
+     *
+     * @returns The singleton `SapClientManager`.
+     *
+     * @usedBy `createSapClient`, `getSapClient`, `isSapClientInitialized`.
      */
     static getInstance() {
         if (!SapClientManager.instance) {
@@ -36,7 +64,14 @@ export class SapClientManager {
         return SapClientManager.instance;
     }
     /**
-     * Initialize SAP client from config
+     * @name SapClientManager.initialize
+     * @description Initializes the SAP client from config, reusing the existing client if config hasn't changed.
+     *
+     * @param config — SAP MCP configuration with RPC URL, program ID, mode, and wallet path.
+     * @returns The initialized `SapClient` instance.
+     * @throws `SapClientError` if client creation fails.
+     *
+     * @usedBy `createSapClient`, `create-server.ts:createSapMcpServer`.
      */
     async initialize(config) {
         if (this.client && this.config && this.isSameClientConfig(this.config, config)) {
@@ -82,7 +117,13 @@ export class SapClientManager {
         }
     }
     /**
-     * Get SAP client instance
+     * @name SapClientManager.getClient
+     * @description Returns the initialized SAP client.
+     *
+     * @returns The `SapClient` instance.
+     * @throws `SapClientError` if the client has not been initialized.
+     *
+     * @usedBy `getSapClient`.
      */
     getClient() {
         if (!this.client) {
@@ -91,13 +132,21 @@ export class SapClientManager {
         return this.client;
     }
     /**
-     * Get client or null if not initialized
+     * @name SapClientManager.getClientOrNull
+     * @description Returns the initialized SAP client or `null` if not yet initialized.
+     *
+     * @returns The `SapClient` instance or `null`.
+     *
+     * @usedBy `isSapClientInitialized`.
      */
     getClientOrNull() {
         return this.client;
     }
     /**
-     * Reset client (for testing)
+     * @name SapClientManager.reset
+     * @description Resets the client and config to `null` (for testing purposes).
+     *
+     * @usedBy Test setup and teardown.
      */
     reset() {
         this.client = null;
@@ -106,21 +155,39 @@ export class SapClientManager {
     }
 }
 /**
- * Create SAP client from config
+ * @name createSapClient
+ * @description Creates or reuses the SAP client from the given configuration.
+ *
+ * @param config — SAP MCP configuration.
+ * @returns The initialized `SapClient` instance.
+ * @throws `SapClientError` if initialization fails.
+ *
+ * @usedBy `create-server.ts:createSapMcpServer`.
  */
 export async function createSapClient(config) {
     const manager = SapClientManager.getInstance();
     return manager.initialize(config);
 }
 /**
- * Get existing SAP client
+ * @name getSapClient
+ * @description Returns the currently initialized SAP client.
+ *
+ * @returns The `SapClient` instance.
+ * @throws `SapClientError` if the client has not been initialized.
+ *
+ * @usedBy Tool handlers across the SAP MCP runtime.
  */
 export function getSapClient() {
     const manager = SapClientManager.getInstance();
     return manager.getClient();
 }
 /**
- * Check if SAP client is initialized
+ * @name isSapClientInitialized
+ * @description Checks whether the SAP client has been initialized.
+ *
+ * @returns `true` if the client is initialized, `false` otherwise.
+ *
+ * @usedBy Health checks and startup validation.
  */
 export function isSapClientInitialized() {
     const manager = SapClientManager.getInstance();

package/dist/sap/sap-client-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"sap-client-manager.js","sourceRoot":"","sources":["../../src/sap/sap-client-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sap-client-manager.js","sourceRoot":"","sources":["../../src/sap/sap-client-manager.ts"],"names":[],"mappings":"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"}

package/dist/sap/sap-errors.d.ts

@@ -1,13 +1,32 @@
 /**
- * SAP-specific error handling
+ * @name sap/sap-errors
+ * @description SAP SDK error mapping and type-guarding utilities.
+ *
+ * @flow
+ *   1. `mapSapError` normalizes unknown errors into `SapSdkError` instances.
+ *   2. `isSapError` is a type guard for checking if an error is already a `SapSdkError`.
+ *
+ * @module sap/sap-errors
  */
 import { SapSdkError } from '../core/errors.js';
 /**
- * Map SAP SDK errors to user-friendly messages
+ * @name mapSapError
+ * @description Maps unknown SAP SDK errors to user-friendly `SapSdkError` instances.
+ *
+ * @param error — Unknown error value to normalize.
+ * @returns A `SapSdkError` wrapping the original error message.
+ *
+ * @usedBy Tool error handlers across the SAP MCP runtime.
  */
 export declare function mapSapError(error: unknown): SapSdkError;
 /**
- * Check if error is a SAP SDK error
+ * @name isSapError
+ * @description Type guard that checks whether an error is a `SapSdkError`.
+ *
+ * @param error — Unknown error value to check.
+ * @returns `true` if the error is a `SapSdkError`, narrowing the type.
+ *
+ * @usedBy Tool error handlers across the SAP MCP runtime.
  */
 export declare function isSapError(error: unknown): error is SapSdkError;
 //# sourceMappingURL=sap-errors.d.ts.map

package/dist/sap/sap-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sap-errors.d.ts","sourceRoot":"","sources":["../../src/sap/sap-errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAUvD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAE/D"}
+{"version":3,"file":"sap-errors.d.ts","sourceRoot":"","sources":["../../src/sap/sap-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAUvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAE/D"}

package/dist/sap/sap-errors.js

@@ -1,9 +1,22 @@
 /**
- * SAP-specific error handling
+ * @name sap/sap-errors
+ * @description SAP SDK error mapping and type-guarding utilities.
+ *
+ * @flow
+ *   1. `mapSapError` normalizes unknown errors into `SapSdkError` instances.
+ *   2. `isSapError` is a type guard for checking if an error is already a `SapSdkError`.
+ *
+ * @module sap/sap-errors
  */
 import { SapSdkError } from '../core/errors.js';
 /**
- * Map SAP SDK errors to user-friendly messages
+ * @name mapSapError
+ * @description Maps unknown SAP SDK errors to user-friendly `SapSdkError` instances.
+ *
+ * @param error — Unknown error value to normalize.
+ * @returns A `SapSdkError` wrapping the original error message.
+ *
+ * @usedBy Tool error handlers across the SAP MCP runtime.
  */
 export function mapSapError(error) {
     if (error instanceof SapSdkError) {
@@ -15,7 +28,13 @@ export function mapSapError(error) {
     return new SapSdkError('Unknown SAP SDK error');
 }
 /**
- * Check if error is a SAP SDK error
+ * @name isSapError
+ * @description Type guard that checks whether an error is a `SapSdkError`.
+ *
+ * @param error — Unknown error value to check.
+ * @returns `true` if the error is a `SapSdkError`, narrowing the type.
+ *
+ * @usedBy Tool error handlers across the SAP MCP runtime.
  */
 export function isSapError(error) {
     return error instanceof SapSdkError;

package/dist/sap/sap-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"sap-errors.js","sourceRoot":"","sources":["../../src/sap/sap-errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,IAAI,WAAW,CAAC,uBAAuB,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,YAAY,WAAW,CAAC;AACtC,CAAC"}
+{"version":3,"file":"sap-errors.js","sourceRoot":"","sources":["../../src/sap/sap-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,IAAI,WAAW,CAAC,uBAAuB,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,YAAY,WAAW,CAAC;AACtC,CAAC"}

package/dist/sap/sap-types.d.ts

@@ -1,9 +1,31 @@
 /**
- * SAP type definitions
+ * @name sap/sap-types
+ * @description SAP Protocol on-chain account type definitions.
+ *
+ * These types mirror the on-chain data structures for agents, stats, escrows,
+ * vaults, and tools in the SAP Protocol program.
+ *
+ * @flow
+ *   1. SAP MCP tool handlers cast deserialized on-chain account data to these types.
+ *   2. `sap/index.ts` re-exports them for external consumers.
+ *
+ * @module sap/sap-types
  */
 import type { PublicKey } from '@solana/web3.js';
 /**
- * SAP Agent account
+ * @name SapAgent
+ * @description On-chain SAP agent account data.
+ *
+ * @property wallet       — Agent's Solana wallet public key.
+ * @property pda          — Program Derived Address of the agent account.
+ * @property name         — Agent display name.
+ * @property capabilities — Array of capability identifier strings.
+ * @property metadataUri  — Optional URI to off-chain agent metadata.
+ * @property x402Endpoint — Optional URL for the agent's x402 payment endpoint.
+ * @property isActive     — Whether the agent is currently active.
+ * @property registeredAt — Unix timestamp of agent registration.
+ *
+ * @usedBy SAP registry tools, `sap/index.ts`
  */
 export interface SapAgent {
     wallet: PublicKey;
@@ -16,7 +38,16 @@ export interface SapAgent {
     registeredAt: number;
 }
 /**
- * SAP Agent stats
+ * @name SapAgentStats
+ * @description Aggregate statistics for a SAP agent.
+ *
+ * @property totalCalls      — Total number of calls made by the agent.
+ * @property totalEarnings   — Total earnings in lamports.
+ * @property reputationScore — Numerical reputation score.
+ * @property feedbackCount   — Number of feedback attestations received.
+ * @property averageRating   — Average rating from attestations.
+ *
+ * @usedBy SAP reputation tools, `sap/index.ts`
  */
 export interface SapAgentStats {
     totalCalls: number;
@@ -26,7 +57,20 @@ export interface SapAgentStats {
     averageRating: number;
 }
 /**
- * SAP Escrow
+ * @name SapEscrow
+ * @description On-chain SAP escrow account data for payment settlement.
+ *
+ * @property pda           — Program Derived Address of the escrow account.
+ * @property depositor     — Public key of the depositor.
+ * @property agent         — Public key of the agent the escrow is for.
+ * @property balance       — Current escrow balance in lamports.
+ * @property pricePerCall  — Price per call in lamports.
+ * @property maxCalls      — Maximum calls covered by the escrow.
+ * @property callsRemaining — Number of calls remaining in the escrow.
+ * @property expiresAt     — Unix timestamp of escrow expiry.
+ * @property isActive      — Whether the escrow is currently active.
+ *
+ * @usedBy SAP settlement tools, `sap/index.ts`
  */
 export interface SapEscrow {
     pda: PublicKey;
@@ -40,7 +84,16 @@ export interface SapEscrow {
     isActive: boolean;
 }
 /**
- * SAP Vault
+ * @name SapVault
+ * @description On-chain SAP memory vault account data.
+ *
+ * @property pda               — Program Derived Address of the vault account.
+ * @property agent             — Public key of the agent owning the vault.
+ * @property nonce             — Cryptographic nonce for the vault.
+ * @property totalInscriptions — Total number of inscriptions in the vault.
+ * @property currentEpoch      — Current epoch number of the vault.
+ *
+ * @usedBy SAP memory tools, `sap/index.ts`
  */
 export interface SapVault {
     pda: PublicKey;
@@ -50,7 +103,23 @@ export interface SapVault {
     currentEpoch: number;
 }
 /**
- * SAP Tool
+ * @name SapTool
+ * @description On-chain SAP tool schema account data.
+ *
+ * @property pda              — Program Derived Address of the tool schema account.
+ * @property agent            — Public key of the agent that published the tool.
+ * @property name             — Tool name string.
+ * @property protocolHash     — Hash of the tool protocol definition.
+ * @property descriptionHash  — Hash of the tool description.
+ * @property inputSchemaHash  — Hash of the tool input JSON schema.
+ * @property outputSchemaHash — Hash of the tool output JSON schema.
+ * @property httpMethod       — HTTP method the tool exposes.
+ * @property category         — Numeric category code for tool classification.
+ * @property paramsCount      — Total number of parameters the tool accepts.
+ * @property requiredParams   — Number of required parameters.
+ * @property isCompound       — Whether the tool is a compound (multi-step) tool.
+ *
+ * @usedBy SAP tool-schema tools, `sap/index.ts`
  */
 export interface SapTool {
     pda: PublicKey;

package/dist/sap/sap-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sap-types.d.ts","sourceRoot":"","sources":["../../src/sap/sap-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,SAAS,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,UAAU,CAAC;IACzB,eAAe,EAAE,UAAU,CAAC;IAC5B,eAAe,EAAE,UAAU,CAAC;IAC5B,gBAAgB,EAAE,UAAU,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;CACrB"}
+{"version":3,"file":"sap-types.d.ts","sourceRoot":"","sources":["../../src/sap/sap-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,SAAS,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,UAAU,CAAC;IACzB,eAAe,EAAE,UAAU,CAAC;IAC5B,eAAe,EAAE,UAAU,CAAC;IAC5B,gBAAgB,EAAE,UAAU,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;CACrB"}

package/dist/sap/sap-types.js

@@ -1,5 +1,15 @@
 /**
- * SAP type definitions
+ * @name sap/sap-types
+ * @description SAP Protocol on-chain account type definitions.
+ *
+ * These types mirror the on-chain data structures for agents, stats, escrows,
+ * vaults, and tools in the SAP Protocol program.
+ *
+ * @flow
+ *   1. SAP MCP tool handlers cast deserialized on-chain account data to these types.
+ *   2. `sap/index.ts` re-exports them for external consumers.
+ *
+ * @module sap/sap-types
  */
 export {};
 //# sourceMappingURL=sap-types.js.map

package/dist/sap/sap-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"sap-types.js","sourceRoot":"","sources":["../../src/sap/sap-types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"sap-types.js","sourceRoot":"","sources":["../../src/sap/sap-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/schemas/common.schema.d.ts

@@ -1,25 +1,56 @@
 /**
- * Common Zod schemas
+ * @name schemas/common
+ * @description Shared Zod schema primitives reused across every SAP MCP tool schema.
+ *
+ * These base schemas — wallet addresses, public keys, signatures, PDAs, pagination,
+ * amounts, and SOL amounts — are imported by domain-specific schema modules to
+ * build consistent validation rules without duplication.
+ *
+ * @flow
+ *   1. Domain schema modules (identity, registry, payments, etc.) import the
+ *      primitives they need from this file.
+ *   2. `schemas/index.ts` re-exports everything for the MCP tool layer.
+ *   3. Tool handlers consume the composed schemas for input validation.
+ *
+ * @module schemas/common
  */
 import { z } from 'zod';
 /**
- * Shared wallet schema definition used by the SAP MCP runtime.
+ * @name WalletSchema
+ * @description Zod schema validating a base58-encoded Solana wallet address.
+ *
+ * @usedBy `identity.schema.ts`, `registry.schema.ts`, `payments.schema.ts`, `reputation.schema.ts`, `settlement.schema.ts`
  */
 export declare const WalletSchema: z.ZodString;
 /**
- * Shared public key schema definition used by the SAP MCP runtime.
+ * @name PublicKeySchema
+ * @description Zod schema validating a base58-encoded Solana public key.
+ *
+ * @usedBy Domain schema modules requiring generic public key validation.
  */
 export declare const PublicKeySchema: z.ZodString;
 /**
- * Shared signature schema definition used by the SAP MCP runtime.
+ * @name SignatureSchema
+ * @description Zod schema validating a base58-encoded transaction signature.
+ *
+ * @usedBy `execution-proof.schema.ts`, `transaction.schema.ts`
  */
 export declare const SignatureSchema: z.ZodString;
 /**
- * Shared pda schema definition used by the SAP MCP runtime.
+ * @name PdaSchema
+ * @description Zod schema validating a base58-encoded Program Derived Address.
+ *
+ * @usedBy `memory.schema.ts`, `registry.schema.ts`, `settlement.schema.ts`
  */
 export declare const PdaSchema: z.ZodString;
 /**
- * Shared pagination schema definition used by the SAP MCP runtime.
+ * @name PaginationSchema
+ * @description Zod schema for pagination parameters (limit and offset) with sensible defaults.
+ *
+ * @property limit  — Maximum number of items to return (default 50).
+ * @property offset — Number of items to skip (default 0).
+ *
+ * @usedBy List-type MCP tools across the SAP MCP runtime.
  */
 export declare const PaginationSchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
@@ -32,11 +63,17 @@ export declare const PaginationSchema: z.ZodObject<{
     offset?: number | undefined;
 }>;
 /**
- * Shared amount schema definition used by the SAP MCP runtime.
+ * @name AmountSchema
+ * @description Zod schema validating a positive amount in lamports (1 SOL = 1e9 lamports).
+ *
+ * @usedBy `payments.schema.ts`, `settlement.schema.ts`
  */
 export declare const AmountSchema: z.ZodNumber;
 /**
- * Shared sol amount schema definition used by the SAP MCP runtime.
+ * @name SolAmountSchema
+ * @description Zod schema validating a non-negative amount in SOL.
+ *
+ * @usedBy Transaction and balance-related MCP tools.
  */
 export declare const SolAmountSchema: z.ZodNumber;
 //# sourceMappingURL=common.schema.d.ts.map

package/dist/schemas/common.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/common.schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,YAAY,aAAiD,CAAC;AAC3E;;GAEG;AACH,eAAO,MAAM,eAAe,aAA6C,CAAC;AAC1E;;GAEG;AACH,eAAO,MAAM,eAAe,aAAwD,CAAC;AACrF;;GAEG;AACH,eAAO,MAAM,SAAS,aAA0D,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAG3B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,aAAuD,CAAC;AACjF;;GAEG;AACH,eAAO,MAAM,eAAe,aAAqD,CAAC"}
+{"version":3,"file":"common.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/common.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,aAAiD,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,eAAe,aAA6C,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,eAAe,aAAwD,CAAC;AAErF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,aAA0D,CAAC;AAEjF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAG3B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,aAAuD,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,aAAqD,CAAC"}