@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/dist/cjs/modules/base.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * @module base
+ * @description Abstract base class for all SDK modules.
+ *
+ * Provides shared access to the Anchor program, provider,
+ * and typed `fetch` / `fetchNullable` helpers.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseModule = void 0;
+const anchor_1 = require("@coral-xyz/anchor");
+/**
+ * @name BaseModule
+ * @description Abstract base module inherited by every domain module in the SDK.
+ * Encapsulates the Anchor program reference, provider access, and common
+ * helpers for account fetching and BN construction.
+ *
+ * @abstract
+ * @category Modules
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * class MyModule extends BaseModule {
+ *   async doSomething() {
+ *     const data = await this.fetchAccount<MyData>("myAccount", pda);
+ *   }
+ * }
+ * ```
+ */
+class BaseModule {
+    program;
+    /**
+     * Create a new module instance.
+     *
+     * @param program - The Anchor `Program` instance for the SAP IDL.
+     * @protected
+     */
+    constructor(program) {
+        this.program = program;
+    }
+    /**
+     * @name methods
+     * @description Instruction method namespace — bypasses `noUncheckedIndexedAccess`
+     *   on `Program<any>` where every property is `T | undefined`.
+     *   Used internally by subclasses to build and send instructions.
+     * @returns The Anchor program `methods` object for chaining instruction builders.
+     * @protected
+     * @since v0.1.0
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get methods() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.program.methods;
+    }
+    /**
+     * @name provider
+     * @description The AnchorProvider from the program, giving access to
+     *   the connection and wallet for signing transactions.
+     * @returns {AnchorProvider} The Anchor provider instance.
+     * @protected
+     * @since v0.1.0
+     */
+    get provider() {
+        return this.program.provider;
+    }
+    /**
+     * @name walletPubkey
+     * @description Convenience accessor for the signer wallet's public key.
+     * @returns {PublicKey} The public key of the connected wallet.
+     * @protected
+     * @since v0.1.0
+     */
+    get walletPubkey() {
+        return this.provider.wallet.publicKey;
+    }
+    /**
+     * @name fetchAccount
+     * @description Generic account fetch — deserializes the on-chain account
+     *   data into the given type `T`, or throws if the account does not exist.
+     * @typeParam T - The expected deserialized account data type.
+     * @param accountName - The Anchor account discriminator name (e.g. `"agentAccount"`).
+     * @param address - The public key of the account to fetch.
+     * @returns {Promise<T>} The deserialized account data.
+     * @throws Will throw if the account does not exist on-chain.
+     * @protected
+     * @since v0.1.0
+     */
+    async fetchAccount(accountName, address) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        return this.program.account[accountName].fetch(address);
+    }
+    /**
+     * @name fetchAccountNullable
+     * @description Generic nullable account fetch — deserializes the on-chain
+     *   account data into type `T`, or returns `null` if the account does not exist.
+     * @typeParam T - The expected deserialized account data type.
+     * @param accountName - The Anchor account discriminator name (e.g. `"agentAccount"`).
+     * @param address - The public key of the account to fetch.
+     * @returns {Promise<T | null>} The deserialized account data, or `null`.
+     * @protected
+     * @since v0.1.0
+     */
+    async fetchAccountNullable(accountName, address) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        return this.program.account[accountName].fetchNullable(address);
+    }
+    /**
+     * @name bn
+     * @description Create an Anchor `BN` from a number, bigint, or existing BN.
+     *   Passes through values that are already `BN` instances.
+     * @param value - The numeric value to convert.
+     * @returns {BN} An Anchor-compatible big number.
+     * @protected
+     * @since v0.1.0
+     */
+    bn(value) {
+        if (anchor_1.BN.isBN(value))
+            return value;
+        return new anchor_1.BN(value.toString());
+    }
+}
+exports.BaseModule = BaseModule;
+//# sourceMappingURL=base.js.map

