@bloque/sdk 0.0.21 → 0.0.22

package/README.md

@@ -31,10 +31,13 @@ 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
+- **User Sessions**: Secure user session management with `connect()` for authenticated operations
 - **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
 
+> **📌 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.
+
 ## Installation
 
 ```bash
@@ -51,6 +54,7 @@ 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
   auth: {
     type: 'apiKey',
     apiKey: process.env.BLOQUE_API_KEY!,
@@ -59,7 +63,22 @@ const bloque = new SDK({
   platform: 'node', // optional: 'node' | 'bun' | 'deno'
 });
 
-// Create an organization
+// 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);
+}
+
+// Create an organization (direct SDK access, no connect needed)
 async function createOrganization() {
   const params: CreateOrgParams = {
     org_type: 'business',
@@ -79,20 +98,10 @@ async function createOrganization() {
     },
   };
 
-  const organization = await bloque.orgs.create(params);
+  const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
+  const organization = await userSession.orgs.create(params);
   console.log('Organization created:', organization);
 }
-
-// Create a virtual card
-async function createCard() {
-  const card = await bloque.accounts.card.create({
-    urn: 'did:bloque:user:123e4567',
-    name: 'My Virtual Card',
-  });
-
-  console.log('Card created:', card.urn);
-  console.log('Last four digits:', card.lastFour);
-}
 ```
 
 ### Frontend (Browser, React Native)
