{"_id":"@abdullah5603/api-response-kit","_rev":"2-55742774395fd54314379fe49efafa79","name":"@abdullah5603/api-response-kit","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@abdullah5603/api-response-kit","version":"0.1.0","keywords":["api","response","express","node","http","json","typescript"],"author":{"name":"Abdullah"},"license":"MIT","_id":"@abdullah5603/api-response-kit@0.1.0","maintainers":[{"name":"abdullah5603","email":"abdullah72308@gmail.com"}],"homepage":"https://github.com/Abdullah-5603/api-response-kit#readme","bugs":{"url":"https://github.com/Abdullah-5603/api-response-kit/issues"},"dist":{"shasum":"78d0540ca56a0775a3ef2f36837335d968245757","tarball":"https://registry.npmjs.org/@abdullah5603/api-response-kit/-/api-response-kit-0.1.0.tgz","fileCount":10,"integrity":"sha512-2PNLFpXBV+wRDqyHwYVHF4J7b1TrYZktLRYdlvZp8p8YRbTHAsXuN2/NvFMwCc+zkxliXkv/BSx3v25hI7ZtVQ==","signatures":[{"sig":"MEYCIQDoWpoLyAsFXcvLHbRusWUF2pKF/X39VlVupRfWXe6OgQIhAObmXNM1MbqUecy7glyoT8Ds3Kx+fi6TQ52IUoEYl+MS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":83068},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"f35cd79633f4e5ebaece972b97a8001851289d09","scripts":{"lint":"prettier --check .","test":"vitest run","build":"tsup","clean":"node ./scripts/clean.mjs","format":"prettier --write .","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run clean && npm run lint && npm run typecheck && npm run test && npm run build"},"_npmUser":{"name":"abdullah5603","email":"abdullah72308@gmail.com"},"repository":{"url":"git+https://github.com/Abdullah-5603/api-response-kit.git","type":"git"},"_npmVersion":"11.11.0","description":"Small, dependency-light TypeScript helpers for standardized API responses in Node.js and Express-style backends.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"npm@11.11.0","devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.4","prettier":"^3.8.2","typescript":"^5.9.3","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/api-response-kit_0.1.0_1777731738641_0.40738770893641973","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@abdullah5603/api-response-kit","version":"0.1.1","description":"Small, dependency-light TypeScript helpers for standardized API responses in Node.js and Express-style backends.","keywords":["api","response","express","node","http","json","typescript"],"homepage":"https://github.com/Abdullah-5603/api-response-kit#readme","repository":{"type":"git","url":"git+https://github.com/Abdullah-5603/api-response-kit.git"},"bugs":{"url":"https://github.com/Abdullah-5603/api-response-kit/issues"},"license":"MIT","author":{"name":"Abdullah"},"type":"module","packageManager":"npm@11.11.0","sideEffects":false,"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","default":"./dist/index.js"},"./package.json":"./package.json"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"scripts":{"clean":"node ./scripts/clean.mjs","build":"tsup","test":"vitest run","test:watch":"vitest","lint":"prettier --check .","format":"prettier --write .","typecheck":"tsc --noEmit","prepublishOnly":"npm run clean && npm run lint && npm run typecheck && npm run test && npm run build"},"devDependencies":{"@types/node":"^25.6.0","prettier":"^3.8.2","tsup":"^8.5.1","typescript":"^5.9.3","vitest":"^4.1.4"},"gitHead":"256aec55aa6c8a4923d407a8b615e309d83f233d","_id":"@abdullah5603/api-response-kit@0.1.1","_nodeVersion":"22.22.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-3KPSQQ/2nCRNHAWPz0if0rVqTDHtv7khEPfLAbmKGC+WNODPvTEhcJcFgCqafSJXkOrYXOwA0sGNhCNNcyXXHA==","shasum":"e0e8bcc772165d8490dd16d32e5268888bebf284","tarball":"https://registry.npmjs.org/@abdullah5603/api-response-kit/-/api-response-kit-0.1.1.tgz","fileCount":10,"unpackedSize":83120,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCdaWtVPriHubWxmfF1TXExnuHEUH6y6SWm+4zPWdn6NgIgZEyXLoMuBPEE5sElkcwY8PLpIt6rkPt/2FrzF6aGXoo="}]},"_npmUser":{"name":"abdullah5603","email":"abdullah72308@gmail.com"},"directories":{},"maintainers":[{"name":"abdullah5603","email":"abdullah72308@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/api-response-kit_0.1.1_1777732823926_0.66531943198548"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-02T14:22:18.558Z","modified":"2026-05-02T14:40:24.198Z","0.1.0":"2026-05-02T14:22:18.828Z","0.1.1":"2026-05-02T14:40:24.096Z"},"bugs":{"url":"https://github.com/Abdullah-5603/api-response-kit/issues"},"author":{"name":"Abdullah"},"license":"MIT","homepage":"https://github.com/Abdullah-5603/api-response-kit#readme","keywords":["api","response","express","node","http","json","typescript"],"repository":{"type":"git","url":"git+https://github.com/Abdullah-5603/api-response-kit.git"},"description":"Small, dependency-light TypeScript helpers for standardized API responses in Node.js and Express-style backends.","maintainers":[{"name":"abdullah5603","email":"abdullah72308@gmail.com"}],"readme":"# @abdullah5603/api-response-kit\n\nSmall, dependency-light TypeScript helpers for standardized API responses in Node.js and Express-style backends.\n\n## Purpose\n\n`@abdullah5603/api-response-kit` gives you a compact set of response builders that keep API payloads consistent across services, controllers, and middleware. It is ESM-first, ships CommonJS output, generates declaration files, and keeps runtime dependencies at zero.\n\n## Installation\n\n```bash\nnpm install @abdullah5603/api-response-kit\n```\n\n## Quick Start\n\n```ts\nimport { badRequest, ok } from '@abdullah5603/api-response-kit';\n\nconst success = ok(\n  {\n    user: {\n      id: 'u_123',\n      name: 'Ada Lovelace',\n    },\n  },\n  { request_id: 'req_123' }\n);\n\nconst failure = badRequest('Validation failed', [\n  { field: 'email', message: 'Email is required' },\n]);\n```\n\nSuccess payloads look like this:\n\n```json\n{\n  \"success\": true,\n  \"status_code\": 200,\n  \"message\": \"OK\",\n  \"data\": {\n    \"user\": {\n      \"id\": \"u_123\",\n      \"name\": \"Ada Lovelace\"\n    }\n  },\n  \"meta\": {\n    \"request_id\": \"req_123\"\n  }\n}\n```\n\nError payloads look like this:\n\n```json\n{\n  \"success\": false,\n  \"status_code\": 400,\n  \"message\": \"Validation failed\",\n  \"errors\": [\n    {\n      \"field\": \"email\",\n      \"message\": \"Email is required\"\n    }\n  ]\n}\n```\n\n## API Reference\n\n### Success Helpers\n\n- `ok(data, meta?)`\n- `created(data, meta?)`\n- `accepted(data, meta?)`\n- `noContent(meta?)`\n\n### Error Helpers\n\n- `badRequest(message?, errors?, meta?)`\n- `unauthorized(message?, meta?)`\n- `forbidden(message?, meta?)`\n- `notFound(message?, meta?)`\n- `conflict(message?, meta?)`\n- `unprocessableEntity(message?, errors?, meta?)`\n- `tooManyRequests(message?, meta?)`\n- `error(message?, meta?)`\n\n### Advanced Helpers\n\n- `custom({ success, status_code, message, data, errors, meta })`\n- `send(res, payload)`\n- `isSuccessStatus(statusCode)`\n- `isErrorStatus(statusCode)`\n- `paginationMeta({ page, limit, total, total_pages? })`\n- `mergeMeta(...metaObjects)`\n\n### Exported Types\n\n- `ApiResponse`\n- `BaseResponse`\n- `SuccessResponse`\n- `ErrorResponse`\n- `CustomResponseInput`\n- `Meta`\n- `MetaValue`\n- `PaginationDetails`\n- `PaginationMetaInput`\n- `ExpressLikeResponse`\n- `ResponseDispatcher`\n\n## Express Usage\n\n```ts\nimport { notFound, ok, send } from '@abdullah5603/api-response-kit';\n\nexport async function getUser(req, res) {\n  const user = await findUserById(req.params.id);\n\n  if (!user) {\n    return send(res, notFound('User not found'));\n  }\n\n  return send(res, ok(user, { request_id: req.id }));\n}\n```\n\n`send()` uses `res.status(...).json(...)` for standard responses and `res.status(204).send()` for `noContent()` payloads.\n\n## Custom Response Example\n\n```ts\nimport { custom } from '@abdullah5603/api-response-kit';\n\nconst payload = custom({\n  success: false,\n  status_code: 409,\n  message: 'Slug already exists',\n  errors: [{ field: 'slug', code: 'duplicate' }],\n  meta: { request_id: 'req_409' },\n});\n```\n\n## Pagination Example\n\n```ts\nimport { mergeMeta, ok, paginationMeta } from '@abdullah5603/api-response-kit';\n\nconst meta = mergeMeta(paginationMeta({ page: 2, limit: 25, total: 87 }), {\n  request_id: 'req_page_2',\n});\n\nconst payload = ok(\n  [\n    { id: 'u_1', name: 'Ada' },\n    { id: 'u_2', name: 'Linus' },\n  ],\n  meta\n);\n```\n\n## TypeScript Usage Example\n\n```ts\nimport type { SuccessResponse } from '@abdullah5603/api-response-kit';\nimport { ok } from '@abdullah5603/api-response-kit';\n\ntype User = {\n  id: string;\n  name: string;\n};\n\nconst payload: SuccessResponse<User, 200> = ok({\n  id: 'u_123',\n  name: 'Ada Lovelace',\n});\n```\n\n## Error Response Examples\n\n```ts\nimport {\n  badRequest,\n  tooManyRequests,\n  unprocessableEntity,\n} from '@abdullah5603/api-response-kit';\n\nbadRequest('Missing fields', [{ field: 'email' }]);\nunprocessableEntity('Invalid input', { email: ['Already used'] });\ntooManyRequests();\n```\n\n## Development Scripts\n\n- `npm run clean`\n- `npm run build`\n- `npm run test`\n- `npm run test:watch`\n- `npm run lint`\n- `npm run format`\n- `npm run typecheck`\n\n## Design Notes\n\n- Returns plain serializable objects.\n- Never mutates caller input.\n- Omits `undefined` keys from output.\n- Keeps the public API intentionally small.\n- Treats invalid usage as a developer error with explicit exceptions.\n\n## Publishing Notes\n\n- The package is scoped and intended for public npm publishing: `@abdullah5603/api-response-kit`.\n- Build output is generated into `dist/`.\n- Declaration files are emitted alongside the ESM and CommonJS builds.\n- `prepublishOnly` runs clean, lint, typecheck, tests, and build before publishing.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}