package/dist/cjs/modules/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/modules/base.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,8CAA0E;AA2B1E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAsB,UAAU;IAOC;IAN/B;;;;;OAKG;IACH,YAA+B,OAAmB;QAAnB,YAAO,GAAP,OAAO,CAAY;IAAG,CAAC;IAEtD;;;;;;;;OAQG;IACH,8DAA8D;IAC9D,IAAc,OAAO;QACnB,+DAA+D;QAC/D,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACH,IAAc,QAAQ;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,QAA0B,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,IAAc,YAAY;QACxB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;IACxC,CAAC;IAED;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,YAAY,CAC1B,WAAmB,EACnB,OAAkB;QAElB,0GAA0G;QAC1G,OAAQ,IAAI,CAAC,OAAO,CAAC,OAAe,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,OAAO,CAAe,CAAC;IACjF,CAAC;IAED;;;;;;;;;;OAUG;IACO,KAAK,CAAC,oBAAoB,CAClC,WAAmB,EACnB,OAAkB;QAElB,0GAA0G;QAC1G,OAAQ,IAAI,CAAC,OAAO,CAAC,OAAe,CAAC,WAAW,CAAC,CAAC,aAAa,CAAC,OAAO,CAAsB,CAAC;IAChG,CAAC;IAED;;;;;;;;OAQG;IACO,EAAE,CAAC,KAA2B;QACtC,IAAI,WAAE,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,OAAO,IAAI,WAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClC,CAAC;CACF;AAnGD,gCAmGC"}

