@bloque/sdk-core 0.0.23 → 0.0.24

package/dist/errors.d.ts

@@ -1,8 +1,223 @@
+/**
+ * Options for creating a BloqueAPIError.
+ */
+export interface BloqueAPIErrorOptions {
+    /** HTTP status code (e.g., 400, 401, 500) */
+    status?: number;
+    /** Error code from the API (e.g., 'INVALID_ALIAS', 'INSUFFICIENT_FUNDS') */
+    code?: string;
+    /** Request ID for tracing (from response headers) */
+    requestId?: string;
+    /** Original response body for debugging */
+    response?: unknown;
+    /** Cause of the error (e.g., network error, parse error) */
+    cause?: Error;
+}
+/**
+ * Base error class for all Bloque API errors.
+ *
+ * This error is thrown when the API returns an error response
+ * or when a network/timeout error occurs during a request.
+ */
 export declare class BloqueAPIError extends Error {
+    /** HTTP status code (e.g., 400, 401, 500) */
     readonly status?: number;
+    /** Error code from the API (e.g., 'INVALID_ALIAS', 'INSUFFICIENT_FUNDS') */
     readonly code?: string;
-    constructor(message: string, status?: number, code?: string);
+    /** Request ID for tracing (from response headers) */
+    readonly requestId?: string;
+    /** Timestamp when the error occurred */
+    readonly timestamp: Date;
+    /** Original response body for debugging */
+    readonly response?: unknown;
+    /** Cause of the error (e.g., network error, parse error) */
+    readonly cause?: Error;
+    constructor(message: string, options?: BloqueAPIErrorOptions);
+    /**
+     * Returns a JSON representation of the error.
+     * Useful for logging and debugging.
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string | undefined;
+        requestId: string | undefined;
+        timestamp: string;
+        response: unknown;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when the API rate limit is exceeded (HTTP 429).
+ *
+ * The SDK will automatically retry these requests if retry is enabled.
+ * Check the `retryAfter` field to know when to retry manually if needed.
+ */
+export declare class BloqueRateLimitError extends BloqueAPIError {
+    /** Number of seconds to wait before retrying (from Retry-After header) */
+    readonly retryAfter?: number;
+    constructor(message: string, options?: BloqueAPIErrorOptions & {
+        retryAfter?: number;
+    });
+    toJSON(): {
+        retryAfter: number | undefined;
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string | undefined;
+        requestId: string | undefined;
+        timestamp: string;
+        response: unknown;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when authentication fails (HTTP 401 or 403).
+ *
+ * Possible causes:
+ * - Invalid or expired API key
+ * - Invalid or expired JWT token
+ * - Insufficient permissions for the requested operation
+ */
+export declare class BloqueAuthenticationError extends BloqueAPIError {
+    constructor(message: string, options?: BloqueAPIErrorOptions);
+}
+/**
+ * Error thrown when request validation fails (HTTP 400).
+ *
+ * Possible causes:
+ * - Missing required fields
+ * - Invalid field format
+ * - Invalid field values
+ * - Business rule validation failures
+ */
+export declare class BloqueValidationError extends BloqueAPIError {
+    /** Validation errors by field (if provided by API) */
+    readonly validationErrors?: Record<string, string[]>;
+    constructor(message: string, options?: BloqueAPIErrorOptions & {
+        validationErrors?: Record<string, string[]>;
+    });
+    toJSON(): {
+        validationErrors: Record<string, string[]> | undefined;
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string | undefined;
+        requestId: string | undefined;
+        timestamp: string;
+        response: unknown;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when a resource is not found (HTTP 404).
+ *
+ * Possible causes:
+ * - Invalid resource ID
+ * - Resource was deleted
+ * - User doesn't have access to the resource
+ */
+export declare class BloqueNotFoundError extends BloqueAPIError {
+    /** Type of resource that was not found (e.g., 'identity', 'account') */
+    readonly resourceType?: string;
+    /** ID of the resource that was not found */
+    readonly resourceId?: string;
+    constructor(message: string, options?: BloqueAPIErrorOptions & {
+        resourceType?: string;
+        resourceId?: string;
+    });
+    toJSON(): {
+        resourceType: string | undefined;
+        resourceId: string | undefined;
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string | undefined;
+        requestId: string | undefined;
+        timestamp: string;
+        response: unknown;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when an operation requires more funds than available.
+ *
+ * This is a domain-specific error for financial operations.
+ */
+export declare class BloqueInsufficientFundsError extends BloqueAPIError {
+    /** Amount requested for the operation */
+    readonly requestedAmount?: number;
+    /** Available balance */
+    readonly availableBalance?: number;
+    /** Currency code (e.g., 'USD', 'CLP') */
+    readonly currency?: string;
+    constructor(message: string, options?: BloqueAPIErrorOptions & {
+        requestedAmount?: number;
+        availableBalance?: number;
+        currency?: string;
+    });
+    toJSON(): {
+        requestedAmount: number | undefined;
+        availableBalance: number | undefined;
+        currency: string | undefined;
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string | undefined;
+        requestId: string | undefined;
+        timestamp: string;
+        response: unknown;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when a network error occurs.
+ *
+ * Possible causes:
+ * - No internet connection
+ * - DNS resolution failure
+ * - Connection refused
+ * - SSL/TLS errors
+ */
+export declare class BloqueNetworkError extends BloqueAPIError {
+    constructor(message: string, options?: BloqueAPIErrorOptions);
+}
+/**
+ * Error thrown when a request times out.
+ *
+ * The request exceeded the configured timeout duration.
+ * The SDK will automatically retry if retry is enabled.
+ */
+export declare class BloqueTimeoutError extends BloqueAPIError {
+    /** Timeout duration in milliseconds */
+    readonly timeoutMs: number;
+    constructor(message: string, options?: BloqueAPIErrorOptions & {
+        timeoutMs: number;
+    });
+    toJSON(): {
+        timeoutMs: number;
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string | undefined;
+        requestId: string | undefined;
+        timestamp: string;
+        response: unknown;
+        stack: string | undefined;
+    };
 }
+/**
+ * Error thrown when the SDK is misconfigured.
+ *
+ * This error is thrown before making any API requests.
+ */
 export declare class BloqueConfigError extends Error {
     constructor(message: string);
 }
+/**
+ * Factory function to create the appropriate error type based on status code and error code.
+ *
+ * @internal
+ */
+export declare function createBloqueError(message: string, options?: BloqueAPIErrorOptions): BloqueAPIError;

package/dist/http-client.d.ts

@@ -1,11 +1,55 @@
-import type { BloqueConfig, RequestOptions } from './types';
+import type { BloqueSDKConfig, RequestOptions } from './types';
 export declare class HttpClient {
-    readonly config: BloqueConfig;
+    /**
+     * Internal configuration with runtime state.
+     * @internal - Do not access directly. Use public getters instead.
+     * This field is private to prevent external access and mutations.
+     */
+    private readonly _config;
     private readonly baseUrl;
     private readonly publicRoutes;
-    constructor(config: BloqueConfig);
+    constructor(config: BloqueSDKConfig);
+    /**
+     * Get the origin identifier.
+     * @public
+     */
+    get origin(): string;
+    /**
+     * Get the authentication strategy.
+     * @public
+     */
+    get auth(): import("./types").AuthStrategy;
+    /**
+     * Get the URN of the currently connected identity.
+     * @public
+     * @returns The URN if a session is active, undefined otherwise.
+     */
+    get urn(): string | undefined;
+    /**
+     * Set the access token for authenticated requests.
+     * @internal - Called internally after successful authentication.
+     */
+    setAccessToken(token: string): void;
+    /**
+     * Set the URN of the connected identity.
+     * @internal - Called internally when connecting to a user session.
+     */
+    setUrn(urn: string): void;
     private validateConfig;
     private isPublicRoute;
     private buildAuthHeaders;
+    /**
+     * Determines if an error is retryable.
+     */
+    private isRetryableError;
+    /**
+     * Calculates the delay before the next retry attempt.
+     * Respects the Retry-After header if present, otherwise uses exponential backoff.
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleeps for the specified duration in milliseconds.
+     */
+    private sleep;
     request<T, U = unknown>(options: RequestOptions<U>): Promise<T>;
 }

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,t)=>{for(var r in t)__webpack_require__.o(t,r)&&!__webpack_require__.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},__webpack_require__.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),__webpack_require__.r=e=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{API_BASE_URLS:()=>API_BASE_URLS,BaseClient:()=>BaseClient,DEFAULT_HEADERS:()=>DEFAULT_HEADERS,BloqueAPIError:()=>BloqueAPIError,BloqueConfigError:()=>BloqueConfigError,HttpClient:()=>HttpClient});class BaseClient{httpClient;constructor(e){this.httpClient=e}}const API_BASE_URLS={sandbox:"https://dev.bloque.app",production:"https://api.bloque.app"},DEFAULT_HEADERS={"Content-Type":"application/json"};class BloqueAPIError extends Error{status;code;constructor(e,t,r){super(e),this.name="BloqueAPIError",this.status=t,this.code=r,Object.setPrototypeOf(this,BloqueAPIError.prototype)}}class BloqueConfigError extends Error{constructor(e){super(e),this.name="BloqueConfigError",Object.setPrototypeOf(this,BloqueConfigError.prototype)}}const isFrontendPlatform=e=>"browser"===e||"react-native"===e,createLocalStorageAdapter=()=>({get:()=>"u"<typeof localStorage?null:localStorage.getItem("access_token"),set:e=>{"u">typeof localStorage&&localStorage.setItem("access_token",e)},clear:()=>{"u">typeof localStorage&&localStorage.removeItem("access_token")}});class HttpClient{config;baseUrl;publicRoutes=["/api/aliases","/api/origins/*/assert","/api/origins"];constructor(e){this.validateConfig(e),this.config=e,this.baseUrl=API_BASE_URLS[e.mode??"production"]}validateConfig(e){if(e.mode??="production",e.platform??="node",!["sandbox","production"].includes(e.mode))throw new BloqueConfigError('Mode must be either "sandbox" or "production"');if("apiKey"===e.auth.type){if(!e.auth.apiKey?.trim())throw new BloqueConfigError("API key is required for apiKey authentication");if(isFrontendPlatform(e.platform))throw new BloqueConfigError("API key authentication is not allowed in frontend platforms")}if("jwt"===e.auth.type&&!e.tokenStorage)if("browser"===e.platform)e.tokenStorage=createLocalStorageAdapter();else throw new BloqueConfigError("tokenStorage must be provided when using JWT authentication")}isPublicRoute(e){let t=e.split("?")[0];return this.publicRoutes.some(e=>{let r=e.replace(/\*/g,"[^/]+");return RegExp(`^${r}$`).test(t)})}buildAuthHeaders(e){if(this.isPublicRoute(e))return{};if("apiKey"===this.config.auth.type)return this.config.accessToken?{Authorization:`Bearer ${this.config.accessToken}`}:{Authorization:this.config.auth.apiKey};if("jwt"===this.config.auth.type){let e=this.config.tokenStorage?.get();if(!e)throw new BloqueConfigError("Authentication token is missing");return{Authorization:`Bearer ${e}`}}return{}}async request(e){let{method:t,path:r,body:o,headers:i={}}=e,a=`${this.baseUrl}${r}`,s={...DEFAULT_HEADERS,...this.buildAuthHeaders(r),...i};try{let e=await fetch(a,{method:t,headers:s,body:o?JSON.stringify(o):void 0}),r=await e.json().catch(()=>({}));if(!e.ok)throw new BloqueAPIError(r.message||`HTTP ${e.status}: ${e.statusText}`,e.status,r.code);return r}catch(e){if(e instanceof BloqueAPIError)throw e;if(e instanceof Error)throw new BloqueAPIError(`Request failed: ${e.message}`,void 0,"NETWORK_ERROR");throw new BloqueAPIError("Unknown error occurred",void 0,"UNKNOWN_ERROR")}}}for(var __rspack_i in exports.API_BASE_URLS=__webpack_exports__.API_BASE_URLS,exports.BaseClient=__webpack_exports__.BaseClient,exports.BloqueAPIError=__webpack_exports__.BloqueAPIError,exports.BloqueConfigError=__webpack_exports__.BloqueConfigError,exports.DEFAULT_HEADERS=__webpack_exports__.DEFAULT_HEADERS,exports.HttpClient=__webpack_exports__.HttpClient,__webpack_exports__)-1===["API_BASE_URLS","BaseClient","BloqueAPIError","BloqueConfigError","DEFAULT_HEADERS","HttpClient"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
+"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,r)=>{for(var t in r)__webpack_require__.o(r,t)&&!__webpack_require__.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:r[t]})},__webpack_require__.o=(e,r)=>Object.prototype.hasOwnProperty.call(e,r),__webpack_require__.r=e=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{BloqueInsufficientFundsError:()=>BloqueInsufficientFundsError,API_BASE_URLS:()=>API_BASE_URLS,BloqueAuthenticationError:()=>BloqueAuthenticationError,BloqueNetworkError:()=>BloqueNetworkError,BloqueAPIError:()=>BloqueAPIError,BloqueConfigError:()=>BloqueConfigError,BloqueRateLimitError:()=>BloqueRateLimitError,BloqueValidationError:()=>BloqueValidationError,DEFAULT_HEADERS:()=>DEFAULT_HEADERS,BaseClient:()=>BaseClient,BloqueNotFoundError:()=>BloqueNotFoundError,HttpClient:()=>HttpClient,createBloqueError:()=>createBloqueError,BloqueTimeoutError:()=>BloqueTimeoutError});class BaseClient{httpClient;constructor(e){this.httpClient=e}}const API_BASE_URLS={sandbox:"https://dev.bloque.app",production:"https://api.bloque.app"},DEFAULT_HEADERS={"Content-Type":"application/json"};class BloqueAPIError extends Error{status;code;requestId;timestamp;response;cause;constructor(e,r){super(e),this.name="BloqueAPIError",this.status=r?.status,this.code=r?.code,this.requestId=r?.requestId,this.response=r?.response,this.cause=r?.cause,this.timestamp=new Date,Object.setPrototypeOf(this,BloqueAPIError.prototype)}toJSON(){return{name:this.name,message:this.message,status:this.status,code:this.code,requestId:this.requestId,timestamp:this.timestamp.toISOString(),response:this.response,stack:this.stack}}}class BloqueRateLimitError extends BloqueAPIError{retryAfter;constructor(e,r){super(e,{...r,status:429}),this.name="BloqueRateLimitError",this.retryAfter=r?.retryAfter,Object.setPrototypeOf(this,BloqueRateLimitError.prototype)}toJSON(){return{...super.toJSON(),retryAfter:this.retryAfter}}}class BloqueAuthenticationError extends BloqueAPIError{constructor(e,r){super(e,r),this.name="BloqueAuthenticationError",Object.setPrototypeOf(this,BloqueAuthenticationError.prototype)}}class BloqueValidationError extends BloqueAPIError{validationErrors;constructor(e,r){super(e,{...r,status:400}),this.name="BloqueValidationError",this.validationErrors=r?.validationErrors,Object.setPrototypeOf(this,BloqueValidationError.prototype)}toJSON(){return{...super.toJSON(),validationErrors:this.validationErrors}}}class BloqueNotFoundError extends BloqueAPIError{resourceType;resourceId;constructor(e,r){super(e,{...r,status:404}),this.name="BloqueNotFoundError",this.resourceType=r?.resourceType,this.resourceId=r?.resourceId,Object.setPrototypeOf(this,BloqueNotFoundError.prototype)}toJSON(){return{...super.toJSON(),resourceType:this.resourceType,resourceId:this.resourceId}}}class BloqueInsufficientFundsError extends BloqueAPIError{requestedAmount;availableBalance;currency;constructor(e,r){super(e,r),this.name="BloqueInsufficientFundsError",this.requestedAmount=r?.requestedAmount,this.availableBalance=r?.availableBalance,this.currency=r?.currency,Object.setPrototypeOf(this,BloqueInsufficientFundsError.prototype)}toJSON(){return{...super.toJSON(),requestedAmount:this.requestedAmount,availableBalance:this.availableBalance,currency:this.currency}}}class BloqueNetworkError extends BloqueAPIError{constructor(e,r){super(e,{...r,code:r?.code??"NETWORK_ERROR"}),this.name="BloqueNetworkError",Object.setPrototypeOf(this,BloqueNetworkError.prototype)}}class BloqueTimeoutError extends BloqueAPIError{timeoutMs;constructor(e,r){super(e,{...r,code:"TIMEOUT_ERROR"}),this.name="BloqueTimeoutError",this.timeoutMs=r?.timeoutMs??0,Object.setPrototypeOf(this,BloqueTimeoutError.prototype)}toJSON(){return{...super.toJSON(),timeoutMs:this.timeoutMs}}}class BloqueConfigError extends Error{constructor(e){super(e),this.name="BloqueConfigError",Object.setPrototypeOf(this,BloqueConfigError.prototype)}}const ERROR_CODE_MAP={INSUFFICIENT_FUNDS:BloqueInsufficientFundsError,INSUFFICIENT_BALANCE:BloqueInsufficientFundsError};function createBloqueError(e,r){let{status:t,code:o}=r??{};if(o&&ERROR_CODE_MAP[o])return new ERROR_CODE_MAP[o](e,r);switch(t){case 400:return new BloqueValidationError(e,r);case 401:case 403:return new BloqueAuthenticationError(e,r);case 404:return new BloqueNotFoundError(e,r);case 429:return new BloqueRateLimitError(e,r);default:return new BloqueAPIError(e,r)}}const isFrontendPlatform=e=>"browser"===e||"react-native"===e,createLocalStorageAdapter=()=>("u">typeof console&&console.warn&&console.warn("[Bloque SDK Security Warning] Using localStorage for token storage. localStorage is vulnerable to XSS attacks. For production use, provide a custom tokenStorage with httpOnly cookies or secure storage. See: https://owasp.org/www-community/attacks/xss/"),{get:()=>"u"<typeof localStorage?null:localStorage.getItem("access_token"),set:e=>{"u">typeof localStorage&&localStorage.setItem("access_token",e)},clear:()=>{"u">typeof localStorage&&localStorage.removeItem("access_token")}});class HttpClient{_config;baseUrl;publicRoutes=["/api/aliases","/api/origins/*/assert","/api/origins"];constructor(e){const r={...e};this.validateConfig(r),this._config=r,this.baseUrl=API_BASE_URLS[e.mode??"production"]}get origin(){return this._config.origin}get auth(){return this._config.auth}get urn(){return this._config.urn}setAccessToken(e){this._config.accessToken=e}setUrn(e){this._config.urn=e}validateConfig(e){if(e.mode??="production",e.platform??="node",e.timeout??=3e4,e.retry??={},e.retry.enabled??=!0,e.retry.maxRetries??=3,e.retry.initialDelay??=1e3,e.retry.maxDelay??=3e4,!["sandbox","production"].includes(e.mode))throw new BloqueConfigError('Mode must be either "sandbox" or "production"');if(void 0!==e.timeout&&e.timeout<0)throw new BloqueConfigError("Timeout must be a non-negative number");if(void 0!==e.retry.maxRetries&&e.retry.maxRetries<0)throw new BloqueConfigError("maxRetries must be a non-negative number");if(void 0!==e.retry.initialDelay&&e.retry.initialDelay<0)throw new BloqueConfigError("initialDelay must be a non-negative number");if(void 0!==e.retry.maxDelay&&e.retry.maxDelay<0)throw new BloqueConfigError("maxDelay must be a non-negative number");if("apiKey"===e.auth.type){if(!e.auth.apiKey?.trim())throw new BloqueConfigError("API key is required for apiKey authentication");if(isFrontendPlatform(e.platform))throw new BloqueConfigError("API key authentication is not allowed in frontend platforms")}if("jwt"===e.auth.type&&!e.tokenStorage)if("browser"===e.platform)e.tokenStorage=createLocalStorageAdapter();else throw new BloqueConfigError("tokenStorage must be provided when using JWT authentication")}isPublicRoute(e){let r=e.split("?")[0];return this.publicRoutes.some(e=>{let t=e.replace(/\*/g,"[^/]+");return RegExp(`^${t}$`).test(r)})}buildAuthHeaders(e){if(this.isPublicRoute(e))return{};if("apiKey"===this._config.auth.type)return this._config.accessToken?{Authorization:`Bearer ${this._config.accessToken}`}:{Authorization:this._config.auth.apiKey};if("jwt"===this._config.auth.type){let e=this._config.tokenStorage?.get();if(!e)throw new BloqueConfigError("Authentication token is missing");return{Authorization:`Bearer ${e}`}}return{}}isRetryableError(e){return e instanceof BloqueRateLimitError||e instanceof BloqueNetworkError||e instanceof BloqueTimeoutError||e instanceof Error&&"status"in e&&503===e.status}calculateRetryDelay(e,r){let{initialDelay:t=1e3,maxDelay:o=3e4}=this._config.retry??{};if(r){let e=Number.parseInt(r,10);if(!Number.isNaN(e))return Math.min(1e3*e,o);let t=new Date(r);if(!Number.isNaN(t.getTime()))return Math.min(Math.max(t.getTime()-Date.now(),0),o)}let s=t*2**e,i=.25*s*(2*Math.random()-1);return Math.min(s+i,o)}sleep(e){return new Promise(r=>setTimeout(r,e))}async request(e){let r,{method:t,path:o,body:s,headers:i={},timeout:a}=e,u=`${this.baseUrl}${o}`,n={...DEFAULT_HEADERS,...this.buildAuthHeaders(o),...i},l=void 0!==a?a:this._config.timeout??3e4,{enabled:c=!0,maxRetries:_=3}=this._config.retry??{},p=0;for(;p<=(c?_:0);){let e,o=new AbortController;l>0&&(e=setTimeout(()=>{o.abort()},l));try{let i=await fetch(u,{method:t,headers:n,body:s?JSON.stringify(s):void 0,signal:o.signal});void 0!==e&&clearTimeout(e);let a=await i.json().catch(()=>({}));if(!i.ok){let e=i.headers.get("X-Request-ID")??i.headers.get("Request-ID")??void 0,t=i.headers.get("Retry-After"),o=429===i.status?new BloqueRateLimitError(a.message||"Rate limit exceeded",{status:i.status,code:a.code,requestId:e,response:a,retryAfter:t?Number.parseInt(t,10):void 0}):createBloqueError(a.message||`HTTP ${i.status}: ${i.statusText}`,{status:i.status,code:a.code,requestId:e,response:a});if(c&&p<_&&this.isRetryableError(o)){r=o;let e=this.calculateRetryDelay(p,t??void 0);await this.sleep(e),p++;continue}throw o}return a}catch(o){let t;if(void 0!==e&&clearTimeout(e),o&&"object"==typeof o&&"name"in o&&"string"==typeof o.name&&o.name.startsWith("Bloque")&&!this.isRetryableError(o))throw o;if(t=o instanceof Error&&"AbortError"===o.name?new BloqueTimeoutError(`Request timeout after ${l}ms`,{timeoutMs:l,cause:o}):o instanceof Error?new BloqueNetworkError(`Request failed: ${o.message}`,{cause:o}):createBloqueError("Unknown error occurred",{code:"UNKNOWN_ERROR"}),c&&p<_&&this.isRetryableError(t)){r=t;let e=this.calculateRetryDelay(p);await this.sleep(e),p++;continue}throw t}}throw r||createBloqueError("Request failed after retries",{code:"MAX_RETRIES_EXCEEDED"})}}for(var __rspack_i in exports.API_BASE_URLS=__webpack_exports__.API_BASE_URLS,exports.BaseClient=__webpack_exports__.BaseClient,exports.BloqueAPIError=__webpack_exports__.BloqueAPIError,exports.BloqueAuthenticationError=__webpack_exports__.BloqueAuthenticationError,exports.BloqueConfigError=__webpack_exports__.BloqueConfigError,exports.BloqueInsufficientFundsError=__webpack_exports__.BloqueInsufficientFundsError,exports.BloqueNetworkError=__webpack_exports__.BloqueNetworkError,exports.BloqueNotFoundError=__webpack_exports__.BloqueNotFoundError,exports.BloqueRateLimitError=__webpack_exports__.BloqueRateLimitError,exports.BloqueTimeoutError=__webpack_exports__.BloqueTimeoutError,exports.BloqueValidationError=__webpack_exports__.BloqueValidationError,exports.DEFAULT_HEADERS=__webpack_exports__.DEFAULT_HEADERS,exports.HttpClient=__webpack_exports__.HttpClient,exports.createBloqueError=__webpack_exports__.createBloqueError,__webpack_exports__)-1===["API_BASE_URLS","BaseClient","BloqueAPIError","BloqueAuthenticationError","BloqueConfigError","BloqueInsufficientFundsError","BloqueNetworkError","BloqueNotFoundError","BloqueRateLimitError","BloqueTimeoutError","BloqueValidationError","DEFAULT_HEADERS","HttpClient","createBloqueError"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/index.js

@@ -1 +1 @@
-class t{httpClient;constructor(t){this.httpClient=t}}let e={sandbox:"https://dev.bloque.app",production:"https://api.bloque.app"},o={"Content-Type":"application/json"};class r extends Error{status;code;constructor(t,e,o){super(t),this.name="BloqueAPIError",this.status=e,this.code=o,Object.setPrototypeOf(this,r.prototype)}}class i extends Error{constructor(t){super(t),this.name="BloqueConfigError",Object.setPrototypeOf(this,i.prototype)}}class s{config;baseUrl;publicRoutes=["/api/aliases","/api/origins/*/assert","/api/origins"];constructor(t){this.validateConfig(t),this.config=t,this.baseUrl=e[t.mode??"production"]}validateConfig(t){if(t.mode??="production",t.platform??="node",!["sandbox","production"].includes(t.mode))throw new i('Mode must be either "sandbox" or "production"');if("apiKey"===t.auth.type){let e;if(!t.auth.apiKey?.trim())throw new i("API key is required for apiKey authentication");if("browser"===(e=t.platform)||"react-native"===e)throw new i("API key authentication is not allowed in frontend platforms")}if("jwt"===t.auth.type&&!t.tokenStorage)if("browser"===t.platform)t.tokenStorage={get:()=>"u"<typeof localStorage?null:localStorage.getItem("access_token"),set:t=>{"u">typeof localStorage&&localStorage.setItem("access_token",t)},clear:()=>{"u">typeof localStorage&&localStorage.removeItem("access_token")}};else throw new i("tokenStorage must be provided when using JWT authentication")}isPublicRoute(t){let e=t.split("?")[0];return this.publicRoutes.some(t=>{let o=t.replace(/\*/g,"[^/]+");return RegExp(`^${o}$`).test(e)})}buildAuthHeaders(t){if(this.isPublicRoute(t))return{};if("apiKey"===this.config.auth.type)return this.config.accessToken?{Authorization:`Bearer ${this.config.accessToken}`}:{Authorization:this.config.auth.apiKey};if("jwt"===this.config.auth.type){let t=this.config.tokenStorage?.get();if(!t)throw new i("Authentication token is missing");return{Authorization:`Bearer ${t}`}}return{}}async request(t){let{method:e,path:i,body:s,headers:a={}}=t,n=`${this.baseUrl}${i}`,c={...o,...this.buildAuthHeaders(i),...a};try{let t=await fetch(n,{method:e,headers:c,body:s?JSON.stringify(s):void 0}),o=await t.json().catch(()=>({}));if(!t.ok)throw new r(o.message||`HTTP ${t.status}: ${t.statusText}`,t.status,o.code);return o}catch(t){if(t instanceof r)throw t;if(t instanceof Error)throw new r(`Request failed: ${t.message}`,void 0,"NETWORK_ERROR");throw new r("Unknown error occurred",void 0,"UNKNOWN_ERROR")}}}export{e as API_BASE_URLS,t as BaseClient,r as BloqueAPIError,i as BloqueConfigError,o as DEFAULT_HEADERS,s as HttpClient};
+class e{httpClient;constructor(e){this.httpClient=e}}let t={sandbox:"https://dev.bloque.app",production:"https://api.bloque.app"},r={"Content-Type":"application/json"};class o extends Error{status;code;requestId;timestamp;response;cause;constructor(e,t){super(e),this.name="BloqueAPIError",this.status=t?.status,this.code=t?.code,this.requestId=t?.requestId,this.response=t?.response,this.cause=t?.cause,this.timestamp=new Date,Object.setPrototypeOf(this,o.prototype)}toJSON(){return{name:this.name,message:this.message,status:this.status,code:this.code,requestId:this.requestId,timestamp:this.timestamp.toISOString(),response:this.response,stack:this.stack}}}class s extends o{retryAfter;constructor(e,t){super(e,{...t,status:429}),this.name="BloqueRateLimitError",this.retryAfter=t?.retryAfter,Object.setPrototypeOf(this,s.prototype)}toJSON(){return{...super.toJSON(),retryAfter:this.retryAfter}}}class i extends o{constructor(e,t){super(e,t),this.name="BloqueAuthenticationError",Object.setPrototypeOf(this,i.prototype)}}class a extends o{validationErrors;constructor(e,t){super(e,{...t,status:400}),this.name="BloqueValidationError",this.validationErrors=t?.validationErrors,Object.setPrototypeOf(this,a.prototype)}toJSON(){return{...super.toJSON(),validationErrors:this.validationErrors}}}class n extends o{resourceType;resourceId;constructor(e,t){super(e,{...t,status:404}),this.name="BloqueNotFoundError",this.resourceType=t?.resourceType,this.resourceId=t?.resourceId,Object.setPrototypeOf(this,n.prototype)}toJSON(){return{...super.toJSON(),resourceType:this.resourceType,resourceId:this.resourceId}}}class u extends o{requestedAmount;availableBalance;currency;constructor(e,t){super(e,t),this.name="BloqueInsufficientFundsError",this.requestedAmount=t?.requestedAmount,this.availableBalance=t?.availableBalance,this.currency=t?.currency,Object.setPrototypeOf(this,u.prototype)}toJSON(){return{...super.toJSON(),requestedAmount:this.requestedAmount,availableBalance:this.availableBalance,currency:this.currency}}}class c extends o{constructor(e,t){super(e,{...t,code:t?.code??"NETWORK_ERROR"}),this.name="BloqueNetworkError",Object.setPrototypeOf(this,c.prototype)}}class l extends o{timeoutMs;constructor(e,t){super(e,{...t,code:"TIMEOUT_ERROR"}),this.name="BloqueTimeoutError",this.timeoutMs=t?.timeoutMs??0,Object.setPrototypeOf(this,l.prototype)}toJSON(){return{...super.toJSON(),timeoutMs:this.timeoutMs}}}class h extends Error{constructor(e){super(e),this.name="BloqueConfigError",Object.setPrototypeOf(this,h.prototype)}}let p={INSUFFICIENT_FUNDS:u,INSUFFICIENT_BALANCE:u};function d(e,t){let{status:r,code:u}=t??{};if(u&&p[u])return new p[u](e,t);switch(r){case 400:return new a(e,t);case 401:case 403:return new i(e,t);case 404:return new n(e,t);case 429:return new s(e,t);default:return new o(e,t)}}class m{_config;baseUrl;publicRoutes=["/api/aliases","/api/origins/*/assert","/api/origins"];constructor(e){let r={...e};this.validateConfig(r),this._config=r,this.baseUrl=t[e.mode??"production"]}get origin(){return this._config.origin}get auth(){return this._config.auth}get urn(){return this._config.urn}setAccessToken(e){this._config.accessToken=e}setUrn(e){this._config.urn=e}validateConfig(e){if(e.mode??="production",e.platform??="node",e.timeout??=3e4,e.retry??={},e.retry.enabled??=!0,e.retry.maxRetries??=3,e.retry.initialDelay??=1e3,e.retry.maxDelay??=3e4,!["sandbox","production"].includes(e.mode))throw new h('Mode must be either "sandbox" or "production"');if(void 0!==e.timeout&&e.timeout<0)throw new h("Timeout must be a non-negative number");if(void 0!==e.retry.maxRetries&&e.retry.maxRetries<0)throw new h("maxRetries must be a non-negative number");if(void 0!==e.retry.initialDelay&&e.retry.initialDelay<0)throw new h("initialDelay must be a non-negative number");if(void 0!==e.retry.maxDelay&&e.retry.maxDelay<0)throw new h("maxDelay must be a non-negative number");if("apiKey"===e.auth.type){let t;if(!e.auth.apiKey?.trim())throw new h("API key is required for apiKey authentication");if("browser"===(t=e.platform)||"react-native"===t)throw new h("API key authentication is not allowed in frontend platforms")}if("jwt"===e.auth.type&&!e.tokenStorage)if("browser"===e.platform)"u">typeof console&&console.warn&&console.warn("[Bloque SDK Security Warning] Using localStorage for token storage. localStorage is vulnerable to XSS attacks. For production use, provide a custom tokenStorage with httpOnly cookies or secure storage. See: https://owasp.org/www-community/attacks/xss/"),e.tokenStorage={get:()=>"u"<typeof localStorage?null:localStorage.getItem("access_token"),set:e=>{"u">typeof localStorage&&localStorage.setItem("access_token",e)},clear:()=>{"u">typeof localStorage&&localStorage.removeItem("access_token")}};else throw new h("tokenStorage must be provided when using JWT authentication")}isPublicRoute(e){let t=e.split("?")[0];return this.publicRoutes.some(e=>{let r=e.replace(/\*/g,"[^/]+");return RegExp(`^${r}$`).test(t)})}buildAuthHeaders(e){if(this.isPublicRoute(e))return{};if("apiKey"===this._config.auth.type)return this._config.accessToken?{Authorization:`Bearer ${this._config.accessToken}`}:{Authorization:this._config.auth.apiKey};if("jwt"===this._config.auth.type){let e=this._config.tokenStorage?.get();if(!e)throw new h("Authentication token is missing");return{Authorization:`Bearer ${e}`}}return{}}isRetryableError(e){return e instanceof s||e instanceof c||e instanceof l||e instanceof Error&&"status"in e&&503===e.status}calculateRetryDelay(e,t){let{initialDelay:r=1e3,maxDelay:o=3e4}=this._config.retry??{};if(t){let e=Number.parseInt(t,10);if(!Number.isNaN(e))return Math.min(1e3*e,o);let r=new Date(t);if(!Number.isNaN(r.getTime()))return Math.min(Math.max(r.getTime()-Date.now(),0),o)}let s=r*2**e,i=.25*s*(2*Math.random()-1);return Math.min(s+i,o)}sleep(e){return new Promise(t=>setTimeout(t,e))}async request(e){let t,{method:o,path:i,body:a,headers:n={},timeout:u}=e,h=`${this.baseUrl}${i}`,p={...r,...this.buildAuthHeaders(i),...n},m=void 0!==u?u:this._config.timeout??3e4,{enabled:y=!0,maxRetries:f=3}=this._config.retry??{},g=0;for(;g<=(y?f:0);){let e,r=new AbortController;m>0&&(e=setTimeout(()=>{r.abort()},m));try{let i=await fetch(h,{method:o,headers:p,body:a?JSON.stringify(a):void 0,signal:r.signal});void 0!==e&&clearTimeout(e);let n=await i.json().catch(()=>({}));if(!i.ok){let e=i.headers.get("X-Request-ID")??i.headers.get("Request-ID")??void 0,r=i.headers.get("Retry-After"),o=429===i.status?new s(n.message||"Rate limit exceeded",{status:i.status,code:n.code,requestId:e,response:n,retryAfter:r?Number.parseInt(r,10):void 0}):d(n.message||`HTTP ${i.status}: ${i.statusText}`,{status:i.status,code:n.code,requestId:e,response:n});if(y&&g<f&&this.isRetryableError(o)){t=o;let e=this.calculateRetryDelay(g,r??void 0);await this.sleep(e),g++;continue}throw o}return n}catch(o){let r;if(void 0!==e&&clearTimeout(e),o&&"object"==typeof o&&"name"in o&&"string"==typeof o.name&&o.name.startsWith("Bloque")&&!this.isRetryableError(o))throw o;if(r=o instanceof Error&&"AbortError"===o.name?new l(`Request timeout after ${m}ms`,{timeoutMs:m,cause:o}):o instanceof Error?new c(`Request failed: ${o.message}`,{cause:o}):d("Unknown error occurred",{code:"UNKNOWN_ERROR"}),y&&g<f&&this.isRetryableError(r)){t=r;let e=this.calculateRetryDelay(g);await this.sleep(e),g++;continue}throw r}}throw t||d("Request failed after retries",{code:"MAX_RETRIES_EXCEEDED"})}}export{t as API_BASE_URLS,e as BaseClient,o as BloqueAPIError,i as BloqueAuthenticationError,h as BloqueConfigError,u as BloqueInsufficientFundsError,c as BloqueNetworkError,n as BloqueNotFoundError,s as BloqueRateLimitError,l as BloqueTimeoutError,a as BloqueValidationError,r as DEFAULT_HEADERS,m as HttpClient,d as createBloqueError};

package/dist/types.d.ts

@@ -80,6 +80,52 @@ export type Platform =
  *
  * This allows consumers to customize the storage mechanism
  * (localStorage, sessionStorage, cookies, in-memory, etc.).
+ *
+ * ⚠️ SECURITY CONSIDERATIONS:
+ *
+ * **localStorage / sessionStorage (INSECURE)**:
+ * - Vulnerable to XSS attacks - any malicious script can read the token
+ * - Should ONLY be used for development/testing or non-sensitive apps
+ * - NOT recommended for production applications handling sensitive data
+ *
+ * **httpOnly Cookies (RECOMMENDED)**:
+ * - Best security practice - not accessible to JavaScript
+ * - Protects against XSS attacks
+ * - Requires server-side cooperation to set cookies
+ *
+ * **Secure Storage (RECOMMENDED for mobile)**:
+ * - Use platform-specific secure storage (e.g., Keychain on iOS, Keystore on Android)
+ * - Libraries: @react-native-async-storage/async-storage, expo-secure-store
+ *
+ * **In-Memory Storage**:
+ * - Most secure against XSS
+ * - Token lost on page refresh/app restart
+ * - Good for short-lived sessions
+ *
+ * Example implementation using httpOnly cookies:
+ * ```typescript
+ * const cookieStorage: TokenStorage = {
+ *   get: () => {
+ *     // Token is automatically sent in httpOnly cookie
+ *     // You may need to fetch from server or return null
+ *     return null;
+ *   },
+ *   set: (token) => {
+ *     // Send to server to set httpOnly cookie
+ *     fetch('/api/auth/set-token', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ token })
+ *     });
+ *   },
+ *   clear: () => {
+ *     // Call server to clear cookie
+ *     fetch('/api/auth/logout', { method: 'POST' });
+ *   }
+ * };
+ * ```
+ *
+ * @see https://owasp.org/www-community/attacks/xss/
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html#local-storage
  */
 export interface TokenStorage {
     /**
@@ -91,6 +137,9 @@ export interface TokenStorage {
     /**
      * Persists a JWT token.
      *
+     * ⚠️ WARNING: If using localStorage/sessionStorage, this token will be
+     * accessible to any JavaScript code on the page, including malicious scripts.
+     *
      * @param token The JWT token to store.
      */
     set(token: string): void;
@@ -106,12 +155,14 @@ export type AuthStrategy = {
     type: 'jwt';
 };
 /**
- * Main configuration object for the Bloque SDK.
+ * Public configuration object for the Bloque SDK.
  *
- * This configuration is resolved once when initializing
- * the SDK (via `new SDK()` or `init()` in the modular API).
+ * This is the configuration interface that users should use when
+ * initializing the SDK (via `new SDK()` or `init()` in the modular API).
+ *
+ * @public
  */
-export interface BloqueConfig {
+export interface BloqueSDKConfig {
     /**
      * Origin identifier for the SDK.
      *
@@ -160,23 +211,97 @@ export interface BloqueConfig {
     /**
      * JWT token storage strategy.
      *
-     * Only applies when `runtime` is set to `client`.
+     * Only applies when `platform` is set to `browser` or `react-native`.
+     *
+     * **Default behavior (browser only)**:
+     * - The SDK uses `localStorage` by default for browser platform
+     * - ⚠️ localStorage is INSECURE and vulnerable to XSS attacks
+     * - A security warning will be logged to the console
      *
-     * By default, the SDK uses `localStorage` to persist
-     * the JWT token. This behavior can be overridden to
-     * use alternative storage mechanisms.
+     * **For production applications**, provide a custom `tokenStorage` using:
+     * - httpOnly cookies (recommended - immune to XSS)
+     * - Secure storage libraries (for React Native)
+     * - sessionStorage (slightly better than localStorage, but still vulnerable)
+     * - In-memory storage (most secure, but lost on refresh)
+     *
+     * @see TokenStorage for security considerations and examples
      */
     tokenStorage?: TokenStorage;
     /**
-     * Optional access token to be used for authentication.
+     * Default timeout for HTTP requests in milliseconds.
+     *
+     * If a request takes longer than this timeout, it will be aborted
+     * and throw a BloqueAPIError with code 'TIMEOUT_ERROR'.
+     *
+     * Can be overridden per-request using the `timeout` option in RequestOptions.
+     *
+     * Set to 0 to disable timeouts globally (not recommended for production).
+     *
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Retry configuration for failed requests.
+     *
+     * When enabled, the SDK will automatically retry failed requests with
+     * exponential backoff for the following scenarios:
+     * - 429 (Too Many Requests)
+     * - 503 (Service Unavailable)
+     * - Network errors (timeouts, connection failures)
+     *
+     * The SDK respects the `Retry-After` header when present.
+     *
+     * @default { enabled: true, maxRetries: 3, initialDelay: 1000 }
+     */
+    retry?: {
+        /**
+         * Whether to enable automatic retries.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Maximum number of retry attempts.
+         * @default 3
+         */
+        maxRetries?: number;
+        /**
+         * Initial delay in milliseconds before the first retry.
+         * Subsequent retries use exponential backoff: delay * (2 ^ attempt).
+         * @default 1000 (1 second)
+         */
+        initialDelay?: number;
+        /**
+         * Maximum delay in milliseconds between retries.
+         * Prevents exponential backoff from growing too large.
+         * @default 30000 (30 seconds)
+         */
+        maxDelay?: number;
+    };
+}
+/**
+ * Internal configuration object with runtime state.
+ *
+ * Extends the public configuration with internal fields that are
+ * managed by the SDK at runtime (access tokens, session state, etc.).
+ *
+ * @internal - This interface is not part of the public API.
+ * Users should not depend on these fields as they may change without notice.
+ */
+export interface BloqueInternalConfig extends BloqueSDKConfig {
+    /**
+     * Access token for authenticated requests.
      *
-     * Mainly intended for internal use or advanced scenarios.
+     * @internal
+     * Set internally after successful authentication (register/connect).
+     * Should not be accessed or modified by SDK users.
      */
     accessToken?: string;
     /**
-     * Optional user URN to scope the SDK instance to a specific user.
+     * URN of the currently connected identity.
      *
-     * Mainly intended for internal use or advanced scenarios.
+     * @internal
+     * Set internally when connecting to a user session.
+     * Should not be accessed or modified by SDK users.
      */
     urn?: string;
 }
@@ -185,6 +310,18 @@ export interface RequestOptions<U = unknown> {
     path: string;
     body?: U;
     headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * If not specified, uses the default timeout from SDK config.
+     * Set to 0 to disable timeout for this specific request.
+     *
+     * When a request exceeds the timeout, it will be aborted and
+     * throw a BloqueAPIError with code 'TIMEOUT_ERROR'.
+     *
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
 }
 export interface BloqueResponse<T> {
     data?: T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloque/sdk-core",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Core utilities and types for Bloque SDK.",
   "type": "module",
   "keywords": [