@bloque/sdk 0.0.22 → 0.0.24

package/README.md

@@ -15,7 +15,7 @@ The official TypeScript/JavaScript SDK for integrating [Bloque](https://www.bloq
 > }
 > ```
 >
-> Replace `x.x.x` with the latest version from [npm](https://www.npmjs.com/package/@bloque/sdk).
+> Replace with the latest version from [npm](https://www.npmjs.com/package/@bloque/sdk).
 
 ## Platform Support
 
@@ -25,23 +25,40 @@ This SDK is compatible with multiple JavaScript runtimes:
 - **Bun** 1.x or higher
 - **Deno** Latest version
 - **Web/Browsers** Modern browsers with ES2020+ support
+- **React Native** Latest version
 
 ## Features
 
 - **TypeScript First**: Built with TypeScript for complete type safety
-- **Simple API**: Intuitive interface for managing organizations, compliance, accounts, and identity
-- **Identity Registration**: Register individual users (KYC) and businesses (KYB) with multi-method authentication
-- **User Sessions**: Secure user session management with `connect()` for authenticated operations
-- **Fully Async**: Promise-based API for modern JavaScript workflows
+- **Modular Architecture**: Import only what you need - accounts, identity, compliance, or organizations
+- **Multi-Runtime**: Works seamlessly across Node.js, Bun, Deno, browsers, and React Native
+- **Account Management**: Create and manage virtual cards, virtual accounts, and Bancolombia accounts
+- **Identity System**: Register individual users (KYC) and businesses (KYB) with multi-method authentication
+- **Compliance Ready**: Built-in KYC/KYB verification workflows
+- **Transfer System**: Transfer funds between accounts with multiple asset support
+- **Production Ready**:
+  - ✅ Automatic retry with exponential backoff
+  - ✅ Configurable timeouts (default: 30s)
+  - ✅ Specific error types for better error handling
+  - ✅ Request ID tracking for debugging
+  - ✅ Security warnings for insecure practices
 - **Lightweight**: Minimal dependencies for optimal bundle size
-- **Modular**: Import only what you need with tree-shakeable exports
-
-> **📌 Important:** Most operations require connecting to a user session first using `bloque.connect(urn)`. This ensures proper authentication and authorization. See the [User Sessions](#user-sessions-with-connect) section for details.
+- **Fully Async**: Promise-based API for modern JavaScript workflows
 
 ## Installation
 
 ```bash
+# npm
+npm install @bloque/sdk
+
+# bun
 bun add @bloque/sdk
+
+# pnpm
+pnpm add @bloque/sdk
+
+# yarn
+yarn add @bloque/sdk
 ```
 
 ## Quick Start
@@ -50,58 +67,34 @@ bun add @bloque/sdk
 
 ```typescript
 import { SDK } from '@bloque/sdk';
-import type { CreateOrgParams } from '@bloque/sdk/orgs';
 
 // Initialize the SDK with API key (backend only)
 const bloque = new SDK({
-  origin: 'your-origin-name', // Required: your origin identifier
+  origin: 'your-origin-name',
   auth: {
     type: 'apiKey',
     apiKey: process.env.BLOQUE_API_KEY!,
   },
   mode: 'production', // or 'sandbox' for testing
   platform: 'node', // optional: 'node' | 'bun' | 'deno'
+  timeout: 30000, // optional: request timeout in ms
+  retry: { // optional: retry configuration
+    enabled: true,
+    maxRetries: 3,
+    initialDelay: 1000,
+  },
 });
 
-// Connect to user session for account operations
-async function createCard() {
-  // First, connect to the user's session
-  const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
-
-  // Now create a virtual card through the session
-  const card = await userSession.accounts.card.create({
-    urn: 'did:bloque:your-origin:user-alias',
-    name: 'My Virtual Card',
-  });
-
-  console.log('Card created:', card.urn);
-  console.log('Last four digits:', card.lastFour);
-}
+// Connect to user session
+const session = await bloque.connect('did:bloque:your-origin:user-alias');
 