package/dist/cjs/modules/escrow.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * @module escrow
+ * @description x402 escrow settlement layer — create, deposit,
+ * settle, withdraw, batch settle, and close escrow accounts.
+ *
+ * Supports both SOL and SPL token escrows. SPL operations require
+ * passing additional `AccountMeta[]` via the `splAccounts` parameter.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EscrowModule = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const base_1 = require("./base");
+const pda_1 = require("../pda");
+/**
+ * @name EscrowModule
+ * @description Manages x402-compatible escrow accounts for agent micropayments.
+ *   Provides methods to create, fund, settle, withdraw, batch-settle, close,
+ *   and fetch escrow PDAs on the Solana Agent Protocol.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Create a SOL escrow for an agent
+ * const sig = await sap.escrow.create(agentWallet, {
+ *   pricePerCall: new BN(1_000_000),
+ *   maxCalls: new BN(100),
+ *   initialDeposit: new BN(100_000_000),
+ *   expiresAt: null,
+ *   volumeCurve: null,
+ *   tokenMint: null,
+ *   tokenDecimals: null,
+ * });
+ * ```
+ */
+class EscrowModule extends base_1.BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveEscrow
+     * @description Derive the `EscrowAccount` PDA for a given agent and depositor.
+     * @param agentPda - The agent account PDA.
+     * @param depositor - The depositor wallet. Defaults to the connected wallet.
+     * @returns A tuple of `[PublicKey, bump]` for the escrow PDA.
+     * @see {@link deriveEscrow} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveEscrow(agentPda, depositor) {
+        return (0, pda_1.deriveEscrow)(agentPda, depositor ?? this.walletPubkey);
+    }
+    // ── Instructions ─────────────────────────────────────
+    /**
+     * @name create
+     * @description Create a new escrow for agent micropayments.
+     *
+     *   For **SOL escrow**: pass `tokenMint: null` and leave `splAccounts` empty.
+     *   For **SPL escrow**: pass `tokenMint`, `tokenDecimals`, and provide
+     *   `splAccounts` with `[depositorAta, escrowAta, tokenMint, tokenProgram]`.
+     *
+     * @param agentWallet - The wallet of the agent to pay.
+     * @param args - Escrow creation parameters (price, max calls, deposit, expiry, volume curve, token info).
+     * @param splAccounts - Remaining accounts for SPL token transfers:
+     *   `[depositorAta, escrowAta, tokenMint, tokenProgram]`. Defaults to `[]`.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async create(agentWallet, args, splAccounts = []) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [escrowPda] = this.deriveEscrow(agentPda);
+        const [statsPda] = (0, pda_1.deriveAgentStats)(agentPda);
+        return this.methods
+            .createEscrow(args.pricePerCall, args.maxCalls, args.initialDeposit, args.expiresAt, args.volumeCurve, args.tokenMint, args.tokenDecimals)
+            .accounts({
+            depositor: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+            escrow: escrowPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .remainingAccounts(splAccounts)
+            .rpc();
+    }
+    /**
+     * @name deposit
+     * @description Deposit additional funds into an existing escrow.
+     * @param agentWallet - The wallet of the agent associated with the escrow.
+     * @param amount - The amount to deposit (lamports for SOL, smallest unit for SPL).
+     * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async deposit(agentWallet, amount, splAccounts = []) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [escrowPda] = this.deriveEscrow(agentPda);
+        return this.methods
+            .depositEscrow(this.bn(amount))
+            .accounts({
+            depositor: this.walletPubkey,
+            escrow: escrowPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .remainingAccounts(splAccounts)
+            .rpc();
+    }
+    /**
+     * @name settle
+     * @description Agent settles calls — claims earned funds from the escrow.
+     *   Must be called by the agent owner wallet.
+     * @param depositorWallet - The wallet of the client who funded the escrow.
+     * @param callsToSettle - Number of calls to settle payment for.
+     * @param serviceHash - A 32-byte SHA-256 hash identifying the service rendered.
+     * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async settle(depositorWallet, callsToSettle, serviceHash, splAccounts = []) {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [escrowPda] = (0, pda_1.deriveEscrow)(agentPda, depositorWallet);
+        const [statsPda] = (0, pda_1.deriveAgentStats)(agentPda);
+        return this.methods
+            .settleCalls(this.bn(callsToSettle), serviceHash)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+            escrow: escrowPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .remainingAccounts(splAccounts)
+            .rpc();
+    }
+    /**
+     * @name withdraw
+     * @description Client withdraws un-settled funds from their escrow.
+     * @param agentWallet - The wallet of the agent associated with the escrow.
+     * @param amount - The amount to withdraw (lamports for SOL, smallest unit for SPL).
+     * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async withdraw(agentWallet, amount, splAccounts = []) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [escrowPda] = this.deriveEscrow(agentPda);
+        return this.methods
+            .withdrawEscrow(this.bn(amount))
+            .accounts({
+            depositor: this.walletPubkey,
+            escrow: escrowPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .remainingAccounts(splAccounts)
+            .rpc();
+    }
+    /**
+     * @name close
+     * @description Close an empty escrow PDA (balance must be 0) and reclaim rent.
+     * @param agentWallet - The wallet of the agent associated with the escrow.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async close(agentWallet) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [escrowPda] = this.deriveEscrow(agentPda);
+        return this.methods
+            .closeEscrow()
+            .accounts({
+            depositor: this.walletPubkey,
+            escrow: escrowPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name settleBatch
+     * @description Batch settlement — process up to 10 settlements in a single
+     *   transaction. Must be called by the agent owner wallet.
+     * @param depositorWallet - The wallet of the client who funded the escrow.
+     * @param settlements - Array of settlement entries (up to 10).
+     * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async settleBatch(depositorWallet, settlements, splAccounts = []) {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [escrowPda] = (0, pda_1.deriveEscrow)(agentPda, depositorWallet);
+        const [statsPda] = (0, pda_1.deriveAgentStats)(agentPda);
+        return this.methods
+            .settleBatch(settlements)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+            escrow: escrowPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .remainingAccounts(splAccounts)
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetch
+     * @description Fetch a deserialized `EscrowAccount`.
+     * @param agentPda - The agent account PDA.
+     * @param depositor - The depositor wallet. Defaults to the connected wallet.
+     * @returns {Promise<EscrowAccountData>} The escrow account data.
+     * @throws Will throw if the escrow account does not exist.
+     * @since v0.1.0
+     */
+    async fetch(agentPda, depositor) {
+        const [pda] = this.deriveEscrow(agentPda, depositor);
+        return this.fetchAccount("escrowAccount", pda);
+    }
+    /**
+     * @name fetchNullable
+     * @description Fetch a deserialized `EscrowAccount`, or `null` if it
+     *   does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @param depositor - The depositor wallet. Defaults to the connected wallet.
+     * @returns {Promise<EscrowAccountData | null>} The escrow data or `null`.
+     * @since v0.1.0
+     */
+    async fetchNullable(agentPda, depositor) {
+        const [pda] = this.deriveEscrow(agentPda, depositor);
+        return this.fetchAccountNullable("escrowAccount", pda);
+    }
+    /**
+     * @name fetchByPda
+     * @description Fetch an escrow account by its PDA address directly,
+     *   bypassing PDA derivation.
+     * @param escrowPda - The escrow PDA public key.
+     * @returns {Promise<EscrowAccountData>} The escrow account data.
+     * @throws Will throw if the escrow account does not exist.
+     * @since v0.1.0
+     */
+    async fetchByPda(escrowPda) {
+        return this.fetchAccount("escrowAccount", escrowPda);
+    }
+}
+exports.EscrowModule = EscrowModule;
+//# sourceMappingURL=escrow.js.map

