{"_id":"@antfu/experimental-logs-sdk","_rev":"4-975da175d6bbbda17d0eae2362fdf95f","name":"@antfu/experimental-logs-sdk","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.0":{"name":"@antfu/experimental-logs-sdk","version":"0.0.0","keywords":[],"author":{"name":"Anthony Fu","email":"anthonyfu117@hotmail.com"},"license":"MIT","_id":"@antfu/experimental-logs-sdk@0.0.0","maintainers":[{"name":"antfu","email":"anthonyfu117@hotmail.com"}],"homepage":"https://github.com/antfu/logs-sdk#readme","bugs":{"url":"https://github.com/antfu/logs-sdk/issues"},"dist":{"shasum":"1f5aa5e3f51cbbf5819f1fbd404c1a9964629373","tarball":"https://registry.npmjs.org/@antfu/experimental-logs-sdk/-/experimental-logs-sdk-0.0.0.tgz","fileCount":10,"integrity":"sha512-zYMEEYZuhSZMzNOLwRQ7gTt2/TgYPGhO6QI59iM79yvknYcYwtvBdjili0Gs/DaY5l+1m9n8I1S9pbefUNKa4g==","signatures":[{"sig":"MEQCIEQX3ZfcFJk78xYrgOJUHhkqo55l5j8KcrzrJk/QiUTjAiB5cR0umC8sAfzk9z2vARFQZ2wW7lSDuzBOu7F87K0yDw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19144},"main":"./dist/index.mjs","type":"module","_from":"file:antfu-experimental-logs-sdk-0.0.0.tgz","types":"./dist/index.d.mts","module":"./dist/index.mjs","exports":{".":"./dist/index.mjs","./package.json":"./package.json","./formatters/ansi":"./dist/formatters/ansi.mjs","./formatters/json":"./dist/formatters/json.mjs"},"funding":"https://github.com/sponsors/antfu","scripts":{"dev":"tsdown --watch","lint":"eslint","test":"vitest","build":"tsdown","start":"tsx src/index.ts","release":"bumpp","typecheck":"tsc"},"_npmUser":{"name":"antfu","email":"anthonyfu117@hotmail.com"},"_resolved":"/private/var/folders/k2/15r3mnl91_711l9vkdk1hjtw0000gn/T/f77325fc8e68de5b19fe2a750287dbce/antfu-experimental-logs-sdk-0.0.0.tgz","_integrity":"sha512-zYMEEYZuhSZMzNOLwRQ7gTt2/TgYPGhO6QI59iM79yvknYcYwtvBdjili0Gs/DaY5l+1m9n8I1S9pbefUNKa4g==","repository":{"url":"git+https://github.com/antfu/logs-sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"Structured diagnostic code library","directories":{},"lint-staged":{"*":"eslint --fix"},"sideEffects":false,"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vite":"^7.3.1","yaml":"^2.8.2","bumpp":"^10.4.0","eslint":"^9.39.2","tsdown":"^0.17.3","vitest":"^4.0.17","publint":"^0.3.16","tinyexec":"^1.0.2","@antfu/ni":"^28.2.0","typescript":"^5.9.3","@types/node":"^25.0.9","lint-staged":"^16.2.7","@antfu/utils":"^9.3.0","simple-git-hooks":"^2.13.1","@antfu/eslint-config":"^7.0.1","vitest-package-exports":"^1.1.2","rolldown-plugin-dts-snapshot":"^0.3.2"},"simple-git-hooks":{"pre-commit":"pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/experimental-logs-sdk_0.0.0_1775611592917_0.7648172372981268","host":"s3://npm-registry-packages-npm-production"}},"0.0.1":{"name":"@antfu/experimental-logs-sdk","version":"0.0.1","keywords":[],"author":{"name":"Anthony Fu","email":"anthonyfu117@hotmail.com"},"license":"MIT","_id":"@antfu/experimental-logs-sdk@0.0.1","maintainers":[{"name":"antfu","email":"anthonyfu117@hotmail.com"}],"homepage":"https://github.com/antfu/logs-sdk#readme","bugs":{"url":"https://github.com/antfu/logs-sdk/issues"},"dist":{"shasum":"009f8ab34008ad5f2a3b0a4c0f9de8e792ce3980","tarball":"https://registry.npmjs.org/@antfu/experimental-logs-sdk/-/experimental-logs-sdk-0.0.1.tgz","fileCount":11,"integrity":"sha512-wo2SnNimhWlXk7ZgvR6oueTu57EesG6ixQiPxCqPw44HQ+f5woV63AiPczkOFiMcJzeblzGk/2BBmzZ9BSEvEw==","signatures":[{"sig":"MEQCIEDWzLyaeku5PY1qEJvKm45rd9og1Hzlm3ZZEep+HGCoAiBg46+Tu2FqmZWaq60cV+26U69wK1nr+Tl9I68cfmpEHA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34767},"main":"./dist/index.mjs","type":"module","_from":"file:antfu-experimental-logs-sdk-0.0.1.tgz","types":"./dist/index.d.mts","module":"./dist/index.mjs","exports":{".":"./dist/index.mjs","./package.json":"./package.json","./formatters/ansi":"./dist/formatters/ansi.mjs","./formatters/json":"./dist/formatters/json.mjs"},"funding":"https://github.com/sponsors/antfu","scripts":{"dev":"tsdown --watch","lint":"eslint","test":"vitest","build":"tsdown","start":"tsx src/index.ts","release":"bumpp","typecheck":"tsc"},"_npmUser":{"name":"antfu","email":"anthonyfu117@hotmail.com"},"_resolved":"/private/var/folders/k2/15r3mnl91_711l9vkdk1hjtw0000gn/T/facaaf4be94859ca1fd773c5886d0aa0/antfu-experimental-logs-sdk-0.0.1.tgz","_integrity":"sha512-wo2SnNimhWlXk7ZgvR6oueTu57EesG6ixQiPxCqPw44HQ+f5woV63AiPczkOFiMcJzeblzGk/2BBmzZ9BSEvEw==","repository":{"url":"git+https://github.com/antfu/logs-sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"Structured diagnostic code library","directories":{},"lint-staged":{"*":"eslint --fix"},"sideEffects":false,"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vite":"^7.3.1","yaml":"^2.8.2","bumpp":"^10.4.0","eslint":"^9.39.2","tsdown":"^0.17.3","vitest":"^4.0.17","publint":"^0.3.16","tinyexec":"^1.0.2","@antfu/ni":"^28.2.0","typescript":"^5.9.3","@types/node":"^25.0.9","lint-staged":"^16.2.7","@antfu/utils":"^9.3.0","simple-git-hooks":"^2.13.1","@antfu/eslint-config":"^7.0.1","vitest-package-exports":"^1.1.2","rolldown-plugin-dts-snapshot":"^0.3.2"},"simple-git-hooks":{"pre-commit":"pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/experimental-logs-sdk_0.0.1_1775612270921_0.8427210124163518","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@antfu/experimental-logs-sdk","version":"0.0.2","keywords":[],"author":{"name":"Anthony Fu","email":"anthonyfu117@hotmail.com"},"license":"MIT","_id":"@antfu/experimental-logs-sdk@0.0.2","maintainers":[{"name":"antfu","email":"anthonyfu117@hotmail.com"}],"homepage":"https://github.com/antfu/logs-sdk#readme","bugs":{"url":"https://github.com/antfu/logs-sdk/issues"},"dist":{"shasum":"454435d170626f71ea21ace9b4f95137e8ca122f","tarball":"https://registry.npmjs.org/@antfu/experimental-logs-sdk/-/experimental-logs-sdk-0.0.2.tgz","fileCount":12,"integrity":"sha512-qvXEI4ZoO7UJ7Jreslj+8yqUTj+6Rvkd1zTt1cZ9lvrCvLgc7X5ANwIYyhHsVnF88mgGl2p0oKzP2Svif57hgg==","signatures":[{"sig":"MEUCIQChXarspvpakm+4mveNfqi+EesN7NaHBtNvqF/QNQdcmAIgPjrgkNfYjzQRAdWcoIo588sOPiRL+Fmd/15GFKUAgTQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36697},"main":"./dist/index.mjs","type":"module","_from":"file:antfu-experimental-logs-sdk-0.0.2.tgz","types":"./dist/index.d.mts","module":"./dist/index.mjs","exports":{".":"./dist/index.mjs","./package.json":"./package.json","./formatters/ansi":"./dist/formatters/ansi.mjs","./formatters/json":"./dist/formatters/json.mjs"},"funding":"https://github.com/sponsors/antfu","scripts":{"dev":"tsdown --watch","lint":"eslint","test":"vitest","build":"tsdown","start":"tsx src/index.ts","release":"bumpp","typecheck":"tsc"},"_npmUser":{"name":"antfu","email":"anthonyfu117@hotmail.com"},"_resolved":"/private/var/folders/k2/15r3mnl91_711l9vkdk1hjtw0000gn/T/83802eec3a72603fdd002317117883f5/antfu-experimental-logs-sdk-0.0.2.tgz","_integrity":"sha512-qvXEI4ZoO7UJ7Jreslj+8yqUTj+6Rvkd1zTt1cZ9lvrCvLgc7X5ANwIYyhHsVnF88mgGl2p0oKzP2Svif57hgg==","repository":{"url":"git+https://github.com/antfu/logs-sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"Structured diagnostic code library","directories":{},"lint-staged":{"*":"eslint --fix"},"sideEffects":false,"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vite":"^7.3.1","yaml":"^2.8.2","bumpp":"^10.4.0","eslint":"^9.39.2","tsdown":"^0.17.3","vitest":"^4.0.17","publint":"^0.3.16","tinyexec":"^1.0.2","@antfu/ni":"^28.2.0","typescript":"^5.9.3","@types/node":"^25.0.9","lint-staged":"^16.2.7","@antfu/utils":"^9.3.0","simple-git-hooks":"^2.13.1","@antfu/eslint-config":"^7.0.1","vitest-package-exports":"^1.1.2","rolldown-plugin-dts-snapshot":"^0.3.2"},"simple-git-hooks":{"pre-commit":"pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/experimental-logs-sdk_0.0.2_1775621790924_0.999163357472197","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@antfu/experimental-logs-sdk","type":"module","version":"0.0.3","description":"Structured diagnostic code library","author":{"name":"Anthony Fu","email":"anthonyfu117@hotmail.com"},"license":"MIT","funding":"https://github.com/sponsors/antfu","homepage":"https://github.com/antfu/logs-sdk#readme","repository":{"type":"git","url":"git+https://github.com/antfu/logs-sdk.git"},"bugs":{"url":"https://github.com/antfu/logs-sdk/issues"},"keywords":[],"sideEffects":false,"exports":{".":"./dist/index.mjs","./formatters/ansi":"./dist/formatters/ansi.mjs","./formatters/json":"./dist/formatters/json.mjs","./rolldown":"./dist/rolldown.mjs","./unplugin":"./dist/unplugin.mjs","./vite":"./dist/vite.mjs","./package.json":"./package.json"},"types":"./dist/index.d.mts","peerDependencies":{"magic-string":">=0.30.0","oxc-parser":">=0.50.0","unplugin":">=2.0.0"},"peerDependenciesMeta":{"magic-string":{"optional":true},"oxc-parser":{"optional":true},"unplugin":{"optional":true}},"devDependencies":{"@antfu/eslint-config":"^8.1.0","@antfu/ni":"^30.0.0","@antfu/utils":"^9.3.0","@types/node":"^25.5.2","bumpp":"^11.0.1","esbuild":"^0.28.0","eslint":"^10.2.0","lint-staged":"^16.4.0","magic-string":"^0.30.21","oxc-parser":"^0.124.0","publint":"^0.3.18","rolldown-plugin-dts-snapshot":"^0.4.0","simple-git-hooks":"^2.13.1","tinyexec":"^1.1.1","tsdown":"^0.21.7","tsx":"^4.21.0","typescript":"^6.0.2","unplugin":"^3.0.0","vite":"^8.0.7","vitest":"^4.1.3","vitest-package-exports":"^1.2.0","yaml":"^2.8.3"},"simple-git-hooks":{"pre-commit":"pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"},"lint-staged":{"*":"eslint --fix"},"scripts":{"build":"tsdown","dev":"tsdown --watch","lint":"eslint","release":"bumpp","start":"tsx src/index.ts","test":"vitest","typecheck":"tsc"},"_id":"@antfu/experimental-logs-sdk@0.0.3","_integrity":"sha512-qaxCGIEuFAzk3PVy2yAvVsVtpty8mIGjoN5PY9jSeR8FGnHbDS+c3vJTgdriWiwwl8QWpit+pGq8KgMlHc9W6Q==","_resolved":"/private/var/folders/k2/15r3mnl91_711l9vkdk1hjtw0000gn/T/daa7b3fcd7842a5e45ea5b922b387755/antfu-experimental-logs-sdk-0.0.3.tgz","_from":"file:antfu-experimental-logs-sdk-0.0.3.tgz","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-qaxCGIEuFAzk3PVy2yAvVsVtpty8mIGjoN5PY9jSeR8FGnHbDS+c3vJTgdriWiwwl8QWpit+pGq8KgMlHc9W6Q==","shasum":"a3185e5921558963b74c765e126149217b30bcc0","tarball":"https://registry.npmjs.org/@antfu/experimental-logs-sdk/-/experimental-logs-sdk-0.0.3.tgz","fileCount":20,"unpackedSize":48282,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDMgcJlZ4WQPvCT5J47CB92oRhkQZ4NFAbOvwsucHyOTAIgQCw7oSMDHg5I5ghQyY9mRKzu8Mj9k/VI4WkGjeLt1dY="}]},"_npmUser":{"name":"antfu","email":"anthonyfu117@hotmail.com"},"directories":{},"maintainers":[{"name":"antfu","email":"anthonyfu117@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/experimental-logs-sdk_0.0.3_1775699091372_0.566950738241019"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-08T01:26:32.721Z","modified":"2026-04-09T01:44:51.680Z","0.0.0":"2026-04-08T01:26:33.085Z","0.0.1":"2026-04-08T01:37:51.084Z","0.0.2":"2026-04-08T04:16:31.068Z","0.0.3":"2026-04-09T01:44:51.575Z"},"bugs":{"url":"https://github.com/antfu/logs-sdk/issues"},"author":{"name":"Anthony Fu","email":"anthonyfu117@hotmail.com"},"license":"MIT","homepage":"https://github.com/antfu/logs-sdk#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/antfu/logs-sdk.git"},"description":"Structured diagnostic code library","maintainers":[{"name":"antfu","email":"anthonyfu117@hotmail.com"}],"readme":"# logs-sdk\n\nStructured diagnostic codes for JavaScript/TypeScript libraries and frameworks.\n\n`logs-sdk` makes every error, warning, and suggestion a **structured, typed, machine-readable object** — with a stable code, a human explanation, and enough context for an agent to act on it precisely.\n\n## What it looks like\n\n```\n[NUXT_B2011] Invalid plugin `/plugins/bad.ts`. src option is required.\n├▶ see: https://nuxt.com/e/b2011\n├▶ fix: Pass a string path or an object with a `src` property to `addPlugin()`.\n╰▶ hint: Check your module's addPlugin() calls\n```\n\nEvery diagnostic has a **stable code**, a **human-readable explanation**, and structured fields — `fix`, `why`, `hint`, `docs` — that tell you what happened and how to resolve it. The `see` link points to a dedicated documentation page for that error code, with detailed explanations, examples, and common solutions.\n\nThese error messages are designed to be **actionable** — not just telling you what went wrong, but guiding you toward the fix.\n\n## For humans\n\nA code like `NUXT_B2011` is stable and searchable — look it up in docs, find it in source, share it in issues. The structured fields give you immediate guidance: you don't need to search for the error message to find the fix, it's right there. And when you need more detail, the docs link takes you to a dedicated page for that specific error code — with full context, examples, and walkthroughs.\n\nWhen library authors define diagnostics in one place, messages stay consistent. Every occurrence of `NUXT_B2011` produces the same explanation, the same fix, the same docs link.\n\n## For AI agents\n\nStructured diagnostics enable a different kind of agent integration — **precise rather than probabilistic**.\n\nEvery diagnostic has a stable code an agent can dispatch on directly, instead of pattern-matching on message text. The object carries everything needed to act: what happened (`message`), why (`why`), how to fix it (`fix`), where to learn more (`docs`), and machine-readable details (`context`, `sources`). The per-code documentation pages are equally useful for agents — they can crawl or fetch them for deeper context when the inline fields aren't enough.\n\nAn agent can resolve the issue without asking the user for more information. Users don't need to configure anything — if a library uses `logs-sdk`, its diagnostics are already agent-ready. All codes are defined in a catalog, so an agent can enumerate the full error surface ahead of time. And when multiple libraries in a stack adopt it, agents get uniformly structured data from every layer.\n\n## Usage\n\n### Define diagnostics\n\n`defineDiagnostics()` declares the diagnostic codes for a domain — pure data, no side effects.\n\n`docsBase` can be a string (auto-appends `/${code.toLowerCase()}`) or a function for full control over the URL:\n\n```ts\nimport { defineDiagnostics } from 'logs-sdk'\n\n// Function form — strip the project prefix for cleaner URLs\nconst diagnostics = defineDiagnostics({\n  docsBase: code => `https://nuxt.com/e/${code.replace('NUXT_', '').toLowerCase()}`,\n  codes: {\n    NUXT_B2011: {\n      message: (p: { src: string }) => `Invalid plugin \\`${p.src}\\`. src option is required.`,\n      fix: 'Pass a string path or an object with a `src` property to `addPlugin()`.',\n    },\n    NUXT_B5001: {\n      message: 'Missing compatibilityDate in nuxt.config.',\n      fix: (p: { date: string }) => `Add \\`compatibilityDate: '${p.date}'\\` to your nuxt.config.`,\n      hint: 'This ensures consistent behavior across Nuxt versions.',\n      level: 'warn',\n    },\n  },\n})\n// diagnostics.NUXT_B2011({ src: '...' }).docs → 'https://nuxt.com/e/b2011'\n```\n\n```ts\n// String form — simple base URL, code appended automatically\nconst diagnostics = defineDiagnostics({\n  docsBase: 'https://example.com/errors',\n  codes: {\n    MY_E001: { message: 'Something went wrong.' },\n  },\n})\n// diagnostics.MY_E001().docs → 'https://example.com/errors/my_e001'\n```\n\n### Create a logger\n\n`createLogger()` binds diagnostics to output — formatting and reporting.\n\n```ts\nimport { createLogger } from 'logs-sdk'\n\nconst log = createLogger({\n  diagnostics: [diagnostics],\n})\n\nlog.NUXT_B2011({ src: pluginPath }).throw()\nlog.NUXT_B5001({ date: '2025-01-01' }).warn()\n```\n\n`log.NUXT_B2011` is cmd+clickable, TypeScript enforces params, and actions are chainable — `.throw()`, `.warn()`, `.error()`, `.log()`.\n\n### Multiple diagnostic sets\n\n```ts\nconst log = createLogger({\n  diagnostics: [nuxtDiagnostics, i18nDiagnostics],\n})\n\nlog.NUXT_B2011({ src: pluginPath }).throw() // [NUXT_B2011] ...\nlog.I18N_I001({ locale: 'fr' }).warn() // [I18N_I001] ...\n```\n\n### Custom reporters\n\n```ts\nconst log = createLogger({\n  diagnostics: [diagnostics],\n  reporter: (diagnostic, formatted) => {\n    console.error(formatted)\n    sentry.captureMessage(formatted, { tags: { code: diagnostic.code } })\n  },\n})\n```\n\n## Features\n\n- Typed diagnostic factories — cmd+clickable, hover shows params, TypeScript enforces correctness\n- Structured `Diagnostic` objects — serializable, transportable across process boundaries\n- Chainable actions — `.throw()`, `.warn()`, `.error()`, `.log()`\n- Pluggable formatters — plain text, ANSI colors, JSON\n- Pluggable reporters — console, HTTP, custom\n- Multiple diagnostic sets — compose diagnostics from different libraries\n- Zero runtime dependencies\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}