-// Create an organization (direct SDK access, no connect needed)
-async function createOrganization() {
-  const params: CreateOrgParams = {
-    org_type: 'business',
-    profile: {
-      legal_name: 'Acme Corporation',
-      tax_id: '123456789',
-      incorporation_date: '2020-01-01',
-      business_type: 'llc',
-      incorporation_country_code: 'US',
-      incorporation_state: 'CA',
-      address_line1: '123 Main St',
-      postal_code: '12345',
-      city: 'San Francisco',
-    },
-    metadata: {
-      source: 'api',
-    },
-  };
+// Create a virtual card
+const card = await session.accounts.card.create({
+  name: 'My Virtual Card',
+});
 
-  const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
-  const organization = await userSession.orgs.create(params);
-  console.log('Organization created:', organization);
-}
+console.log('Card created:', card.urn);
+console.log('Last four digits:', card.lastFour);
 ```
 
 ### Frontend (Browser, React Native)
@@ -111,1174 +104,579 @@ import { SDK } from '@bloque/sdk';
 
 // Initialize the SDK with JWT authentication
 const bloque = new SDK({
+  origin: 'your-origin-name',
   auth: { type: 'jwt' },
   mode: 'production',
   platform: 'browser', // or 'react-native'
-  // tokenStorage is optional for browser (uses localStorage by default)
-  // for react-native, provide a custom storage implementation
-});
-
-// After user registration, the SDK automatically stores the JWT
-const result = await bloque.identity.origins.register('ethereum-mainnet', {
-  assertionResult: { /* ... */ },
-  type: 'individual',
-  profile: { /* ... */ }
-});
-
-// The token is now stored and used for subsequent requests
-const alias = await bloque.identity.aliases.get('user@example.com');
-```
-
-## Configuration
-
-### Initialize the SDK
-
-The SDK supports different authentication methods depending on where it's running:
-
-#### Backend Configuration (API Key)
-
-For server-side applications (Node.js, Bun, Deno):
-
-```typescript
-import { SDK } from '@bloque/sdk';
-
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!, // Your Bloque API key
-  },
-  mode: 'production', // 'sandbox' or 'production'
-  platform: 'node', // optional: 'node' | 'bun' | 'deno' (defaults to 'node')
-});
-```
-
-#### Frontend Configuration (JWT)
-
-For client-side applications (Browser, React Native):
-
-```typescript
-import { SDK } from '@bloque/sdk';
-
-// Browser
-const bloque = new SDK({
-  auth: { type: 'jwt' },
-  mode: 'production',
-  platform: 'browser',
-  // tokenStorage is optional - uses localStorage by default
-});
-
-// React Native (with custom storage)
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
-const bloque = new SDK({
-  auth: { type: 'jwt' },
-  mode: 'production',
-  platform: 'react-native',
+  // For browser: uses localStorage by default (with security warning)
+  // For react-native: provide custom tokenStorage
   tokenStorage: {
-    get: async () => await AsyncStorage.getItem('access_token'),
-    set: async (token: string) => await AsyncStorage.setItem('access_token', token),
-    clear: async () => await AsyncStorage.removeItem('access_token'),
-  },
-});
-```
-
-### Configuration Options
-
-- **`origin`** (string, required): Your origin identifier/namespace
-  - This identifies your application or organization in the Bloque platform
-  - Example: `'my-app'`, `'bloque-root'`, `'ethereum-mainnet'`
-
-- **`auth`** (object, required): Authentication configuration
-  - `type: 'apiKey'`: For backend platforms
-    - `apiKey` (string, required): Your Bloque API key
-  - `type: 'jwt'`: For frontend platforms
-    - Requires storing and managing JWT tokens via `tokenStorage`
-
-- **`mode`** ('sandbox' | 'production', optional): Environment mode
-  - `sandbox`: For testing and development
-  - `production`: For live operations (default)
-
-- **`platform`** (string, optional): Execution platform
-  - Backend: `'node'` (default) | `'bun'` | `'deno'`
-  - Frontend: `'browser'` | `'react-native'`
-  - Determines available authentication methods
-
-- **`tokenStorage`** (object, optional): JWT token storage mechanism
-  - Required for JWT authentication on non-browser platforms
-  - Browser automatically uses `localStorage` if not provided
-  - Must implement: `get()`, `set(token)`, `clear()`
-
-### User Sessions with `connect()`
-
-Most operations in the SDK require connecting to a user session first. This ensures proper authentication and authorization for user-specific operations.
-
-```typescript
-// Initialize SDK
-const bloque = new SDK({
-  origin: 'your-origin',
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
+    get: () => {
+      // Your secure storage implementation
+      return AsyncStorage.getItem('bloque_token');
+    },
+    set: (token) => {
+      AsyncStorage.setItem('bloque_token', token);
+    },
+    clear: () => {
+      AsyncStorage.removeItem('bloque_token');
+    },
   },
-  mode: 'production',
 });
 
-// Connect to user session
-const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
+// Register a new user
+const result = await bloque.identity.origins.register(
+  'did:bloque:your-origin:ethereum-mainnet',
+  {
+    assertionResult: { /* signing challenge result */ },
+    type: 'individual',
+    profile: {
+      firstName: 'John',
+      lastName: 'Doe',
+      email: 'john@example.com',
+    },
+  }
+);
 
-// Now perform operations through the session
-const card = await userSession.accounts.card.create({
-  urn: 'did:bloque:your-origin:user-alias',
-  name: 'My Card',
-});
+// The JWT is automatically stored and used for subsequent requests
 ```
 
-**What `connect()` does:**
-- Authenticates the user with the specified URN
-- Obtains an access token for the user session
-- Returns a session object with access to: `accounts`, `compliance`, `identity`, `orgs`
-
-**URN Format:**
-- Pattern: `did:bloque:{origin}:{user-alias}`
-- Example: `did:bloque:my-app:john-doe`
-- The `{origin}` must match the origin specified in SDK configuration
-- The `{user-alias}` is the user's unique identifier in your origin
-
-### Platform and Authentication Compatibility
-
-| Platform | API Key Auth | JWT Auth | Token Storage |
-|----------|--------------|----------|---------------|
-| `node` | ✅ | ✅ | Required for JWT |
-| `bun` | ✅ | ✅ | Required for JWT |
-| `deno` | ✅ | ✅ | Required for JWT |
-| `browser` | ❌ | ✅ | Optional (uses localStorage) |
-| `react-native` | ❌ | ✅ | Required |
-
-## API Reference
-
-### Organizations
-
-The organizations resource allows you to create and manage organizations in the Bloque platform.
+## Configuration
 