package/dist/cjs/modules/escrow.js.map

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

package/dist/cjs/modules/feedback.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * @module feedback
+ * @description Trustless reputation system — give, update, revoke, and close
+ *   on-chain feedback entries for agents.
+ *
+ * Feedback entries are PDA-based reviews tied to an agent and a reviewer wallet,
+ * enabling permissionless, verifiable reputation on Solana.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeedbackModule = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const base_1 = require("./base");
+const pda_1 = require("../pda");
+/**
+ * @name FeedbackModule
+ * @description Manages on-chain feedback entries for the Solana Agent Protocol.
+ *   Provides methods to give, update, revoke, close, and fetch feedback PDAs
+ *   that form the trustless reputation layer.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * const sig = await sap.feedback.give(agentWallet, {
+ *   score: 5,
+ *   tag: { quality: {} },
+ *   commentHash: null,
+ * });
+ * ```
+ */
+class FeedbackModule extends base_1.BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveFeedback
+     * @description Derive the `FeedbackAccount` PDA for a given agent and reviewer.
+     * @param agentPda - The agent account PDA to review.
+     * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+     * @returns A tuple of `[PublicKey, bump]` for the feedback PDA.
+     * @see {@link deriveFeedback} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveFeedback(agentPda, reviewer) {
+        return (0, pda_1.deriveFeedback)(agentPda, reviewer ?? this.walletPubkey);
+    }
+    // ── Instructions ─────────────────────────────────────
+    /**
+     * @name give
+     * @description Leave on-chain feedback for an agent. Creates a new
+     *   `FeedbackAccount` PDA owned by the reviewer.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @param args - Feedback parameters (score, tag, optional comment hash).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async give(agentWallet, args) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [feedbackPda] = this.deriveFeedback(agentPda);
+        const [globalPda] = (0, pda_1.deriveGlobalRegistry)();
+        return this.methods
+            .giveFeedback(args.score, args.tag, args.commentHash ?? null)
+            .accounts({
+            reviewer: this.walletPubkey,
+            agent: agentPda,
+            feedback: feedbackPda,
+            globalRegistry: globalPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name update
+     * @description Update an existing feedback entry. Only the original reviewer
+     *   may update their feedback.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @param args - Updated feedback parameters (new score, optional new tag, optional comment hash).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async update(agentWallet, args) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [feedbackPda] = this.deriveFeedback(agentPda);
+        return this.methods
+            .updateFeedback(args.newScore, args.newTag ?? null, args.commentHash ?? null)
+            .accounts({
+            reviewer: this.walletPubkey,
+            agent: agentPda,
+            feedback: feedbackPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name revoke
+     * @description Revoke a feedback entry, marking it as revoked and excluding
+     *   it from reputation calculations.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async revoke(agentWallet) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [feedbackPda] = this.deriveFeedback(agentPda);
+        return this.methods
+            .revokeFeedback()
+            .accounts({
+            reviewer: this.walletPubkey,
+            agent: agentPda,
+            feedback: feedbackPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name close
+     * @description Close a revoked feedback PDA and reclaim rent to the reviewer.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async close(agentWallet) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [feedbackPda] = this.deriveFeedback(agentPda);
+        return this.methods
+            .closeFeedback()
+            .accounts({
+            reviewer: this.walletPubkey,
+            feedback: feedbackPda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetch
+     * @description Fetch a deserialized `FeedbackAccount`.
+     * @param agentPda - The agent account PDA.
+     * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+     * @returns {Promise<FeedbackAccountData>} The feedback account data.
+     * @throws Will throw if the feedback account does not exist.
+     * @since v0.1.0
+     */
+    async fetch(agentPda, reviewer) {
+        const [pda] = this.deriveFeedback(agentPda, reviewer);
+        return this.fetchAccount("feedbackAccount", pda);
+    }
+    /**
+     * @name fetchNullable
+     * @description Fetch a deserialized `FeedbackAccount`, or `null` if it
+     *   does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+     * @returns {Promise<FeedbackAccountData | null>} The feedback data or `null`.
+     * @since v0.1.0
+     */
+    async fetchNullable(agentPda, reviewer) {
+        const [pda] = this.deriveFeedback(agentPda, reviewer);
+        return this.fetchAccountNullable("feedbackAccount", pda);
+    }
+}
+exports.FeedbackModule = FeedbackModule;
+//# sourceMappingURL=feedback.js.map

