@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.15.0

package/dist/esm/modules/tools.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @module tools
+ * @description Tool schema registry and session checkpoints for the
+ * Synapse Agent Protocol.
+ *
+ * Covers: publish, inscribe schema, update, deactivate/reactivate,
+ * close, report invocations, and session checkpoint management.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import type { ToolDescriptorData, SessionCheckpointData, PublishToolArgs, UpdateToolArgs, InscribeToolSchemaArgs } from "../types";
+/**
+ * @name ToolsModule
+ * @description Manages tool descriptors and session checkpoints for the
+ *   Synapse Agent Protocol. Provides methods to publish, update, deactivate,
+ *   reactivate, close, and fetch tool descriptors, as well as inscribe
+ *   JSON schemas into TX logs and manage session checkpoints.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Publish a tool by name (auto-hashes)
+ * const sig = await sap.tools.publishByName(
+ *   "getWeather", "mcp-v1", "Fetch weather",
+ *   '{"type":"object"}', '{"type":"object"}',
+ *   0, 1, 2, 1, false,
+ * );
+ * ```
+ */
+export declare class ToolsModule extends BaseModule {
+    /**
+     * @name deriveTool
+     * @description Derive the `ToolDescriptor` PDA for a given agent and tool name.
+     *   The tool name is SHA-256 hashed internally.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns A tuple of `[PublicKey, bump]` for the tool PDA.
+     * @see {@link deriveTool} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveTool(agentPda: PublicKey, toolName: string): readonly [PublicKey, number];
+    /**
+     * @name publish
+     * @description Publish a new tool descriptor for an agent using pre-computed
+     *   hashes. For auto-hashing, prefer {@link publishByName}.
+     * @param args - Tool publication parameters (name, hashes, HTTP method, category, params, etc.).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    publish(args: PublishToolArgs): Promise<TransactionSignature>;
+    /**
+     * @name publishByName
+     * @description Convenience method to publish a tool using string names.
+     *   All string arguments are automatically SHA-256 hashed.
+     * @param toolName - Human-readable tool name.
+     * @param protocolId - Protocol identifier (e.g. `"mcp-v1"`).
+     * @param description - Tool description text.
+     * @param inputSchema - JSON schema string for input validation.
+     * @param outputSchema - JSON schema string for output validation.
+     * @param httpMethod - Numeric HTTP method enum value.
+     * @param category - Numeric tool category enum value.
+     * @param paramsCount - Total number of parameters.
+     * @param requiredParams - Number of required parameters.
+     * @param isCompound - Whether the tool is a compound (multi-step) tool.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    publishByName(toolName: string, protocolId: string, description: string, inputSchema: string, outputSchema: string, httpMethod: number, category: number, paramsCount: number, requiredParams: number, isCompound: boolean): Promise<TransactionSignature>;
+    /**
+     * @name inscribeSchema
+     * @description Inscribe a full JSON schema into the transaction log (zero rent).
+     *   The schema is stored as TX log data, not as PDA account data.
+     * @param toolName - The human-readable tool name.
+     * @param args - Schema inscription parameters (type, data, hash, compression).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    inscribeSchema(toolName: string, args: InscribeToolSchemaArgs): Promise<TransactionSignature>;
+    /**
+     * @name update
+     * @description Update a tool’s schema hashes and bump its version.
+     *   All fields are optional — only non-null values are written.
+     * @param toolName - The human-readable tool name.
+     * @param args - Partial update parameters (hashes, method, category, params).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    update(toolName: string, args: UpdateToolArgs): Promise<TransactionSignature>;
+    /**
+     * @name deactivate
+     * @description Deactivate a tool. The tool remains discoverable but is
+     *   marked as unavailable.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    deactivate(toolName: string): Promise<TransactionSignature>;
+    /**
+     * @name reactivate
+     * @description Reactivate a previously deactivated tool.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    reactivate(toolName: string): Promise<TransactionSignature>;
+    /**
+     * @name close
+     * @description Close a tool PDA and reclaim rent to the owner wallet.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    close(toolName: string): Promise<TransactionSignature>;
+    /**
+     * @name reportInvocations
+     * @description Report tool invocation count. Updates the on-chain counter
+     *   for analytics and discovery ranking.
+     * @param toolName - The human-readable tool name.
+     * @param invocations - The number of invocations to report.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    reportInvocations(toolName: string, invocations: number | bigint): Promise<TransactionSignature>;
+    /**
+     * @name createCheckpoint
+     * @description Create a checkpoint snapshot of the current session state.
+     *   Checkpoints are indexed by session PDA and checkpoint index.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    createCheckpoint(sessionPda: PublicKey, checkpointIndex: number): Promise<TransactionSignature>;
+    /**
+     * @name closeCheckpoint
+     * @description Close a checkpoint PDA and reclaim rent.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    closeCheckpoint(sessionPda: PublicKey, checkpointIndex: number): Promise<TransactionSignature>;
+    /**
+     * @name fetch
+     * @description Fetch a deserialized `ToolDescriptor` account.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<ToolDescriptorData>} The tool descriptor data.
+     * @throws Will throw if the tool descriptor does not exist.
+     * @since v0.1.0
+     */
+    fetch(agentPda: PublicKey, toolName: string): Promise<ToolDescriptorData>;
+    /**
+     * @name fetchNullable
+     * @description Fetch a deserialized `ToolDescriptor` account, or `null`
+     *   if it does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<ToolDescriptorData | null>} The tool data or `null`.
+     * @since v0.1.0
+     */
+    fetchNullable(agentPda: PublicKey, toolName: string): Promise<ToolDescriptorData | null>;
+    /**
+     * @name fetchCheckpoint
+     * @description Fetch a deserialized `SessionCheckpoint` account by session PDA and index.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<SessionCheckpointData>} The checkpoint data.
+     * @throws Will throw if the checkpoint does not exist.
+     * @since v0.1.0
+     */
+    fetchCheckpoint(sessionPda: PublicKey, checkpointIndex: number): Promise<SessionCheckpointData>;
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/esm/modules/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/modules/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAOpC,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,sBAAsB,EACvB,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,WAAY,SAAQ,UAAU;IAGzC;;;;;;;;;OASG;IACH,UAAU,CACR,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,MAAM,GACf,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAM/B;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAyDnE;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,OAAO,GAClB,OAAO,CAAC,oBAAoB,CAAC;IA8BhC;;;;;;;;OAQG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAmBhC;;;;;;;;OAQG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,oBAAoB,CAAC;IAsBhC;;;;;;;OAOG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAcjE;;;;;;OAMG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAcjE;;;;;;OAMG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgB5D;;;;;;;;OAQG;IACG,iBAAiB,CACrB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAgBhC;;;;;;;;OAQG;IACG,gBAAgB,CACpB,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,oBAAoB,CAAC;IAchC;;;;;;;OAOG;IACG,eAAe,CACnB,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,oBAAoB,CAAC;IAehC;;;;;;;;OAQG;IACG,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAK/E;;;;;;;;OAQG;IACG,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAK9F;;;;;;;;OAQG;IACG,eAAe,CACnB,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,qBAAqB,CAAC;CAIlC"}

package/dist/esm/modules/vault.d.ts

@@ -0,0 +1,240 @@
+/**
+ * @module vault
+ * @description Encrypted memory vault — init, session management, inscribe,
+ * delegate access, nonce rotation, and close operations.
+ *
+ * Vaults provide encrypted, session-scoped memory storage for agents,
+ * with support for epoch-based pagination and hot-wallet delegation.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import type { MemoryVaultData, SessionLedgerData, EpochPageData, VaultDelegateData, InscribeMemoryArgs, CompactInscribeArgs } from "../types";
+/**
+ * @name VaultModule
+ * @description Manages encrypted memory vaults for the Synapse Agent Protocol.
+ *   Provides methods to initialise vaults, open/close sessions, inscribe
+ *   encrypted data, manage delegates (hot wallets), rotate nonces, and
+ *   fetch all related account types.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Initialize a vault
+ * await sap.vault.initVault([...nonce]);
+ * // Open a session and inscribe data
+ * await sap.vault.openSession([...sessionHash]);
+ * ```
+ */
+export declare class VaultModule extends BaseModule {
+    /**
+     * @name deriveVault
+     * @description Derive the `MemoryVault` PDA for a given agent.
+     * @param agentPda - The agent account PDA.
+     * @returns A tuple of `[PublicKey, bump]` for the vault PDA.
+     * @see {@link deriveVault} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveVault(agentPda: PublicKey): readonly [PublicKey, number];
+    /**
+     * @name deriveSession
+     * @description Derive the `SessionLedger` PDA for a given vault and session hash.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionHash - A unique session identifier (32 bytes).
+     * @returns A tuple of `[PublicKey, bump]` for the session PDA.
+     * @see {@link deriveSession} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveSession(vaultPda: PublicKey, sessionHash: Uint8Array): readonly [PublicKey, number];
+    /**
+     * @name initVault
+     * @description Initialize an encrypted memory vault for the caller's agent.
+     *   Creates the `MemoryVault` PDA and sets the initial encryption nonce.
+     * @param vaultNonce - The initial encryption nonce (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    initVault(vaultNonce: number[]): Promise<TransactionSignature>;
+    /**
+     * @name openSession
+     * @description Open a new session within a vault. Creates a `SessionLedger`
+     *   PDA identified by the session hash.
+     * @param sessionHash - A unique session identifier (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    openSession(sessionHash: number[]): Promise<TransactionSignature>;
+    /**
+     * @name inscribe
+     * @description Inscribe encrypted data into the transaction log.
+     *   Account resolution is handled by Anchor via remaining accounts.
+     * @param args - Inscription parameters (sequence, encrypted data, nonce, content hash, fragments, compression, epoch).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    inscribe(args: InscribeMemoryArgs): Promise<TransactionSignature>;
+    /**
+     * @name inscribeWithAccounts
+     * @description Full inscribe with explicit session and epoch page PDAs.
+     *   Use this when you need manual control over account resolution.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochPagePda - The epoch page PDA for the target epoch.
+     * @param vaultPda - The memory vault PDA.
+     * @param args - Inscription parameters.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    inscribeWithAccounts(sessionPda: PublicKey, epochPagePda: PublicKey, vaultPda: PublicKey, args: InscribeMemoryArgs): Promise<TransactionSignature>;
+    /**
+     * @name compactInscribe
+     * @description Simplified inscription (4 args vs 8) for single-fragment writes.
+     * @param sessionPda - The session ledger PDA.
+     * @param vaultPda - The memory vault PDA.
+     * @param args - Compact inscription parameters (sequence, encrypted data, nonce, content hash).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    compactInscribe(sessionPda: PublicKey, vaultPda: PublicKey, args: CompactInscribeArgs): Promise<TransactionSignature>;
+    /**
+     * @name closeSession
+     * @description Close a session — no more inscriptions will be allowed.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA to close.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    closeSession(vaultPda: PublicKey, sessionPda: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @name closeVault
+     * @description Close the `MemoryVault` PDA and reclaim rent to the owner wallet.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    closeVault(): Promise<TransactionSignature>;
+    /**
+     * @name closeSessionPda
+     * @description Close a `SessionLedger` PDA (session must be closed first).
+     *   Reclaims rent to the owner wallet.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA to close.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    closeSessionPda(vaultPda: PublicKey, sessionPda: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @name closeEpochPage
+     * @description Close an `EpochPage` PDA and reclaim rent.
+     * @param sessionPda - The session ledger PDA that owns this epoch page.
+     * @param epochIndex - The zero-based epoch index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    closeEpochPage(sessionPda: PublicKey, epochIndex: number): Promise<TransactionSignature>;
+    /**
+     * @name rotateNonce
+     * @description Rotate the vault encryption nonce. All future inscriptions
+     *   will use the new nonce.
+     * @param newNonce - The replacement nonce (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    rotateNonce(newNonce: number[]): Promise<TransactionSignature>;
+    /**
+     * @name addDelegate
+     * @description Authorize a delegate (hot wallet) for vault operations.
+     *   Creates a `VaultDelegate` PDA with the specified permissions and expiry.
+     * @param delegatePubkey - The public key of the delegate wallet to authorize.
+     * @param permissions - Bitmask of permitted operations.
+     * @param expiresAt - Unix timestamp when delegation expires.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    addDelegate(delegatePubkey: PublicKey, permissions: number, expiresAt: number | bigint): Promise<TransactionSignature>;
+    /**
+     * @name revokeDelegate
+     * @description Revoke a delegate’s authorization, closing their `VaultDelegate` PDA.
+     * @param delegatePubkey - The public key of the delegate wallet to revoke.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    revokeDelegate(delegatePubkey: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @name inscribeDelegated
+     * @description Inscribe data via an authorized delegate (hot wallet).
+     *   The transaction is signed by the delegate instead of the vault owner.
+     * @param delegateWallet - The delegate wallet public key.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochPagePda - The epoch page PDA.
+     * @param args - Inscription parameters.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    inscribeDelegated(delegateWallet: PublicKey, vaultPda: PublicKey, sessionPda: PublicKey, epochPagePda: PublicKey, args: InscribeMemoryArgs): Promise<TransactionSignature>;
+    /**
+     * @name fetchVault
+     * @description Fetch a deserialized `MemoryVault` account.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<MemoryVaultData>} The vault account data.
+     * @throws Will throw if the vault account does not exist.
+     * @since v0.1.0
+     */
+    fetchVault(agentPda: PublicKey): Promise<MemoryVaultData>;
+    /**
+     * @name fetchVaultNullable
+     * @description Fetch a deserialized `MemoryVault` account, or `null`
+     *   if it does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<MemoryVaultData | null>} The vault data or `null`.
+     * @since v0.1.0
+     */
+    fetchVaultNullable(agentPda: PublicKey): Promise<MemoryVaultData | null>;
+    /**
+     * @name fetchSession
+     * @description Fetch a deserialized `SessionLedger` account by vault and session hash.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionHash - The session identifier used during creation.
+     * @returns {Promise<SessionLedgerData>} The session ledger data.
+     * @throws Will throw if the session does not exist.
+     * @since v0.1.0
+     */
+    fetchSession(vaultPda: PublicKey, sessionHash: Uint8Array): Promise<SessionLedgerData>;
+    /**
+     * @name fetchSessionByPda
+     * @description Fetch a deserialized `SessionLedger` account by its PDA directly,
+     *   bypassing PDA derivation.
+     * @param sessionPda - The session ledger PDA.
+     * @returns {Promise<SessionLedgerData>} The session ledger data.
+     * @throws Will throw if the session does not exist.
+     * @since v0.1.0
+     */
+    fetchSessionByPda(sessionPda: PublicKey): Promise<SessionLedgerData>;
+    /**
+     * @name fetchEpochPage
+     * @description Fetch a deserialized `EpochPage` account.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochIndex - The zero-based epoch index.
+     * @returns {Promise<EpochPageData>} The epoch page data.
+     * @throws Will throw if the epoch page does not exist.
+     * @since v0.1.0
+     */
+    fetchEpochPage(sessionPda: PublicKey, epochIndex: number): Promise<EpochPageData>;
+    /**
+     * @name fetchDelegate
+     * @description Fetch a deserialized `VaultDelegate` account.
+     * @param vaultPda - The memory vault PDA.
+     * @param delegatePubkey - The delegate wallet public key.
+     * @returns {Promise<VaultDelegateData>} The delegate account data.
+     * @throws Will throw if the delegate does not exist.
+     * @since v0.1.0
+     */
+    fetchDelegate(vaultPda: PublicKey, delegatePubkey: PublicKey): Promise<VaultDelegateData>;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/esm/modules/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/modules/vault.ts"],"names":[],"mappings":"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"}

package/dist/esm/parser/client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @module parser/client
+ * @description Object-oriented wrapper for transaction parsing.
+ *
+ * Binds the Anchor `Program` reference so callers do not need to
+ * pass it on every call. Designed as a lazy singleton accessible
+ * from {@link SapClient.parser}.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * const client = SapClient.from(provider);
+ *
+ * // Parse a full transaction
+ * const parsed = client.parser.parseTransaction(txResponse);
+ *
+ * // Quick instruction names
+ * const names = client.parser.instructionNames(txResponse);
+ *
+ * // From pre-built instructions
+ * const decoded = client.parser.fromInstructions(ixList);
+ * ```
+ */
+import type { Program } from "@coral-xyz/anchor";
+import type { TransactionInstruction, TransactionResponse, VersionedTransactionResponse } from "@solana/web3.js";
+import { AddressLookupTableAccount } from "@solana/web3.js";
+import type { DecodedSapInstruction, ParsedSapTransaction, ParseFilterOptions } from "./types";
+import { type InnerInstructionGroup } from "./inner";
+/**
+ * Stateful transaction parser bound to a specific Anchor `Program`.
+ *
+ * Stores the program reference, instruction coder, and program ID
+ * internally so that repeated parse calls require only the
+ * transaction data as input.
+ *
+ * @name TransactionParser
+ * @category Parser
+ * @since v0.5.0
+ */
+export declare class TransactionParser {
+    private readonly program;
+    private readonly coder;
+    private readonly programId;
+    /**
+     * Create a new TransactionParser.
+     *
+     * @param program - An Anchor `Program` built from the SAP IDL.
+     */
+    constructor(program: Program<any>);
+    /**
+     * Full parse: instructions + inner calls + events.
+     *
+     * @param tx - Raw transaction response from `connection.getTransaction`.
+     * @param options - Optional filters for instructions, events, and inner calls.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Complete parsed transaction, or `null` if the input is nullish.
+     *
+     * @since v0.5.0
+     */
+    parseTransaction(tx: TransactionResponse | VersionedTransactionResponse | null | undefined, options?: ParseFilterOptions, addressLookupTables?: AddressLookupTableAccount[]): ParsedSapTransaction | null;
+    /**
+     * Parse a batch of transactions.
+     *
+     * @param txs - Array of transaction responses (may contain `null` entries).
+     * @param options - Optional parse filters.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Non-null parsed transactions.
+     *
+     * @since v0.5.0
+     */
+    parseBatch(txs: (TransactionResponse | VersionedTransactionResponse | null | undefined)[], options?: ParseFilterOptions, addressLookupTables?: AddressLookupTableAccount[]): ParsedSapTransaction[];
+    /**
+     * Decode top-level SAP instructions from a transaction response.
+     *
+     * @param tx - Raw transaction response.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Decoded SAP instructions.
+     *
+     * @since v0.5.0
+     */
+    instructionsFromTransaction(tx: TransactionResponse | VersionedTransactionResponse, addressLookupTables?: AddressLookupTableAccount[]): DecodedSapInstruction[];
+    /**
+     * Extract only the instruction names from a transaction response.
+     *
+     * @param tx - Raw transaction response.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Instruction name strings.
+     *
+     * @since v0.5.0
+     */
+    instructionNames(tx: TransactionResponse | VersionedTransactionResponse, addressLookupTables?: AddressLookupTableAccount[]): string[];
+    /**
+     * Decode SAP instructions from a pre-built instruction array.
+     *
+     * @param instructions - The instruction list to decode.
+     * @returns Decoded SAP instructions.
+     *
+     * @since v0.5.0
+     */
+    fromInstructions(instructions: TransactionInstruction[]): DecodedSapInstruction[];
+    /**
+     * Check if any instruction in the list targets the SAP program.
+     *
+     * @param instructions - The instruction array to inspect.
+     * @returns `true` if at least one instruction targets SAP.
+     *
+     * @since v0.5.0
+     */
+    isSapTransaction(instructions: TransactionInstruction[]): boolean;
+    /**
+     * Decode inner (CPI) instructions from transaction metadata.
+     *
+     * @param innerGroups - The `tx.meta.innerInstructions` array.
+     * @param tx - The transaction response (for account key resolution).
+     * @returns Decoded inner instructions.
+     *
+     * @since v0.5.0
+     */
+    decodeInner(innerGroups: InnerInstructionGroup[], tx: TransactionResponse | VersionedTransactionResponse): import("./types").DecodedInnerInstruction[];
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/esm/parser/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/parser/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAEV,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,EAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,SAAS,CAAC;AAIjB,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAUhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;;;;OAIG;gBAE0B,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC;IAKlD;;;;;;;;;OASG;IACH,gBAAgB,CACd,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,EACzE,OAAO,CAAC,EAAE,kBAAkB,EAC5B,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,oBAAoB,GAAG,IAAI;IAU9B;;;;;;;;;OASG;IACH,UAAU,CACR,GAAG,EAAE,CAAC,mBAAmB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAC9E,OAAO,CAAC,EAAE,kBAAkB,EAC5B,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,oBAAoB,EAAE;IAUzB;;;;;;;;OAQG;IACH,2BAA2B,CACzB,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,qBAAqB,EAAE;IAS1B;;;;;;;;OAQG;IACH,gBAAgB,CACd,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,MAAM,EAAE;IAMX;;;;;;;OAOG;IACH,gBAAgB,CACd,YAAY,EAAE,sBAAsB,EAAE,GACrC,qBAAqB,EAAE;IAI1B;;;;;;;OAOG;IACH,gBAAgB,CAAC,YAAY,EAAE,sBAAsB,EAAE,GAAG,OAAO;IAIjE;;;;;;;;OAQG;IACH,WAAW,CACT,WAAW,EAAE,qBAAqB,EAAE,EACpC,EAAE,EAAE,mBAAmB,GAAG,4BAA4B;CAUzD"}

package/dist/esm/parser/complete.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module parser/complete
+ * @description Full SAP transaction parser: instructions + args + accounts + events.
+ *
+ * This is "Case 2 Complete": given a raw transaction response, produce a
+ * single {@link ParsedSapTransaction} containing every decoded instruction,
+ * all inner (CPI) calls, and all SAP events extracted from the logs.
+ *
+ * Designed for indexer pipelines where the decode step must be pure,
+ * deterministic, and fully testable without an RPC connection.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * import { parseSapTransactionComplete } from "@synapse-sap/sdk/parser";
+ * import { SAP_PROGRAM_ID, SAP_IDL } from "@synapse-sap/sdk";
+ * import { Program } from "\@coral-xyz/anchor";
+ *
+ * const program = new Program(SAP_IDL, provider);
+ * const tx = await connection.getTransaction(sig, {
+ *   commitment: "confirmed",
+ *   maxSupportedTransactionVersion: 0,
+ * });
+ *
+ * const parsed = parseSapTransactionComplete(tx, program, SAP_PROGRAM_ID);
+ * console.log(parsed.instructions.map(i => i.name));
+ * console.log(parsed.events.map(e => e.name));
+ * ```
+ */
+import { AddressLookupTableAccount, type PublicKey, type TransactionResponse, type VersionedTransactionResponse } from "@solana/web3.js";
+import type { Program } from "@coral-xyz/anchor";
+import type { ParsedSapTransaction, ParseFilterOptions } from "./types";
+/**
+ * Parse a complete SAP transaction into a unified result.
+ *
+ * Combines three stages:
+ * 1. **Instruction decode** - top-level SAP instructions with args and accounts
+ * 2. **Inner instruction decode** - CPI calls with full account reconstruction
+ * 3. **Event extraction** - SAP events decoded from the transaction logs
+ *
+ * All three stages are safe: malformed data produces `null` fields
+ * rather than exceptions. This makes the function suitable for
+ * batch-processing in indexer workers where a single bad transaction
+ * must not halt the pipeline.
+ *
+ * @param tx - The raw transaction response from `connection.getTransaction`.
+ * @param program - An Anchor `Program` instance built from the SAP IDL.
+ *   The coder and program ID are extracted automatically.
+ * @param sapProgramId - The SAP program public key. Passed explicitly so
+ *   callers can target devnet/localnet deployments independently.
+ * @param options - Optional filters for instructions, events, and inner calls.
+ * @param addressLookupTables - Resolved lookup table accounts for v0 transactions.
+ * @returns A fully parsed transaction, or `null` if the input is `null`/`undefined`.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+export declare function parseSapTransactionComplete(tx: TransactionResponse | VersionedTransactionResponse | null | undefined, program: Program<any>, sapProgramId: PublicKey, options?: ParseFilterOptions, addressLookupTables?: AddressLookupTableAccount[]): ParsedSapTransaction | null;
+/**
+ * Parse multiple transactions in batch.
+ *
+ * Convenience wrapper for indexer pipelines that process pages of
+ * transactions. Skips `null` entries and failed decodes silently.
+ *
+ * @param txs - Array of transaction responses (may contain `null` entries).
+ * @param program - The Anchor SAP program instance.
+ * @param sapProgramId - The SAP program public key.
+ * @param options - Optional parse filters applied to every transaction.
+ * @param addressLookupTables - Lookup tables for v0 transactions.
+ * @returns An array of non-null parsed transactions.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * const signatures = await connection.getSignaturesForAddress(agentPda);
+ * const txs = await Promise.all(
+ *   signatures.map(s => connection.getTransaction(s.signature, { ... }))
+ * );
+ * const parsed = parseSapTransactionBatch(txs, program, SAP_PROGRAM_ID, {
+ *   includeEvents: true,
+ *   includeInner: true,
+ * });
+ * ```
+ */
+export declare function parseSapTransactionBatch(txs: (TransactionResponse | VersionedTransactionResponse | null | undefined)[], program: Program<any>, sapProgramId: PublicKey, options?: ParseFilterOptions, addressLookupTables?: AddressLookupTableAccount[]): ParsedSapTransaction[];
+//# sourceMappingURL=complete.d.ts.map

package/dist/esm/parser/complete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../../../src/parser/complete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,yBAAyB,EACzB,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAClC,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAGnB,MAAM,SAAS,CAAC;AAcjB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,EAEzE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EACrB,YAAY,EAAE,SAAS,EACvB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,oBAAoB,GAAG,IAAI,CAoE7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,CAAC,mBAAmB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAE9E,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EACrB,YAAY,EAAE,SAAS,EACvB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,oBAAoB,EAAE,CAaxB"}