-#### Create an Organization
+### Full Configuration Options
 
 ```typescript
-// Connect to user session first
-const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
-
-// Create organization through the session
-const organization = await userSession.orgs.create(params);
-```
-
-**Parameters**:
+interface BloqueSDKConfig {
+  // Required
+  origin: string; // Your origin identifier
+  auth: AuthStrategy; // Authentication strategy
 
-```typescript
-interface CreateOrgParams {
-  org_type: 'business' | 'individual';  // Organization type
-  profile: OrgProfile;                   // Organization profile details
-  metadata?: Record<string, unknown>;    // Optional custom metadata
+  // Optional
+  platform?: Platform; // Runtime platform (default: 'node')
+  mode?: Mode; // Environment mode (default: 'production')
+  timeout?: number; // Request timeout in ms (default: 30000)
+  tokenStorage?: TokenStorage; // JWT storage (required for react-native)
+  retry?: RetryConfig; // Retry configuration
 }
 
-interface OrgProfile {
-  legal_name: string;                    // Legal name of the organization
-  tax_id: string;                        // Tax ID number
-  incorporation_date: string;            // Date of incorporation (YYYY-MM-DD)
-  business_type: string;                 // Type of business (e.g., 'llc', 'corporation')
-  incorporation_country_code: string;    // Country code (ISO 3166-1 alpha-2)
-  incorporation_state?: string;          // State/province (optional)
-  address_line1: string;                 // Primary address line
-  address_line2?: string;                // Secondary address line (optional)
-  postal_code: string;                   // Postal/ZIP code
-  city: string;                          // City
-  logo_url?: string;                     // Logo URL (optional)
-  places?: Place[];                      // Additional places/locations (optional)
-}
+// Authentication strategies
+type AuthStrategy =
+  | { type: 'apiKey'; apiKey: string } // Backend only
+  | { type: 'jwt' }; // Frontend (browser/react-native)
 
-interface Place {
-  country_code: string;                  // Country code
-  state: string;                         // State/province
-  address_line1: string;                 // Address line 1
-  postal_code: string;                   // Postal code
-  city: string;                          // City
-  is_primary: boolean;                   // Whether this is the primary place
-}
-```
+// Platforms
+type Platform = 'node' | 'bun' | 'deno' | 'browser' | 'react-native';
 
-**Response**:
+// Modes
+type Mode = 'production' | 'sandbox';
 
-```typescript
-interface Organization {
-  urn: string;                           // Unique resource name
-  org_type: 'business' | 'individual';   // Organization type
-  profile: OrgProfile;                   // Organization profile
-  metadata?: Record<string, unknown>;    // Custom metadata
-  status: OrgStatus;                     // Organization status
+// Retry configuration
+interface RetryConfig {
+  enabled?: boolean; // default: true
+  maxRetries?: number; // default: 3
+  initialDelay?: number; // default: 1000ms
+  maxDelay?: number; // default: 30000ms
 }
-
-type OrgStatus =
-  | 'awaiting_compliance_verification'
-  | 'active'
-  | 'suspended'
-  | 'closed';
 ```
 
-### Compliance
-
-The compliance resource provides KYC (Know Your Customer) verification functionality.
+## SDK Structure
 
-#### Start KYC Verification
-
-Start a KYC verification process for a user:
+After connecting to a user session, you have access to these clients:
 
 ```typescript
-// Connect to user session
-const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
+const session = await bloque.connect('did:bloque:your-origin:user-alias');
 
-// Start KYC verification
-const verification = await userSession.compliance.kyc.startVerification({
-  urn: 'did:bloque:your-origin:user-alias',
-});
+// Available clients
+session.accounts    // Account management
+session.identity    // Identity and aliases
+session.compliance  // KYC/KYB verification
+session.orgs        // Organization management
 ```
 
-**Parameters**:
+## Accounts Client
 
-```typescript
-interface KycVerificationParams {
-  /**
-   * URN (Uniform Resource Name) that uniquely identifies the user
-   * within the system. This value is used to associate the KYC
-   * verification process with a specific user.
-   *
-   * @example "did:bloque:origin:..."
-   */
-  urn: string;
-
-  /**
-   * URL where webhook notifications will be sent when the verification
-   * status changes (optional).
-   *
-   * @example "https://api.example.com/webhooks/kyc"
-   */
-  webhookUrl?: string;
-}
-```
+The accounts client provides access to multiple account types:
 
-**Response**:
+### Virtual Cards
 
 ```typescript
-interface KycVerificationResponse {
-  url: string;  // URL where the user should complete the verification
-  status: 'awaiting_compliance_verification' | 'approved' | 'rejected';
-}
-```
+// Create a virtual card
+const card = await session.accounts.card.create({
+  name: 'My Card',
+  webhookUrl: 'https://your-app.com/webhooks/card',
+});
 
-#### Get KYC Verification Status
+// List cards
+const cards = await session.accounts.card.list();
 
-Get the current status of a KYC verification:
+// Check balance
+const balance = await session.accounts.card.balance({
+  urn: card.urn,
+});
 
-```typescript
-const status = await bloque.compliance.kyc.getVerification({
-  urn: 'did:bloque:user:123e4567',
+// Get movements/transactions
+const movements = await session.accounts.card.movements({
+  urn: card.urn,
+  asset: 'DUSD/6',
+  limit: 50,
+  direction: 'in', // 'in' | 'out'
 });
-```
 
-**Parameters**:
+// Update card
+const updated = await session.accounts.card.updateMetadata({
+  urn: card.urn,
+  metadata: { name: 'Updated Name' },
+});
 
-```typescript
-interface GetKycVerificationParams {
-  /**
-   * URN (Uniform Resource Name) that uniquely identifies the user
-   * within the system.
-   *
-   * @example "did:bloque:user:123e4567"
-   */
-  urn: string;
-}
+// Manage card state
+await session.accounts.card.activate(card.urn);
+await session.accounts.card.freeze(card.urn);
+await session.accounts.card.disable(card.urn);
 ```
 
-**Response**:
+### Virtual Accounts
+
+Virtual accounts are simple testing accounts requiring only basic personal information:
 
 ```typescript
-interface KycVerificationStatus {
-  status: 'awaiting_compliance_verification' | 'approved' | 'rejected';
-  url: string;                                  // URL for verification
-  completedAt: string | null;                               // Completion date (ISO 8601)
-}
-```
+// Create a virtual account
+const account = await session.accounts.virtual.create({
+  firstName: 'John',
+  lastName: 'Doe',
+  metadata: {
+    environment: 'testing',
+    purpose: 'integration-test',
+  },
+});
 
-### Accounts
+// Update metadata
+await session.accounts.virtual.updateMetadata({
+  urn: account.urn,
+  metadata: { updated_by: 'admin' },
+});
 
-The accounts resource allows you to create virtual cards for users.
+// Manage account state
+await session.accounts.virtual.activate(account.urn);
+await session.accounts.virtual.freeze(account.urn);
+await session.accounts.virtual.disable(account.urn);
+```
 
-#### Create a Virtual Card
+### Bancolombia Accounts
 
-Create a virtual card for a user:
+Colombian virtual accounts with unique reference code system:
 
 ```typescript
-// Connect to user session
-const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
-
-// Create virtual card
-const card = await userSession.accounts.card.create({
-  urn: 'did:bloque:your-origin:user-alias',
-  name: 'My Virtual Card', // Optional
+// Create a Bancolombia account
+const account = await session.accounts.bancolombia.create({
+  name: 'Main Account',
+  webhookUrl: 'https://your-app.com/webhooks/bancolombia',
 });
-```
 
-**Parameters**:
+console.log('Reference code:', account.referenceCode);
 
-```typescript
-interface CreateCardParams {
-  /**
-   * URN of the account holder (user or organization)
-   * @example "did:bloque:user:123e4567"
-   */
-  urn: string;
-
-  /**
-   * Display name for the card (optional)
-   */
-  name?: string;
-}
-```
+// Update metadata or name
+await session.accounts.bancolombia.updateMetadata({
+  urn: account.urn,
+  metadata: { category: 'savings' },
+});
 
-**Response**:
+await session.accounts.bancolombia.updateName(account.urn, 'Savings Account');
 
-```typescript
-interface CardAccount {
-  urn: string;                    // Unique resource name
-  id: string;                     // Card account ID
-  lastFour: string;               // Last four digits
-  productType: 'CREDIT' | 'DEBIT'; // Card product type
-  status: 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_in_progress' | 'creation_failed';
-  cardType: 'VIRTUAL' | 'PHYSICAL'; // Card type
-  detailsUrl: string;             // PCI-compliant URL to view card details
-  ownerUrn: string;               // Owner URN
-  webhookUrl: string | null;      // Webhook URL (if configured)
-  metadata?: Record<string, unknown>; // Custom metadata
-  createdAt: string;              // Creation timestamp (ISO 8601)
-  updatedAt: string;              // Last update timestamp (ISO 8601)
-}
+// Manage account state
+await session.accounts.bancolombia.activate(account.urn);
+await session.accounts.bancolombia.freeze(account.urn);
+await session.accounts.bancolombia.disable(account.urn);
 ```
 
-### Identity
-
-The identity resource allows you to register identities, retrieve user aliases, and manage authentication origins.
+### Transfers
 
-#### Register Identity
-
-Register a new user or business identity to an authentication origin. Supports individual users (KYC) and businesses (KYB):
+Transfer funds between any account types:
 
 ```typescript
-// Register individual user
-const individual = await bloque.identity.origins.register('ethereum-mainnet', {
-  assertionResult: {
-    alias: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
-    challengeType: 'SIGNING_CHALLENGE',
-    value: {
-      signature: '0x1234567890abcdef...',
-      alias: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
-    }
+const result = await session.accounts.transfer({
+  sourceUrn: 'did:bloque:account:card:usr-123:crd-456',
+  destinationUrn: 'did:bloque:account:virtual:acc-789',
+  amount: '1000000', // Amount in smallest unit
+  asset: 'DUSD/6', // 'DUSD/6' | 'KSM/12'
+  metadata: {
+    description: 'Payment for services',
   },
-  type: 'individual',
-  profile: {
-    firstName: 'John',
-    lastName: 'Doe',
-    email: 'john@example.com'
-  }
 });
 
-// Register business
-const business = await bloque.identity.origins.register('bloque-api', {
-  assertionResult: {
-    alias: 'business-123',
-    challengeType: 'API_KEY',
-    value: {
-      apiKey: 'sk_live_abc123',
-      alias: 'business-123'
-    }
-  },
-  type: 'business',
-  profile: {
-    legalName: 'Acme Corporation',
-    name: 'Acme Corp',
-    taxId: '12-3456789',
-    type: 'LLC',
-    incorporationDate: '2020-01-15',
-    addressLine1: '123 Business St',
-    city: 'New York',
-    state: 'NY',
-    postalCode: '10001',
-    country: 'United States'
-  }
-});
+console.log('Transfer queued:', result.queueId);
+console.log('Status:', result.status); // 'queued' | 'processing' | 'completed' | 'failed'
 ```
 
-**Parameters**:
-
-```typescript
-// Registration parameters (discriminated union by type)
-type RegisterParams = IndividualRegisterParams | BusinessRegisterParams;
-
-interface IndividualRegisterParams {
-  assertionResult: AssertionResult;
-  extraContext?: Record<string, unknown>;
-  type: 'individual';
-  profile: UserProfile;
-}
+## Identity Client
 
-interface BusinessRegisterParams {
-  assertionResult: AssertionResult;
-  extraContext?: Record<string, unknown>;
-  type: 'business';
-  profile: BusinessProfile;
-}
+Manage user identities and authentication:
 
-// Assertion result for challenge verification
-interface AssertionResult {
-  alias: string;                                  // Identity identifier
-  challengeType: 'SIGNING_CHALLENGE' | 'API_KEY' | 'OAUTH_REDIRECT' | 'WEBAUTHN' | 'OTP' | 'PASSWORD';
-  value: {
-    signature?: string;                           // For SIGNING_CHALLENGE
-    apiKey?: string;                              // For API_KEY
-    alias: string;
-  };
-  originalChallengeParams?: {
-    challenge: string;
-    timestamp: number;
-  };
-}
+```typescript
+// Get alias information
+const alias = await session.identity.aliases.get('user@example.com');
 
-// Individual user profile (KYC)
-interface UserProfile {
-  firstName?: string;
-  lastName?: string;
-  birthdate?: string;                             // ISO 8601 (YYYY-MM-DD)
-  email?: string;
-  phone?: string;
-  gender?: string;
-  addressLine1?: string;
-  addressLine2?: string;
-  city?: string;
-  state?: string;
-  postalCode?: string;
-  neighborhood?: string;
-  countryOfBirthCode?: string;
-  countryOfResidenceCode?: string;
-  personalIdType?: string;
-  personalIdNumber?: string;
-}
+// List available origins
+const origins = await session.identity.origins.list();
 
-// Business profile (KYB)
-interface BusinessProfile {
-  // Required fields
-  addressLine1: string;
-  city: string;
-  country: string;
-  incorporationDate: string;
-  legalName: string;
-  name: string;
-  postalCode: string;
-  state: string;
-  taxId: string;
-  type: string;
-
-  // Optional fields
-  addressLine2?: string;
-  countryCode?: string;
-  email?: string;
-  logo?: string;
-  phone?: string;
-
-  // Beneficial owner information
-  ownerName?: string;
-  ownerIdType?: string;
-  ownerIdNumber?: string;
-  ownerAddressLine1?: string;
-  ownerCity?: string;
-  ownerState?: string;
-  ownerPostalCode?: string;
-  ownerCountryCode?: string;
-}
-```
-
-**Response**:
+// Register a new identity (individual)
+const result = await bloque.identity.origins.register(
+  'did:bloque:your-origin:ethereum-mainnet',
+  {
+    assertionResult: {
+      alias: '0x742d35Cc...',
+      challengeType: 'SIGNING_CHALLENGE',
+      value: {
+        signature: '0x...',
+        alias: '0x742d35Cc...',
+      },
+    },
+    type: 'individual',
+    profile: {
+      firstName: 'John',
+      lastName: 'Doe',
+      email: 'john@example.com',
+      birthdate: '1990-01-15',
+      countryOfResidenceCode: 'US',
+    },
+  }
+);
+
+// Register a business
+const businessResult = await bloque.identity.origins.register(
+  'did:bloque:your-origin:ethereum-mainnet',
+  {
+    assertionResult: { /* ... */ },
+    type: 'business',
+    profile: {
+      legalName: 'Acme Corporation',
+      taxId: '123456789',
+      incorporationDate: '2020-01-01',
+      type: 'llc',
+      addressLine1: '123 Main St',
+      city: 'San Francisco',
+      state: 'CA',
+      country: 'US',
+      postalCode: '12345',
+      // ... other required fields
+    },
+  }
+);
 
-```typescript
-interface RegisterResult {
-  accessToken: string;  // JWT access token for authenticated sessions
-}
+// OTP-based authentication
+const otpEmail = await bloque.identity.origins.email.assert('user@example.com');
+const otpWhatsApp = await bloque.identity.origins.whatsapp.assert('+1234567890');
+const otpCustom = await bloque.identity.origins.custom('my-origin').assert('user-id');
 ```
 
-#### Get Alias
+## Compliance Client
 
-Retrieve alias information by the alias value:
+KYC/KYB verification workflows:
 
 ```typescript
-const alias = await bloque.identity.aliases.get('user@example.com');
-```
-
-**Parameters**:
+// Start KYC verification
+const verification = await session.compliance.kyc.startVerification({
+  urn: 'did:bloque:user:123e4567',
+  webhookUrl: 'https://your-app.com/webhooks/kyc',
+});
 
-```typescript
-// Pass the alias string directly
-const alias: string = 'user@example.com' | '+1234567890';
-```
+console.log('Verification URL:', verification.url);
+console.log('Status:', verification.status);
 
-**Response**:
+// Get verification status
+const status = await session.compliance.kyc.getVerification({
+  urn: 'did:bloque:user:123e4567',
+});
 
-```typescript
-interface Alias {
-  id: string;                                  // Unique alias ID
-  alias: string;                               // Alias value
-  type: 'phone' | 'email' | string;           // Alias type
-  urn: string;                                 // Associated user URN
-  origin: string;                              // Origin identifier
-  details: {
-    phone?: string;                            // Phone details (if applicable)
-  };
-  metadata: {
-    alias: string;                             // Alias in metadata
-    [key: string]: unknown;                    // Additional metadata
-  };
-  status: 'active' | 'inactive' | 'revoked';  // Alias status
-  is_public: boolean;                          // Whether alias is public
-  is_primary: boolean;                         // Whether this is the primary alias
-  created_at: string;                          // Creation timestamp (ISO 8601)
-  updated_at: string;                          // Last update timestamp (ISO 8601)
-}
+console.log('Status:', status.status);
+console.log('Completed at:', status.completedAt);
 ```
 
-## Examples
+## Organizations Client
 
-### Creating a Business Organization
+Create and manage organizations:
 
 ```typescript
-import { SDK } from '@bloque/sdk';
-import type { CreateOrgParams } from '@bloque/sdk/orgs';
-
-// Initialize SDK with your API key
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: 'production',
-});
-
-// Create a business organization
-const params: CreateOrgParams = {
+const org = await session.orgs.create({
   org_type: 'business',
   profile: {
     legal_name: 'Acme Corporation',
-    tax_id: '12-3456789',
-    incorporation_date: '2020-01-15',
+    tax_id: '123456789',
+    incorporation_date: '2020-01-01',
     business_type: 'llc',
     incorporation_country_code: 'US',
     incorporation_state: 'CA',
-    address_line1: '123 Market Street',
-    address_line2: 'Suite 400',
-    postal_code: '94103',
+    address_line1: '123 Main St',
+    address_line2: 'Suite 100',
+    postal_code: '12345',
     city: 'San Francisco',
-    logo_url: 'https://example.com/logo.png',
   },
   metadata: {
-    source: 'web_app',
-    campaign: 'q1_2024',
-  },
-};
-
-try {
-  const organization = await bloque.orgs.create(params);
-  console.log('Organization created:', organization.urn);
-  console.log('Status:', organization.status);
-} catch (error) {
-  console.error('Failed to create organization:', error);
-}
-```
-
-### Creating an Individual Organization
-
-```typescript
-import { SDK } from '@bloque/sdk';
-import type { CreateOrgParams } from '@bloque/sdk/orgs';
-
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
+    industry: 'technology',
   },
-  mode: 'sandbox',
 });
 
-const params: CreateOrgParams = {
-  org_type: 'individual',
-  profile: {
-    legal_name: 'John Doe',
-    tax_id: '123-45-6789',
-    incorporation_date: '1990-05-20',
-    business_type: 'sole_proprietorship',
-    incorporation_country_code: 'US',
-    address_line1: '456 Oak Avenue',
-    postal_code: '10001',
-    city: 'New York',
-  },
-};
-
-const organization = await bloque.orgs.create(params);
-console.log('Individual organization created:', organization);
+console.log('Organization created:', org.urn);
+console.log('Status:', org.status);
 ```
 
-### Organization with Multiple Locations
-
-```typescript
-import { SDK } from '@bloque/sdk';
-import type { CreateOrgParams } from '@bloque/sdk/orgs';
-
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: 'production',
-});
-
-const params: CreateOrgParams = {
-  org_type: 'business',
-  profile: {
-    legal_name: 'Global Tech Solutions Inc.',
-    tax_id: '98-7654321',
-    incorporation_date: '2018-03-10',
-    business_type: 'corporation',
-    incorporation_country_code: 'US',
-    incorporation_state: 'DE',
-    address_line1: '789 Corporate Blvd',
-    postal_code: '19801',
-    city: 'Wilmington',
-    places: [
-      {
-        country_code: 'US',
-        state: 'CA',
-        address_line1: '100 Silicon Valley Drive',
-        postal_code: '94025',
-        city: 'Menlo Park',
-        is_primary: true,
-      },
-      {
-        country_code: 'US',
-        state: 'NY',
-        address_line1: '250 Broadway',
-        postal_code: '10007',
-        city: 'New York',
-        is_primary: false,
-      },
-    ],
-  },
-};
-
-const organization = await bloque.orgs.create(params);
-console.log('Multi-location organization created');
-```
+## Error Handling
 
-### Starting KYC Verification
+The SDK provides specific error types for better error handling:
 
 ```typescript
-import { SDK } from '@bloque/sdk';
-import type { KycVerificationParams } from '@bloque/sdk/compliance';
-
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: 'production',
-});
-
-// Start KYC verification for a user
-const params: KycVerificationParams = {
-  urn: 'did:bloque:origin:user-123',
-  webhookUrl: 'https://api.example.com/webhooks/kyc', // Optional webhook URL
-};
+import {
+  BloqueRateLimitError,
+  BloqueAuthenticationError,
+  BloqueValidationError,
+  BloqueNotFoundError,
+  BloqueInsufficientFundsError,
+  BloqueNetworkError,
+  BloqueTimeoutError,
+} from '@bloque/sdk';
 
 try {
-  const verification = await bloque.compliance.kyc.startVerification(params);
-
-  console.log('Verification URL:', verification.url);
-  console.log('Status:', verification.status);
-
-  // Redirect the user to verification.url to complete KYC
-  // Webhook notifications will be sent to the provided webhookUrl
+  const card = await session.accounts.card.create({ name: 'My Card' });
 } catch (error) {
-  console.error('Failed to start KYC verification:', error);
-}
-```
-
-### Getting KYC Verification Status
-
-```typescript
-import { SDK } from '@bloque/sdk';
-import type { GetKycVerificationParams } from '@bloque/sdk/compliance';
-
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: 'production',
-});
-
-// Get verification status
-const params: GetKycVerificationParams = {
-  urn: 'did:bloque:user:123e4567',
-};
-
-try {
-  const status = await bloque.compliance.kyc.getVerification(params);
-
-  console.log('Status:', status.status);
-  console.log('Verification URL:', status.url);
-  console.log('Completed At:', status.completedAt);
-
-  if (status.status === 'approved') {
-    console.log('User verification approved!');
-  } else if (status.status === 'rejected') {
-    console.log('User verification rejected');
-  } else {
-    console.log('Verification still pending');
+  if (error instanceof BloqueRateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
+    console.log(`Request ID: ${error.requestId}`);
+  } else if (error instanceof BloqueValidationError) {
+    console.log('Validation errors:', error.validationErrors);
+  } else if (error instanceof BloqueAuthenticationError) {
+    console.log('Authentication failed. Check your API key.');
+  } else if (error instanceof BloqueNotFoundError) {
+    console.log(`Resource not found: ${error.resourceType}`);
+  } else if (error instanceof BloqueInsufficientFundsError) {
+    console.log(`Insufficient funds: ${error.requestedAmount} ${error.currency}`);
+    console.log(`Available: ${error.availableBalance} ${error.currency}`);
+  } else if (error instanceof BloqueTimeoutError) {
+    console.log(`Request timed out after ${error.timeoutMs}ms`);
+  } else if (error instanceof BloqueNetworkError) {
+    console.log('Network error:', error.message);
   }
-} catch (error) {
-  console.error('Failed to get verification status:', error);
+
+  // All errors have these fields
+  console.log('Error details:', error.toJSON());
 }
 ```
 
-### Creating a Virtual Card
+### Error Metadata
 
-```typescript
-import { SDK } from '@bloque/sdk';
-import type { CreateCardParams } from '@bloque/sdk/accounts';
+All errors include rich metadata for debugging:
 
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: 'production',
-});
+- `message`: Human-readable error message
+- `status`: HTTP status code (if applicable)
+- `code`: Error code from the API
+- `requestId`: Unique request ID for tracing
+- `timestamp`: When the error occurred
+- `response`: Original response body (for debugging)
+- `cause`: Original error (for error chaining)
 
-// Create a virtual card
-const params: CreateCardParams = {
-  urn: 'did:bloque:user:123e4567',
-  name: 'My Business Card', // Optional
-};
+## Retry Logic
 
-try {
-  const card = await bloque.accounts.card.create(params);
-
-  console.log('Card created:', card.urn);
-  console.log('Last four digits:', card.lastFour);
-  console.log('Card type:', card.cardType);
-  console.log('Status:', card.status);
-  console.log('Details URL:', card.detailsUrl);
-
-  // Check if card is ready to use
-  if (card.status === 'active') {
-    console.log('Card is active and ready to use!');
-  } else if (card.status === 'creation_in_progress') {
-    console.log('Card is being created...');
-  }
-} catch (error) {
-  console.error('Failed to create card:', error);
-}
-```
+The SDK automatically retries failed requests with exponential backoff:
 
-### Retrieving User Alias Information
+- **Retried scenarios**: 429 (Rate Limit), 503 (Service Unavailable), network errors, timeouts
+- **Exponential backoff**: Delay increases exponentially (1s → 2s → 4s)
+- **Jitter**: ±25% random jitter to prevent thundering herd
+- **Respects Retry-After**: Honors the `Retry-After` header when present
 
 ```typescript
-import { SDK } from '@bloque/sdk';
-
 const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
+  origin: 'your-origin',
+  auth: { type: 'apiKey', apiKey: 'key' },
+  retry: {
+    enabled: true, // default: true
+    maxRetries: 3, // default: 3
+    initialDelay: 1000, // default: 1000ms
+    maxDelay: 30000, // default: 30000ms
   },
-  mode: 'production',
 });
-
-// Get alias information by email
-try {
-  const alias = await bloque.identity.aliases.get('user@example.com');
-
-  console.log('Alias ID:', alias.id);
-  console.log('Alias type:', alias.type);
-  console.log('Associated URN:', alias.urn);
-  console.log('Status:', alias.status);
-  console.log('Is primary:', alias.is_primary);
-  console.log('Is public:', alias.is_public);
-
-  if (alias.status === 'active') {
-    console.log('Alias is active');
-  }
-} catch (error) {
-  console.error('Failed to retrieve alias:', error);
-}
-
-// Get alias information by phone number
-try {
-  const phoneAlias = await bloque.identity.aliases.get('+1234567890');
-
-  console.log('Phone alias:', phoneAlias.alias);
-  console.log('Phone details:', phoneAlias.details.phone);
-} catch (error) {
-  console.error('Failed to retrieve phone alias:', error);
-}
 ```
 
-### Registering Individual User Identity (KYC)
+## Timeout Configuration
 
-```typescript
-import { SDK } from '@bloque/sdk';
-import type { IndividualRegisterParams } from '@bloque/sdk/identity';
+Configure request timeouts globally or per-request:
 
+```typescript
+// Global timeout
 const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: 'production',
+  origin: 'your-origin',
+  auth: { type: 'apiKey', apiKey: 'key' },
+  timeout: 15000, // 15 seconds
 });
 
-// Register an individual with blockchain signature
-const params: IndividualRegisterParams = {
-  assertionResult: {
-    alias: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
-    challengeType: 'SIGNING_CHALLENGE',
-    value: {
-      signature: '0x1234567890abcdef...',
-      alias: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
-    },
-    originalChallengeParams: {
-      challenge: 'bloque-challenge-1234567890',
-      timestamp: 1640995200
-    }
-  },
-  type: 'individual',
-  profile: {
-    firstName: 'John',
-    lastName: 'Doe',
-    email: 'john.doe@example.com',
-    phone: '+1234567890',
-    birthdate: '1990-01-15',
-    city: 'New York',
-    state: 'NY',
-    postalCode: '10001',
-    addressLine1: '123 Main St',
-    countryOfBirthCode: 'USA',
-    countryOfResidenceCode: 'USA',
-    personalIdType: 'SSN',
-    personalIdNumber: '123-45-6789'
-  }
-};
-
-try {
-  const result = await bloque.identity.origins.register('ethereum-mainnet', params);
-
-  console.log('User registered successfully!');
-  console.log('Access token:', result.accessToken);
-
-  // Store the access token securely for the user's session
-  // Use it for subsequent authenticated API calls
-} catch (error) {
-  console.error('Registration failed:', error);
-}
+// Per-request timeout (override global)
+const card = await session.accounts.card.create(
+  { name: 'My Card' },
+  { timeout: 5000 } // 5 seconds for this request
+);
 ```
 
-### Registering Business Identity (KYB)
+## Security Best Practices
 
-```typescript
-import { SDK } from '@bloque/sdk';
-import type { BusinessRegisterParams } from '@bloque/sdk/identity';
+### API Keys
 
-const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: 'production',
-});
-
-// Register a business with API key authentication
-const params: BusinessRegisterParams = {
-  assertionResult: {
-    alias: 'business-123',
-    challengeType: 'API_KEY',
-    value: {
-      apiKey: 'sk_live_abc123def456',
-      alias: 'business-123'
-    }
-  },
-  type: 'business',
-  profile: {
-    // Required business information
-    legalName: 'Acme Corporation',
-    name: 'Acme Corp',
-    taxId: '12-3456789',
-    type: 'LLC',
-    incorporationDate: '2020-01-15',
-    addressLine1: '123 Business St',
-    city: 'New York',
-    state: 'NY',
-    postalCode: '10001',
-    country: 'United States',
-
-    // Optional business information
-    addressLine2: 'Suite 100',
-    countryCode: 'US',
-    email: 'contact@acme.com',
-    phone: '+1-555-0123',
-    logo: 'https://acme.com/logo.png',
-
-    // Beneficial owner information (for compliance)
-    ownerName: 'Jane Smith',
-    ownerIdType: 'SSN',
-    ownerIdNumber: '123-45-6789',
-    ownerAddressLine1: '456 Owner Ave',
-    ownerCity: 'New York',
-    ownerState: 'NY',
-    ownerPostalCode: '10002',
-    ownerCountryCode: 'US'
-  }
-};
+- ✅ Store API keys in environment variables
+- ✅ Use different keys for development and production
+- ✅ Never commit API keys to version control
+- ✅ Rotate API keys regularly
+- ❌ Never expose API keys in client-side code
 
-try {
-  const result = await bloque.identity.origins.register('bloque-api', params);
-
-  console.log('Business registered successfully!');
-  console.log('Access token:', result.accessToken);
-
-  // Use the access token for authenticated API calls
-} catch (error) {
-  console.error('Business registration failed:', error);
-}
-```
+### Token Storage (Frontend)
 
-### Using in an API Endpoint
+The SDK warns when using insecure storage:
 
 ```typescript
-import { SDK } from '@bloque/sdk';
-import type { CreateOrgParams } from '@bloque/sdk/orgs';
-
+// Browser: localStorage (⚠️ vulnerable to XSS)
 const bloque = new SDK({
-  auth: {
-    type: 'apiKey',
-    apiKey: process.env.BLOQUE_API_KEY!,
-  },
-  mode: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
+  auth: { type: 'jwt' },
+  platform: 'browser',
+  // Uses localStorage by default with security warning
 });
 
-app.post('/api/organizations', async (req, res) => {
-  try {
-    const params: CreateOrgParams = req.body;
-
-    const organization = await bloque.orgs.create(params);
-
-    res.json({
-      success: true,
-      organization,
-    });
-  } catch (error) {
-    console.error('Organization creation failed:', error);
-    res.status(500).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Unknown error',
+// Recommended: httpOnly cookies (immune to XSS)
+const cookieStorage: TokenStorage = {
+  get: () => null, // Token sent automatically in cookie
+  set: async (token) => {
+    await fetch('/api/auth/set-token', {
+      method: 'POST',
+      body: JSON.stringify({ token }),
     });
-  }
-});
-```
-
-
-## Error Handling
-
-The SDK uses standard JavaScript errors. Always wrap API calls in try-catch blocks:
-
-```typescript
-import { SDK } from '@bloque/sdk';
+  },
+  clear: async () => {
+    await fetch('/api/auth/logout', { method: 'POST' });
+  },
+};
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
-  mode: 'production',
+  auth: { type: 'jwt' },
+  platform: 'browser',
+  tokenStorage: cookieStorage,
 });
