@bloque/sdk 0.0.20 → 0.0.21

package/README.md

@@ -30,6 +30,7 @@ This SDK is compatible with multiple JavaScript runtimes:
 
 - **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
 - **Fully Async**: Promise-based API for modern JavaScript workflows
 - **Lightweight**: Minimal dependencies for optimal bundle size
 - **Modular**: Import only what you need with tree-shakeable exports
@@ -42,14 +43,20 @@ bun add @bloque/sdk
 
 ## Quick Start
 
+### Backend (Node.js, Bun, Deno)
+
 ```typescript
 import { SDK } from '@bloque/sdk';
 import type { CreateOrgParams } from '@bloque/sdk/orgs';
 
-// Initialize the SDK (server-side only)
+// Initialize the SDK with API key (backend only)
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'production', // or 'sandbox' for testing
+  platform: 'node', // optional: 'node' | 'bun' | 'deno'
 });
 
 // Create an organization
@@ -88,26 +95,115 @@ async function createCard() {
 }
 ```
 
+### Frontend (Browser, React Native)
+
+```typescript
+import { SDK } from '@bloque/sdk';
+
+// Initialize the SDK with JWT authentication
+const bloque = new SDK({
+  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';
-import type { BloqueConfig } from '@bloque/sdk';
 
 const bloque = new SDK({
-  apiKey: 'your-api-key-here',    // Required: Your Bloque API key
-  mode: 'sandbox',                 // Required: 'sandbox' or 'production'
+  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',
+  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
 
-- **`apiKey`** (string, required): Your Bloque API key
-- **`mode`** ('sandbox' | 'production', required): Environment mode
+- **`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
+  - `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()`
+
+### 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
 
@@ -306,7 +402,152 @@ interface CardAccount {
 
 ### Identity
 
-The identity resource allows you to retrieve user aliases (alternative identifiers like email or phone).
+The identity resource allows you to register identities, retrieve user aliases, and manage authentication origins.
+
+#### Register Identity
+
+Register a new user or business identity to an authentication origin. Supports individual users (KYC) and businesses (KYB):
+
+```typescript
+// Register individual user
+const individual = await bloque.identity.origins.register('ethereum-mainnet', {
+  assertionResult: {
+    alias: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+    challengeType: 'SIGNING_CHALLENGE',
+    value: {
+      signature: '0x1234567890abcdef...',
+      alias: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
+    }
+  },
+  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'
+  }
+});
+```
+
+**Parameters**:
+
+```typescript
+// Registration parameters (discriminated union by type)
+type RegisterParams = IndividualRegisterParams | BusinessRegisterParams;
+
+interface IndividualRegisterParams {
+  assertionResult: AssertionResult;
+  extraContext?: Record<string, unknown>;
+  type: 'individual';
+  profile: UserProfile;
+}
+
+interface BusinessRegisterParams {
+  assertionResult: AssertionResult;
+  extraContext?: Record<string, unknown>;
+  type: 'business';
+  profile: BusinessProfile;
+}
+
+// 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;
+  };
+}
+
+// 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;
+}
+
+// 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**:
+
+```typescript
+interface RegisterResult {
+  accessToken: string;  // JWT access token for authenticated sessions
+}
+```
 
 #### Get Alias
 
@@ -357,7 +598,10 @@ import type { CreateOrgParams } from '@bloque/sdk/orgs';
 
 // Initialize SDK with your API key
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'production',
 });
 
@@ -399,7 +643,10 @@ import { SDK } from '@bloque/sdk';
 import type { CreateOrgParams } from '@bloque/sdk/orgs';
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'sandbox',
 });
 
@@ -428,7 +675,10 @@ import { SDK } from '@bloque/sdk';
 import type { CreateOrgParams } from '@bloque/sdk/orgs';
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'production',
 });
 
@@ -476,7 +726,10 @@ import { SDK } from '@bloque/sdk';
 import type { KycVerificationParams } from '@bloque/sdk/compliance';
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'production',
 });
 
@@ -506,7 +759,10 @@ import { SDK } from '@bloque/sdk';
 import type { GetKycVerificationParams } from '@bloque/sdk/compliance';
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'production',
 });
 
@@ -541,7 +797,10 @@ import { SDK } from '@bloque/sdk';
 import type { CreateCardParams } from '@bloque/sdk/accounts';
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'production',
 });
 
@@ -577,7 +836,10 @@ try {
 import { SDK } from '@bloque/sdk';
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: 'production',
 });
 
@@ -610,6 +872,134 @@ try {
 }
 ```
 
+### Registering Individual User Identity (KYC)
+
+```typescript
+import { SDK } from '@bloque/sdk';
+import type { IndividualRegisterParams } from '@bloque/sdk/identity';
+
+const bloque = new SDK({
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
+  mode: 'production',
+});
+
+// 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);
+}
+```
+
+### Registering Business Identity (KYB)
+
+```typescript
+import { SDK } from '@bloque/sdk';
+import type { BusinessRegisterParams } from '@bloque/sdk/identity';
+
+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'
+  }
+};
+
+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);
+}
+```
+
 ### Using in an API Endpoint
 
 ```typescript
@@ -617,7 +1007,10 @@ import { SDK } from '@bloque/sdk';
 import type { CreateOrgParams } from '@bloque/sdk/orgs';
 
 const bloque = new SDK({
-  apiKey: process.env.BLOQUE_API_KEY!,
+  auth: {
+    type: 'apiKey',
+    apiKey: process.env.BLOQUE_API_KEY!,
+  },
   mode: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
 });
 
@@ -765,6 +1158,13 @@ import type {
 // Identity types
 import type {
   Alias,
+  RegisterParams,
+  IndividualRegisterParams,
+  BusinessRegisterParams,
+  RegisterResult,
+  UserProfile,
+  BusinessProfile,
+  AssertionResult,
 } from '@bloque/sdk/identity';
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloque/sdk",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "Official Bloque SDK",
   "type": "module",
   "keywords": [
@@ -63,10 +63,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@bloque/sdk-accounts": "0.0.20",
-    "@bloque/sdk-compliance": "0.0.20",
-    "@bloque/sdk-core": "0.0.20",
-    "@bloque/sdk-identity": "0.0.20",
-    "@bloque/sdk-orgs": "0.0.20"
+    "@bloque/sdk-accounts": "0.0.21",
+    "@bloque/sdk-compliance": "0.0.21",
+    "@bloque/sdk-core": "0.0.21",
+    "@bloque/sdk-identity": "0.0.21",
+    "@bloque/sdk-orgs": "0.0.21"
   }
 }