@@ -175,6 +184,10 @@ const bloque = new SDK({
 
 ### 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
@@ -195,6 +208,42 @@ const bloque = new SDK({
   - 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!,
+  },
+  mode: 'production',
+});
+
+// Connect to user session
+const userSession = await bloque.connect('did:bloque:your-origin:user-alias');
+
+// Now perform operations through the session
+const card = await userSession.accounts.card.create({
+  urn: 'did:bloque:your-origin:user-alias',
+  name: 'My Card',
+});
+```
+
+**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 |
@@ -214,7 +263,11 @@ The organizations resource allows you to create and manage organizations in the
 #### Create an Organization
 
 ```typescript
-const organization = await bloque.orgs.create(params);
+// 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**:
@@ -278,8 +331,12 @@ The compliance resource provides KYC (Know Your Customer) verification functiona
 Start a KYC verification process for a user:
 
 ```typescript
-const verification = await bloque.compliance.kyc.startVerification({
-  urn: 'did:bloque:origin:user-id',
+// Connect to user session
+const userSession = 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',
 });
 ```
 
@@ -358,8 +415,12 @@ The accounts resource allows you to create virtual cards for users.
 Create a virtual card for a user:
 
 ```typescript
-const card = await bloque.accounts.card.create({
-  urn: 'did:bloque:user:123e4567',
+// 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
 });
 ```

package/dist/bloque.d.ts

@@ -5,9 +5,12 @@ import { IdentityClient } from '@bloque/sdk-identity';
 import { OrgsClient } from '@bloque/sdk-orgs';
 export declare class SDK {
     private readonly httpClient;
-    readonly accounts: AccountsClient;
-    readonly compliance: ComplianceClient;
-    readonly identity: IdentityClient;
-    readonly orgs: OrgsClient;
     constructor(config: BloqueConfig);
+    private extractUserAlias;
+    connect(urn: string): Promise<{
+        accounts: AccountsClient;
+        compliance: ComplianceClient;
+        identity: IdentityClient;
+        orgs: OrgsClient;
+    }>;
 }

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,_)=>{for(var t in _)__webpack_require__.o(_,t)&&!__webpack_require__.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:_[t]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__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__,{SDK:()=>SDK});const sdk_accounts_namespaceObject=require("@bloque/sdk-accounts"),sdk_compliance_namespaceObject=require("@bloque/sdk-compliance"),sdk_core_namespaceObject=require("@bloque/sdk-core"),sdk_identity_namespaceObject=require("@bloque/sdk-identity"),sdk_orgs_namespaceObject=require("@bloque/sdk-orgs");class SDK{httpClient;accounts;compliance;identity;orgs;constructor(e){this.httpClient=new sdk_core_namespaceObject.HttpClient(e),this.accounts=new sdk_accounts_namespaceObject.AccountsClient(this.httpClient),this.compliance=new sdk_compliance_namespaceObject.ComplianceClient(this.httpClient),this.identity=new sdk_identity_namespaceObject.IdentityClient(this.httpClient),this.orgs=new sdk_orgs_namespaceObject.OrgsClient(this.httpClient)}}for(var __rspack_i in exports.SDK=__webpack_exports__.SDK,__webpack_exports__)-1===["SDK"].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,t)=>{for(var _ in t)__webpack_require__.o(t,_)&&!__webpack_require__.o(e,_)&&Object.defineProperty(e,_,{enumerable:!0,get:t[_]})},__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__,{SDK:()=>SDK});const sdk_accounts_namespaceObject=require("@bloque/sdk-accounts"),sdk_compliance_namespaceObject=require("@bloque/sdk-compliance"),sdk_core_namespaceObject=require("@bloque/sdk-core"),sdk_identity_namespaceObject=require("@bloque/sdk-identity"),sdk_orgs_namespaceObject=require("@bloque/sdk-orgs");class SDK{httpClient;constructor(e){this.httpClient=new sdk_core_namespaceObject.HttpClient(e)}extractUserAlias(e){let t=e.match(/^did:bloque:[^:]+:([^:]+)$/);if(!t)throw Error(`Invalid user alias URN: ${e}`);return t[1]}async connect(e){let t=this.httpClient.config,_=await this.httpClient.request({path:`/api/origins/${t.origin}/connect`,method:"POST",body:{assertion_result:{challengeType:"API_KEY",value:{api_key:"apiKey"===t.auth.type?t.auth.apiKey:"",alias:this.extractUserAlias(e)}},extra_context:{}}});return this.httpClient.config.accessToken=_.result.access_token,{accounts:new sdk_accounts_namespaceObject.AccountsClient(this.httpClient),compliance:new sdk_compliance_namespaceObject.ComplianceClient(this.httpClient),identity:new sdk_identity_namespaceObject.IdentityClient(this.httpClient),orgs:new sdk_orgs_namespaceObject.OrgsClient(this.httpClient)}}}for(var __rspack_i in exports.SDK=__webpack_exports__.SDK,__webpack_exports__)-1===["SDK"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/index.js

@@ -1 +1 @@
-import{AccountsClient as t}from"@bloque/sdk-accounts";import{ComplianceClient as i}from"@bloque/sdk-compliance";import{HttpClient as o}from"@bloque/sdk-core";import{IdentityClient as e}from"@bloque/sdk-identity";import{OrgsClient as s}from"@bloque/sdk-orgs";class n{httpClient;accounts;compliance;identity;orgs;constructor(n){this.httpClient=new o(n),this.accounts=new t(this.httpClient),this.compliance=new i(this.httpClient),this.identity=new e(this.httpClient),this.orgs=new s(this.httpClient)}}export{n as SDK};
+import{AccountsClient as t}from"@bloque/sdk-accounts";import{ComplianceClient as e}from"@bloque/sdk-compliance";import{HttpClient as i}from"@bloque/sdk-core";import{IdentityClient as o}from"@bloque/sdk-identity";import{OrgsClient as s}from"@bloque/sdk-orgs";class n{httpClient;constructor(t){this.httpClient=new i(t)}extractUserAlias(t){let e=t.match(/^did:bloque:[^:]+:([^:]+)$/);if(!e)throw Error(`Invalid user alias URN: ${t}`);return e[1]}async connect(i){let n=this.httpClient.config,r=await this.httpClient.request({path:`/api/origins/${n.origin}/connect`,method:"POST",body:{assertion_result:{challengeType:"API_KEY",value:{api_key:"apiKey"===n.auth.type?n.auth.apiKey:"",alias:this.extractUserAlias(i)}},extra_context:{}}});return this.httpClient.config.accessToken=r.result.access_token,{accounts:new t(this.httpClient),compliance:new e(this.httpClient),identity:new o(this.httpClient),orgs:new s(this.httpClient)}}}export{n as SDK};

package/package.json

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