@bloque/sdk-accounts 0.0.24 → 0.0.26

package/dist/polygon/types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Parameters for listing polygon accounts
+ */
+export interface ListPolygonAccountsParams {
+    /**
+     * URN of the account holder (user or organization) to filter by
+     * @example "did:bloque:bloque-root:nestor"
+     */
+    holderUrn?: string;
+    /**
+     * URN of a specific polygon account to retrieve
+     * @example "did:bloque:account:polygon:0x05B10c9B6241b73fc8c906fB7979eFc7764AB731"
+     */
+    urn?: string;
+}
+/**
+ * Result of listing polygon accounts
+ */
+export interface ListPolygonAccountsResult {
+    /** Array of polygon accounts with balance information */
+    accounts: PolygonAccount[];
+}
+/**
+ * Parameters for creating a polygon account
+ */
+export interface CreatePolygonAccountParams {
+    /**
+     * URN of the account holder (user or organization)
+     *
+     * @example "did:bloque:user:123e4567"
+     */
+    holderUrn?: string;
+    /**
+     * Ledger account ID to associate with the polygon account
+     * If not provided, a new ledger account will be created automatically
+     */
+    ledgerId?: string;
+    /**
+     * Webhook URL to receive account events
+     */
+    webhookUrl?: string;
+    /**
+     * Custom metadata to attach to the polygon account
+     * Must be a Record<string, string> (all values must be strings)
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * Parameters for updating polygon account metadata
+ */
+export interface UpdatePolygonMetadataParams {
+    /**
+     * URN of the polygon account to update
+     *
+     * @example "did:bloque:account:polygon:0x05B10c9B6241b73fc8c906fB7979eFc7764AB731"
+     */
+    urn: string;
+    /**
+     * Metadata to update
+     * Note: 'source' is a reserved field and cannot be modified
+     */
+    metadata: Record<string, string> & {
+        source?: never;
+    };
+}
+/**
+ * Polygon account response
+ */
+export interface PolygonAccount {
+    /**
+     * Unique resource name for the polygon account
+     */
+    urn: string;
+    /**
+     * Account ID
+     */
+    id: string;
+    /**
+     * Polygon wallet address
+     */
+    address: string;
+    /**
+     * Network name (always "polygon")
+     */
+    network: string;
+    /**
+     * Account status
+     */
+    status: 'creation_in_progress' | 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_failed';
+    /**
+     * Owner URN
+     */
+    ownerUrn: string;
+    /**
+     * Ledger account ID associated with the polygon account
+     */
+    ledgerId: string;
+    /**
+     * Webhook URL (if configured)
+     */
+    webhookUrl: string | null;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Creation timestamp
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: string;
+    /**
+     * Token balances (optional, included in list responses and after creation)
+     */
+    balance?: Record<string, {
+        current: string;
+        pending: string;
+        in: string;
+        out: string;
+    }>;
+}

package/dist/types.d.ts

@@ -1,6 +1,22 @@
 /**
  * Public types for @bloque/sdk-accounts
  */
+/**
+ * Options for account creation
+ */
+export interface CreateAccountOptions {
+    /**
+     * If true, wait for the account to become active before returning
+     * This will poll the account status every second until it's active
+     * @default false
+     */
+    waitLedger?: boolean;
+    /**
+     * Maximum time to wait in milliseconds (only applies when waitLedger is true)
+     * @default 60000 (60 seconds)
+     */
+    timeout?: number;
+}
 /**
  * Supported asset types for transfers and movements
  */
@@ -46,3 +62,80 @@ export interface TransferResult {
     /** Human-readable message about the transfer status */
     message: string;
 }
+/**
+ * Account status
+ */
+export type AccountStatus = 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_in_progress' | 'creation_failed';
+/**
+ * Account medium/type
+ */
+export type AccountMedium = 'bancolombia' | 'card' | 'virtual' | 'polygon' | 'us-account';
+/**
+ * Token balance information
+ */
+export interface TokenBalance {
+    /** Current balance */
+    current: string;
+    /** Pending balance */
+    pending: string;
+    /** Incoming amount */
+    in: string;
+    /** Outgoing amount */
+    out: string;
+}
+/**
+ * Generic account response
+ * Details type varies based on account medium
+ */
+export interface Account<TDetails = unknown> {
+    /** Unique account identifier */
+    id: string;
+    /** Unique resource name for the account */
+    urn: string;
+    /** Account type/medium */
+    medium: AccountMedium;
+    /** Account-specific details (structure varies by medium) */
+    details: TDetails;
+    /** Ledger account ID */
+    ledgerId: string;
+    /** Account status */
+    status: AccountStatus;
+    /** Owner URN */
+    ownerUrn: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Webhook URL (if configured) */
+    webhookUrl: string | null;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Token balances by asset */
+    balance: Record<string, TokenBalance>;
+}
+/**
+ * Parameters for listing accounts
+ */
+export interface ListAccountsParams {
+    /**
+     * URN of the account holder (user or organization) to filter by
+     * @example "did:bloque:bloque-root:nestor"
+     */
+    holderUrn?: string;
+    /**
+     * Specific account URN to retrieve
+     * @example "did:bloque:account:card:usr-123:crd-456"
+     */
+    urn?: string;
+    /**
+     * Account medium/type to filter by
+     */
+    medium?: AccountMedium;
+}
+/**
+ * Result of listing accounts
+ */
+export interface ListAccountsResult {
+    /** Array of accounts */
+    accounts: Account[];
+}

package/dist/us/types.d.ts

@@ -0,0 +1,257 @@
+import type { TokenBalance, UsAccountType } from '../internal/wire-types';
+/**
+ * Address information for US account creation
+ */
+export interface UsAccountAddress {
+    /**
+     * Street address line 1
+     * @example "456 Wall Street"
+     */
+    streetLine1: string;
+    /**
+     * Street address line 2 (optional)
+     * @example "Suite 789"
+     */
+    streetLine2?: string;
+    /**
+     * City
+     * @example "New York"
+     */
+    city: string;
+    /**
+     * State code (2 letters)
+     * @example "NY"
+     */
+    state: string;
+    /**
+     * Postal code
+     * @example "10005"
+     */
+    postalCode: string;
+    /**
+     * Country code (2 letters)
+     * @example "US"
+     */
+    country: string;
+}
+/**
+ * Parameters for creating a US account
+ */
+export interface CreateUsAccountParams {
+    /**
+     * URN of the account holder (user or organization)
+     * @internal - Not exposed in public documentation
+     */
+    holderUrn?: string;
+    /**
+     * Account type (individual or business)
+     * @example "individual"
+     */
+    type: UsAccountType;
+    /**
+     * First name
+     * @example "Robert"
+     */
+    firstName: string;
+    /**
+     * Middle name (optional)
+     * @example "James"
+     */
+    middleName?: string;
+    /**
+     * Last name
+     * @example "Johnson"
+     */
+    lastName: string;
+    /**
+     * Email address
+     * @example "robert.johnson@example.com"
+     */
+    email: string;
+    /**
+     * Phone number with country code
+     * @example "+12125551234"
+     */
+    phone: string;
+    /**
+     * Address information
+     */
+    address: UsAccountAddress;
+    /**
+     * Birth date in YYYY-MM-DD format
+     * @example "1985-03-15"
+     */
+    birthDate: string;
+    /**
+     * Tax identification number (SSN for individuals, EIN for businesses)
+     * @example "123-45-6789"
+     */
+    taxIdentificationNumber: string;
+    /**
+     * Government ID issuing country (2-letter code)
+     * @example "US"
+     */
+    govIdCountry: string;
+    /**
+     * Base64-encoded image of government ID front
+     */
+    govIdImageFront: string;
+    /**
+     * Signed agreement ID obtained from getTosLink
+     * @example "0d139f8e-14b0-4540-92ba-4e66c619b533"
+     */
+    signedAgreementId: string;
+    /**
+     * Webhook URL to receive account events
+     */
+    webhookUrl?: string;
+    /**
+     * Ledger account ID to associate with this account
+     */
+    ledgerId?: string;
+    /**
+     * Custom metadata to associate with the account
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for getting TOS link
+ */
+export interface GetTosLinkParams {
+    /**
+     * Redirect URI after user accepts terms of service
+     * @example "https://myapp.com/callback"
+     */
+    redirectUri: string;
+}
+/**
+ * Result of getting TOS link
+ */
+export interface TosLinkResult {
+    /**
+     * URL to redirect user to accept terms of service
+     * @example "https://dashboard.bridge.xyz/accept-terms-of-service?session_token=4d5d8c45-9feb-422a-bb5e-0fd32e3b3c53"
+     */
+    url: string;
+}
+/**
+ * Parameters for listing US accounts
+ */
+export interface ListUsAccountsParams {
+    /**
+     * URN of the account holder (user or organization) to filter by
+     * @example "did:bloque:bloque-root:nestor"
+     */
+    holderUrn?: string;
+    /**
+     * URN of a specific US account to retrieve
+     * @example "did:bloque:account:us-account:usr-123:us-456"
+     */
+    urn?: string;
+}
+/**
+ * Result of listing US accounts
+ */
+export interface ListUsAccountsResult {
+    /** Array of US accounts with balance information */
+    accounts: UsAccount[];
+}
+/**
+ * Parameters for updating US account metadata
+ */
+export interface UpdateUsMetadataParams {
+    /**
+     * URN of the US account to update
+     * @example "did:bloque:mediums:us-account:account:123e4567"
+     */
+    urn: string;
+    /**
+     * Metadata to update
+     */
+    metadata: Record<string, unknown>;
+}
+/**
+ * US account information
+ */
+export interface UsAccount {
+    /**
+     * Unique resource name for the US account
+     */
+    urn: string;
+    /**
+     * US account ID
+     */
+    id: string;
+    /**
+     * Account type (individual or business)
+     */
+    type: UsAccountType;
+    /**
+     * First name
+     */
+    firstName: string;
+    /**
+     * Middle name (if provided)
+     */
+    middleName?: string;
+    /**
+     * Last name
+     */
+    lastName: string;
+    /**
+     * Email address
+     */
+    email: string;
+    /**
+     * Phone number
+     */
+    phone: string;
+    /**
+     * Address information
+     */
+    address: UsAccountAddress;
+    /**
+     * Birth date in YYYY-MM-DD format
+     */
+    birthDate: string;
+    /**
+     * Bank account number (if available)
+     */
+    accountNumber?: string;
+    /**
+     * Bank routing number (if available)
+     */
+    routingNumber?: string;
+    /**
+     * Current status of the account
+     */
+    status: 'active' | 'disabled' | 'frozen' | 'deleted' | 'creation_in_progress' | 'creation_failed';
+    /**
+     * Owner URN
+     */
+    ownerUrn: string;
+    /**
+     * Ledger account ID associated with this account
+     */
+    ledgerId: string;
+    /**
+     * Webhook URL (if configured)
+     */
+    webhookUrl: string | null;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Creation timestamp
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: string;
+    /**
+     * Token balances (only included in list responses)
+     */
+    balance?: Record<string, TokenBalance>;
+}

package/dist/us/us-client.d.ts

@@ -0,0 +1,170 @@
+import { BaseClient } from '@bloque/sdk-core';
+import type { CreateAccountOptions } from '../types';
+import type { CreateUsAccountParams, GetTosLinkParams, ListUsAccountsParams, ListUsAccountsResult, TosLinkResult, UpdateUsMetadataParams, UsAccount } from './types';
+export declare class UsClient extends BaseClient {
+    /**
+     * Get Terms of Service acceptance link
+     *
+     * This method generates a URL where users can accept the terms of service
+     * required for US account creation. After acceptance, a signed_agreement_id
+     * will be provided which is required for account creation.
+     *
+     * @param params - TOS link parameters
+     * @returns Promise resolving to the TOS acceptance URL
+     *
+     * @example
+     * ```typescript
+     * const tosLink = await bloque.accounts.us.getTosLink({
+     *   redirectUri: 'https://myapp.com/callback'
+     * });
+     *
+     * // Redirect user to tosLink.url
+     * // After acceptance, extract signed_agreement_id from callback
+     * ```
+     */
+    getTosLink(params: GetTosLinkParams): Promise<TosLinkResult>;
+    /**
+     * Create a new US bank account
+     *
+     * Creates a US bank account after the user has accepted the terms of service.
+     * You must first call getTosLink to obtain a signed_agreement_id.
+     *
+     * @param params - US account creation parameters
+     * @param options - Creation options (optional)
+     * @returns Promise resolving to the created US account
+     *
+     * @example
+     * ```typescript
+     * // First, get TOS link and have user accept
+     * const tosLink = await bloque.accounts.us.getTosLink({
+     *   redirectUri: 'https://myapp.com/callback'
+     * });
+     *
+     * // After user accepts, create account with signed_agreement_id
+     * const account = await bloque.accounts.us.create({
+     *   type: 'individual',
+     *   firstName: 'Robert',
+     *   middleName: 'James',
+     *   lastName: 'Johnson',
+     *   email: 'robert.johnson@example.com',
+     *   phone: '+12125551234',
+     *   address: {
+     *     streetLine1: '456 Wall Street',
+     *     streetLine2: 'Suite 789',
+     *     city: 'New York',
+     *     state: 'NY',
+     *     postalCode: '10005',
+     *     country: 'US'
+     *   },
+     *   birthDate: '1985-03-15',
+     *   taxIdentificationNumber: '123-45-6789',
+     *   govIdCountry: 'US',
+     *   govIdImageFront: 'base64_encoded_image',
+     *   signedAgreementId: '0d139f8e-14b0-4540-92ba-4e66c619b533'
+     * });
+     *
+     * // Create and wait for active status
+     * const account = await bloque.accounts.us.create({
+     *   // ... params
+     * }, { waitLedger: true });
+     * ```
+     */
+    create(params: CreateUsAccountParams, options?: CreateAccountOptions): Promise<UsAccount>;
+    /**
+     * List US bank accounts
+     *
+     * Retrieves a list of US bank accounts, optionally filtered by holder URN or specific account URN.
+     *
+     * @param params - List parameters (optional)
+     * @returns Promise resolving to list of US accounts with balances
+     *
+     * @example
+     * ```typescript
+     * // List all US accounts for the authenticated holder
+     * const result = await bloque.accounts.us.list();
+     *
+     * // List US accounts for a specific holder
+     * const result = await bloque.accounts.us.list({
+     *   holderUrn: 'did:bloque:bloque-root:nestor'
+     * });
+     *
+     * // Get a specific US account
+     * const result = await bloque.accounts.us.list({
+     *   urn: 'did:bloque:account:us-account:usr-123:us-456'
+     * });
+     * ```
+     */
+    list(params?: ListUsAccountsParams): Promise<ListUsAccountsResult>;
+    /**
+     * Update US account metadata
+     *
+     * @param params - Metadata update parameters
+     * @returns Promise resolving to the updated US account
+     *
+     * @example
+     * ```typescript
+     * const account = await bloque.accounts.us.updateMetadata({
+     *   urn: 'did:bloque:mediums:us-account:account:123',
+     *   metadata: {
+     *     updated_by: 'admin',
+     *     update_reason: 'customer_request'
+     *   }
+     * });
+     * ```
+     */
+    updateMetadata(params: UpdateUsMetadataParams): Promise<UsAccount>;
+    /**
+     * Activate a US account
+     *
+     * @param urn - US account URN
+     * @returns Promise resolving to the updated US account
+     *
+     * @example
+     * ```typescript
+     * const account = await bloque.accounts.us.activate(
+     *   'did:bloque:mediums:us-account:account:123'
+     * );
+     * ```
+     */
+    activate(urn: string): Promise<UsAccount>;
+    /**
+     * Freeze a US account
+     *
+     * @param urn - US account URN
+     * @returns Promise resolving to the updated US account
+     *
+     * @example
+     * ```typescript
+     * const account = await bloque.accounts.us.freeze(
+     *   'did:bloque:mediums:us-account:account:123'
+     * );
+     * ```
+     */
+    freeze(urn: string): Promise<UsAccount>;
+    /**
+     * Disable a US account
+     *
+     * @param urn - US account URN
+     * @returns Promise resolving to the updated US account
+     *
+     * @example
+     * ```typescript
+     * const account = await bloque.accounts.us.disable(
+     *   'did:bloque:mediums:us-account:account:123'
+     * );
+     * ```
+     */
+    disable(urn: string): Promise<UsAccount>;
+    /**
+     * Private method to poll account status until it becomes active
+     */
+    private _waitForActiveStatus;
+    /**
+     * Private method to update account status
+     */
+    private _updateStatus;
+    /**
+     * Private method to map API response to UsAccount
+     */
+    private _mapAccountResponse;
+}

package/dist/virtual/types.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Parameters for listing virtual accounts
+ */
+export interface ListVirtualAccountsParams {
+    /**
+     * URN of the account holder (user or organization) to filter by
+     * @example "did:bloque:bloque-root:nestor"
+     */
+    holderUrn?: string;
+    /**
+     * URN of a specific virtual account to retrieve
+     * @example "did:bloque:account:virtual:275d10a2-0854-4081-9d61-ea506e917335"
+     */
+    urn?: string;
+}
+/**
+ * Result of listing virtual accounts
+ */
+export interface ListVirtualAccountsResult {
+    /** Array of virtual accounts with balance information */
+    accounts: VirtualAccount[];
+}
 /**
  * Parameters for creating a virtual account
  */
@@ -101,4 +123,13 @@ export interface VirtualAccount {
      * Last update timestamp
      */
     updatedAt: string;
+    /**
+     * Token balances (optional, included in list responses and after creation)
+     */
+    balance?: Record<string, {
+        current: string;
+        pending: string;
+        in: string;
+        out: string;
+    }>;
 }