{"id":37845656,"url":"https://github.com/blnkfinance/blnk-ts","last_synced_at":"2026-01-16T16:03:12.617Z","repository":{"id":258001071,"uuid":"860055985","full_name":"blnkfinance/blnk-ts","owner":"blnkfinance","description":"The official TypeScript SDK for Blnk.","archived":false,"fork":false,"pushed_at":"2025-06-21T12:26:50.000Z","size":484,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-21T13:30:59.046Z","etag":null,"topics":["backend","blnk","fintech","js","ledger","nodejs","ts"],"latest_commit_sha":null,"homepage":"https://docs.blnkfinance.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blnkfinance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-19T18:33:08.000Z","updated_at":"2025-06-21T12:26:53.000Z","dependencies_parsed_at":"2024-10-26T18:26:34.210Z","dependency_job_id":"cc8f0440-5b31-42b1-a397-6819377bc286","html_url":"https://github.com/blnkfinance/blnk-ts","commit_stats":null,"previous_names":["blnkfinance/blnk-ts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/blnkfinance/blnk-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blnkfinance%2Fblnk-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blnkfinance%2Fblnk-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blnkfinance%2Fblnk-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blnkfinance%2Fblnk-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blnkfinance","download_url":"https://codeload.github.com/blnkfinance/blnk-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blnkfinance%2Fblnk-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","blnk","fintech","js","ledger","nodejs","ts"],"created_at":"2026-01-16T16:03:12.489Z","updated_at":"2026-01-16T16:03:12.581Z","avatar_url":"https://github.com/blnkfinance.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Blnk logo](https://res.cloudinary.com/dmxizylxw/image/upload/v1724847576/blnk_github_logo_eyy2lf.png)\n\n## Blnk TypeScript SDK Documentation\n\n\n---\n\n## 1. Installation\n\n### Prerequisites\nEnsure that you have the following installed on your machine:\n- **Docker** and **Docker Compose** for running Blnk’s server locally.\n- **Node.js** (v14 or later) and **npm** for installing the Blnk TypeScript SDK.\n\n### Step 1: Clone the Blnk Repository\n\nTo start, clone the Blnk repository from GitHub:\n\n```bash\ngit clone https://github.com/blnkfinance/blnk \u0026\u0026 cd blnk\n```\n\n### Step 2: Install Blnk TypeScript SDK\n\nInstall the Blnk TypeScript SDK in your project:\n\n```bash\nnpm install @blnkfinance/blnk-typescript --save\n```\n\n### Step 3: Setting Up Configuration\n\nIn your cloned directory, create a configuration file named `blnk.json` with the following content:\n\n```json\n{\n  \"project_name\": \"Blnk\",\n  \"data_source\": {\n    \"dns\": \"postgres://postgres:password@postgres:5432/blnk?sslmode=disable\"\n  },\n  \"redis\": {\n    \"dns\": \"redis:6379\"\n  },\n  \"server\": {\n    \"domain\": \"blnk.io\",\n    \"ssl\": false,\n    \"ssl_email\": \"jerryenebeli@gmail.com\",\n    \"port\": \"5001\"\n  },\n  \"notification\": {\n    \"slack\": {\n      \"webhook_url\": \"https://hooks.slack.com\"\n    }\n  }\n}\n```\n\nThis configuration sets up connections to PostgreSQL and Redis, specifies your server details, and allows Slack notifications if needed.\n\n---\n\n## 2. Launching Blnk\n\nWith Docker Compose, launch the Blnk server:\n\n```bash\ndocker compose up\n```\n\nOnce running, your server will be accessible at [http://localhost:5001](http://localhost:5001).\n\n---\n\n## 3. Using the Blnk CLI\n\nThe Blnk CLI offers quick access to manage ledgers, balances, and transactions. To verify the installation and view available commands, use:\n\n```bash\nblnk --help\n```\n\n---\n\n## 4. Creating Your First Ledger\n\n### What is a Ledger?\nIn Blnk, ledgers are used to categorize balances for organized tracking. When you first install Blnk, an internal ledger called the General Ledger is created by default.\n\n### Step-by-Step: Creating a Ledger\n\nUsing the SDK, create a ledger for user accounts:\n\n```typescript\nimport { BlnkInit } from '@blnkfinance/blnk-typescript';\n\nconst blnk = await BlnkInit('\u003csecret_key_if_set\u003e', { baseUrl: 'http://localhost:5001' });\nconst { Ledgers } = blnk;\n\nconst newLedger = await Ledgers.create({\n    name: \"Customer Savings Account\",\n    meta_data: {\n        project_owner: \"YOUR_APP_NAME\"\n    }\n});\nconsole.log(\"Ledger Created:\", newLedger);\n```\n\nThis creates a new ledger for storing customer balances.\n\n---\n\n## 5. Creating Balances\n\nBalances represent the store of value within a ledger, like a wallet or account. Each balance belongs to a ledger.\n\n### Step-by-Step: Creating a Balance\n\nTo create a balance, specify the `ledger_id` and other details:\n\n```typescript\nconst { LedgerBalances } = blnk;\n\nconst newBalance = await LedgerBalances.create({\n    ledger_id: \"ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc\",\n    currency: \"USD\",\n    meta_data: {\n        first_name: \"Alice\",\n        last_name: \"Hart\",\n        account_number: \"1234567890\"\n    }\n});\nconsole.log(\"Balance Created:\", newBalance);\n```\n\n---\n\n## 6. Recording Transactions\n\nTransactions track financial activities within your application. Blnk ensures that each transaction is both immutable and idempotent.\n\n### Step-by-Step: Recording a Transaction\n\nTo record a transaction, you’ll need the `source` and `destination` balance IDs:\n\n```typescript\nconst { Transactions } = blnk;\n\nconst newTransaction = await Transactions.create({\n    amount: 750,\n    reference: \"ref_001adcfgf\",\n    currency: \"USD\",\n    precision: 100,\n    source: \"bln_28edb3e5-c168-4127-a1c4-16274e7a28d3\",\n    destination: \"bln_ebcd230f-6265-4d4a-a4ca-45974c47f746\",\n    description: \"Sent from app\",\n    meta_data: {\n        sender_name: \"John Doe\",\n        sender_account: \"00000000000\"\n    }\n});\nconsole.log(\"Transaction Recorded:\", newTransaction);\n```\n\n---\n\n## 7. Bulk Transactions\n\nThe Blnk JavaScript SDK supports bulk transactions, allowing you to submit multiple transaction records in a single request for improved performance and atomic transaction processing.\n\n### Overview\n\nThe bulk transactions API provides the following benefits:\n- **Performance**: Submit multiple transactions in one API call\n- **Atomicity**: Ensure all transactions succeed or fail together (when `atomic: true`)\n- **Async Processing**: Process large batches asynchronously\n- **Inflight Support**: Create multiple inflight transactions that can be committed or voided later\n\n### Method Signature\n\n```typescript\nasync createBulk\u003cT extends Record\u003cstring, unknown\u003e\u003e(data: BulkTransactions\u003cT\u003e)\n```\n\n### Parameters\n\n#### BulkTransactions Interface\n\n```typescript\ninterface BulkTransactions\u003cT extends Record\u003cstring, unknown\u003e\u003e {\n  atomic?: boolean;        // Optional: All transactions succeed or fail together\n  inflight?: boolean;      // Optional: Create transactions as inflight\n  run_async?: boolean;     // Optional: Process transactions asynchronously\n  transactions: CreateTransactions\u003cT\u003e[]; // Required: Array of transaction objects\n}\n```\n\n### Usage Examples\n\n#### Basic Bulk Transactions\n\n```typescript\nconst { Transactions } = blnk;\n\n// Basic bulk transactions without additional options\nconst basicBulkData = {\n  transactions: [\n    {\n      amount: 1000,\n      precision: 100,\n      reference: 'bulk_txn_001',\n      description: 'Payment 1',\n      currency: 'USD',\n      source: '@source_account_1',\n      destination: '@destination_account_1',\n    },\n    {\n      amount: 2000,\n      precision: 100,\n      reference: 'bulk_txn_002',\n      description: 'Payment 2',\n      currency: 'USD',\n      source: '@source_account_2',\n      destination: '@destination_account_2',\n    },\n  ],\n};\n\nconst response = await Transactions.createBulk(basicBulkData);\nconsole.log('Bulk transaction response:', response);\n```\n\n#### Atomic Bulk Transactions\n\n```typescript\n// Atomic transactions - all succeed or all fail\nconst atomicBulkData = {\n  atomic: true,\n  transactions: [\n    {\n      amount: 5000,\n      precision: 100,\n      reference: 'atomic_txn_001',\n      description: 'Atomic payment 1',\n      currency: 'USD',\n      source: '@source_account_1',\n      destination: '@destination_account_1',\n    },\n    {\n      amount: 3000,\n      precision: 100,\n      reference: 'atomic_txn_002',\n      description: 'Atomic payment 2',\n      currency: 'USD',\n      source: '@source_account_2',\n      destination: '@destination_account_2',\n    },\n  ],\n};\n\nconst atomicResponse = await Transactions.createBulk(atomicBulkData);\n```\n\n#### Async Bulk Transactions with All Options\n\n```typescript\n// Process transactions asynchronously with atomic and inflight options\nconst asyncBulkData = {\n  atomic: true,\n  inflight: true,\n  run_async: true,\n  transactions: [\n    {\n      amount: 12000,\n      precision: 100,\n      reference: 'async_txn_001',\n      description: 'Async atomic inflight payment 1',\n      currency: 'USD',\n      source: '@source_account_1',\n      destination: '@destination_account_1',\n      allow_overdraft: true,\n      inflight_expiry_date: new Date(Date.now() + 48 * 60 * 60 * 1000), // 48 hours\n      meta_data: {\n        department: 'sales',\n        project: 'Q4_campaign',\n      },\n    },\n    {\n      amount: 8500,\n      precision: 100,\n      reference: 'async_txn_002',\n      description: 'Async atomic inflight payment 2',\n      currency: 'USD',\n      source: '@source_account_2',\n      destination: '@destination_account_2',\n      allow_overdraft: true,\n      inflight_expiry_date: new Date(Date.now() + 48 * 60 * 60 * 1000), // 48 hours\n      meta_data: {\n        department: 'marketing',\n        project: 'Q4_campaign',\n      },\n    },\n  ],\n};\n\nconst asyncResponse = await Transactions.createBulk(asyncBulkData);\n```\n\n### Response Format\n\n```typescript\ninterface BulkTransactionResponse\u003cT extends Record\u003cstring, unknown\u003e\u003e {\n  id: string;                                    // Bulk transaction ID\n  atomic: boolean;                               // Whether transactions were atomic\n  inflight: boolean;                             // Whether transactions were created as inflight\n  run_async: boolean;                            // Whether processing was asynchronous\n  transactions: CreateTransactionResponse\u003cT\u003e[];  // Array of individual transaction responses\n  created_at: Date;                              // Creation timestamp\n}\n```\n\n### Validation Rules\n\nThe bulk transactions API validates the following:\n\n1. **Required Fields**: `transactions` array must be provided and cannot be empty\n2. **Transaction Validation**: Each transaction in the array must pass standard transaction validation\n3. **Unique References**: All transaction references must be unique within the bulk request\n4. **Boolean Flags**: `atomic`, `inflight`, and `run_async` must be booleans if provided\n5. **Standard Transaction Rules**: All existing transaction validation rules apply to each transaction\n\n### Error Handling\n\n```typescript\ntry {\n  const response = await Transactions.createBulk(bulkData);\n  if (response.status === 201) {\n    console.log('Bulk transactions created successfully:', response.data);\n  } else {\n    console.error('Bulk transaction error:', response.message);\n  }\n} catch (error) {\n  console.error('Network or system error:', error);\n}\n```\n\n### Migration from Single Transactions\n\nConverting from single transactions to bulk transactions is straightforward:\n\n#### Before (Single Transactions)\n```typescript\nconst tx1 = await Transactions.create(transactionData1);\nconst tx2 = await Transactions.create(transactionData2);\n```\n\n#### After (Bulk Transactions)\n```typescript\nconst bulkResponse = await Transactions.createBulk({\n  transactions: [transactionData1, transactionData2]\n});\n```\n\nThis migration provides better performance and the option for atomic processing.\n\n---\n\n## 8. Viewing Ledgers, Balances, and Transactions\n\nThe Blnk CLI allows you to list all ledgers, balances, and transactions quickly:\n\n- **List Ledgers:** `blnk ledgers list`\n- **List Balances:** `blnk balances list`\n- **List Transactions:** `blnk transactions list`\n\n---\n\n## Additional Resources\n\nFor more examples and advanced use cases, please refer to the [Examples Code](https://github.com/blnkfinance/blnk-ts/tree/main/examples).\n\n### Issue Reporting\nIf you encounter any issues, please [report them on GitHub](https://github.com/blnkfinance/blnk/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblnkfinance%2Fblnk-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblnkfinance%2Fblnk-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblnkfinance%2Fblnk-ts/lists"}