{"_id":"@diabolicallabs/notifier-core","name":"@diabolicallabs/notifier-core","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@diabolicallabs/notifier-core","version":"1.0.0","description":"Shared Notifier interface, PlatformError taxonomy, Logger, and retryWithJitter helper for the Diabolical Labs notifier package family. Zero runtime deps. © Diabolical Labs","author":{"name":"Diana Ismail","email":"diana@deeismail.com","url":"https://deeismail.com"},"publisher":"Diabolical Labs","license":"MIT","type":"module","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"main":"./dist/index.js","types":"./dist/index.d.ts","repository":{"type":"git","url":"git+https://github.com/mannism/dlabs-toolkit.git","directory":"packages/notifier-core"},"homepage":"https://github.com/mannism/dlabs-toolkit#readme","bugs":{"url":"https://github.com/mannism/dlabs-toolkit/issues"},"engines":{"node":">=20"},"devDependencies":{"@types/node":"^25.9.0","@vitest/coverage-v8":"^4.1.6","tsup":"^8.3.5","vitest":"^4.1.6"},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","lint":"biome check ./src","test":"vitest run --coverage","test:watch":"vitest"},"_id":"@diabolicallabs/notifier-core@1.0.0","_integrity":"sha512-5ZNDKq2Bg0QBhRQdUcot/utHGEHxuvlLEWllhAaHDWdWtDhlMweSj5INNd82ojqdYtw49gRQ2FapszdbSdDD4Q==","_resolved":"/tmp/8f3bf097f60a39b18cbc8a49a0b1c423/diabolicallabs-notifier-core-1.0.0.tgz","_from":"file:diabolicallabs-notifier-core-1.0.0.tgz","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-5ZNDKq2Bg0QBhRQdUcot/utHGEHxuvlLEWllhAaHDWdWtDhlMweSj5INNd82ojqdYtw49gRQ2FapszdbSdDD4Q==","shasum":"5ed2e8de8e099e930ce8c4663bbfcd2e92e37273","tarball":"https://registry.npmjs.org/@diabolicallabs/notifier-core/-/notifier-core-1.0.0.tgz","fileCount":6,"unpackedSize":24031,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC2BwskJo6CGzxatSuMkusxkQS0wmalV+FsygzUOhZIzAIhAN/GmknWwcYLOu0uhweqwDwsOBYCp49CjXmm6kQ7BbUU"}]},"_npmUser":{"name":"shackled78","email":"shackled78@gmail.com"},"directories":{},"maintainers":[{"name":"shackled78","email":"shackled78@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/notifier-core_1.0.0_1779599988757_0.5569440941590307"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-24T05:19:48.627Z","1.0.0":"2026-05-24T05:19:48.897Z","modified":"2026-05-24T05:19:49.165Z"},"maintainers":[{"name":"shackled78","email":"shackled78@gmail.com"}],"description":"Shared Notifier interface, PlatformError taxonomy, Logger, and retryWithJitter helper for the Diabolical Labs notifier package family. Zero runtime deps. © Diabolical Labs","homepage":"https://github.com/mannism/dlabs-toolkit#readme","repository":{"type":"git","url":"git+https://github.com/mannism/dlabs-toolkit.git","directory":"packages/notifier-core"},"author":{"name":"Diana Ismail","email":"diana@deeismail.com","url":"https://deeismail.com"},"bugs":{"url":"https://github.com/mannism/dlabs-toolkit/issues"},"license":"MIT","readme":"# `@diabolicallabs/notifier-core`\n\nShared interface, error taxonomy, Logger, and retry helper for the Diabolical Labs notifier package family.\n\nZero runtime dependencies — types, error classes, and a pure retry function only.\n\n## Install\n\n```bash\npnpm add @diabolicallabs/notifier-core\n```\n\n## Usage\n\n### Portable notifier interface\n\n```ts\nimport type { Notifier, NotifyMessage, NotifyResult } from '@diabolicallabs/notifier-core';\n\n// Accept any platform notifier via the portable interface\nfunction sendAlert(notifier: Notifier, channel: string, text: string): Promise<NotifyResult> {\n  return notifier.send({ to: channel, text });\n}\n```\n\n### Error handling\n\n```ts\nimport {\n  PlatformError,\n  PlatformAuthError,\n  PlatformRateLimitError,\n  PlatformNotFoundError,\n  PlatformValidationError,\n  PlatformUnavailableError,\n} from '@diabolicallabs/notifier-core';\n\ntry {\n  await notifier.send({ to: 'my-channel', text: 'hello' });\n} catch (err) {\n  if (err instanceof PlatformRateLimitError) {\n    console.log(`Rate limited. Kind: ${err.kind}, retry after: ${err.retryAfterMs}ms`);\n  } else if (err instanceof PlatformAuthError) {\n    console.error('Authentication failed — check your token');\n  } else if (err instanceof PlatformError) {\n    console.error(`Platform error on ${err.platform}: [${err.code}] ${err.message}`);\n  }\n}\n```\n\n### retryWithJitter helper\n\n```ts\nimport { retryWithJitter, PlatformRateLimitError } from '@diabolicallabs/notifier-core';\n\nconst result = await retryWithJitter(\n  () => fetch('https://api.example.com/send', { method: 'POST', body: '...' }),\n  {\n    maxRetries: 3,\n    baseDelayMs: 250,\n    capDelayMs: 2000,\n    isRetryable: (err) => !(err instanceof PlatformAuthError),\n    onRetry: (err, attempt, delayMs) =>\n      logger.warn('SEND_RETRY', { attempt, delayMs }),\n  },\n);\n```\n\n### Pluggable logger\n\n```ts\nimport type { Logger } from '@diabolicallabs/notifier-core';\n\nconst myLogger: Logger = {\n  warn: (event, data) => pino.warn({ event, ...data }),\n};\n```\n\n## Configuration\n\n`notifier-core` has no configuration. It is a types + pure-function package.\n\n## Error taxonomy\n\n| Class | When thrown | Retryable |\n|---|---|---|\n| `PlatformError` | Base class — generic fallback | Depends on subclass |\n| `PlatformAuthError` | Invalid or revoked credentials | No |\n| `PlatformNotFoundError` | Channel/chat not found, bot blocked | No |\n| `PlatformRateLimitError` | 429 after retries exhausted | No (retried internally; thrown when done) |\n| `PlatformValidationError` | Bad payload, missing field | No |\n| `PlatformUnavailableError` | 5xx after retries exhausted | Potentially (external) |\n\n`PlatformRateLimitError` has two additional fields:\n- `kind: 'exceeded' | 'unavailable'` — `'exceeded'` = real rate limit; `'unavailable'` = infrastructure broken\n- `retryAfterMs: number | null` — milliseconds to wait before retrying\n\n## Retry formula\n\nFull-jitter exponential backoff (AWS recommendation):\n\n```\ndelay = min(capDelayMs, baseDelayMs * 2^n) * random(0, 1)\n```\n\nPrevents thundering herd on concurrent failures.\n\n## License\n\nMIT — © Diabolical Labs\n","readmeFilename":"README.md","_rev":"1-6f184f37d99d58759d05db855ab92671"}