{"_id":"@apiddress/sdk","_rev":"2-b7e8d5cc3b05e7f6244e7807500f4844","name":"@apiddress/sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@apiddress/sdk","version":"0.1.0","keywords":["email","validation","email-verification","apiddress"],"license":"MIT","_id":"@apiddress/sdk@0.1.0","maintainers":[{"name":"ath_yaya","email":"yanis@apiddress.com"}],"dist":{"shasum":"17f25ae6fe38e06fb55c4d98e9720ac88ab8325b","tarball":"https://registry.npmjs.org/@apiddress/sdk/-/sdk-0.1.0.tgz","fileCount":19,"integrity":"sha512-ZlrEqhgX2i1sdf/N6B7cVyWRB5yzgxxYC1M7/ylogHcxjYSc1CfGuT5wllj6qs3FHCwtOjKH/LedVLzfNfAyrA==","signatures":[{"sig":"MEQCIHsu76SLlFNtGpSAxAyQyi2nJYJi09ySlHWVVeTBBCOBAiA0biW0MEhzniz3gLmk6ZQIoDDcIjlyXeju9nTyEoic/g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32006},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"7d273b2e01473f4c31415c4b2eb0e8b6aee47cd0","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json"},"_npmUser":{"name":"ath_yaya","email":"yanis@apiddress.com"},"_npmVersion":"11.3.0","description":"Official Node.js SDK for the APIddress email validation API","directories":{},"_nodeVersion":"24.2.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.8.0","@types/node":"^22.15.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1781304592286_0.6146951150311268","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@apiddress/sdk","version":"0.1.1","description":"Official Node.js SDK for the APIddress email validation API","keywords":["email","validation","email-verification","apiddress"],"license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run"},"devDependencies":{"@types/node":"^22.15.0","typescript":"^5.8.0","vitest":"^3.1.0"},"_id":"@apiddress/sdk@0.1.1","gitHead":"7d273b2e01473f4c31415c4b2eb0e8b6aee47cd0","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-EFSAI+vetjEwb1YPNNOOA+uNqShGYADJe31dXmBMT6WsyV9GgfI+qS5aVZo8TURnxXKYuTQTNgbA5C6PNVYYwg==","shasum":"27cdbcc2cabd331cbd5fa1617d4404a2137f83a4","tarball":"https://registry.npmjs.org/@apiddress/sdk/-/sdk-0.1.1.tgz","fileCount":19,"unpackedSize":32044,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD+7WM9F508PM0d8rLEOI+prS1a38D5g9NfkZuXuWSe1QIgWEYiIm9stT/azfaIPpiVzQ1UiAvQ32oii4qnUAnVU5Y="}]},"_npmUser":{"name":"ath_yaya","email":"yanis@apiddress.com"},"directories":{},"maintainers":[{"name":"ath_yaya","email":"yanis@apiddress.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.1_1781304880991_0.6920927131497117"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T22:49:52.159Z","modified":"2026-06-12T22:54:41.251Z","0.1.0":"2026-06-12T22:49:52.460Z","0.1.1":"2026-06-12T22:54:41.132Z"},"license":"MIT","keywords":["email","validation","email-verification","apiddress"],"description":"Official Node.js SDK for the APIddress email validation API","maintainers":[{"name":"ath_yaya","email":"yanis@apiddress.com"}],"readme":"# apiddress\n\nOfficial Node.js SDK for the [APIddress](https://apiddress.com) email validation API.\n\n- Zero runtime dependencies (built on global `fetch`)\n- Node 18+, ESM, full TypeScript types\n- Automatic retry with backoff on `429` and `5xx` (batch creation is never retried)\n\n## Install\n\n```bash\nnpm install @apiddress/sdk\n```\n\n## Quickstart\n\n```js\nimport { APIddress } from \"@apiddress/sdk\";\n\nconst client = new APIddress(\"YOUR_API_KEY\");\n\nconst result = await client.validateEmail(\"ada@stripe.com\");\nconsole.log(result.status); // \"valid\"\nconsole.log(result.score);  // 0.98\n```\n\n## Configuration\n\n```js\nconst client = new APIddress(\"YOUR_API_KEY\", {\n  baseUrl: \"https://api.apiddress.com\", // default\n  timeoutMs: 10_000,                    // per-request timeout, default 10s\n  maxRetries: 2,                        // retries on 429/5xx, default 2\n});\n```\n\n## Usage\n\n### Validate one email\n\n```js\nconst result = await client.validateEmail(\"john@company.com\", {\n  check_smtp: false,       // default\n  allow_role_based: true,  // default\n});\n// result.status: \"valid\" | \"invalid\" | \"risky\" | \"disposable\" | \"unknown\"\n// result.suggestion: \"john@gmail.com\" for typo-like addresses, else null\n// result.checks: { syntax, domain_exists, mx, smtp, disposable, ... }\n```\n\nA malformed value (e.g. `\"not-an-email\"`) is a verdict, not an error: you get\n`status: \"invalid\"` with `reason: \"invalid_syntax\"`.\n\n### Validate up to 100 emails synchronously\n\n```js\nconst { count, results } = await client.validateEmails([\n  \"a@example.com\",\n  \"b@example.com\",\n]);\n```\n\n### Batch jobs (up to 5000 emails)\n\n```js\nconst batch = await client.createBatch(emails, {\n  callback_url: \"https://yourapp.com/webhooks/apiddress\", // optional\n});\n\nconst done = await client.waitForBatch(batch.batch_id, {\n  pollMs: 1_000,     // default\n  timeoutMs: 60_000, // default\n});\nconsole.log(done.status, done.results.length);\n\n// Or poll yourself:\nconst status = await client.getBatch(batch.batch_id);\n```\n\n`waitForBatch` resolves with the terminal state (`\"completed\"` or `\"failed\"`) —\ncheck `status` before using `results`.\n\n### Account\n\n```js\nconst profile = await client.me();        // plan, limits, usage\nconst usage = await client.usage();       // current month\nconst may = await client.usage(\"2026-05\"); // specific month\nconst health = await client.health();     // no auth required\n```\n\n## Error handling\n\nEvery failed request throws an `APIddressError`:\n\n```js\nimport { APIddress, APIddressError } from \"@apiddress/sdk\";\n\ntry {\n  await client.validateEmail(\"john@company.com\");\n} catch (err) {\n  if (err instanceof APIddressError) {\n    console.error(err.status, err.code, err.message, err.details);\n    // 429 quota_exceeded \"Monthly request limit exceeded.\" { requests_used: ..., requests_limit: ... }\n  }\n}\n```\n\n| `status` | `code` |\n| -------- | ------------------ |\n| 400 | `invalid_request` |\n| 401 | `unauthorized` |\n| 404 | `not_found` |\n| 429 | `quota_exceeded` |\n| 500 | `internal_error` |\n| 0 | `timeout` (request or `waitForBatch` timeout) |\n\n## Development\n\n```bash\nnpm install\nnpm run build   # tsc -> dist/ (ESM + .d.ts)\n\n# Integration tests need a live backend:\nAPIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev npm test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}