@bloque/sdk-accounts 0.0.3

package/README.md

@@ -0,0 +1,253 @@
+# @bloque/sdk-accounts
+
+Financial accounts and payment methods client for the [Bloque](https://www.bloque.app) platform.
+
+## Features
+
+- **Virtual Cards**: Create virtual cards instantly
+- **TypeScript First**: Built with TypeScript for complete type safety
+- **Simple API**: Minimal input required - just URN and optional name
+- **Fully Async**: Promise-based API for modern JavaScript workflows
+- **Secure**: PCI-compliant card details URL
+
+## Installation
+
+This package is included in the main `@bloque/sdk` package. You typically don't need to install it separately.
+
+```bash
+bun add @bloque/sdk
+```
+
+If you need to use this package standalone:
+
+```bash
+bun add @bloque/sdk-accounts @bloque/sdk-core
+```
+
+## Usage
+
+### With the Main SDK (Recommended)
+
+```typescript
+import { SDK } from '@bloque/sdk';
+
+const bloque = new SDK({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  mode: 'production',
+});
+
+// Create a virtual card
+const card = await bloque.accounts.card.create({
+  urn: 'did:bloque:user:123',
+  name: 'My Virtual Card', // Optional
+});
+
+console.log('Card created:', card.urn);
+console.log('Last four digits:', card.lastFour);
+console.log('Card details URL:', card.detailsUrl);
+console.log('Status:', card.status);
+```
+
+## API Reference
+
+### Card Accounts
+
+Create virtual cards instantly.
+
+#### `card.create(params)`
+
+```typescript
+const card = await bloque.accounts.card.create({
+  urn: 'did:bloque:user:123',
+  name: 'My Virtual Card', // Optional
+});
+```
+
+**Parameters**:
+
+```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;
+}
+```
+
+**Returns**:
+
+```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)
+}
+```
+
+## Complete Examples
+
+### Basic Card Creation
+
+```typescript
+import { SDK } from '@bloque/sdk';
+
+const bloque = new SDK({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  mode: 'production',
+});
+
+// Create a virtual card with just URN
+const card = await bloque.accounts.card.create({
+  urn: 'did:bloque:user:123e4567',
+});
+
+console.log('Card created:', card.urn);
+console.log('Last four:', card.lastFour);
+console.log('Status:', card.status);
+```
+
+### Card Creation with Name
+
+```typescript
+import { SDK } from '@bloque/sdk';
+
+const bloque = new SDK({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  mode: 'production',
+});
+
+// Create a named virtual card
+const card = await bloque.accounts.card.create({
+  urn: 'did:bloque:user:123e4567',
+  name: 'My Business Card',
+});
+
+console.log('Card name:', card.metadata?.name);
+console.log('Card details URL:', card.detailsUrl);
+```
+
+### Creating Multiple Cards
+
+```typescript
+import { SDK } from '@bloque/sdk';
+
+const bloque = new SDK({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  mode: 'production',
+});
+
+const userUrn = 'did:bloque:user:123e4567';
+
+// Create multiple cards for the same user
+const personalCard = await bloque.accounts.card.create({
+  urn: userUrn,
+  name: 'Personal Card',
+});
+
+const businessCard = await bloque.accounts.card.create({
+  urn: userUrn,
+  name: 'Business Card',
+});
+
+console.log('Personal card:', personalCard.lastFour);
+console.log('Business card:', businessCard.lastFour);
+```
+
+### Error Handling
+
+```typescript
+import { SDK } from '@bloque/sdk';
+
+const bloque = new SDK({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  mode: 'production',
+});
+
+try {
+  const card = await bloque.accounts.card.create({
+    urn: 'did:bloque:user:123e4567',
+    name: 'My Card',
+  });
+
+  console.log('Card created successfully:', card.urn);
+
+  // 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) {
+  if (error instanceof Error) {
+    console.error('Failed to create card:', error.message);
+  }
+}
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and includes complete type definitions:
+
+```typescript
+import type {
+  CardAccount,
+  CreateCardParams,
+} from '@bloque/sdk-accounts';
+
+// Type-safe card creation
+const params: CreateCardParams = {
+  urn: 'did:bloque:user:123e4567',
+  name: 'My Card', // Optional
+};
+
+const card: CardAccount = await bloque.accounts.card.create(params);
+
+// TypeScript infers all card properties with full type safety
+console.log(card.lastFour); // string
+console.log(card.status);   // 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_in_progress' | 'creation_failed'
+console.log(card.cardType); // 'VIRTUAL' | 'PHYSICAL'
+```
+
+## Card Status
+
+Cards have a status field indicating their current state:
+
+- `creation_in_progress`: Card is being created
+- `creation_failed`: Card creation failed
+- `active`: Card is active and ready to use
+- `disabled`: Card has been disabled
+- `frozen`: Card has been temporarily frozen
+- `deleted`: Card has been deleted
+
+## Requirements
+
+- Node.js 22.x or higher / Bun 1.x or higher
+- TypeScript 5.x or higher (for TypeScript projects)
+
+## Links
+
+- [Homepage](https://www.bloque.app)
+- [Main SDK Documentation](../sdk/README.md)
+- [GitHub Repository](https://github.com/bloque-app/sdk)
+- [Issue Tracker](https://github.com/bloque-app/sdk/issues)
+
+## License
+
+[MIT](../../LICENSE)
+
+Copyright (c) 2025-present Bloque Copilot Inc.

package/dist/api-types.d.ts

@@ -0,0 +1,51 @@
+interface Account<TDetails = unknown> {
+    id: string;
+    urn: string;
+    medium: 'bancolombia' | 'card';
+    details: TDetails;
+    status: 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_in_progress' | 'creation_failed';
+    owner_urn: string;
+    created_at: string;
+    updated_at: string;
+    webhook_url: string | null;
+    metadata?: Record<string, unknown>;
+}
+export type CardType = 'VIRTUAL' | 'PHYSICAL';
+export interface CreateAccountRequest<TInput = unknown> {
+    holder_urn: string;
+    input: TInput;
+    metadata?: Record<string, unknown>;
+    webhook_url?: string;
+}
+export type CreateCardAccountInput = {
+    create: {
+        card_type: CardType;
+    };
+};
+export interface CreateAccountResponse<TDetails = unknown> {
+    result: {
+        account: Account<TDetails>;
+    };
+    req_id: string;
+}
+export type CardDetails = {
+    id: string;
+    email: string;
+    operational_country: 'COL';
+    client_id: string;
+    card_id: string;
+    card_last_four: string;
+    card_provider: 'VISA';
+    card_product_type: 'CREDIT';
+    card_status: 'ACTIVE';
+    card_url_details: string;
+    card_type: CardType;
+    user_id: string;
+};
+export type BancolombiaDetails = {
+    id: string;
+    reference_code: string;
+    payment_agreement_code: string;
+    network: string[];
+};
+export {};

package/dist/bancolombia/client.d.ts

@@ -0,0 +1,21 @@
+import type { HttpClient } from '@bloque/sdk-core';
+import type { BancolombiaAccount, CreateBancolombiaAccountParams } from './types';
+export declare class BancolombiaClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a new Bancolombia account
+     *
+     * @param params - Bancolombia account creation parameters
+     * @returns Promise resolving to the created Bancolombia account
+     *
+     * @example
+     * ```typescript
+     * const account = await bloque.accounts.bancolombia.create({
+     *   urn: 'did:bloque:user:123',
+     *   name: 'Main Account'
+     * });
+     * ```
+     */
+    create(params: CreateBancolombiaAccountParams): Promise<BancolombiaAccount>;
+}

package/dist/bancolombia/types.d.ts

@@ -0,0 +1,63 @@
+export interface CreateBancolombiaAccountParams {
+    /**
+     * URN of the account holder (user or organization)
+     *
+     * @example "did:bloque:user:123e4567"
+     */
+    urn: string;
+    /**
+     * Display name for the card
+     */
+    name?: string;
+    /**
+     * URN of an existing card to link with the Bancolombia account
+     *
+     * @example "did:bloque:card:123e4567"
+     */
+    cardUrn?: string;
+    /**
+     * Custom metadata to attach to the Bancolombia account
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Bancolombia account response
+ */
+export interface BancolombiaAccount {
+    /**
+     * Unique resource name for the Bancolombia account
+     */
+    urn: string;
+    /**
+     * Account ID
+     */
+    id: string;
+    /**
+     * Reference code for the Bancolombia account
+     */
+    referenceCode: string;
+    /**
+     * Account status
+     */
+    status: 'creation_in_progress' | 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_failed';
+    /**
+     * Owner URN
+     */
+    ownerUrn: string;
+    /**
+     * Webhook URL (if configured)
+     */
+    webhookUrl: string | null;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Creation timestamp
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: string;
+}

package/dist/card/client.d.ts

@@ -0,0 +1,21 @@
+import type { HttpClient } from '@bloque/sdk-core';
+import type { CardAccount, CreateCardParams } from './types';
+export declare class CardClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a new card account
+     *
+     * @param params - Card creation parameters
+     * @returns Promise resolving to the created card account
+     *
+     * @example
+     * ```typescript
+     * const card = await bloque.accounts.card.create({
+     *   urn: 'did:bloque:user:123',
+     *   name: 'My Card',
+     * });
+     * ```
+     */
+    create(params: CreateCardParams): Promise<CardAccount>;
+}

package/dist/card/types.d.ts

@@ -0,0 +1,67 @@
+import type { CardType } from '../api-types';
+export interface CreateCardParams {
+    /**
+     * URN of the account holder (user or organization)
+     *
+     * @example "did:bloque:user:123e4567"
+     */
+    urn: string;
+    /**
+     * Display name for the card
+     */
+    name?: string;
+    /**
+     * Custom metadata to associate with the card
+     */
+    metadata?: Record<string, unknown>;
+}
+export interface CardAccount {
+    /**
+     * Unique resource name for the card account
+     */
+    urn: string;
+    /**
+     * Card account ID
+     */
+    id: string;
+    /**
+     * Last four digits of the card
+     */
+    lastFour: string;
+    /**
+     * Type of card product (CREDIT, DEBIT)
+     */
+    productType: 'CREDIT' | 'DEBIT';
+    /**
+     * Current status of the card
+     */
+    status: 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_in_progress' | 'creation_failed';
+    /**
+     * Type of card (VIRTUAL, PHYSICAL)
+     */
+    cardType: CardType;
+    /**
+     * URL to view card details (PCI-compliant)
+     */
+    detailsUrl: string;
+    /**
+     * Owner URN
+     */
+    ownerUrn: string;
+    /**
+     * Webhook URL (if configured)
+     */
+    webhookUrl: string | null;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Creation timestamp
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: string;
+}

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import type { HttpClient } from '@bloque/sdk-core';
+import { BancolombiaClient } from './bancolombia/client';
+import { CardClient } from './card/client';
+/**
+ * Accounts client for managing financial accounts and payment methods
+ *
+ * Provides access to various account types through specialized sub-clients:
+ * - card: Credit/debit cards
+ * - virtual: Virtual accounts
+ * - bancolombia: Bancolombia accounts
+ * - us: US bank accounts
+ * - polygon: Polygon wallets
+ */
+export declare class AccountsClient {
+    private readonly httpClient;
+    readonly bancolombia: BancolombiaClient;
+    readonly card: CardClient;
+    constructor(httpClient: HttpClient);
+}

package/dist/index.cjs

@@ -0,0 +1,124 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    AccountsClient: ()=>AccountsClient,
+    CardClient: ()=>CardClient
+});
+class CardClient {
+    httpClient;
+    constructor(httpClient){
+        this.httpClient = httpClient;
+    }
+    async create(params) {
+        const request = {
+            holder_urn: params.urn,
+            input: {
+                create: {
+                    card_type: 'VIRTUAL'
+                }
+            },
+            metadata: {
+                source: "sdk-typescript",
+                name: params.name,
+                ...params.metadata
+            }
+        };
+        const response = await this.httpClient.request({
+            method: 'POST',
+            path: '/api/mediums/card',
+            body: request
+        });
+        const account = response.result.account;
+        return {
+            urn: account.urn,
+            id: account.id,
+            lastFour: account.details.card_last_four,
+            productType: account.details.card_product_type,
+            status: account.status,
+            cardType: account.details.card_type,
+            detailsUrl: account.details.card_url_details,
+            ownerUrn: account.owner_urn,
+            webhookUrl: account.webhook_url,
+            metadata: account.metadata,
+            createdAt: account.created_at,
+            updatedAt: account.updated_at
+        };
+    }
+}
+class BancolombiaClient {
+    httpClient;
+    constructor(httpClient){
+        this.httpClient = httpClient;
+    }
+    async create(params) {
+        const request = {
+            holder_urn: params.urn,
+            input: {},
+            metadata: {
+                source: "sdk-typescript",
+                name: params.name,
+                card_urn: params.cardUrn,
+                ...params.metadata
+            }
+        };
+        const response = await this.httpClient.request({
+            method: 'POST',
+            path: '/api/mediums/bancolombia',
+            body: request
+        });
+        const account = response.result.account;
+        return {
+            urn: account.urn,
+            id: account.id,
+            referenceCode: account.details.reference_code,
+            status: account.status,
+            ownerUrn: account.owner_urn,
+            webhookUrl: account.webhook_url,
+            metadata: account.metadata,
+            createdAt: account.created_at,
+            updatedAt: account.updated_at
+        };
+    }
+}
+class AccountsClient {
+    httpClient;
+    bancolombia;
+    card;
+    constructor(httpClient){
+        this.httpClient = httpClient;
+        this.bancolombia = new BancolombiaClient(this.httpClient);
+        this.card = new CardClient(this.httpClient);
+    }
+}
+exports.AccountsClient = __webpack_exports__.AccountsClient;
+exports.CardClient = __webpack_exports__.CardClient;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "AccountsClient",
+    "CardClient"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './card/client';
+export * from './card/types';
+export * from './client';

package/dist/index.js

@@ -0,0 +1,87 @@
+class CardClient {
+    httpClient;
+    constructor(httpClient){
+        this.httpClient = httpClient;
+    }
+    async create(params) {
+        const request = {
+            holder_urn: params.urn,
+            input: {
+                create: {
+                    card_type: 'VIRTUAL'
+                }
+            },
+            metadata: {
+                source: "sdk-typescript",
+                name: params.name,
+                ...params.metadata
+            }
+        };
+        const response = await this.httpClient.request({
+            method: 'POST',
+            path: '/api/mediums/card',
+            body: request
+        });
+        const account = response.result.account;
+        return {
+            urn: account.urn,
+            id: account.id,
+            lastFour: account.details.card_last_four,
+            productType: account.details.card_product_type,
+            status: account.status,
+            cardType: account.details.card_type,
+            detailsUrl: account.details.card_url_details,
+            ownerUrn: account.owner_urn,
+            webhookUrl: account.webhook_url,
+            metadata: account.metadata,
+            createdAt: account.created_at,
+            updatedAt: account.updated_at
+        };
+    }
+}
+class BancolombiaClient {
+    httpClient;
+    constructor(httpClient){
+        this.httpClient = httpClient;
+    }
+    async create(params) {
+        const request = {
+            holder_urn: params.urn,
+            input: {},
+            metadata: {
+                source: "sdk-typescript",
+                name: params.name,
+                card_urn: params.cardUrn,
+                ...params.metadata
+            }
+        };
+        const response = await this.httpClient.request({
+            method: 'POST',
+            path: '/api/mediums/bancolombia',
+            body: request
+        });
+        const account = response.result.account;
+        return {
+            urn: account.urn,
+            id: account.id,
+            referenceCode: account.details.reference_code,
+            status: account.status,
+            ownerUrn: account.owner_urn,
+            webhookUrl: account.webhook_url,
+            metadata: account.metadata,
+            createdAt: account.created_at,
+            updatedAt: account.updated_at
+        };
+    }
+}
+class AccountsClient {
+    httpClient;
+    bancolombia;
+    card;
+    constructor(httpClient){
+        this.httpClient = httpClient;
+        this.bancolombia = new BancolombiaClient(this.httpClient);
+        this.card = new CardClient(this.httpClient);
+    }
+}
+export { AccountsClient, CardClient };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@bloque/sdk-accounts",
+  "version": "0.0.3",
+  "type": "module",
+  "keywords": [
+    "bloque",
+    "sdk",
+    "api",
+    "accounts",
+    "payments"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "git+https://github.com/bloque-app/sdk.git#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bloque-app/sdk.git",
+    "directory": "packages/accounts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "clean": "rm -rf node_modules && rm -rf dist",
+    "check": "biome check --write",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@bloque/sdk-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@rslib/core": "catalog:",
+    "@types/node": "catalog:",
+    "@typescript/native-preview": "catalog:",
+    "typescript": "catalog:"
+  }
+}