{"_rev":"4-48fc74d840f75ad40f9689031f0f2fbc","time":{"created":"2026-05-14T17:25:50.907Z","modified":"2026-05-14T17:25:51.501Z","0.1.0":"2026-05-14T17:19:19.465Z","0.1.1":"2026-05-14T17:25:51.179Z"},"_id":"@api-gouv-dinum/api-particulier","name":"@api-gouv-dinum/api-particulier","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@api-gouv-dinum/api-particulier","version":"0.1.1","description":"Official Node.js client for API Particulier v3","type":"module","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest"},"engines":{"node":">=18.0.0"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/datagouv/apistration.git","directory":"clients/node/api-particulier"},"keywords":["api-particulier","api-gouv","france"],"devDependencies":{"@types/node":"^25.8.0","tsup":"^8.0.0","typescript":"^5.4.0","vitest":"^3.0.0"},"_id":"@api-gouv-dinum/api-particulier@0.1.1","bugs":{"url":"https://github.com/datagouv/apistration/issues"},"homepage":"https://github.com/datagouv/apistration#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-x7+1Au7C55zhG3EaFk+x0Nlll35jqgSuEyWEztgRv57WsqoWVUcaHy13Iec+5kEJS9xy4KM0/NrupYbSJEITHQ==","shasum":"1e993293d900fc878380b4482142b63237d98e06","tarball":"https://registry.npmjs.org/@api-gouv-dinum/api-particulier/-/api-particulier-0.1.1.tgz","fileCount":9,"unpackedSize":312864,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGxrvfd/x8PUt6PauGhwJYaZioss0vBMU2+fO/fj7P2eAiEA5mh3aWllfoYFeDLyMB6YPw3basleumRrKNraCqUFNMQ="}]},"_npmUser":{"name":"api-gouv","email":"equipe@entreprise.api.gouv.fr"},"directories":{},"maintainers":[{"name":"api-gouv","email":"equipe@entreprise.api.gouv.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/api-particulier_0.1.1_1778779551030_0.9914473782067974"},"_hasShrinkwrap":false}},"maintainers":[{"name":"api-gouv","email":"equipe@entreprise.api.gouv.fr"}],"description":"Official Node.js client for API Particulier v3","homepage":"https://github.com/datagouv/apistration#readme","keywords":["api-particulier","api-gouv","france"],"repository":{"type":"git","url":"git+https://github.com/datagouv/apistration.git","directory":"clients/node/api-particulier"},"bugs":{"url":"https://github.com/datagouv/apistration/issues"},"license":"MIT","readme":"# @api-gouv-dinum/api-particulier\n\nOfficial Node.js client for [API Particulier v3](https://particulier.api.gouv.fr).\n\n## Installation\n\n```bash\nnpm install @api-gouv-dinum/api-particulier\n```\n\nRequires Node.js >= 18.0.0 (uses native `fetch`).\n\n## Configuration\n\n```typescript\nimport { Client } from '@api-gouv-dinum/api-particulier';\n\nconst client = new Client({\n  token: 'your-jwt-token',\n  environment: 'production', // or 'staging'\n  defaultParams: {\n    recipient: '13002526500013', // SIRET of your administration\n  },\n});\n```\n\nEnvironment variables are also supported:\n- `API_PARTICULIER_TOKEN`\n- `API_PARTICULIER_ENV` (`production` | `staging`)\n- `API_PARTICULIER_BASE_URL` (custom override)\n\n## Quickstart\n\n```typescript\n// Using the low-level escape hatch\nconst response = await client.get('/v3/dss/quotient_familial/identite', {\n  params: {\n    nom: 'Dupont',\n    prenoms: ['Jean'],\n    date_de_naissance: '1990-01-01',\n  },\n});\n\nconsole.log(response.data);\nconsole.log(response.rateLimit);\n```\n\nTyped resource methods are also available:\n\n```typescript\nconst response = await client.dss.quotient_familial_identite(/* params */);\n```\n\n## Error handling\n\n```typescript\nimport {\n  RateLimitError,\n  ProviderError,\n  ValidationError,\n  TransportError,\n} from '@api-gouv-dinum/api-particulier';\n\ntry {\n  await client.get('/v3/dss/quotient_familial/identite', { params: { ... } });\n} catch (error) {\n  if (error instanceof RateLimitError) {\n    console.log('Retry after', error.retryAfter, 'seconds');\n  } else if (error instanceof ProviderError) {\n    console.log('Provider down, retry in', error.retryAfter, 's');\n  }\n}\n```\n\n## Testing\n\nStub the global `fetch`. API Particulier logs redact query strings by default (PII protection).\n\n### Stubbing a 200 response\n\n```typescript\nimport { Client } from '@api-gouv-dinum/api-particulier';\nimport { vi } from 'vitest';\n\nglobalThis.fetch = vi.fn().mockResolvedValue({\n  ok: true,\n  status: 200,\n  text: () => Promise.resolve(JSON.stringify({\n    data: { quotient_familial: 1500 },\n    links: {},\n    meta: {},\n  })),\n  headers: new Headers({\n    'RateLimit-Limit': '50',\n    'RateLimit-Remaining': '49',\n    'RateLimit-Reset': String(Math.floor(Date.now() / 1000) + 60),\n  }),\n});\n\nconst client = new Client({\n  token: 'test-token',\n  environment: 'staging',\n  defaultParams: { recipient: '41816609600069' },\n});\n\nconst response = await client.get('/v3/dss/quotient_familial/identite');\nexpect(response.data.quotient_familial).toBe(1500);\nexpect(response.rateLimit!.remaining).toBe(49);\n```\n\n### Stubbing a 429 rate limit\n\n```typescript\nconst futureReset = Math.floor(Date.now() / 1000) + 30;\n\nglobalThis.fetch = vi.fn().mockResolvedValue({\n  ok: false,\n  status: 429,\n  text: () => Promise.resolve(JSON.stringify({\n    errors: [{ code: '00429', title: 'Too Many Requests' }],\n  })),\n  headers: new Headers({ 'RateLimit-Reset': String(futureReset) }),\n});\n\ntry {\n  await client.get('/v3/test');\n} catch (error) {\n  expect(error).toBeInstanceOf(RateLimitError);\n  expect(error.retryAfter).toBeGreaterThan(0);\n}\n```\n","readmeFilename":"README.md"}