@subscrypts/subscrypts-sdk-react 1.6.0

package/dist/types/wallet.types.d.ts

@@ -0,0 +1,53 @@
+import { BrowserProvider, Signer } from 'ethers';
+
+/**
+ * Network configuration
+ */
+export interface NetworkConfig {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    blockExplorer: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+}
+/**
+ * Wallet connection state
+ */
+export interface WalletState {
+    address: string | null;
+    chainId: number | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    error: Error | null;
+}
+/**
+ * External wallet configuration (for Wagmi/RainbowKit integration)
+ */
+export interface ExternalWalletConfig {
+    provider: BrowserProvider;
+    signer: Signer;
+    address: string;
+}
+/**
+ * Wallet provider type (browser extension)
+ */
+export interface EthereumProvider {
+    request: (args: {
+        method: string;
+        params?: unknown[];
+    }) => Promise<unknown>;
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+    removeListener: (event: string, handler: (...args: unknown[]) => void) => void;
+    isMetaMask?: boolean;
+    isCoinbaseWallet?: boolean;
+}
+declare global {
+    interface Window {
+        ethereum?: EthereumProvider;
+    }
+}
+//# sourceMappingURL=wallet.types.d.ts.map

package/dist/types/wallet.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.types.d.ts","sourceRoot":"","sources":["../../src/types/wallet.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE;QACd,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;IACnE,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;IAC/E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,QAAQ,CAAC,EAAE,gBAAgB,CAAC;KAC7B;CACF"}

package/dist/utils/errorMessages.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Error message mapping for human-readable blockchain errors.
+ *
+ * Maps ethers.js error codes and common blockchain errors
+ * to user-friendly messages with actionable suggestions.
+ */
+/**
+ * Configuration for a user-facing error message
+ */
+export interface ErrorMessageConfig {
+    /** Short error title */
+    title: string;
+    /** User-friendly error description */
+    message: string;
+    /** Actionable suggestion for the user */
+    suggestion: string;
+    /** Whether the user can retry this operation */
+    isRetryable: boolean;
+}
+/**
+ * Map of known error codes to user-friendly messages.
+ * Covers ethers.js v6 error codes and common contract revert reasons.
+ */
+export declare const ERROR_CODE_MAP: Record<string, ErrorMessageConfig>;
+/**
+ * Extract the error code from an unknown error object.
+ * Handles ethers.js errors, SubscryptsError, and generic errors.
+ */
+export declare function getErrorCode(error: unknown): string;
+/**
+ * Get a user-friendly error message for any error.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await subscribe({ planId: '1', ... });
+ * } catch (err) {
+ *   const { title, message, suggestion, isRetryable } = getErrorMessage(err);
+ *   // Display to user
+ * }
+ * ```
+ */
+export declare function getErrorMessage(error: unknown): ErrorMessageConfig;
+//# sourceMappingURL=errorMessages.d.ts.map

