@4mica/sdk 0.5.6 → 1.0.1

package/dist/client/recipient.js

@@ -9,6 +9,7 @@ const models_1 = require("../models");
 const debug_1 = require("../debug");
 const utils_1 = require("../utils");
 const shared_1 = require("./shared");
+/** Recipient-side operations: tab management, guarantee issuance, remuneration. */
 class RecipientClient {
     client;
     constructor(client) {
@@ -20,6 +21,17 @@ class RecipientClient {
     get guaranteeDomain() {
         return this.client.guaranteeDomain;
     }
+    /**
+     * Create a payment tab via the core RPC.
+     *
+     * @param userAddress - Address of the payer.
+     * @param recipientAddress - Address of the recipient.
+     * @param erc20Token - ERC20 token address for the tab, or `null`/`undefined` for ETH.
+     * @param ttl - Optional time-to-live in seconds.
+     * @returns `{ tabId, assetAddress, nextReqId }` — the tab ID, the asset address as stored
+     *   by the core (use this for all subsequent claims), and the first request ID to use.
+     * @throws {@link RpcError} if the request fails.
+     */
     async createTab(userAddress, recipientAddress, erc20Token, ttl) {
         const body = {
             user_address: (0, utils_1.normalizeAddress)(userAddress),
@@ -31,12 +43,39 @@ class RecipientClient {
         const record = result;
         const tabIdRaw = record.id ?? record.tabId ?? record.tab_id;
         const tabId = (0, shared_1.isNumericLike)(tabIdRaw) ? tabIdRaw : 0;
-        return (0, utils_1.parseU256)(tabId);
+        const erc20Raw = record.erc20_token ?? record.erc20Token;
+        const assetAddress = typeof erc20Raw === 'string' && erc20Raw
+            ? erc20Raw
+            : '0x0000000000000000000000000000000000000000';
+        const nextReqIdRaw = record.next_req_id ?? record.nextReqId ?? 0;
+        return {
+            tabId: (0, utils_1.parseU256)(tabId),
+            assetAddress,
+            nextReqId: (0, utils_1.parseU256)((0, shared_1.isNumericLike)(nextReqIdRaw) ? nextReqIdRaw : 0),
+        };
     }
+    /**
+     * Query the on-chain payment status of a tab.
+     *
+     * @param tabId - Tab identifier.
+     * @returns `{ paid, remunerated, asset }`.
+     */
     async getTabPaymentStatus(tabId) {
         const status = await this.client.gateway.getPaymentStatus(tabId);
         return (0, shared_1.tabStatusFromRpc)(status);
     }
+    /**
+     * Issue a BLS-signed payment guarantee certificate via the core RPC.
+     *
+     * The returned {@link BLSCert} can be stored and later passed to
+     * {@link remunerate} to claim the payment on-chain.
+     *
+     * @param claims - Signed payment claims (V1 or V2).
+     * @param signature - ECDSA signature hex string from the payer.
+     * @param scheme - Signing scheme used to produce the signature.
+     * @returns BLS certificate with ABI-encoded claims and BLS signature.
+     * @throws {@link RpcError} if the core service rejects the request.
+     */
     async issuePaymentGuarantee(claims, signature, scheme) {
         const payload = (0, payment_1.buildPaymentPayload)(claims, signature, scheme);
         const cert = await this.client.rpc.issueGuarantee(payload);
@@ -45,19 +84,59 @@ class RecipientClient {
         const signatureOut = typeof record.signature === 'string' ? record.signature : '';
         return { claims: certClaims, signature: signatureOut };
     }
-    verifyPaymentGuarantee(cert) {
+    /**
+     * Verify and decode a BLS guarantee certificate.
+     *
+     * Decodes the ABI-encoded claims and validates the domain separator against
+     * the on-chain configuration. For V2 certificates, the active V2 domain is
+     * fetched from the contract and verified to be enabled.
+     *
+     * @param cert - BLS certificate (hex-encoded claims + hex-encoded signature).
+     * @returns Decoded {@link PaymentGuaranteeClaims}, including validation policy for V2.
+     * @throws {@link VerificationError} on domain mismatch, invalid length, or disabled version.
+     */
+    async verifyPaymentGuarantee(cert) {
         const claims = (0, guarantee_1.decodeGuaranteeClaims)(cert.claims);
-        const domainHex = this.guaranteeDomain.startsWith('0x')
-            ? this.guaranteeDomain.slice(2)
-            : Buffer.from(this.guaranteeDomain).toString('hex');
+        let expectedDomain;
+        if (claims.version === 2) {
+            const { domainSeparator, enabled } = await this.client.gateway.getGuaranteeVersionConfig(2);
+            if (!enabled) {
+                throw new errors_1.VerificationError('guarantee version 2 is not enabled on-chain');
+            }
+            expectedDomain = domainSeparator;
+        }
+        else {
+            expectedDomain = this.guaranteeDomain;
+        }
+        const domainHex = expectedDomain.startsWith('0x')
+            ? expectedDomain.slice(2)
+            : Buffer.from(expectedDomain).toString('hex');
+        if (domainHex.length !== 64) {
+            throw new errors_1.VerificationError(`guarantee domain separator has invalid length: expected 32 bytes, got ${domainHex.length / 2}`);
+        }
         const claimsHex = Buffer.from(claims.domain).toString('hex');
         if (claimsHex !== domainHex) {
             throw new errors_1.VerificationError('guarantee domain mismatch');
         }
         return claims;
     }
+    /**
+     * Claim payment on-chain by submitting a verified BLS certificate.
+     *
+     * Verifies the certificate first (see {@link verifyPaymentGuarantee}), then
+     * converts the BLS signature into the G2 coordinate words expected by the
+     * contract and submits the `remunerate` transaction.
+     *
+     * Requires the optional `@noble/curves` package for BLS point decompression.
+     *
+     * @param cert - BLS certificate to settle.
+     * @param waitOptions - Optional timeout/polling overrides for receipt polling.
+     * @throws {@link VerificationError} if the certificate is invalid or `claims`/`signature`
+     *   are not hex strings.
+     * @throws {@link ContractError} if the contract call fails.
+     */
     async remunerate(cert, waitOptions) {
-        this.verifyPaymentGuarantee(cert);
+        await this.verifyPaymentGuarantee(cert);
         const describeValue = (value) => {
             if (value === null)
                 return 'null';
@@ -88,42 +167,86 @@ class RecipientClient {
         }
         return this.client.gateway.remunerate(claimsBytes, sigWords);
     }
+    /** List all tabs for this recipient that have been settled on-chain. */
     async listSettledTabs() {
         const tabs = await this.client.rpc.listSettledTabs(this.recipientAddress);
         return tabs.map((t) => models_1.TabInfo.fromRpc(t));
     }
+    /** List all tabs with outstanding (un-remunerated) guarantees for this recipient. */
     async listPendingRemunerations() {
         const items = await this.client.rpc.listPendingRemunerations(this.recipientAddress);
         return items.map((item) => models_1.PendingRemunerationInfo.fromRpc(item));
     }
+    /**
+     * Fetch a single tab by ID.
+     *
+     * @param tabId - Tab identifier.
+     * @returns The tab, or `null` if not found.
+     */
     async getTab(tabId) {
         const result = await this.client.rpc.getTab(tabId);
         return result ? models_1.TabInfo.fromRpc(result) : null;
     }
+    /**
+     * List all tabs belonging to this recipient.
+     *
+     * @param settlementStatuses - Optional filter on settlement status (e.g. `['PENDING']`).
+     */
     async listRecipientTabs(settlementStatuses) {
         const tabs = await this.client.rpc.listRecipientTabs(this.recipientAddress, settlementStatuses);
         return tabs.map((t) => models_1.TabInfo.fromRpc(t));
     }
+    /**
+     * List all guarantee requests associated with a tab.
+     *
+     * @param tabId - Tab identifier.
+     */
     async getTabGuarantees(tabId) {
         const guarantees = await this.client.rpc.getTabGuarantees(tabId);
         return guarantees.map((g) => models_1.GuaranteeInfo.fromRpc(g));
     }
+    /**
+     * Fetch the most recent guarantee for a tab.
+     *
+     * @param tabId - Tab identifier.
+     * @returns The latest {@link GuaranteeInfo}, or `null` if none exists.
+     */
     async getLatestGuarantee(tabId) {
         const result = await this.client.rpc.getLatestGuarantee(tabId);
         return result ? models_1.GuaranteeInfo.fromRpc(result) : null;
     }
+    /**
+     * Fetch a specific guarantee by tab ID and request ID.
+     *
+     * @param tabId - Tab identifier.
+     * @param reqId - Guarantee request identifier.
+     * @returns The {@link GuaranteeInfo}, or `null` if not found.
+     */
     async getGuarantee(tabId, reqId) {
         const result = await this.client.rpc.getGuarantee(tabId, reqId);
         return result ? models_1.GuaranteeInfo.fromRpc(result) : null;
     }
+    /** List all on-chain payments received by this recipient. */
     async listRecipientPayments() {
         const payments = await this.client.rpc.listRecipientPayments(this.recipientAddress);
         return payments.map((p) => models_1.RecipientPaymentInfo.fromRpc(p));
     }
+    /**
+     * List collateral deposit/withdrawal events associated with a tab.
+     *
+     * @param tabId - Tab identifier.
+     */
     async getCollateralEventsForTab(tabId) {
         const events = await this.client.rpc.getCollateralEventsForTab(tabId);
         return events.map((ev) => models_1.CollateralEventInfo.fromRpc(ev));
     }
+    /**
+     * Fetch the collateral balance a user has locked for a specific asset.
+     *
+     * @param userAddress - Address of the payer.
+     * @param assetAddress - ERC20 token address, or zero address for ETH.
+     * @returns Balance info, or `null` if no record exists.
+     */
     async getUserAssetBalance(userAddress, assetAddress) {
         const balance = await this.client.rpc.getUserAssetBalance(userAddress, assetAddress);
         return balance ? models_1.AssetBalanceInfo.fromRpc(balance) : null;

package/dist/client/user.d.ts

@@ -1,17 +1,93 @@
-import { PaymentGuaranteeRequestClaims, PaymentSignature, SigningScheme, TabPaymentStatus, UserInfo } from '../models';
+import { PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2, PaymentSignature, SigningScheme, TabPaymentStatus, UserInfo } from '../models';
 import type { TxReceiptWaitOptions } from '../contract';
 import type { Client } from './index';
+/** Payer-side operations: collateral management, payment signing, withdrawals. */
 export declare class UserClient {
     private client;
     constructor(client: Client);
+    /** 32-byte V1 guarantee domain separator (hex-prefixed). */
     get guaranteeDomain(): string;
+    /**
+     * Approve the Core4Mica contract to spend an ERC20 token on your behalf.
+     * Call this before {@link deposit} for ERC20 deposits.
+     *
+     * @param token - ERC20 token contract address.
+     * @param amount - Amount to approve (in token base units).
+     * @param waitOptions - Optional timeout/polling overrides for receipt polling.
+     */
     approveErc20(token: string, amount: number | bigint | string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
+    /**
+     * Deposit collateral into the Core4Mica contract.
+     *
+     * @param amount - Amount to deposit (in wei for ETH, base units for ERC20).
+     * @param erc20Token - ERC20 token address. Omit to deposit ETH.
+     *   Call {@link approveErc20} first when depositing ERC20.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     deposit(amount: number | bigint | string, erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
+    /**
+     * Fetch all asset positions for the current signer.
+     *
+     * @returns Array of positions — one entry per deposited asset, including
+     *   locked collateral and any pending withdrawal.
+     * @throws {@link ContractError} if the contract call fails.
+     */
     getUser(): Promise<UserInfo[]>;
+    /**
+     * Query the on-chain payment status of a tab.
+     *
+     * @param tabId - Tab identifier.
+     * @returns `{ paid, remunerated, asset }` — cumulative amount paid, whether
+     *   it has been remunerated on-chain, and the asset address.
+     */
     getTabPaymentStatus(tabId: number | bigint): Promise<TabPaymentStatus>;
-    signPayment(claims: PaymentGuaranteeRequestClaims, scheme?: SigningScheme): Promise<PaymentSignature>;
+    /**
+     * Sign a payment guarantee request with the configured signer.
+     *
+     * @param claims - V1 or V2 payment claims. Build V1 with
+     *   {@link PaymentGuaranteeRequestClaims.new}; build V2 with
+     *   {@link PaymentGuaranteeRequestClaimsV2} (requires validation policy fields).
+     * @param scheme - Signing scheme. Defaults to `EIP712`.
+     *   Use `EIP191` for wallets that do not support typed data.
+     * @returns 65-byte ECDSA signature plus the scheme used.
+     * @throws {@link SigningError} if the signer address does not match `claims.userAddress`
+     *   or the signing scheme is not supported by the account.
+     */
+    signPayment(claims: PaymentGuaranteeRequestClaims | PaymentGuaranteeRequestClaimsV2, scheme?: SigningScheme): Promise<PaymentSignature>;
+    /**
+     * Pay a tab by transferring collateral to the recipient.
+     *
+     * Routes to `payTabErc20` when `erc20Token` is provided, otherwise `payTabEth`.
+     *
+     * @param tabId - Tab identifier.
+     * @param reqId - Request ID from the latest guarantee (used for ETH payment memo).
+     * @param amount - Amount to pay (in token base units / wei).
+     * @param recipientAddress - Address of the recipient.
+     * @param erc20Token - ERC20 token address. Omit to pay in ETH.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     payTab(tabId: number | bigint, reqId: number | bigint, amount: number | bigint | string, recipientAddress: string, erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
+    /**
+     * Initiate a collateral withdrawal request. The withdrawal is subject to an
+     * on-chain timelock before it can be finalised.
+     *
+     * @param amount - Amount to withdraw (base units / wei).
+     * @param erc20Token - ERC20 token address. Omit to withdraw ETH.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     requestWithdrawal(amount: number | bigint | string, erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
+    /**
+     * Cancel a pending withdrawal request before the timelock expires.
+     *
+     * @param erc20Token - ERC20 token address. Omit to cancel an ETH withdrawal.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     cancelWithdrawal(erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
+    /**
+     * Finalise a withdrawal after the timelock has elapsed.
+     *
+     * @param erc20Token - ERC20 token address. Omit to finalise an ETH withdrawal.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     finalizeWithdrawal(erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
 }

package/dist/client/user.js

@@ -4,26 +4,45 @@ exports.UserClient = void 0;
 const models_1 = require("../models");
 const shared_1 = require("./shared");
 const utils_1 = require("../utils");
+/** Payer-side operations: collateral management, payment signing, withdrawals. */
 class UserClient {
     client;
     constructor(client) {
         this.client = client;
     }
+    /** 32-byte V1 guarantee domain separator (hex-prefixed). */
     get guaranteeDomain() {
         return this.client.guaranteeDomain;
     }
+    /**
+     * Approve the Core4Mica contract to spend an ERC20 token on your behalf.
+     * Call this before {@link deposit} for ERC20 deposits.
+     *
+     * @param token - ERC20 token contract address.
+     * @param amount - Amount to approve (in token base units).
+     * @param waitOptions - Optional timeout/polling overrides for receipt polling.
+     */
     async approveErc20(token, amount, waitOptions) {
-        if (waitOptions) {
-            return this.client.gateway.approveErc20(token, amount, waitOptions);
-        }
-        return this.client.gateway.approveErc20(token, amount);
+        return this.client.gateway.approveErc20(token, amount, waitOptions);
     }
+    /**
+     * Deposit collateral into the Core4Mica contract.
+     *
+     * @param amount - Amount to deposit (in wei for ETH, base units for ERC20).
+     * @param erc20Token - ERC20 token address. Omit to deposit ETH.
+     *   Call {@link approveErc20} first when depositing ERC20.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     async deposit(amount, erc20Token, waitOptions) {
-        if (waitOptions) {
-            return this.client.gateway.deposit(amount, erc20Token, waitOptions);
-        }
-        return this.client.gateway.deposit(amount, erc20Token);
+        return this.client.gateway.deposit(amount, erc20Token, waitOptions);
     }
+    /**
+     * Fetch all asset positions for the current signer.
+     *
+     * @returns Array of positions — one entry per deposited asset, including
+     *   locked collateral and any pending withdrawal.
+     * @throws {@link ContractError} if the contract call fails.
+     */
     async getUser() {
         const assets = await this.client.gateway.getUserAssets();
         return assets.map((a) => ({
@@ -33,42 +52,78 @@ class UserClient {
             withdrawalRequestTimestamp: Number(a.withdrawalRequestTimestamp),
         }));
     }
+    /**
+     * Query the on-chain payment status of a tab.
+     *
+     * @param tabId - Tab identifier.
+     * @returns `{ paid, remunerated, asset }` — cumulative amount paid, whether
+     *   it has been remunerated on-chain, and the asset address.
+     */
     async getTabPaymentStatus(tabId) {
         const status = await this.client.gateway.getPaymentStatus(tabId);
         return (0, shared_1.tabStatusFromRpc)(status);
     }
+    /**
+     * Sign a payment guarantee request with the configured signer.
+     *
+     * @param claims - V1 or V2 payment claims. Build V1 with
+     *   {@link PaymentGuaranteeRequestClaims.new}; build V2 with
+     *   {@link PaymentGuaranteeRequestClaimsV2} (requires validation policy fields).
+     * @param scheme - Signing scheme. Defaults to `EIP712`.
+     *   Use `EIP191` for wallets that do not support typed data.
+     * @returns 65-byte ECDSA signature plus the scheme used.
+     * @throws {@link SigningError} if the signer address does not match `claims.userAddress`
+     *   or the signing scheme is not supported by the account.
+     */
     async signPayment(claims, scheme = models_1.SigningScheme.EIP712) {
         return this.client.signer.signRequest(this.client.params, claims, scheme);
     }
+    /**
+     * Pay a tab by transferring collateral to the recipient.
+     *
+     * Routes to `payTabErc20` when `erc20Token` is provided, otherwise `payTabEth`.
+     *
+     * @param tabId - Tab identifier.
+     * @param reqId - Request ID from the latest guarantee (used for ETH payment memo).
+     * @param amount - Amount to pay (in token base units / wei).
+     * @param recipientAddress - Address of the recipient.
+     * @param erc20Token - ERC20 token address. Omit to pay in ETH.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     async payTab(tabId, reqId, amount, recipientAddress, erc20Token, waitOptions) {
         if (erc20Token) {
-            if (waitOptions) {
-                return this.client.gateway.payTabErc20(tabId, amount, erc20Token, recipientAddress, waitOptions);
-            }
-            return this.client.gateway.payTabErc20(tabId, amount, erc20Token, recipientAddress);
-        }
-        if (waitOptions) {
-            return this.client.gateway.payTabEth(tabId, reqId, amount, recipientAddress, waitOptions);
+            return this.client.gateway.payTabErc20(tabId, amount, erc20Token, recipientAddress, waitOptions);
         }
-        return this.client.gateway.payTabEth(tabId, reqId, amount, recipientAddress);
+        return this.client.gateway.payTabEth(tabId, reqId, amount, recipientAddress, waitOptions);
     }
+    /**
+     * Initiate a collateral withdrawal request. The withdrawal is subject to an
+     * on-chain timelock before it can be finalised.
+     *
+     * @param amount - Amount to withdraw (base units / wei).
+     * @param erc20Token - ERC20 token address. Omit to withdraw ETH.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     async requestWithdrawal(amount, erc20Token, waitOptions) {
-        if (waitOptions) {
-            return this.client.gateway.requestWithdrawal(amount, erc20Token, waitOptions);
-        }
-        return this.client.gateway.requestWithdrawal(amount, erc20Token);
+        return this.client.gateway.requestWithdrawal(amount, erc20Token, waitOptions);
     }
+    /**
+     * Cancel a pending withdrawal request before the timelock expires.
+     *
+     * @param erc20Token - ERC20 token address. Omit to cancel an ETH withdrawal.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     async cancelWithdrawal(erc20Token, waitOptions) {
-        if (waitOptions) {
-            return this.client.gateway.cancelWithdrawal(erc20Token, waitOptions);
-        }
-        return this.client.gateway.cancelWithdrawal(erc20Token);
+        return this.client.gateway.cancelWithdrawal(erc20Token, waitOptions);
     }
+    /**
+     * Finalise a withdrawal after the timelock has elapsed.
+     *
+     * @param erc20Token - ERC20 token address. Omit to finalise an ETH withdrawal.
+     * @param waitOptions - Optional timeout/polling overrides.
+     */
     async finalizeWithdrawal(erc20Token, waitOptions) {
-        if (waitOptions) {
-            return this.client.gateway.finalizeWithdrawal(erc20Token, waitOptions);
-        }
-        return this.client.gateway.finalizeWithdrawal(erc20Token);
+        return this.client.gateway.finalizeWithdrawal(erc20Token, waitOptions);
     }
 }
 exports.UserClient = UserClient;

package/dist/config.d.ts

@@ -1,14 +1,35 @@
 import { Account } from 'viem/accounts';
+/** Validated configuration used to construct a {@link Client}. Produced by {@link ConfigBuilder.build}. */
 export interface Config {
+    /** URL of the 4Mica core RPC service. */
     rpcUrl: string;
+    /** viem `Account` used to sign payments and authenticate requests. */
     signer: Account;
+    /** Override for the Ethereum HTTP RPC URL (defaults to the value returned by the core service). */
     ethereumHttpRpcUrl?: string;
+    /** Override for the Core4Mica contract address (defaults to the value returned by the core service). */
     contractAddress?: string;
+    /** API key for admin-scoped RPC endpoints. */
     adminApiKey?: string;
+    /** Static bearer token for authenticated RPC calls. Mutually exclusive with SIWE auth. */
     bearerToken?: string;
+    /** URL of the SIWE authentication endpoint. Defaults to `rpcUrl` when auth is enabled. */
     authUrl?: string;
+    /** Seconds before token expiry at which the auth session proactively refreshes. Defaults to 60. */
     authRefreshMarginSecs?: number;
 }
+/**
+ * Fluent builder for {@link Config}.
+ *
+ * @example
+ * ```ts
+ * const cfg = new ConfigBuilder()
+ *   .walletPrivateKey('0x...')
+ *   .build();
+ * ```
+ *
+ * All fields can also be supplied from environment variables via {@link fromEnv}.
+ */
 export declare class ConfigBuilder {
     private _rpcUrl;
     private _walletPrivateKey;
@@ -20,16 +41,45 @@ export declare class ConfigBuilder {
     private _authEnabled;
     private _authUrl?;
     private _authRefreshMarginSecs?;
+    /** Override the 4Mica core RPC URL. Defaults to `https://api.4mica.xyz/`. */
     rpcUrl(value: string): ConfigBuilder;
+    /** Set the wallet private key (hex string). Mutually exclusive with {@link signer}. */
     walletPrivateKey(value: string): ConfigBuilder;
+    /** Set a pre-built viem `Account` directly. Mutually exclusive with {@link walletPrivateKey}. */
     signer(value: Account): ConfigBuilder;
+    /** Override the Ethereum HTTP RPC URL used for on-chain calls. */
     ethereumHttpRpcUrl(value: string): ConfigBuilder;
+    /** Override the Core4Mica contract address. */
     contractAddress(value: string): ConfigBuilder;
+    /** Set an admin API key for privileged RPC endpoints. */
     adminApiKey(value: string): ConfigBuilder;
+    /** Set a static bearer token for authenticated RPC calls. Disables SIWE auth. */
     bearerToken(value: string): ConfigBuilder;
+    /** Enable SIWE authentication using the default RPC URL as the auth endpoint. Auth is enabled by default; this is a no-op unless you previously called a method that disabled it. */
     enableAuth(): ConfigBuilder;
+    /** Set a custom SIWE authentication endpoint and enable auth. */
     authUrl(value: string): ConfigBuilder;
+    /** Set the number of seconds before token expiry at which the session proactively refreshes. Enables auth. */
     authRefreshMarginSecs(value: number): ConfigBuilder;
+    /**
+     * Load configuration from environment variables.
+     *
+     * Recognised variables:
+     * - `4MICA_RPC_URL`
+     * - `4MICA_WALLET_PRIVATE_KEY`
+     * - `4MICA_ETHEREUM_HTTP_RPC_URL`
+     * - `4MICA_CONTRACT_ADDRESS`
+     * - `4MICA_ADMIN_API_KEY`
+     * - `4MICA_BEARER_TOKEN`
+     * - `4MICA_AUTH_URL`
+     * - `4MICA_AUTH_REFRESH_MARGIN_SECS`
+     */
     fromEnv(): ConfigBuilder;
+    /**
+     * Validate all settings and return an immutable {@link Config}.
+     *
+     * @throws {@link ConfigError} if required fields are missing, URLs are invalid,
+     *   or the auth refresh margin is not a finite non-negative number.
+     */
     build(): Config;
 }

package/dist/config.js

@@ -4,6 +4,18 @@ exports.ConfigBuilder = void 0;
 const accounts_1 = require("viem/accounts");
 const errors_1 = require("./errors");
 const utils_1 = require("./utils");
+/**
+ * Fluent builder for {@link Config}.
+ *
+ * @example
+ * ```ts
+ * const cfg = new ConfigBuilder()
+ *   .walletPrivateKey('0x...')
+ *   .build();
+ * ```
+ *
+ * All fields can also be supplied from environment variables via {@link fromEnv}.
+ */
 class ConfigBuilder {
     _rpcUrl = 'https://api.4mica.xyz/';
     _walletPrivateKey;
@@ -12,51 +24,74 @@ class ConfigBuilder {
     _contractAddress;
     _adminApiKey;
     _bearerToken;
-    _authEnabled = false;
+    _authEnabled = true;
     _authUrl;
     _authRefreshMarginSecs;
+    /** Override the 4Mica core RPC URL. Defaults to `https://api.4mica.xyz/`. */
     rpcUrl(value) {
         this._rpcUrl = value;
         return this;
     }
+    /** Set the wallet private key (hex string). Mutually exclusive with {@link signer}. */
     walletPrivateKey(value) {
         this._walletPrivateKey = value;
         return this;
     }
+    /** Set a pre-built viem `Account` directly. Mutually exclusive with {@link walletPrivateKey}. */
     signer(value) {
         this._signer = value;
         return this;
     }
+    /** Override the Ethereum HTTP RPC URL used for on-chain calls. */
     ethereumHttpRpcUrl(value) {
         this._ethereumHttpRpcUrl = value;
         return this;
     }
+    /** Override the Core4Mica contract address. */
     contractAddress(value) {
         this._contractAddress = value;
         return this;
     }
+    /** Set an admin API key for privileged RPC endpoints. */
     adminApiKey(value) {
         this._adminApiKey = value;
         return this;
     }
+    /** Set a static bearer token for authenticated RPC calls. Disables SIWE auth. */
     bearerToken(value) {
         this._bearerToken = value;
         return this;
     }
+    /** Enable SIWE authentication using the default RPC URL as the auth endpoint. Auth is enabled by default; this is a no-op unless you previously called a method that disabled it. */
     enableAuth() {
         this._authEnabled = true;
         return this;
     }
+    /** Set a custom SIWE authentication endpoint and enable auth. */
     authUrl(value) {
         this._authUrl = value;
         this._authEnabled = true;
         return this;
     }
+    /** Set the number of seconds before token expiry at which the session proactively refreshes. Enables auth. */
     authRefreshMarginSecs(value) {
         this._authRefreshMarginSecs = value;
         this._authEnabled = true;
         return this;
     }
+    /**
+     * Load configuration from environment variables.
+     *
+     * Recognised variables:
+     * - `4MICA_RPC_URL`
+     * - `4MICA_WALLET_PRIVATE_KEY`
+     * - `4MICA_ETHEREUM_HTTP_RPC_URL`
+     * - `4MICA_CONTRACT_ADDRESS`
+     * - `4MICA_ADMIN_API_KEY`
+     * - `4MICA_BEARER_TOKEN`
+     * - `4MICA_AUTH_URL`
+     * - `4MICA_AUTH_REFRESH_MARGIN_SECS`
+     */
     fromEnv() {
         const env = process.env;
         if (env['4MICA_RPC_URL'])
@@ -81,6 +116,12 @@ class ConfigBuilder {
         }
         return this;
     }
+    /**
+     * Validate all settings and return an immutable {@link Config}.
+     *
+     * @throws {@link ConfigError} if required fields are missing, URLs are invalid,
+     *   or the auth refresh margin is not a finite non-negative number.
+     */
     build() {
         if (!this._signer && !this._walletPrivateKey) {
             throw new errors_1.ConfigError('missing signer or wallet_private_key');