@smoothsend/sdk 1.0.0

package/dist/types/errors.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Error handling system for SmoothSend SDK v2
+ * Provides typed error classes for different failure scenarios
+ *
+ * @remarks
+ * All SDK errors extend SmoothSendError for consistent error handling
+ * Use instanceof checks to handle specific error types
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.transfer(request, wallet);
+ * } catch (error) {
+ *   if (error instanceof AuthenticationError) {
+ *     console.error('Invalid API key');
+ *   } else if (error instanceof RateLimitError) {
+ *     console.error('Rate limit exceeded');
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base error class for all SmoothSend SDK errors
+ *
+ * @remarks
+ * All SDK-specific errors extend this class
+ * Contains error code, HTTP status code, and additional details
+ *
+ * @example
+ * ```typescript
+ * throw new SmoothSendError(
+ *   'Something went wrong',
+ *   'CUSTOM_ERROR',
+ *   500,
+ *   { additionalInfo: 'details' }
+ * );
+ * ```
+ */
+export declare class SmoothSendError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    /**
+     * Creates a new SmoothSendError
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param statusCode - HTTP status code (if applicable)
+     * @param details - Additional error details
+     */
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: any | undefined);
+}
+/**
+ * Authentication error - thrown when API key is invalid, missing, or expired
+ *
+ * @remarks
+ * HTTP Status Code: 401
+ * Indicates authentication failure with the proxy worker
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.transfer(request, wallet);
+ * } catch (error) {
+ *   if (error instanceof AuthenticationError) {
+ *     console.error('Invalid API key:', error.message);
+ *     console.log('Get a new key at:', error.details.suggestion);
+ *   }
+ * }
+ * ```
+ */
+export declare class AuthenticationError extends SmoothSendError {
+    /**
+     * Creates a new AuthenticationError
+     *
+     * @param message - Human-readable error message
+     * @param details - Additional error details
+     */
+    constructor(message: string, details?: any);
+}
+/**
+ * Rate limit error - thrown when request rate limit is exceeded
+ *
+ * @remarks
+ * HTTP Status Code: 429
+ * Contains rate limit details including reset time
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.transfer(request, wallet);
+ * } catch (error) {
+ *   if (error instanceof RateLimitError) {
+ *     console.error('Rate limit exceeded');
+ *     console.log(`Limit: ${error.limit}`);
+ *     console.log(`Remaining: ${error.remaining}`);
+ *     console.log(`Resets at: ${error.resetTime}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class RateLimitError extends SmoothSendError {
+    limit: number;
+    remaining: number;
+    resetTime: string;
+    /**
+     * Creates a new RateLimitError
+     *
+     * @param message - Human-readable error message
+     * @param limit - Maximum requests allowed per period
+     * @param remaining - Remaining requests in current period
+     * @param resetTime - When the rate limit resets (ISO 8601 timestamp)
+     */
+    constructor(message: string, limit: number, remaining: number, resetTime: string);
+}
+/**
+ * Validation error - thrown when request parameters are invalid
+ *
+ * @remarks
+ * HTTP Status Code: 400
+ * Contains field name that failed validation
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.transfer(request, wallet);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error(`Invalid ${error.field}:`, error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class ValidationError extends SmoothSendError {
+    field: string;
+    /**
+     * Creates a new ValidationError
+     *
+     * @param message - Human-readable error message
+     * @param field - Name of the field that failed validation
+     * @param details - Additional error details
+     */
+    constructor(message: string, field: string, details?: any);
+}
+/**
+ * Network error - thrown when network connectivity issues occur
+ *
+ * @remarks
+ * HTTP Status Code: 0 (no HTTP response)
+ * Indicates network connectivity problems
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.transfer(request, wallet);
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     console.error('Network error:', error.message);
+ *     console.log('Original error:', error.originalError);
+ *   }
+ * }
+ * ```
+ */
+export declare class NetworkError extends SmoothSendError {
+    originalError?: Error | undefined;
+    /**
+     * Creates a new NetworkError
+     *
+     * @param message - Human-readable error message
+     * @param originalError - Original error that caused the network failure
+     */
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Helper function to create appropriate error from HTTP response
+ *
+ * @remarks
+ * Parses HTTP error response and creates typed error object
+ * Used internally by HTTP client
+ *
+ * @param statusCode - HTTP status code
+ * @param errorData - Error response data from API
+ * @param defaultMessage - Default message if none provided in response
+ * @returns Typed error object
+ *
+ * @example
+ * ```typescript
+ * const error = createErrorFromResponse(401, {
+ *   error: 'Invalid API key',
+ *   details: { field: 'apiKey' }
+ * });
+ * throw error;
+ * ```
+ */
+export declare function createErrorFromResponse(statusCode: number, errorData: any, defaultMessage?: string): SmoothSendError;
+/**
+ * Helper function to create network error from exception
+ *
+ * @remarks
+ * Wraps generic exceptions in NetworkError for consistent error handling
+ * Used internally by HTTP client
+ *
+ * @param error - Original error or exception
+ * @returns NetworkError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch(url);
+ * } catch (error) {
+ *   throw createNetworkError(error);
+ * }
+ * ```
+ */
+export declare function createNetworkError(error: any): NetworkError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAW/B,IAAI,EAAE,MAAM;IACZ,UAAU,CAAC,EAAE,MAAM;IACnB,OAAO,CAAC,EAAE,GAAG;IAZtB;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,OAAO,CAAC,EAAE,GAAG,YAAA;CAUvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACtD;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAa3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAe,SAAQ,eAAe;IAWxC,KAAK,EAAE,MAAM;IACb,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,MAAM;IAZ1B;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACR,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM;CAgB3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAgB,SAAQ,eAAe;IAQd,KAAK,EAAE,MAAM;IAPjD;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,EAAS,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAajE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAa,SAAQ,eAAe;IAOX,aAAa,CAAC,EAAE,KAAK;IANzD;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAS,aAAa,CAAC,EAAE,KAAK,YAAA;CAY1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,GAAG,EACd,cAAc,GAAE,MAA4B,GAC3C,eAAe,CA0BjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,GAAG,GAAG,YAAY,CAG3D"}