-
-try {
-  const organization = await bloque.orgs.create({
-    org_type: 'business',
-    profile: {
-      legal_name: 'Acme Corp',
-      tax_id: '123456789',
-      incorporation_date: '2020-01-01',
-      business_type: 'llc',
-      incorporation_country_code: 'US',
-      address_line1: '123 Main St',
-      postal_code: '12345',
-      city: 'San Francisco',
-    },
-  });
-  console.log('Success:', organization);
-} catch (error) {
-  if (error instanceof Error) {
-    console.error('Failed to create organization:', error.message);
-  } else {
-    console.error('Unknown error:', error);
-  }
-}
 ```
 
 ## TypeScript Support
 
-This SDK is written in TypeScript and includes complete type definitions. You'll get full autocomplete and type checking when using TypeScript or modern editors like VS Code:
+The SDK is built with TypeScript and provides full type safety:
 
 ```typescript
-import { SDK } from '@bloque/sdk';
 import type {
-  BloqueConfig,
-  CreateOrgParams,
-  Organization,
-  OrgProfile,
-  OrgStatus,
-  OrgType,
-  Place,
-} from '@bloque/sdk/orgs';
+  BloqueSDKConfig,
+  CardAccount,
+  CreateCardParams,
+  VirtualAccount,
+  CreateVirtualAccountParams,
+  TransferParams,
+  TransferResult,
+} from '@bloque/sdk';
 
 // Type-safe configuration
