{"_id":"@danicanod/banquer-connectors","_rev":"2-f981d9ecd6b18dd7c0a9a126f2fcba10","name":"@danicanod/banquer-connectors","dist-tags":{"latest":"3.2.0"},"versions":{"3.1.0":{"name":"@danicanod/banquer-connectors","version":"3.1.0","keywords":["venezuela","banking","banesco","bnc","scraping","automation","playwright","typescript","web-scraping","bank-scraper","financial-data","banking-automation","fintech","venezuela-banks","transaction-scraping","browser-automation","headless-browser"],"author":{"url":"https://github.com/danicanod","name":"Daniel Sanchez","email":"danicanod@gmail.com"},"license":"MIT","_id":"@danicanod/banquer-connectors@3.1.0","maintainers":[{"name":"danicanod","email":"danicanod@gmail.com"}],"homepage":"https://github.com/danicanod/banquer-connectors#readme","bugs":{"url":"https://github.com/danicanod/banquer-connectors/issues"},"os":["linux","darwin","win32"],"cpu":["x64","arm64"],"dist":{"shasum":"3e7c12203076b3d6913c68fed6d7ec0dee73863e","tarball":"https://registry.npmjs.org/@danicanod/banquer-connectors/-/banquer-connectors-3.1.0.tgz","fileCount":115,"integrity":"sha512-sv39vcJ69KnKWdwAk/uEx5/ehr8afO9LSG59euuN2Rsg1cy7O0ZAyk4AJn3ag0LBQll20WGe0vLWX+qbY83r4w==","signatures":[{"sig":"MEUCIQCVzkJUXWKIiFMWhjwgXYEeZz95g7Z7IOP/Z+eN1HHG5gIgBoSU2J68pEv3WX9hSwCsoLxZ8yV8O9GMveMrsK+WeyM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":596899},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0","pnpm":">=8.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./bnc":{"types":"./dist/banks/bnc/index.d.ts","import":"./dist/banks/bnc/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./banesco":{"types":"./dist/banks/banesco/index.d.ts","import":"./dist/banks/banesco/index.js"}},"funding":{"url":"https://github.com/sponsors/danicanod","type":"github"},"gitHead":"3dad9887f3853984ed0035118f123bb2b7be7191","scripts":{"lint":"eslint src/ --ignore-pattern 'src/dev/**'","build":"tsc","clean":"rm -rf dist/","prepare":"tsc","rebuild":"pnpm run clean && pnpm run build","lint:fix":"eslint src/ --ignore-pattern 'src/dev/**' --fix","type-check":"tsc --noEmit","example:bnc":"tsx src/banks/bnc/examples/http-usage.ts","postinstall":"npx playwright install chromium","example:banesco":"tsx src/banks/banesco/examples/basic-usage.ts","example:banesco-hybrid":"tsx src/banks/banesco/examples/hybrid-usage.ts"},"_npmUser":{"name":"danicanod","email":"danicanod@gmail.com"},"repository":{"url":"git+https://github.com/danicanod/banquer-connectors.git","type":"git"},"_npmVersion":"11.18.0","description":"TypeScript library for connecting to Venezuelan bank accounts (Banesco & BNC). Hybrid Playwright/HTTP architecture for reliability and speed.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"dotenv":"^16.5.0","cheerio":"^1.1.2","playwright":"^1.49.1","tough-cookie":"^6.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","eslint":"^9.17.0","globals":"^15.14.0","@eslint/js":"^9.17.0","typescript":"^5.7.2","@types/node":"^22.10.2","@types/cheerio":"^0.22.35","typescript-eslint":"^8.18.2","@types/tough-cookie":"^4.0.5"},"_npmOperationalInternal":{"tmp":"tmp/banquer-connectors_3.1.0_1784382727317_0.7746042355569729","host":"s3://npm-registry-packages-npm-production"}},"3.2.0":{"name":"@danicanod/banquer-connectors","version":"3.2.0","description":"TypeScript library for connecting to Venezuelan bank accounts (Banesco, BNC & Facebank). Hybrid Playwright/HTTP architecture for reliability and speed.","main":"dist/index.js","types":"dist/index.d.ts","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./banesco":{"types":"./dist/banks/banesco/index.d.ts","import":"./dist/banks/banesco/index.js"},"./bnc":{"types":"./dist/banks/bnc/index.d.ts","import":"./dist/banks/bnc/index.js"},"./facebank":{"types":"./dist/banks/facebank/index.d.ts","import":"./dist/banks/facebank/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"}},"scripts":{"build":"tsc","prepare":"tsc","type-check":"tsc --noEmit","test":"node --import tsx --test tests/*.test.ts","test:watch":"node --import tsx --test --watch tests/*.test.ts","lint":"eslint src/ --ignore-pattern 'src/dev/**'","lint:fix":"eslint src/ --ignore-pattern 'src/dev/**' --fix","clean":"rm -rf dist/","rebuild":"pnpm run clean && pnpm run build","example:banesco":"tsx src/banks/banesco/examples/basic-usage.ts","example:banesco-hybrid":"tsx src/banks/banesco/examples/hybrid-usage.ts","example:bnc":"tsx src/banks/bnc/examples/http-usage.ts","example:facebank":"tsx src/banks/facebank/examples/basic-usage.ts","install:browser":"npx playwright install chromium"},"keywords":["venezuela","banking","banesco","bnc","facebank","scraping","automation","playwright","typescript","web-scraping","bank-scraper","financial-data","banking-automation","fintech","venezuela-banks","transaction-scraping","browser-automation","headless-browser"],"repository":{"type":"git","url":"git+https://github.com/danicanod/banquer-connectors.git"},"bugs":{"url":"https://github.com/danicanod/banquer-connectors/issues"},"homepage":"https://github.com/danicanod/banquer-connectors#readme","author":{"name":"Daniel Sanchez","email":"danicanod@gmail.com","url":"https://github.com/danicanod"},"license":"MIT","engines":{"node":">=18.0.0","pnpm":">=8.0.0"},"funding":{"type":"github","url":"https://github.com/sponsors/danicanod"},"os":["linux","darwin","win32"],"cpu":["x64","arm64"],"devDependencies":{"@eslint/js":"^9.17.0","@types/cheerio":"^0.22.35","@types/node":"^22.10.2","@types/tough-cookie":"^4.0.5","eslint":"^9.17.0","globals":"^15.14.0","tsx":"^4.19.4","typescript":"^5.7.2","typescript-eslint":"^8.18.2"},"dependencies":{"cheerio":"^1.1.2","dotenv":"^16.5.0","playwright":"^1.49.1","tough-cookie":"^6.0.0"},"gitHead":"0f6b5d8bfc8c8efe37839c0cb7ebaddac0d448e3","_id":"@danicanod/banquer-connectors@3.2.0","_nodeVersion":"24.14.0","_npmVersion":"11.18.0","dist":{"integrity":"sha512-Fi/3TfwDPXveWyjdHQyajxIYcW3YdHRWZv0E7ADeuyMHLdZHY/O/MSMXnoY29y4oRqeFKkzzjs+PU/pfiG+FhA==","shasum":"264945ecf43b3922833b0c1d97ac4932372255ae","tarball":"https://registry.npmjs.org/@danicanod/banquer-connectors/-/banquer-connectors-3.2.0.tgz","fileCount":167,"unpackedSize":634064,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCqmYpYihLIV0NJxZYdpB0sT8ELxcmY4amQA/BmptHt1gIgefHXz1OGOIM1CAV62yP2dHVWeXHUPwZ3Ig6qORYKSTM="}]},"_npmUser":{"name":"danicanod","email":"danicanod@gmail.com"},"directories":{},"maintainers":[{"name":"danicanod","email":"danicanod@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/banquer-connectors_3.2.0_1784505184341_0.08954942102632679"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-18T13:52:07.207Z","modified":"2026-07-19T23:53:04.601Z","3.1.0":"2026-07-18T13:52:07.456Z","3.2.0":"2026-07-19T23:53:04.456Z"},"bugs":{"url":"https://github.com/danicanod/banquer-connectors/issues"},"author":{"name":"Daniel Sanchez","email":"danicanod@gmail.com","url":"https://github.com/danicanod"},"license":"MIT","homepage":"https://github.com/danicanod/banquer-connectors#readme","keywords":["venezuela","banking","banesco","bnc","facebank","scraping","automation","playwright","typescript","web-scraping","bank-scraper","financial-data","banking-automation","fintech","venezuela-banks","transaction-scraping","browser-automation","headless-browser"],"repository":{"type":"git","url":"git+https://github.com/danicanod/banquer-connectors.git"},"description":"TypeScript library for connecting to Venezuelan bank accounts (Banesco, BNC & Facebank). Hybrid Playwright/HTTP architecture for reliability and speed.","maintainers":[{"name":"danicanod","email":"danicanod@gmail.com"}],"readme":"# Banquer Connectors\n\n\n\n\n\n\n[](https://choosealicense.com/licenses/mit/)\n[](https://www.typescriptlang.org/)\n\n**TypeScript library for connecting to Venezuelan bank accounts**\n\n[Installation](#installation) • [Quick Start](#quick-start) • [API Reference](#api-reference) • [Normalized Output](#normalized-output)\n\n
\n\n---\n\n## Supported Banks\n\n| Bank | Mode | Authentication | Transactions | Speed |\n|------|------|---------------|--------------|-------|\n| **Banesco** | Hybrid (Playwright login + HTTP fetch) | Username + Password + Security Questions | Full history | Fast after login |\n| **BNC** | Pure HTTP (no browser) | Card + ID + Password | Last 25 transactions | ~8-10x faster |\n| **Facebank** (PR) | Browser-driven (Playwright login + in-browser scraping) | Username + Password + emailed OTP | Recent movements | Browser-bound |\n\n## Installation\n\n```bash\nnpm install @danicanod/banquer-connectors\n```\n\n### Prerequisites\n\n- Node.js >= 18\n- npm >= 8\n\n**Banesco** and **Facebank** drive a real browser, so they need Playwright's Chromium.\nIt is **not** installed automatically (BNC is pure HTTP and needs no browser). Install it once:\n\n```bash\nnpx playwright install chromium # or: npm run install:browser\n```\n\n## Quick Start\n\n### Banesco (Hybrid Mode)\n\n```typescript\nimport { createBanescoClient, normalizeTransactions } from '@danicanod/banquer-connectors';\n\nconst client = createBanescoClient({\n username: 'V12345678',\n password: 'your_password',\n securityQuestions: 'anime:Naruto,mascota:Firulais'\n});\n\nawait client.login();\n\nconst accounts = await client.getAccounts();\nconst movements = await client.getAccountMovements(accounts.accounts[0].accountNumber);\n\n// Normalize transactions to unified format\nconst normalized = normalizeTransactions('banesco', movements.transactions);\n\nawait client.close();\n```\n\n### BNC (Pure HTTP - No Browser)\n\n```typescript\nimport { createBncClient, normalizeTransactions } from '@danicanod/banquer-connectors';\n\nconst client = createBncClient({\n id: 'V12345678',\n cardNumber: '1234567890123456',\n password: 'your_password'\n});\n\nawait client.login();\n\nconst result = await client.getTransactions();\nconst normalized = normalizeTransactions('bnc', result.data ?? []);\n\nawait client.close();\n```\n\n### Facebank (Browser-driven + emailed OTP)\n\nFacebank (PR) is a COBIS/Angular SPA: login runs in Playwright and a 5-character\none-time code is emailed at login. Supply it with an `otpProvider` callback, or\nomit it to be prompted on the terminal. The session stays open while data is\nscraped from the live page, so call `close()` when done.\n\n```typescript\nimport { createFacebankClient, normalizeTransactions } from '@danicanod/banquer-connectors';\n\nconst client = createFacebankClient(\n { username: 'your_username', password: 'your_password' },\n { headless: false, otpProvider: async () => '12345' } // omit otpProvider to prompt on stdin\n);\n\nawait client.login();\n\nconst accounts = await client.getAccounts();\nconst movements = await client.getAccountMovements();\nconst normalized = normalizeTransactions('facebank', movements.transactions);\n\nawait client.close();\n```\n\n## API Reference\n\n### BanescoClient\n\n```typescript\nimport { createBanescoClient } from '@danicanod/banquer-connectors';\n\nconst client = createBanescoClient(credentials, config);\n\nawait client.login();\nconst accounts = await client.getAccounts();\nconst movements = await client.getAccountMovements(accountNumber);\nawait client.close();\n```\n\n### BncClient\n\n```typescript\nimport { createBncClient } from '@danicanod/banquer-connectors';\n\nconst client = createBncClient(credentials, config);\n\nawait client.login();\nconst result = await client.getTransactions();\nawait client.close();\n```\n\n### FacebankClient\n\n```typescript\nimport { createFacebankClient } from '@danicanod/banquer-connectors';\n\nconst client = createFacebankClient(credentials, config);\n\nawait client.login(); // Playwright login + emailed OTP\nconst accounts = await client.getAccounts();\nconst movements = await client.getAccountMovements();\nawait client.close(); // closes the browser session\n```\n\n## Normalized Output\n\nUnified `Transaction` type for consistent data across all banks:\n\n```typescript\ninterface Transaction {\n bank: 'banesco' | 'bnc' | 'facebank';\n txnKey: string; // Deterministic hash for idempotent storage\n date: string; // YYYY-MM-DD\n amount: number; // Always positive\n description: string;\n type: 'debit' | 'credit';\n reference?: string;\n accountId?: string;\n raw?: unknown;\n}\n```\n\n### Normalization API\n\n```typescript\nimport { normalizeTransactions, makeTxnKey } from '@danicanod/banquer-connectors';\n\n// Normalize transactions\nconst normalized = normalizeTransactions('banesco', transactions);\n\n// Generate deterministic key\nconst key = makeTxnKey('banesco', { date, amount, description, type });\n```\n\n## Configuration\n\n```typescript\n// Banesco\ninterface BanescoClientConfig {\n headless?: boolean; // Default: true\n timeout?: number; // Default: 60000ms\n debug?: boolean; // Default: false\n browserWSEndpoint?: string; // Optional: attach to a remote browser over CDP\n}\n\n// BNC\ninterface BncClientConfig {\n timeout?: number; // Default: 30000ms\n debug?: boolean; // Default: false\n}\n\n// Facebank\ninterface FacebankClientConfig {\n headless?: boolean; // Default: false\n timeout?: number; // Default: 45000ms\n debug?: boolean; // Default: false\n browserWSEndpoint?: string; // Optional: remote browser over CDP\n otpProvider?: () => Promise; // Supplies the emailed OTP; omit to prompt on stdin\n manualImageFallback?: boolean; // Default: true (pause for the rare image step-up)\n}\n```\n\n### Remote browser (CDP)\n\nBy default Banesco login launches a local Chromium. To run the login step in a\n**remote browser** instead — e.g. a [Browserbase](https://browserbase.com)\nsession on a server that can't launch Chromium — pass its CDP `connectUrl` as\n`browserWSEndpoint`:\n\n```typescript\nimport { createBanescoClient } from '@danicanod/banquer-connectors';\n\nconst client = createBanescoClient(credentials, {\n browserWSEndpoint: session.connectUrl, // e.g. from Browserbase\n});\nawait client.login();\n```\n\n> Note: login runs in the remote browser, but data is then fetched over\n> in-process HTTP, so the host's egress IP differs from the remote browser's.\n> Verify the bank tolerates that before relying on it in production. BNC is pure\n> HTTP and never uses a browser.\n\n## Environment Variables\n\n```bash\n# Banesco\nBANESCO_USERNAME=V12345678\nBANESCO_PASSWORD=your_password\nBANESCO_SECURITY_QUESTIONS=anime:Naruto,mascota:Firulais\n\n# BNC\nBNC_ID=V12345678\nBNC_CARD=1234567890123456\nBNC_PASSWORD=your_password\n\n# Facebank (PR)\nFACEBANK_USERNAME=your_username\nFACEBANK_PASSWORD=your_password\n# Optional — only if the security-image step-up appears:\n# FACEBANK_SECRET_WORD=your_image_alias\n# FACEBANK_SECRET_IMAGE=your_image_id\n```\n\n## Development\n\n```bash\nnpm install\nnpm run type-check\nnpm run lint\nnpm run build\n```\n\n## Contributing\n\n1. Fork the repo and create a feature branch\n2. Run `npm run type-check` and `npm run lint` before committing\n3. Keep PRs focused on a single feature or fix\n4. Update docs if changing the public API\n\n## Security\n\n- **Never commit** `.env` files or credentials\n- Store secrets in environment variables\n- Session data stored in `.sessions/` (gitignored, 24h expiry)\n- All bank connections use HTTPS\n- For vulnerabilities, email danicanod@gmail.com (not public issues)\n\n## Code Style\n\n- TypeScript strict mode, ESLint enforced\n- Logging: `[Component] action (optional data)` — no emojis\n- Prefer `unknown` over `any`; prefix unused params with `_`\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md"}