@open-captable-protocol/canton 0.2.149 → 0.2.151

package/dist/errors/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACU,QAAA,aAAa,GAAG;IAC3B,oBAAoB;IACpB,sBAAsB,EAAE,wBAAwB;IAChD,YAAY,EAAE,cAAc;IAC5B,cAAc,EAAE,gBAAgB;IAChC,YAAY,EAAE,cAAc;IAE5B,kBAAkB;IAClB,kBAAkB,EAAE,oBAAoB;IACxC,aAAa,EAAE,eAAe;IAC9B,oBAAoB,EAAE,sBAAsB;IAC5C,gBAAgB,EAAE,kBAAkB;IAEpC,iBAAiB;IACjB,iBAAiB,EAAE,mBAAmB;IACtC,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;IAE5B,eAAe;IACf,gBAAgB,EAAE,kBAAkB;IACpC,eAAe,EAAE,iBAAiB;IAClC,kBAAkB,EAAE,oBAAoB;CAChC,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Structured error types for the OCP SDK.
+ *
+ * This module provides a hierarchy of error types for different failure modes,
+ * enabling better error handling, debugging, and developer experience.
+ *
+ * @example Error handling
+ * ```typescript
+ * import {
+ *   OcpError,
+ *   OcpValidationError,
+ *   OcpContractError,
+ *   OcpNetworkError,
+ *   OcpParseError,
+ *   OcpErrorCodes,
+ * } from '@open-captable-protocol/canton';
+ *
+ * try {
+ *   await ocp.OpenCapTable.capTable.update(params).create('stakeholder', data).execute();
+ * } catch (error) {
+ *   if (error instanceof OcpValidationError) {
+ *     // Handle validation errors (invalid input)
+ *     console.error(`Invalid input at ${error.fieldPath}: ${error.message}`);
+ *   } else if (error instanceof OcpContractError) {
+ *     // Handle contract errors (DAML/Canton issues)
+ *     console.error(`Contract error on ${error.choice}: ${error.message}`);
+ *   } else if (error instanceof OcpNetworkError) {
+ *     // Handle network errors (connectivity issues)
+ *     console.error(`Network error: ${error.message}`);
+ *   } else if (error instanceof OcpParseError) {
+ *     // Handle parse errors (data transformation issues)
+ *     console.error(`Parse error: ${error.message}`);
+ *   } else if (error instanceof OcpError) {
+ *     // Handle any other OCP errors
+ *     console.error(`OCP Error [${error.code}]: ${error.message}`);
+ *   } else {
+ *     throw error; // Re-throw unknown errors
+ *   }
+ * }
+ * ```
+ */
+export { OcpErrorCodes, type OcpErrorCode } from './codes';
+export { OcpContractError, type OcpContractErrorOptions } from './OcpContractError';
+export { OcpError } from './OcpError';
+export { OcpNetworkError, type OcpNetworkErrorOptions } from './OcpNetworkError';
+export { OcpParseError, type OcpParseErrorOptions } from './OcpParseError';
+export { OcpValidationError, type OcpValidationErrorOptions } from './OcpValidationError';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Structured error types for the OCP SDK.
+ *
+ * This module provides a hierarchy of error types for different failure modes,
+ * enabling better error handling, debugging, and developer experience.
+ *
+ * @example Error handling
+ * ```typescript
+ * import {
+ *   OcpError,
+ *   OcpValidationError,
+ *   OcpContractError,
+ *   OcpNetworkError,
+ *   OcpParseError,
+ *   OcpErrorCodes,
+ * } from '@open-captable-protocol/canton';
+ *
+ * try {
+ *   await ocp.OpenCapTable.capTable.update(params).create('stakeholder', data).execute();
+ * } catch (error) {
+ *   if (error instanceof OcpValidationError) {
+ *     // Handle validation errors (invalid input)
+ *     console.error(`Invalid input at ${error.fieldPath}: ${error.message}`);
+ *   } else if (error instanceof OcpContractError) {
+ *     // Handle contract errors (DAML/Canton issues)
+ *     console.error(`Contract error on ${error.choice}: ${error.message}`);
+ *   } else if (error instanceof OcpNetworkError) {
+ *     // Handle network errors (connectivity issues)
+ *     console.error(`Network error: ${error.message}`);
+ *   } else if (error instanceof OcpParseError) {
+ *     // Handle parse errors (data transformation issues)
+ *     console.error(`Parse error: ${error.message}`);
+ *   } else if (error instanceof OcpError) {
+ *     // Handle any other OCP errors
+ *     console.error(`OCP Error [${error.code}]: ${error.message}`);
+ *   } else {
+ *     throw error; // Re-throw unknown errors
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OcpValidationError = exports.OcpParseError = exports.OcpNetworkError = exports.OcpError = exports.OcpContractError = exports.OcpErrorCodes = void 0;
+// Error codes
+var codes_1 = require("./codes");
+Object.defineProperty(exports, "OcpErrorCodes", { enumerable: true, get: function () { return codes_1.OcpErrorCodes; } });
+// Error classes
+var OcpContractError_1 = require("./OcpContractError");
+Object.defineProperty(exports, "OcpContractError", { enumerable: true, get: function () { return OcpContractError_1.OcpContractError; } });
+var OcpError_1 = require("./OcpError");
+Object.defineProperty(exports, "OcpError", { enumerable: true, get: function () { return OcpError_1.OcpError; } });
+var OcpNetworkError_1 = require("./OcpNetworkError");
+Object.defineProperty(exports, "OcpNetworkError", { enumerable: true, get: function () { return OcpNetworkError_1.OcpNetworkError; } });
+var OcpParseError_1 = require("./OcpParseError");
+Object.defineProperty(exports, "OcpParseError", { enumerable: true, get: function () { return OcpParseError_1.OcpParseError; } });
+var OcpValidationError_1 = require("./OcpValidationError");
+Object.defineProperty(exports, "OcpValidationError", { enumerable: true, get: function () { return OcpValidationError_1.OcpValidationError; } });
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;;;AAEH,cAAc;AACd,iCAA2D;AAAlD,sGAAA,aAAa,OAAA;AAEtB,gBAAgB;AAChB,uDAAoF;AAA3E,oHAAA,gBAAgB,OAAA;AACzB,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,qDAAiF;AAAxE,kHAAA,eAAe,OAAA;AACxB,iDAA2E;AAAlE,8GAAA,aAAa,OAAA;AACtB,2DAA0F;AAAjF,wHAAA,kBAAkB,OAAA"}

package/dist/functions/CouponMinter/index.d.ts

@@ -1,2 +1,3 @@
 export { canMintCouponsNow, type CanMintResult, type CouponMinterPayload, type LastMint } from './canMintCouponsNow';
+export { WaitAbortedError, WaitTimeoutError, getRateLimitStatus, mintWithRateLimit, waitUntilCanMint, type MintWithRateLimitOptions, type MintWithRateLimitResult, type WaitUntilCanMintOptions, } from './waitUntilCanMint';
 //# sourceMappingURL=index.d.ts.map

package/dist/functions/CouponMinter/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/functions/CouponMinter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/functions/CouponMinter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACrH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,oBAAoB,CAAC"}

package/dist/functions/CouponMinter/index.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.canMintCouponsNow = void 0;
+exports.waitUntilCanMint = exports.mintWithRateLimit = exports.getRateLimitStatus = exports.WaitTimeoutError = exports.WaitAbortedError = exports.canMintCouponsNow = void 0;
 var canMintCouponsNow_1 = require("./canMintCouponsNow");
 Object.defineProperty(exports, "canMintCouponsNow", { enumerable: true, get: function () { return canMintCouponsNow_1.canMintCouponsNow; } });
+var waitUntilCanMint_1 = require("./waitUntilCanMint");
+Object.defineProperty(exports, "WaitAbortedError", { enumerable: true, get: function () { return waitUntilCanMint_1.WaitAbortedError; } });
+Object.defineProperty(exports, "WaitTimeoutError", { enumerable: true, get: function () { return waitUntilCanMint_1.WaitTimeoutError; } });
+Object.defineProperty(exports, "getRateLimitStatus", { enumerable: true, get: function () { return waitUntilCanMint_1.getRateLimitStatus; } });
+Object.defineProperty(exports, "mintWithRateLimit", { enumerable: true, get: function () { return waitUntilCanMint_1.mintWithRateLimit; } });
+Object.defineProperty(exports, "waitUntilCanMint", { enumerable: true, get: function () { return waitUntilCanMint_1.waitUntilCanMint; } });
 //# sourceMappingURL=index.js.map

package/dist/functions/CouponMinter/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/functions/CouponMinter/index.ts"],"names":[],"mappings":";;;AAAA,yDAAqH;AAA5G,sHAAA,iBAAiB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/functions/CouponMinter/index.ts"],"names":[],"mappings":";;;AAAA,yDAAqH;AAA5G,sHAAA,iBAAiB,OAAA;AAC1B,uDAS4B;AAR1B,oHAAA,gBAAgB,OAAA;AAChB,oHAAA,gBAAgB,OAAA;AAChB,sHAAA,kBAAkB,OAAA;AAClB,qHAAA,iBAAiB,OAAA;AACjB,oHAAA,gBAAgB,OAAA"}

package/dist/functions/CouponMinter/waitUntilCanMint.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Utility functions for waiting until coupon minting is allowed based on TPS rate limits.
+ *
+ * These utilities provide "fire and forget" style minting with automatic rate limit handling.
+ */
+import { type CanMintResult, type CouponMinterPayload } from './canMintCouponsNow';
+/**
+ * Options for waiting until minting is allowed.
+ */
+export interface WaitUntilCanMintOptions {
+    /**
+     * Maximum time to wait in milliseconds before giving up.
+     * @default 300000 (5 minutes)
+     */
+    maxWaitMs?: number;
+    /**
+     * Minimum polling interval in milliseconds when rate limited.
+     * The actual wait will use the calculated waitMs from canMintCouponsNow,
+     * but this sets a minimum interval between checks.
+     * @default 100
+     */
+    minPollIntervalMs?: number;
+    /**
+     * Signal to abort the wait operation.
+     * If the signal is aborted, the promise will reject with an AbortError.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional callback invoked when waiting starts, providing the estimated wait time.
+     * Useful for logging or updating UI.
+     */
+    onWaitStart?: (waitMs: number) => void;
+}
+/**
+ * Error thrown when the wait operation is aborted.
+ */
+export declare class WaitAbortedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the maximum wait time is exceeded.
+ */
+export declare class WaitTimeoutError extends Error {
+    constructor(maxWaitMs: number);
+}
+/**
+ * Waits until coupon minting is allowed based on the current rate limit state.
+ *
+ * This function will sleep until the rate limit allows minting, checking periodically
+ * until either minting is allowed or the maximum wait time is exceeded.
+ *
+ * @example
+ *   ```typescript
+ *   // Wait until we can mint, then proceed
+ *   await waitUntilCanMint(couponMinterPayload);
+ *   await mintCoupons(...);
+ *   ```
+ *
+ * @example
+ *   ```typescript
+ *   // Wait with a timeout and abort support
+ *   const controller = new AbortController();
+ *   setTimeout(() => controller.abort(), 10000); // 10 second timeout
+ *
+ *   try {
+ *     await waitUntilCanMint(couponMinterPayload, {
+ *       maxWaitMs: 30000,
+ *       signal: controller.signal,
+ *       onWaitStart: (ms) => console.log(`Waiting ${ms}ms for rate limit...`),
+ *     });
+ *     await mintCoupons(...);
+ *   } catch (error) {
+ *     if (error instanceof WaitAbortedError) {
+ *       console.log('Wait was cancelled');
+ *     }
+ *   }
+ *   ```
+ *
+ * @param payload - The CouponMinter contract payload with rate limit state
+ * @param options - Optional configuration for the wait operation
+ * @returns Promise that resolves when minting is allowed
+ * @throws WaitAbortedError if the operation is aborted via the signal
+ * @throws WaitTimeoutError if the maximum wait time is exceeded
+ */
+export declare function waitUntilCanMint(payload: CouponMinterPayload, options?: WaitUntilCanMintOptions): Promise<void>;
+/**
+ * Result of a mintWithRateLimit operation.
+ */
+export interface MintWithRateLimitResult<T> {
+    /** Whether we had to wait due to rate limiting */
+    wasRateLimited: boolean;
+    /** How long we waited in milliseconds (0 if not rate limited) */
+    waitedMs: number;
+    /** The result from the mint function */
+    result: T;
+}
+/**
+ * Options for mintWithRateLimit operation.
+ */
+export interface MintWithRateLimitOptions extends WaitUntilCanMintOptions {
+    /**
+     * Callback invoked just before the mint function is called.
+     * Useful for logging or updating UI.
+     */
+    onBeforeMint?: () => void;
+}
+/**
+ * Waits until minting is allowed, then executes the provided mint function.
+ *
+ * This is a "fire and forget" style wrapper that handles rate limiting automatically.
+ * It waits for the rate limit to allow minting, then executes your mint function.
+ *
+ * @example
+ *   ```typescript
+ *   // Simple usage with async mint function
+ *   const { result, wasRateLimited, waitedMs } = await mintWithRateLimit(
+ *     couponMinterPayload,
+ *     async () => {
+ *       return await ledgerClient.exerciseChoice(
+ *         couponMinterCid,
+ *         'MintCoupons',
+ *         mintParams
+ *       );
+ *     }
+ *   );
+ *   console.log(`Minting complete. Rate limited: ${wasRateLimited}, waited: ${waitedMs}ms`);
+ *   ```
+ *
+ * @example
+ *   ```typescript
+ *   // With callbacks for progress tracking
+ *   const { result } = await mintWithRateLimit(
+ *     couponMinterPayload,
+ *     async () => mintCoupons(params),
+ *     {
+ *       onWaitStart: (ms) => console.log(`Rate limited, waiting ${ms}ms...`),
+ *       onBeforeMint: () => console.log('Submitting mint transaction...'),
+ *       maxWaitMs: 60000,
+ *     }
+ *   );
+ *   ```
+ *
+ * @param payload - The CouponMinter contract payload with rate limit state
+ * @param mintFn - The async function to execute once minting is allowed
+ * @param options - Optional configuration for the wait and mint operation
+ * @returns Promise resolving to the mint result along with rate limit metadata
+ * @throws WaitAbortedError if the operation is aborted via the signal
+ * @throws WaitTimeoutError if the maximum wait time is exceeded
+ * @throws Any error thrown by the mintFn
+ */
+export declare function mintWithRateLimit<T>(payload: CouponMinterPayload, mintFn: () => Promise<T>, options?: MintWithRateLimitOptions): Promise<MintWithRateLimitResult<T>>;
+/**
+ * Checks the current rate limit status and returns detailed information.
+ *
+ * This is a convenience wrapper around canMintCouponsNow that provides
+ * additional context useful for UI display or logging.
+ *
+ * @example
+ *   ```typescript
+ *   const status = getRateLimitStatus(couponMinterPayload);
+ *   if (status.canMint) {
+ *     console.log('Ready to mint!');
+ *   } else {
+ *     console.log(`Rate limited. Can mint in ${status.waitMs}ms (${status.waitSeconds.toFixed(1)}s)`);
+ *   }
+ *   ```
+ *
+ * @param payload - The CouponMinter contract payload
+ * @param now - Optional current time for testing
+ * @returns Detailed rate limit status information
+ */
+export declare function getRateLimitStatus(payload: CouponMinterPayload, now?: Date): CanMintResult & {
+    waitSeconds?: number;
+    isRateLimitEnabled: boolean;
+};
+//# sourceMappingURL=waitUntilCanMint.d.ts.map

package/dist/functions/CouponMinter/waitUntilCanMint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waitUntilCanMint.d.ts","sourceRoot":"","sources":["../../../src/functions/CouponMinter/waitUntilCanMint.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAqB,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAQtG;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,SAA+B;CAInD;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,SAAS,EAAE,MAAM;CAI9B;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCrH;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,kDAAkD;IAClD,cAAc,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,MAAM,EAAE,CAAC,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;IACvE;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAyBrC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE,IAAI,GACT,aAAa,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,OAAO,CAAA;CAAE,CAgBvE"}

package/dist/functions/CouponMinter/waitUntilCanMint.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Utility functions for waiting until coupon minting is allowed based on TPS rate limits.
+ *
+ * These utilities provide "fire and forget" style minting with automatic rate limit handling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaitTimeoutError = exports.WaitAbortedError = void 0;
+exports.waitUntilCanMint = waitUntilCanMint;
+exports.mintWithRateLimit = mintWithRateLimit;
+exports.getRateLimitStatus = getRateLimitStatus;
+const canMintCouponsNow_1 = require("./canMintCouponsNow");
+/** Default polling interval when waiting for mint readiness (in milliseconds) */
+const DEFAULT_POLL_INTERVAL_MS = 100;
+/** Maximum wait time to prevent infinite waiting (5 minutes) */
+const DEFAULT_MAX_WAIT_MS = 5 * 60 * 1000;
+/**
+ * Error thrown when the wait operation is aborted.
+ */
+class WaitAbortedError extends Error {
+    constructor(message = 'Wait operation was aborted') {
+        super(message);
+        this.name = 'WaitAbortedError';
+    }
+}
+exports.WaitAbortedError = WaitAbortedError;
+/**
+ * Error thrown when the maximum wait time is exceeded.
+ */
+class WaitTimeoutError extends Error {
+    constructor(maxWaitMs) {
+        super(`Maximum wait time of ${maxWaitMs}ms exceeded while waiting for rate limit`);
+        this.name = 'WaitTimeoutError';
+    }
+}
+exports.WaitTimeoutError = WaitTimeoutError;
+/**
+ * Sleeps for the specified duration, respecting abort signals.
+ *
+ * @param ms - Duration to sleep in milliseconds
+ * @param signal - Optional abort signal
+ * @returns Promise that resolves after the sleep duration
+ * @throws WaitAbortedError if the signal is aborted during sleep
+ */
+async function sleep(ms, signal) {
+    if (signal?.aborted) {
+        throw new WaitAbortedError();
+    }
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(resolve, ms);
+        if (signal) {
+            const abortHandler = () => {
+                clearTimeout(timeout);
+                reject(new WaitAbortedError());
+            };
+            signal.addEventListener('abort', abortHandler, { once: true });
+            // Clean up the abort handler when the sleep completes
+            const originalResolve = resolve;
+            const wrappedResolve = () => {
+                signal.removeEventListener('abort', abortHandler);
+                originalResolve();
+            };
+            clearTimeout(timeout);
+            setTimeout(wrappedResolve, ms);
+        }
+    });
+}
+/**
+ * Waits until coupon minting is allowed based on the current rate limit state.
+ *
+ * This function will sleep until the rate limit allows minting, checking periodically
+ * until either minting is allowed or the maximum wait time is exceeded.
+ *
+ * @example
+ *   ```typescript
+ *   // Wait until we can mint, then proceed
+ *   await waitUntilCanMint(couponMinterPayload);
+ *   await mintCoupons(...);
+ *   ```
+ *
+ * @example
+ *   ```typescript
+ *   // Wait with a timeout and abort support
+ *   const controller = new AbortController();
+ *   setTimeout(() => controller.abort(), 10000); // 10 second timeout
+ *
+ *   try {
+ *     await waitUntilCanMint(couponMinterPayload, {
+ *       maxWaitMs: 30000,
+ *       signal: controller.signal,
+ *       onWaitStart: (ms) => console.log(`Waiting ${ms}ms for rate limit...`),
+ *     });
+ *     await mintCoupons(...);
+ *   } catch (error) {
+ *     if (error instanceof WaitAbortedError) {
+ *       console.log('Wait was cancelled');
+ *     }
+ *   }
+ *   ```
+ *
+ * @param payload - The CouponMinter contract payload with rate limit state
+ * @param options - Optional configuration for the wait operation
+ * @returns Promise that resolves when minting is allowed
+ * @throws WaitAbortedError if the operation is aborted via the signal
+ * @throws WaitTimeoutError if the maximum wait time is exceeded
+ */
+async function waitUntilCanMint(payload, options) {
+    const { maxWaitMs = DEFAULT_MAX_WAIT_MS, minPollIntervalMs = DEFAULT_POLL_INTERVAL_MS, signal, onWaitStart, } = options ?? {};
+    if (signal?.aborted) {
+        throw new WaitAbortedError();
+    }
+    const startTime = Date.now();
+    // Initial check
+    let result = (0, canMintCouponsNow_1.canMintCouponsNow)(payload);
+    while (!result.canMint) {
+        const elapsed = Date.now() - startTime;
+        // Check if we've exceeded max wait time
+        if (elapsed >= maxWaitMs) {
+            throw new WaitTimeoutError(maxWaitMs);
+        }
+        // Calculate wait time (use the larger of waitMs and minPollIntervalMs)
+        const waitMs = Math.max(result.waitMs, minPollIntervalMs);
+        // Don't wait longer than remaining max wait time
+        const remainingTime = maxWaitMs - elapsed;
+        const actualWaitMs = Math.min(waitMs, remainingTime);
+        // Notify callback if provided
+        onWaitStart?.(actualWaitMs);
+        // Sleep for the calculated duration
+        await sleep(actualWaitMs, signal);
+        // Re-check with current time
+        result = (0, canMintCouponsNow_1.canMintCouponsNow)(payload);
+    }
+}
+/**
+ * Waits until minting is allowed, then executes the provided mint function.
+ *
+ * This is a "fire and forget" style wrapper that handles rate limiting automatically.
+ * It waits for the rate limit to allow minting, then executes your mint function.
+ *
+ * @example
+ *   ```typescript
+ *   // Simple usage with async mint function
+ *   const { result, wasRateLimited, waitedMs } = await mintWithRateLimit(
+ *     couponMinterPayload,
+ *     async () => {
+ *       return await ledgerClient.exerciseChoice(
+ *         couponMinterCid,
+ *         'MintCoupons',
+ *         mintParams
+ *       );
+ *     }
+ *   );
+ *   console.log(`Minting complete. Rate limited: ${wasRateLimited}, waited: ${waitedMs}ms`);
+ *   ```
+ *
+ * @example
+ *   ```typescript
+ *   // With callbacks for progress tracking
+ *   const { result } = await mintWithRateLimit(
+ *     couponMinterPayload,
+ *     async () => mintCoupons(params),
+ *     {
+ *       onWaitStart: (ms) => console.log(`Rate limited, waiting ${ms}ms...`),
+ *       onBeforeMint: () => console.log('Submitting mint transaction...'),
+ *       maxWaitMs: 60000,
+ *     }
+ *   );
+ *   ```
+ *
+ * @param payload - The CouponMinter contract payload with rate limit state
+ * @param mintFn - The async function to execute once minting is allowed
+ * @param options - Optional configuration for the wait and mint operation
+ * @returns Promise resolving to the mint result along with rate limit metadata
+ * @throws WaitAbortedError if the operation is aborted via the signal
+ * @throws WaitTimeoutError if the maximum wait time is exceeded
+ * @throws Any error thrown by the mintFn
+ */
+async function mintWithRateLimit(payload, mintFn, options) {
+    const startTime = Date.now();
+    // Check initial rate limit status
+    const initialCheck = (0, canMintCouponsNow_1.canMintCouponsNow)(payload);
+    const wasRateLimited = !initialCheck.canMint;
+    // Wait if necessary
+    if (wasRateLimited) {
+        await waitUntilCanMint(payload, options);
+    }
+    const waitedMs = Date.now() - startTime;
+    // Notify before mint callback
+    options?.onBeforeMint?.();
+    // Execute the mint function
+    const result = await mintFn();
+    return {
+        wasRateLimited,
+        waitedMs,
+        result,
+    };
+}
+/**
+ * Checks the current rate limit status and returns detailed information.
+ *
+ * This is a convenience wrapper around canMintCouponsNow that provides
+ * additional context useful for UI display or logging.
+ *
+ * @example
+ *   ```typescript
+ *   const status = getRateLimitStatus(couponMinterPayload);
+ *   if (status.canMint) {
+ *     console.log('Ready to mint!');
+ *   } else {
+ *     console.log(`Rate limited. Can mint in ${status.waitMs}ms (${status.waitSeconds.toFixed(1)}s)`);
+ *   }
+ *   ```
+ *
+ * @param payload - The CouponMinter contract payload
+ * @param now - Optional current time for testing
+ * @returns Detailed rate limit status information
+ */
+function getRateLimitStatus(payload, now) {
+    const result = (0, canMintCouponsNow_1.canMintCouponsNow)(payload, now);
+    const isRateLimitEnabled = payload.maxTps !== null;
+    if (result.canMint) {
+        return {
+            ...result,
+            isRateLimitEnabled,
+        };
+    }
+    return {
+        ...result,
+        waitSeconds: result.waitMs / 1000,
+        isRateLimitEnabled,
+    };
+}
+//# sourceMappingURL=waitUntilCanMint.js.map

package/dist/functions/CouponMinter/waitUntilCanMint.js.map

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

package/dist/functions/OpenCapTable/capTable/CapTableBatch.d.ts

@@ -71,7 +71,8 @@ export declare class CapTableBatch {
      * Build and execute the batch update.
      *
      * @returns The result containing the updated cap table contract ID and affected entity IDs
-     * @throws Error if no client was provided or if the batch is empty
+     * @throws OcpValidationError if no client was provided or if the batch is empty
+     * @throws OcpContractError if the UpdateCapTable result is not found in the transaction tree
      */
     execute(): Promise<UpdateCapTableResult>;
     /** Clear all operations from the batch. */

package/dist/functions/OpenCapTable/capTable/CapTableBatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CapTableBatch.d.ts","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/CapTableBatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AACvG,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,kFAAkF,CAAC;AAE1F,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAGL,KAAK,cAAc,EAGnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAGtB,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,+BAA+B,EAAE,iBAAiB,CAAC;IACnD,oFAAoF;IACpF,uBAAuB,CAAC,EAAE,iBAAiB,CAAC;IAC5C,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,OAAO,CAAuB;gBAE1B,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAE,mBAAmB,GAAG,IAAW;IAKlF;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAOvE;;;;;;OAMG;IACH,IAAI,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAOrE;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAM7C,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mCAAmC;IACnC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,KAAK,IAAI,6BAA6B;IAmCtC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAsC9C,2CAA2C;IAC3C,KAAK,IAAI,IAAI;CAMd;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,QAAQ,CAAC,EACrD,UAAU,EAAE;IACV,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;KAAE,CAAC,CAAC;IAC5E,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD,GACA,6BAA6B,CAc/B"}
+{"version":3,"file":"CapTableBatch.d.ts","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/CapTableBatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AACvG,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,kFAAkF,CAAC;AAG1F,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAGL,KAAK,cAAc,EAGnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAGtB,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,+BAA+B,EAAE,iBAAiB,CAAC;IACnD,oFAAoF;IACpF,uBAAuB,CAAC,EAAE,iBAAiB,CAAC;IAC5C,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,OAAO,CAAuB;gBAE1B,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAE,mBAAmB,GAAG,IAAW;IAKlF;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAOvE;;;;;;OAMG;IACH,IAAI,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAOrE;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAM7C,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mCAAmC;IACnC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,KAAK,IAAI,6BAA6B;IAyCtC;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAgD9C,2CAA2C;IAC3C,KAAK,IAAI,IAAI;CAMd;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,QAAQ,CAAC,EACrD,UAAU,EAAE;IACV,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;KAAE,CAAC,CAAC;IAC5E,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD,GACA,6BAA6B,CAc/B"}

package/dist/functions/OpenCapTable/capTable/CapTableBatch.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CapTableBatch = void 0;
 exports.buildUpdateCapTableCommand = buildUpdateCapTableCommand;
 const open_captable_protocol_daml_js_1 = require("@fairmint/open-captable-protocol-daml-js");
+const errors_1 = require("../../../errors");
 const batchTypes_1 = require("./batchTypes");
 const ocfToDaml_1 = require("./ocfToDaml");
 /**
@@ -77,7 +78,9 @@ class CapTableBatch {
      */
     build() {
         if (this.isEmpty) {
-            throw new Error('Cannot build empty batch - add at least one create, edit, or delete operation');
+            throw new errors_1.OcpValidationError('batch', 'Cannot build empty batch - add at least one create, edit, or delete operation', {
+                code: errors_1.OcpErrorCodes.REQUIRED_FIELD_MISSING,
+            });
         }
         // Use the templateId from capTableContractDetails when provided (from actual ledger),
         // otherwise fall back to the DAML-JS package's hardcoded templateId.
@@ -108,11 +111,14 @@ class CapTableBatch {
      * Build and execute the batch update.
      *
      * @returns The result containing the updated cap table contract ID and affected entity IDs
-     * @throws Error if no client was provided or if the batch is empty
+     * @throws OcpValidationError if no client was provided or if the batch is empty
+     * @throws OcpContractError if the UpdateCapTable result is not found in the transaction tree
      */
     async execute() {
         if (!this.client) {
-            throw new Error('Cannot execute batch without a client - use build() instead and submit manually');
+            throw new errors_1.OcpValidationError('client', 'Cannot execute batch without a client - use build() instead and submit manually', {
+                code: errors_1.OcpErrorCodes.REQUIRED_FIELD_MISSING,
+            });
         }
         const { command, disclosedContracts } = this.build();
         const response = await this.client.submitAndWaitForTransactionTree({
@@ -138,7 +144,11 @@ class CapTableBatch {
                 }
             }
         }
-        throw new Error('UpdateCapTable result not found in transaction tree');
+        throw new errors_1.OcpContractError('UpdateCapTable result not found in transaction tree', {
+            contractId: this.params.capTableContractId,
+            choice: 'UpdateCapTable',
+            code: errors_1.OcpErrorCodes.RESULT_NOT_FOUND,
+        });
     }
     /** Clear all operations from the batch. */
     clear() {