-const config: BloqueConfig = {
-  apiKey: 'your-api-key',
-  mode: 'sandbox',
-};
-
-const bloque = new SDK(config);
-
-// Type-safe organization profile
-const profile: OrgProfile = {
-  legal_name: 'Tech Startup Inc.',
-  tax_id: '12-3456789',
-  incorporation_date: '2023-01-15',
-  business_type: 'llc',
-  incorporation_country_code: 'US',
-  incorporation_state: 'CA',
-  address_line1: '456 Innovation Dr',
-  postal_code: '94025',
-  city: 'Menlo Park',
+const config: BloqueSDKConfig = {
+  origin: 'your-origin',
+  auth: { type: 'apiKey', apiKey: 'key' },
+  mode: 'production',
 };
 
-// Type-safe organization creation
-const params: CreateOrgParams = {
-  org_type: 'business',
-  profile,
-  metadata: {
-    vertical: 'fintech',
-    employees: 50,
-  },
+// Type-safe parameters
+const params: CreateCardParams = {
+  name: 'My Card',
 };
 
-// TypeScript infers the return type as Organization
-const org = await bloque.orgs.create(params);
+// Type-safe responses
+const card: CardAccount = await session.accounts.card.create(params);
 ```
 
-**Available Types**:
+## Package Exports
 
-The SDK exports all necessary types for type-safe development:
+The SDK supports modular imports:
 
 ```typescript
-// Main SDK types
-import type { SDK, BloqueConfig } from '@bloque/sdk';
+// Main SDK
+import { SDK } from '@bloque/sdk';
 
-// Organization types
-import type {
-  Organization,
-  CreateOrgParams,
-  CreateOrgResponse,
-  OrgProfile,
-  OrgType,
-  OrgStatus,
-  Place,
-} from '@bloque/sdk/orgs';
-
-// Compliance types
-import type {
-  KycVerificationParams,
-  KycVerificationResponse,
-  GetKycVerificationParams,
-  KycVerificationStatus,
-} from '@bloque/sdk/compliance';
+// Initialization helper
+import { init } from '@bloque/sdk/init';
 
-// Accounts types
-import type {
-  CardAccount,
-  CreateCardParams,
-} from '@bloque/sdk/accounts';
+// Modular clients (tree-shakeable)
+import { AccountsClient } from '@bloque/sdk/accounts';
+import { IdentityClient } from '@bloque/sdk/identity';
+import { ComplianceClient } from '@bloque/sdk/compliance';
+import { OrgsClient } from '@bloque/sdk/orgs';
 
-// Identity types
+// Types
 import type {
-  Alias,
-  RegisterParams,
-  IndividualRegisterParams,
-  BusinessRegisterParams,
-  RegisterResult,
-  UserProfile,
-  BusinessProfile,
-  AssertionResult,
-} from '@bloque/sdk/identity';
+  BloqueSDKConfig,
+  CardAccount,
+  VirtualAccount,
+  BancolombiaAccount,
+} from '@bloque/sdk';
 ```
 
-## Development
+## Advanced Usage
 
-### Building the SDK
+### Custom HTTP Client
 
-```bash
-bun install
-bun run build
-```
+For advanced use cases, access the HTTP client directly:
 
-### Development Mode (Watch)
-
-```bash
-bun run dev
-```
+```typescript
+const session = await bloque.connect('did:bloque:your-origin:user-alias');
 
-### Type Checking
+// Access the HTTP client
+const httpClient = session.accounts.card['httpClient'];
 
-```bash
-bun run typecheck
+// Make custom requests
+const response = await httpClient.request({
+  method: 'GET',
+  path: '/api/custom-endpoint',
+  timeout: 10000,
+});
 ```
 
-### Code Quality
+### Environment-Specific Configuration
 
-```bash
-bun run check
+```typescript
+const config: BloqueSDKConfig = {
+  origin: process.env.BLOQUE_ORIGIN!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
+  mode: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
+  platform: 'node',
+  timeout: Number.parseInt(process.env.BLOQUE_TIMEOUT || '30000', 10),
+  retry: {
+    enabled: process.env.BLOQUE_RETRY_ENABLED !== 'false',
+    maxRetries: Number.parseInt(process.env.BLOQUE_MAX_RETRIES || '3', 10),
+  },
+};
+
+const bloque = new SDK(config);
 ```
 
-## Requirements
+## Examples
 
-- One of the supported runtimes: Node.js 22.x+, Bun 1.x+, Deno, or modern browsers
-- TypeScript 5.x or higher (for TypeScript projects, optional)
+See the [`examples/`](./examples) directory for complete working examples:
 
-## Links
+- `basic-usage.ts` - Basic SDK usage
+- `virtual-cards.ts` - Virtual card management
+- `virtual-accounts.ts` - Virtual account management
+- `transfers.ts` - Account transfers
+- `identity-registration.ts` - User registration
+- `kyc-verification.ts` - KYC workflows
+- `error-handling.ts` - Advanced error handling
 
-- [Homepage](https://www.bloque.app)
-- [GitHub Repository](https://github.com/bloque-app/sdk)
-- [Issue Tracker](https://github.com/bloque-app/sdk/issues)
+## API Documentation
 
-## Package Structure
+For detailed API documentation, visit [docs.bloque.app/sdk](https://docs.bloque.app/sdk).
 
-This monorepo contains the following packages:
+## Support
 
-- **`@bloque/sdk`**: Main SDK package
-- **`@bloque/sdk-core`**: Core utilities and HTTP client
-- **`@bloque/sdk-orgs`**: Organizations API client
-- **`@bloque/sdk-compliance`**: Compliance and KYC verification API client
-- **`@bloque/sdk-accounts`**: Accounts and virtual cards API client
-- **`@bloque/sdk-identity`**: Identity and aliases API client
+- 📧 Email: [support@bloque.app](mailto:support@bloque.app)
+- 💬 Discord: [discord.gg/bloque](https://discord.gg/bloque)
+- 📖 Docs: [docs.bloque.app](https://docs.bloque.app)
+- 🐛 Issues: [GitHub Issues](https://github.com/bloque/sdk/issues)
 
 ## License
 
-[MIT](../../LICENSE)
-
+MIT © [Bloque](https://www.bloque.app)