package/dist/utils/errorMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorMessages.d.ts","sourceRoot":"","sources":["../../src/utils/errorMessages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CA8F7D,CAAC;AAUF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA2CnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAGlE"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Custom error classes for Subscrypts SDK
+ */
+/**
+ * Base error class for Subscrypts SDK
+ */
+export declare class SubscryptsError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Wallet connection errors
+ */
+export declare class WalletError extends SubscryptsError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Network errors
+ */
+export declare class NetworkError extends SubscryptsError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Contract interaction errors
+ */
+export declare class ContractError extends SubscryptsError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Insufficient balance errors
+ */
+export declare class InsufficientBalanceError extends SubscryptsError {
+    required: bigint;
+    available: bigint;
+    token: 'SUBS' | 'USDC';
+    constructor(required: bigint, available: bigint, token: 'SUBS' | 'USDC');
+}
+/**
+ * Transaction errors
+ */
+export declare class TransactionError extends SubscryptsError {
+    txHash?: string | undefined;
+    constructor(message: string, txHash?: string | undefined, details?: Record<string, unknown>);
+}
+/**
+ * Validation errors
+ */
+export declare class ValidationError extends SubscryptsError {
+    constructor(field: string, message: string);
+}
+/**
+ * Sanctions errors - thrown when address is sanctioned
+ */
+export declare class SanctionsError extends SubscryptsError {
+    readonly address: string;
+    readonly isMerchant: boolean;
+    constructor(address: string, isMerchant: boolean, details?: Record<string, unknown>);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAE/B,IAAI,EAAE,MAAM;IAEZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,IAAI,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAM3C;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,eAAe;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,eAAe;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,eAAe;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,eAAe;IAElD,QAAQ,EAAE,MAAM;IAChB,SAAS,EAAE,MAAM;IACjB,KAAK,EAAE,MAAM,GAAG,MAAM;gBAFtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GAAG,MAAM;CAShC;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,eAAe;IACf,MAAM,CAAC,EAAE,MAAM;gBAAvC,OAAO,EAAE,MAAM,EAAS,MAAM,CAAC,EAAE,MAAM,YAAA,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIvF;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,eAAe;gBACtC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI3C;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,eAAe;IACjD,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,UAAU,EAAE,OAAO,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAUpF"}

package/dist/utils/formatters.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Formatting utilities for numbers, dates, and addresses
+ */
+/**
+ * Format bigint token amount to human-readable string
+ */
+export declare function formatTokenAmount(amount: bigint, decimals: number, maxDecimals?: number): string;
+/**
+ * Parse token amount from string to bigint
+ */
+export declare function parseTokenAmount(amount: string, decimals: number): bigint;
+/**
+ * Format SUBS token amount (18 decimals)
+ */
+export declare function formatSubs(amount: bigint): string;
+/**
+ * Format USDC token amount (6 decimals)
+ */
+export declare function formatUsdc(amount: bigint): string;
+/**
+ * Format date for display
+ */
+export declare function formatDate(date: Date): string;
+/**
+ * Format date with time
+ */
+export declare function formatDateTime(date: Date): string;
+/**
+ * Format duration in seconds to human-readable string
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Shorten address for display (0x1234...5678)
+ */
+export declare function shortenAddress(address: string, startChars?: number, endChars?: number): string;
+/**
+ * Format percentage
+ */
+export declare function formatPercentage(value: number, decimals?: number): string;
+/**
+ * Format a fiat (USD) price for display
+ */
+export declare function formatFiatPrice(amount: number, locale?: string): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/utils/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/utils/formatters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAE,MAAU,GAAG,MAAM,CASnG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAM7C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAQjD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAetD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,MAAU,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAKpG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAE5E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAgB,GAAG,MAAM,CAOhF"}

package/dist/utils/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for @subscrypts/subscrypts-sdk-react
+ */
+export * from './errors';
+export * from './validators';
+export * from './formatters';
+export * from './errorMessages';
+export * from './subscriptionStatus';
+export * from './subscriptionHelpers';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Subscrypts SDK Logger
+ *
+ * Configurable logging with three levels:
+ * - silent: No output (production)
+ * - info: User-friendly status messages
+ * - debug: Full developer debugging info
+ */
+export type LogLevel = 'silent' | 'info' | 'debug';
+export interface LoggerConfig {
+    level: LogLevel;
+    prefix?: string;
+}
+export interface PerformanceMetric {
+    operation: string;
+    duration: number;
+    timestamp: number;
+}
+declare class SubscryptsLogger {
+    private level;
+    private prefix;
+    private performanceMetrics;
+    private correlationIdCounter;
+    configure(config: Partial<LoggerConfig>): void;
+    getLevel(): LogLevel;
+    /**
+     * Generate unique correlation ID for tracing related operations
+     */
+    generateCorrelationId(): string;
+    /**
+     * Track performance of async operations (debug mode only)
+     */
+    trackPerformance<T>(operation: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get performance metrics (debug mode only)
+     */
+    getPerformanceMetrics(): PerformanceMetric[];
+    /**
+     * Clear performance metrics
+     */
+    clearMetrics(): void;
+    private shouldLog;
+    /**
+     * Debug level - detailed developer info
+     */
+    debug(message: string, data?: unknown): void;
+    /**
+     * Info level - user-friendly status
+     */
+    info(message: string, data?: unknown): void;
+    /**
+     * Warning - potential issues
+     */
+    warn(message: string, data?: unknown): void;
+    /**
+     * Error - failures
+     */
+    error(message: string, data?: unknown): void;
+    /**
+     * Success - completed operations
+     */
+    success(message: string, data?: unknown): void;
+    /**
+     * Group logs together (debug only)
+     */
+    group(label: string): void;
+    groupEnd(): void;
+    /**
+     * Log a table of data (debug only)
+     */
+    table(data: unknown): void;
+}
+export declare const logger: SubscryptsLogger;
+/**
+ * Helper to format BigInt values for logging
+ * Converts BigInt to string to avoid JSON serialization issues
+ */
+export declare function formatLogValue(value: unknown): unknown;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,cAAM,gBAAgB;IACpB,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,kBAAkB,CAA2B;IACrD,OAAO,CAAC,oBAAoB,CAAK;IAEjC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC;IAKvC,QAAQ,IAAI,QAAQ;IAIpB;;OAEG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;OAEG;IACG,gBAAgB,CAAC,CAAC,EACtB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC;IAqBb;;OAEG;IACH,qBAAqB,IAAI,iBAAiB,EAAE;IAI5C;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB,OAAO,CAAC,SAAS;IAOjB;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMrC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMpC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMrC;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMvC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM;IAMnB,QAAQ;IAMR;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO;CAKpB;AAGD,eAAO,MAAM,MAAM,kBAAyB,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAetD"}

package/dist/utils/permit.utils.d.ts

@@ -0,0 +1,52 @@
+import { ethers } from 'ethers';
+
+/**
+ * EIP-712 domain for PERMIT2 on Arbitrum One
+ */
+export declare const PERMIT2_DOMAIN: {
+    readonly name: "Permit2";
+    readonly chainId: 42161;
+    readonly verifyingContract: "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+};
+/**
+ * EIP-712 types for PERMIT2 PermitTransferFrom
+ */
+export declare const PERMIT2_TYPES: {
+    TokenPermissions: {
+        name: string;
+        type: string;
+    }[];
+    PermitTransferFrom: {
+        name: string;
+        type: string;
+    }[];
+};
+/**
+ * Generate PERMIT2 signature for token transfer
+ *
+ * This function creates a valid EIP-712 signature that allows the spender
+ * to transfer tokens on behalf of the signer through PERMIT2.
+ *
+ * @param signer - Ethers signer (wallet) that will sign the permit
+ * @param tokenAddress - Address of the token to permit (e.g., USDC)
+ * @param amount - Amount of tokens to permit (in wei/token decimals)
+ * @param spender - Address that will be allowed to spend tokens (e.g., Subscrypts contract)
+ * @param deadline - Unix timestamp when the permit expires
+ * @returns Object containing the signature and nonce
+ *
+ * @example
+ * ```typescript
+ * const { signature, nonce } = await generatePermit2Signature(
+ *   signer,
+ *   USDC_ADDRESS,
+ *   parseUnits('100', 6), // 100 USDC
+ *   SUBSCRYPTS_CONTRACT_ADDRESS,
+ *   BigInt(Math.floor(Date.now() / 1000) + 1800) // 30 minutes
+ * );
+ * ```
+ */
+export declare function generatePermit2Signature(signer: ethers.Signer, tokenAddress: string, amount: bigint, spender: string, deadline: bigint): Promise<{
+    signature: string;
+    nonce: string;
+}>;
+//# sourceMappingURL=permit.utils.d.ts.map

package/dist/utils/permit.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permit.utils.d.ts","sourceRoot":"","sources":["../../src/utils/permit.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC;;GAEG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;CAWzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsC/C"}

package/dist/utils/subscriptionHelpers.d.ts

@@ -0,0 +1,67 @@
+import { Subscription } from '../types';
+import { SubscriptionState } from './subscriptionStatus';
+
+/**
+ * Check if a subscription grants active access.
+ * Pure function - no blockchain calls.
+ *
+ * @example
+ * ```typescript
+ * if (canAccess(subscription)) {
+ *   showPremiumContent();
+ * }
+ * ```
+ */
+export declare function canAccess(subscription: Subscription | null): boolean;
+/**
+ * Check if a subscription payment is due (past nextPaymentDate).
+ *
+ * @example
+ * ```typescript
+ * if (isPaymentDue(subscription)) {
+ *   triggerPaymentCollection();
+ * }
+ * ```
+ */
+export declare function isPaymentDue(subscription: Subscription, now?: Date): boolean;
+/**
+ * Check if a subscription should be renewed.
+ * True when: payment is due AND auto-renewing AND has remaining cycles.
+ *
+ * @example
+ * ```typescript
+ * if (shouldRenew(subscription)) {
+ *   processRenewalPayment();
+ * }
+ * ```
+ */
+export declare function shouldRenew(subscription: Subscription, now?: Date): boolean;
+/**
+ * Subscription health summary
+ */
+export interface SubscriptionHealth {
+    /** Normalized subscription state */
+    state: SubscriptionState;
+    /** Whether a payment is currently due */
+    isPaymentDue: boolean;
+    /** Whether the subscription should be renewed */
+    shouldRenew: boolean;
+    /** Days until expiry (null if expired or not found) */
+    daysUntilExpiry: number | null;
+    /** Remaining payment cycles */
+    cyclesRemaining: number;
+}
+/**
+ * Get comprehensive subscription health summary.
+ * Combines status resolution with decision helpers.
+ *
+ * @example
+ * ```typescript
+ * const health = getSubscriptionHealth(subscription);
+ * console.log(health.state);          // 'active'
+ * console.log(health.isPaymentDue);   // false
+ * console.log(health.daysUntilExpiry); // 25
+ * ```
+ */
+export declare function getSubscriptionHealth(subscription: Subscription | null, now?: Date): SubscriptionHealth;
+//# sourceMappingURL=subscriptionHelpers.d.ts.map

package/dist/utils/subscriptionHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptionHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/subscriptionHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAIpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAExF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAMvF;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,KAAK,EAAE,iBAAiB,CAAC;IACzB,yCAAyC;IACzC,YAAY,EAAE,OAAO,CAAC;IACtB,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+BAA+B;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,GAAG,GAAE,IAAiB,GACrB,kBAAkB,CAUpB"}

package/dist/utils/subscriptionStatus.d.ts

@@ -0,0 +1,48 @@
+import { Subscription } from '../types';
+
+/**
+ * Normalized subscription states
+ */
+export type SubscriptionState = 'active' | 'expired' | 'expiring-soon' | 'cancelled' | 'not-found';
+/**
+ * Input for resolving subscription status
+ */
+export interface ResolveStatusInput {
+    /** The subscription to evaluate (null if none exists) */
+    subscription: Subscription | null;
+    /** Reference time for comparison (defaults to now) */
+    now?: Date;
+}
+/**
+ * Resolved subscription status with computed fields
+ */
+export interface ResolvedStatus {
+    /** Normalized subscription state */
+    state: SubscriptionState;
+    /** Whether the subscription grants active access */
+    isActive: boolean;
+    /** Days until expiry (null if expired or not found) */
+    daysUntilExpiry: number | null;
+    /** Next payment date (null if not found) */
+    nextPaymentDate: Date | null;
+    /** Whether auto-renewal is enabled */
+    isAutoRenewing: boolean;
+    /** Remaining payment cycles */
+    remainingCycles: number;
+}
+/**
+ * Resolve the normalized status of a subscription.
+ *
+ * This is a pure function with no side effects or blockchain calls.
+ * It can be used in React components, Node.js scripts, AI agents, etc.
+ *
+ * @example
+ * ```typescript
+ * const status = resolveSubscriptionStatus({ subscription });
+ * if (status.state === 'expiring-soon') {
+ *   showRenewalReminder();
+ * }
+ * ```
+ */
+export declare function resolveSubscriptionStatus(input: ResolveStatusInput): ResolvedStatus;
+//# sourceMappingURL=subscriptionStatus.d.ts.map

package/dist/utils/subscriptionStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptionStatus.d.ts","sourceRoot":"","sources":["../../src/utils/subscriptionStatus.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,SAAS,GACT,eAAe,GACf,WAAW,GACX,WAAW,CAAC;AAEhB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,sDAAsD;IACtD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,KAAK,EAAE,iBAAiB,CAAC;IACzB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,4CAA4C;IAC5C,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,sCAAsC;IACtC,cAAc,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,kBAAkB,GAAG,cAAc,CAqEnF"}

package/dist/utils/validators.d.ts

@@ -0,0 +1,76 @@
+import { Contract } from 'ethers';
+
+/**
+ * Validate Ethereum address
+ */
+export declare function validateAddress(address: string, fieldName?: string): string;
+/**
+ * Validate positive number
+ */
+export declare function validatePositiveNumber(value: number, fieldName?: string): void;
+/**
+ * Validate positive bigint
+ */
+export declare function validatePositiveBigInt(value: bigint, fieldName?: string): void;
+/**
+ * Validate plan ID
+ */
+export declare function validatePlanId(planId: string): void;
+/**
+ * Validate cycle limit
+ */
+export declare function validateCycleLimit(cycles: number): void;
+/**
+ * Validate referral address for a plan
+ *
+ * Referral addresses must be existing subscribers to the same plan to receive
+ * referral bonuses. Invalid referrals are silently ignored by the contract
+ * (no error, no bonus applied).
+ *
+ * Contract requirement: facetSubscription.sol lines 196-198
+ *
+ * @param contract - Subscrypts contract instance
+ * @param planId - Plan ID to check
+ * @param referralAddress - Referral address to validate
+ * @returns true if referral is valid (subscribed to plan), false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = await isValidReferral(contract, '1', '0x123...');
+ * if (!isValid) {
+ *   console.warn('Referral address is not subscribed to this plan');
+ * }
+ * ```
+ */
+export declare function isValidReferral(contract: Contract, planId: string | bigint, referralAddress: string): Promise<boolean>;
+/**
+ * Check if an address is sanctioned
+ *
+ * Pre-flight check before subscription creation to prevent wasted gas.
+ * Uses contract's subCheckSanctions method which queries Chainalysis oracle.
+ *
+ * **Fail-open pattern**: If the check fails (contract error, oracle unavailable),
+ * returns false for both addresses to allow the transaction. This prevents breaking
+ * existing integrations where sanctions checking might not be enabled.
+ *
+ * @param contract - Subscrypts contract instance
+ * @param merchantAddress - Merchant address to check
+ * @param subscriberAddress - Subscriber address to check
+ * @returns Promise<{ merchantSanctioned: boolean, subscriberSanctioned: boolean }>
+ *
+ * @example
+ * ```typescript
+ * const result = await checkSanctions(contract, merchantAddr, subscriberAddr);
+ * if (result.merchantSanctioned) {
+ *   throw new SanctionsError(merchantAddr, true);
+ * }
+ * if (result.subscriberSanctioned) {
+ *   throw new SanctionsError(subscriberAddr, false);
+ * }
+ * ```
+ */
+export declare function checkSanctions(contract: Contract, merchantAddress: string, subscriberAddress: string): Promise<{
+    merchantSanctioned: boolean;
+    subscriberSanctioned: boolean;
+}>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/utils/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/utils/validators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAyB,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGzD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,MAAM,CAWtF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAgB,GAAG,IAAI,CAQvF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAgB,GAAG,IAAI,CAQvF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAInD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAUvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,eAAe,EAAE,MAAM,EACvB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC;IAAE,kBAAkB,EAAE,OAAO,CAAC;IAAC,oBAAoB,EAAE,OAAO,CAAA;CAAE,CAAC,CAazE"}

package/dist/wallet/ExternalConnector.d.ts

@@ -0,0 +1,32 @@
+import { WalletConnector, ConnectResult } from './types';
+import { ExternalWalletConfig } from '../types';
+
+export declare class ExternalConnector implements WalletConnector {
+    readonly id: "external";
+    readonly name = "External Provider";
+    readonly icon?: string;
+    private config;
+    private chainId;
+    constructor(config: ExternalWalletConfig, chainId: number);
+    /**
+     * External providers are always available (they're passed in by the app)
+     */
+    isAvailable(): boolean;
+    /**
+     * Return the external provider/signer directly
+     */
+    connect(): Promise<ConnectResult>;
+    /**
+     * External disconnect is a no-op (managed by the parent app)
+     */
+    disconnect(): Promise<void>;
+    /**
+     * External providers can always reconnect (already connected)
+     */
+    reconnect(): Promise<ConnectResult | null>;
+    /**
+     * Update the external config (called when externalProvider prop changes)
+     */
+    updateConfig(config: ExternalWalletConfig, chainId: number): void;
+}
+//# sourceMappingURL=ExternalConnector.d.ts.map

package/dist/wallet/ExternalConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalConnector.d.ts","sourceRoot":"","sources":["../../src/wallet/ExternalConnector.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEhD,qBAAa,iBAAkB,YAAW,eAAe;IACvD,QAAQ,CAAC,EAAE,EAAG,UAAU,CAAU;IAClC,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;IAKzD;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IASvC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIhD;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;CAIlE"}