{"_id":"@binlookupapi/binlookupapi-ts-sdk","_rev":"3-938bbede3215e8652a992b681f3474ae","name":"@binlookupapi/binlookupapi-ts-sdk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@binlookupapi/binlookupapi-ts-sdk","version":"1.0.0","keywords":["bin","lookup","card","payment","banking","typescript"],"author":{"name":"BINLookupAPI"},"license":"MIT","_id":"@binlookupapi/binlookupapi-ts-sdk@1.0.0","maintainers":[{"name":"brun0coe3","email":"brunocsncoelho@gmail.com"},{"name":"pmierzejewski-cbs","email":"piotr@chargebackstop.com"}],"dist":{"shasum":"1941e6d6c19ccd17f5bc71e43f9848c06c012558","tarball":"https://registry.npmjs.org/@binlookupapi/binlookupapi-ts-sdk/-/binlookupapi-ts-sdk-1.0.0.tgz","fileCount":6,"integrity":"sha512-a1w5T3etPNffJJHUX392V1sHz6s8U5uL7uov/+z76xGWUCQzXhJhjQpxgGDlvfWhL/KjgLXt1YF5dlR9mas+Bw==","signatures":[{"sig":"MEUCIFMKV3XFTcf7bqLXvcjccjYMtbMAf/DKBrqElOPXcRpwAiEAoW2ORp4LzLaEGB3zfH3j4xG8IYsTXivH9Ze760BiCLY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18096},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"b5c1663aefa00fb09ebaf4e4f24549a9e4101ac9","scripts":{"test":"vitest run","build":"tsc","prepare":"npm run build"},"_npmUser":{"name":"brun0coe3","email":"brunocsncoelho@gmail.com"},"_npmVersion":"11.14.1","description":"Official TypeScript SDK for BINLookupAPI","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/binlookupapi-ts-sdk_1.0.0_1779180297052_0.3439641230372379","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@binlookupapi/binlookupapi-ts-sdk","version":"1.0.1","keywords":["bin","lookup","card","payment","banking","typescript"],"author":{"name":"BINLookupAPI"},"license":"MIT","_id":"@binlookupapi/binlookupapi-ts-sdk@1.0.1","maintainers":[{"name":"brun0coe3","email":"brunocsncoelho@gmail.com"},{"name":"pmierzejewski-cbs","email":"piotr@chargebackstop.com"}],"dist":{"shasum":"7a62dc29d67fdfe394ee1a8cd120faab42b7bf24","tarball":"https://registry.npmjs.org/@binlookupapi/binlookupapi-ts-sdk/-/binlookupapi-ts-sdk-1.0.1.tgz","fileCount":6,"integrity":"sha512-CXvgMv77o90R8tNSxMEVob7ky4Odqdq15OcYHHCWP4OVYO+pYHdSup22lWF+PXSM1+zR6f0apaQaUotSg188Yg==","signatures":[{"sig":"MEQCIAk3co1PfWAY1NDuZX5VWPr8vXn7+a4vWpx6TdcELUhmAiAWvWoFzeMuFaipwONvx/Vr/EfOlsOow1fMUQhAvONWDQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18219},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"3c8f344c5e30d2709f079bf5272d167d8bac1757","scripts":{"test":"vitest run","build":"tsc","prepare":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e9397a88-3002-4b61-b970-b6784535bb93"}},"_npmVersion":"11.14.1","description":"Official TypeScript SDK for BINLookupAPI","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/binlookupapi-ts-sdk_1.0.1_1779184929721_0.4139921036187679","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@binlookupapi/binlookupapi-ts-sdk","version":"1.0.2","description":"Official TypeScript SDK for BINLookupAPI","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepare":"npm run build","test":"vitest run"},"keywords":["bin","lookup","card","payment","banking","typescript"],"author":{"name":"BINLookupAPI"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/binlookupapi/binlookupapi-ts-sdk.git"},"devDependencies":{"typescript":"^5.0.0","vitest":"^2.0.0"},"gitHead":"59e20d08c613c8c3972cd1b020d4273cc86e8469","_id":"@binlookupapi/binlookupapi-ts-sdk@1.0.2","bugs":{"url":"https://github.com/binlookupapi/binlookupapi-ts-sdk/issues"},"homepage":"https://github.com/binlookupapi/binlookupapi-ts-sdk#readme","_nodeVersion":"20.20.2","_npmVersion":"11.15.0","dist":{"integrity":"sha512-82B5TKxUEueBAfxYgwRLUyWa7BpJYG9UIfJhDViUhL+5GmVPIh/iV0C+et28GXYqIbtH8PmtoEJePLi50TIomw==","shasum":"bc6661ee0607dd25d764c91588b462f148fb4443","tarball":"https://registry.npmjs.org/@binlookupapi/binlookupapi-ts-sdk/-/binlookupapi-ts-sdk-1.0.2.tgz","fileCount":6,"unpackedSize":18538,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@binlookupapi%2fbinlookupapi-ts-sdk@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAnZ7GuXgnfElDrjfupdohW21l67FkFW/Est0Zjc4p+eAiEAlE/6sIDC/NUWUoV8UXAh+ILi4Lf1ZdORYfa3+lDOHnQ="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e9397a88-3002-4b61-b970-b6784535bb93"}},"directories":{},"maintainers":[{"name":"brun0coe3","email":"brunocsncoelho@gmail.com"},{"name":"pmierzejewski-cbs","email":"piotr@chargebackstop.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/binlookupapi-ts-sdk_1.0.2_1779360229514_0.9486459031998515"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T08:44:56.758Z","modified":"2026-05-21T10:43:49.983Z","1.0.0":"2026-05-19T08:44:57.179Z","1.0.1":"2026-05-19T10:02:09.865Z","1.0.2":"2026-05-21T10:43:49.685Z"},"author":{"name":"BINLookupAPI"},"license":"MIT","keywords":["bin","lookup","card","payment","banking","typescript"],"description":"Official TypeScript SDK for BINLookupAPI","maintainers":[{"name":"brun0coe3","email":"brunocsncoelho@gmail.com"},{"name":"pmierzejewski-cbs","email":"piotr@chargebackstop.com"}],"readme":"# BINLookupAPI TypeScript SDK\n\nA production-ready, fully-typed TypeScript SDK for [BINLookupAPI.com](https://binlookupapi.com). Easily retrieve card network, issuing bank, country, and funding information from Bank Identification Numbers (BINs).\n\n---\n\n## Features\n\n- **Full TypeScript Support**\n  Comprehensive interfaces for all request and response objects.\n\n- **Resilient**\n  Built-in exponential backoff retry logic (`1s`, `2s`, `4s`, `8s`, `16s`) for transient network or server errors.\n\n- **Detailed Error Handling**\n  Custom `BINLookupAPIError` class mapping directly to API error codes.\n\n- **Quota Monitoring**\n  Automatic extraction of rate-limit headers:\n  - `X-Quota-Limit`\n  - `X-Quota-Remaining`\n\n- **Zero Dependencies**\n  Lightweight and uses the native `fetch` API.\n\n---\n\n## Installation\n\n```bash\nnpm i @binlookupapi/binlookupapi-ts-sdk\n# or\nyarn add @binlookupapi/binlookupapi-ts-sdk\n```\n\n---\n\n## Quick Start\n\n1. Sign up and get your free API Key here: https://app.binlookupapi.com/\n\n2.\n```ts\nimport { BINLookupClient, BINLookupAPIError } from '@binlookupapi/binlookupapi-ts-sdk';\n\nconst client = new BINLookupClient({\n  apiKey: 'your_api_key_here'\n});\n\nasync function checkCard(bin: string) {\n  try {\n    const result = await client.lookup(bin);\n\n    console.log(`Scheme: ${result.data.scheme}`); // e.g., \"visa\"\n    console.log(`Bank: ${result.data.issuer.name}`); // e.g., \"ING BANK SLASKI SA\"\n    console.log(`Country: ${result.data.country.name}`); // e.g., \"POLAND\"\n\n    // Check remaining daily quota\n    console.log(`Quota remaining: ${result.quota?.remaining}`);\n  } catch (error) {\n    if (error instanceof BINLookupAPIError) {\n      console.error(`API Error [${error.code}]: ${error.message}`);\n    } else {\n      console.error('An unexpected error occurred:', error);\n    }\n  }\n}\n\ncheckCard('42467101');\n```\n\n---\n\n## Configuration\n\nThe `BINLookupClient` constructor accepts a configuration object:\n\n| Property     | Type     | Default                              | Description                                      |\n|--------------|----------|--------------------------------------|--------------------------------------------------|\n| `apiKey`     | `string` | Required                             | Your API key from the dashboard.                 |\n| `baseUrl`    | `string` | `https://api.binlookupapi.com`       | Custom API endpoint (if using a proxy).          |\n| `maxRetries` | `number` | `5`                                  | Max retries for 5xx errors or network timeouts.  |\n\n---\n\n## API Reference\n\n### `.lookup(bin: number | string)`\n\nPerforms a `POST` request to `/v1/bin`.\n\nThe BIN must be between **4 and 8 digits**.\n\n---\n\n## Response Object (`BINLookupResponse`)\n\n### `data`\n\n| Field        | Description |\n|--------------|-------------|\n| `bin`        | The searched BIN. |\n| `scheme`     | `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`, `diners`, or `unknown`. |\n| `funding`    | `credit`, `debit`, `prepaid`, or `unknown`. |\n| `brand`      | Product name (e.g., `\"PLATINUM\"`). |\n| `country`    | `{ code: string, name: string }` |\n| `issuer`     | `{ name: string, website: string, phone: string }` |\n| `prepaid`    | `boolean` |\n| `commercial` | `boolean` |\n\n### `quota`\n\n| Field        | Description |\n|--------------|-------------|\n| `limit`      | Total daily allowance. |\n| `remaining`  | Requests left for the day. |\n| `reset`      | Unix timestamp of the next reset. |\n\n---\n\n## Error Handling\n\nThe SDK throws a `BINLookupAPIError` for non-200 responses.\n\n| Error Code         | Description                         |\n|--------------------|-------------------------------------|\n| `BAD_REQUEST`      | Invalid BIN format.                 |\n| `UNAUTHORIZED`     | API key is missing or invalid.      |\n| `PAYMENT_REQUIRED` | No active subscription.             |\n| `NOT_FOUND`        | BIN not in database.                |\n| `QUOTA_EXCEEDED`   | Daily limit reached.                |\n| `SERVICE_ERROR`    | Internal API error.                 |\n\n---\n\n## Best Practices\n\n- **Caching**\n  BIN data rarely changes. Cache results for **24–48 hours** to reduce quota usage.\n\n- **Environment Variables**\n  Never hardcode your API key. Use:\n\n  ```bash\n  process.env.BIN_API_KEY\n  ```\n\n- **8-Digit BINs**\n  When possible, provide **8 digits** for the highest accuracy.\n\n---\n\n## Support\n\n- Documentation: https://binlookupapi.com/docs\n- Support: https://binlookupapi.com/contact\n","readmeFilename":"readme.md","homepage":"https://github.com/binlookupapi/binlookupapi-ts-sdk#readme","repository":{"type":"git","url":"git+https://github.com/binlookupapi/binlookupapi-ts-sdk.git"},"bugs":{"url":"https://github.com/binlookupapi/binlookupapi-ts-sdk/issues"}}