package/dist/cjs/modules/feedback.js.map

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

package/dist/cjs/modules/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @module modules
+ * @description Barrel export for all domain modules of the `@synapse-sap/sdk`.
+ *
+ * Re-exports every module class so consumers can import from a single entry point:
+ * ```ts
+ * import { AgentModule, VaultModule } from "@synapse-sap/sdk/modules";
+ * ```
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseModule = exports.LedgerModule = exports.AttestationModule = exports.EscrowModule = exports.VaultModule = exports.ToolsModule = exports.IndexingModule = exports.FeedbackModule = exports.AgentModule = void 0;
+var agent_1 = require("./agent");
+Object.defineProperty(exports, "AgentModule", { enumerable: true, get: function () { return agent_1.AgentModule; } });
+var feedback_1 = require("./feedback");
+Object.defineProperty(exports, "FeedbackModule", { enumerable: true, get: function () { return feedback_1.FeedbackModule; } });
+var indexing_1 = require("./indexing");
+Object.defineProperty(exports, "IndexingModule", { enumerable: true, get: function () { return indexing_1.IndexingModule; } });
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "ToolsModule", { enumerable: true, get: function () { return tools_1.ToolsModule; } });
+var vault_1 = require("./vault");
+Object.defineProperty(exports, "VaultModule", { enumerable: true, get: function () { return vault_1.VaultModule; } });
+var escrow_1 = require("./escrow");
+Object.defineProperty(exports, "EscrowModule", { enumerable: true, get: function () { return escrow_1.EscrowModule; } });
+var attestation_1 = require("./attestation");
+Object.defineProperty(exports, "AttestationModule", { enumerable: true, get: function () { return attestation_1.AttestationModule; } });
+var ledger_1 = require("./ledger");
+Object.defineProperty(exports, "LedgerModule", { enumerable: true, get: function () { return ledger_1.LedgerModule; } });
+var base_1 = require("./base");
+Object.defineProperty(exports, "BaseModule", { enumerable: true, get: function () { return base_1.BaseModule; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/modules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,iCAAsC;AAA7B,oGAAA,WAAW,OAAA;AACpB,uCAA4C;AAAnC,0GAAA,cAAc,OAAA;AACvB,uCAA4C;AAAnC,0GAAA,cAAc,OAAA;AACvB,iCAAsC;AAA7B,oGAAA,WAAW,OAAA;AACpB,iCAAsC;AAA7B,oGAAA,WAAW,OAAA;AACpB,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AACrB,6CAAkD;AAAzC,gHAAA,iBAAiB,OAAA;AAC1B,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AACrB,+BAAoC;AAA3B,kGAAA,UAAU,OAAA"}