@autofleet/slack-notifier 0.1.2-beta-740ca7cd.0

package/README.md

@@ -0,0 +1,116 @@
+# @autofleet/slack-notifier
+
+A small, reusable client for posting messages to a Slack channel from any app or
+microservice in the monorepo. Built on Slack's Web API (`chat.postMessage`) via
+`@slack/web-api`'s `WebClient`, which handles retries, rate limits, and pagination.
+
+## Install
+
+```bash
+pnpm add @autofleet/slack-notifier --filter @autofleet/<your-project>
+```
+
+## Usage
+
+```ts
+import { createSlackNotifier } from '@autofleet/slack-notifier';
+
+const slack = createSlackNotifier({
+  token: process.env.SLACK_BOT_TOKEN ?? '',
+  // Sending is opt-in: `enabled` defaults to false, so without this every send is a no-op.
+  enabled: process.env.NODE_ENV === 'production', // off in dev/test — sendMessage no-ops
+});
+
+await slack.sendMessage({
+  channel: '#ordering-alerts', // channel name or ID
+  text: 'Order sync failed for fleet 1234',
+});
+```
+
+With Block Kit (rich formatting). `text` is always sent as the notification fallback:
+
+```ts
+await slack.sendMessage({
+  channel: '#ordering-alerts',
+  text: 'Order sync failed for fleet 1234',
+  blocks: [
+    { type: 'section', text: { type: 'mrkdwn', text: '*Order sync failed* for fleet `1234`' } },
+  ],
+});
+```
+
+## Configuration
+
+| Field              | Type      | Default | Description |
+| ------------------ | --------- | ------- | --- |
+| `token`            | `string`  | —       | `xoxb-…` bot token, injected by the caller. Validated lazily on first real send. |
+| `enabled`          | `boolean` | `false` | Master on/off switch — **sending is opt-in**. When `false` (the default), `sendMessage` is a no-op (no network call, no token required). Set `true` to actually post. |
+| `defaultChannel`   | `string`  | —       | Fallback channel used when `sendMessage` is called without a `channel`. |
+| `defaultUsername`  | `string`  | —       | Default sender name for every message (override per call with `username`). Needs `chat:write.customize`. |
+| `defaultIconEmoji` | `string`  | —       | Default sender emoji, e.g. `":robot_face:"` (override per call with `iconEmoji`). Needs `chat:write.customize`. |
+| `defaultIconUrl`   | `string`  | —       | Default sender profile picture as an image URL (override per call with `iconUrl`). Takes precedence over `defaultIconEmoji`. Needs `chat:write.customize`. |
+| `logger`           | `Logger`  | —       | Optional logger (compatible with `@autofleet/logger`). |
+
+### Customizing the sender name / picture
+
+You can override the name and avatar shown for messages — either as defaults on the
+notifier, or per call. The avatar can be an **emoji** (`iconEmoji`) or an **image URL**
+(`iconUrl`); if both are given, Slack uses the URL.
+
+```ts
+const slack = createSlackNotifier({
+  token: process.env.SLACK_BOT_TOKEN ?? '',
+  enabled: true,
+  defaultUsername: 'ordering-ms',
+  defaultIconUrl: 'https://example.com/ordering-bot-avatar.png',
+});
+
+// uses the defaults above
+await slack.sendMessage({ channel: '#ops', text: 'hi' });
+
+// per-message override (image avatar)
+await slack.sendMessage({
+  channel: '#ops',
+  text: 'sync failed',
+  username: 'xlr8-sync',
+  iconUrl: 'https://example.com/xlr8-avatar.png',
+});
+
+// per-message override (emoji avatar)
+await slack.sendMessage({
+  channel: '#ops',
+  text: 'sync failed',
+  username: 'xlr8-sync',
+  iconEmoji: ':rotating_light:',
+});
+```
+
+> **Per-message vs. permanent avatar.** `username`/`iconEmoji`/`iconUrl` only override the
+> name and picture **for the messages you send** — they do **not** change the bot's
+> permanent profile. The app's standing name and avatar are set once in the Slack app UI
+> (<https://api.slack.com/apps> → your app → _Basic Information → Display Information_);
+> there is no API to change them from code.
+
+> All three overrides require the bot to have the **`chat:write.customize`** scope, and
+> changes take effect only after the app is **reinstalled** to the workspace. Without the
+> scope Slack silently ignores them and posts under the app's default identity. An
+> `iconUrl` must point to a **publicly reachable** image (Slack fetches it server-side).
+
+The package never reads `process.env` itself — secrets and the enabled flag are injected
+by the caller.
+
+## Behavior
+
+- **Disabled** (`enabled: false`, the default): `sendMessage` resolves to `{ ok: true, skipped: true, channelId: '', ts: '' }` without calling Slack. Sending is opt-in — pass `enabled: true` to post.
+- **Errors**: failures throw a typed `SlackNotifierError` with a `code` (e.g.
+  `channel_not_found`, `not_in_channel`, `invalid_auth`, `missing_token`).
+- **Channels**: with the `chat:write.public` scope the bot can post to any public channel
+  without joining. Private channels require inviting the bot first.
+
+## Slack app setup
+
+The bot needs the `chat:write` and `chat:write.public` scopes — plus `chat:write.customize`
+if you use `username`/`iconEmoji`/`iconUrl`. Create the app at
+<https://api.slack.com/apps>, install it to the workspace, and copy the Bot User OAuth
+Token (`xoxb-…`) into your secret manager as `SLACK_BOT_TOKEN`. After changing scopes,
+reinstall the app for them to take effect.

package/lib/index.cjs

@@ -0,0 +1,2 @@
+let e=require(`@slack/web-api`);var t=class extends Error{constructor(e,t,n){super(e),this.name=`SlackNotifierError`,this.code=t,n?.cause!==void 0&&(this.cause=n.cause)}},n=class{#e;#t;#n;#r;#i;#a;#o;#s;constructor(e){this.#e=e.enabled??!1,this.#t=e.token,this.#n=e.defaultChannel,this.#r=e.defaultUsername,this.#i=e.defaultIconEmoji,this.#a=e.defaultIconUrl,this.#o=e.logger}get enabled(){return this.#e}async sendMessage(e){let n=e.channel??this.#n;if(!this.#e)return this.#o?.debug?.(`slack notifier disabled, skipping message`,{channel:n}),{ok:!0,skipped:!0,channelId:``,ts:``};if(!n)throw new t(`No channel provided and no defaultChannel configured`,`channel_required`);try{let t={channel:n,text:e.text,thread_ts:e.threadTs,username:e.username??this.#r,icon_emoji:e.iconEmoji??this.#i,icon_url:e.iconUrl??this.#a,...e.blocks?{blocks:e.blocks}:{}},r=await this.#c().chat.postMessage(t);return this.#o?.info?.(`slack message sent`,{channel:r.channel,ts:r.ts}),{ok:r.ok??!1,channelId:r.channel??``,ts:r.ts??``}}catch(e){throw this.#l(e)}}#c(){if(!this.#t)throw new t(`Slack bot token is required to send messages`,`missing_token`);return this.#s??=new e.WebClient(this.#t),this.#s}#l(e){if(e instanceof t)return e;let n=e,r=n?.data?.error??n?.code??`unknown_error`,i=`Failed to send Slack message: ${r}`;return this.#o?.error?.(i,{code:r}),new t(i,r,{cause:e})}};function r(e){return new n(e)}exports.SlackNotifier=n,exports.SlackNotifierError=t,exports.createSlackNotifier=r;
+//# sourceMappingURL=index.cjs.map

package/lib/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["#enabled","#token","#defaultChannel","#defaultUsername","#defaultIconEmoji","#defaultIconUrl","#logger","#getClient","#wrapError","#client","WebClient"],"sources":["../src/errors.ts","../src/slack-notifier.ts"],"sourcesContent":["/**\n * Error thrown when sending a Slack message fails. Carries a machine-readable {@link code}\n * (the Slack platform error string where available, e.g. `channel_not_found`,\n * `not_in_channel`, `invalid_auth`) so callers can branch on it.\n */\nexport class SlackNotifierError extends Error {\n  /** Slack platform error code (e.g. `channel_not_found`) or a local code (e.g. `missing_token`). */\n  readonly code: string;\n\n  constructor(message: string, code: string, options?: { cause?: unknown; }) {\n    super(message);\n    this.name = 'SlackNotifierError';\n    this.code = code;\n    if (options?.cause !== undefined) {\n      (this as { cause?: unknown; }).cause = options.cause;\n    }\n  }\n}\n","import { WebClient } from '@slack/web-api';\nimport type { ChatPostMessageArguments } from '@slack/web-api';\nimport { SlackNotifierError } from './errors';\nimport type { Logger, SendMessageInput, SendMessageResult, SlackNotifierConfig } from './types';\n\n/**\n * Posts messages to Slack via the Web API (`chat.postMessage`), using `@slack/web-api`'s\n * `WebClient` (which handles retries, rate limits, and pagination).\n *\n * - The bot token is injected by the caller; the `WebClient` is constructed lazily on the\n *   first real send, so a disabled notifier can be created without a token (e.g. in dev/test).\n * - Sending is opt-in: `enabled` defaults to `false`, so a notifier created without it is a\n *   safe no-op. Set `enabled: true` (e.g. per environment) to actually post to Slack.\n *\n * @example\n * ```typescript\n * const slack = new SlackNotifier({ token: process.env.SLACK_BOT_TOKEN ?? '', enabled: true });\n * await slack.sendMessage({ channel: '#ops-alerts', text: 'Deploy finished ✅' });\n * ```\n */\nexport class SlackNotifier {\n  readonly #enabled: boolean;\n  readonly #token: string;\n  readonly #defaultChannel: string | undefined;\n  readonly #defaultUsername: string | undefined;\n  readonly #defaultIconEmoji: string | undefined;\n  readonly #defaultIconUrl: string | undefined;\n  readonly #logger: Logger | undefined;\n  #client: WebClient | undefined;\n\n  constructor(config: SlackNotifierConfig) {\n    this.#enabled = config.enabled ?? false;\n    this.#token = config.token;\n    this.#defaultChannel = config.defaultChannel;\n    this.#defaultUsername = config.defaultUsername;\n    this.#defaultIconEmoji = config.defaultIconEmoji;\n    this.#defaultIconUrl = config.defaultIconUrl;\n    this.#logger = config.logger;\n  }\n\n  /** Whether this notifier will actually send messages. */\n  public get enabled(): boolean {\n    return this.#enabled;\n  }\n\n  /**\n   * Send a message to a Slack channel.\n   *\n   * When the notifier is disabled this resolves to `{ ok: true, skipped: true }` without\n   * making any network call. Otherwise it posts via `chat.postMessage` and maps the\n   * response, throwing a {@link SlackNotifierError} on failure.\n   */\n  public async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {\n    const channel = input.channel ?? this.#defaultChannel;\n\n    if (!this.#enabled) {\n      this.#logger?.debug?.('slack notifier disabled, skipping message', { channel });\n      return { ok: true, skipped: true, channelId: '', ts: '' };\n    }\n\n    if (!channel) {\n      throw new SlackNotifierError(\n        'No channel provided and no defaultChannel configured',\n        'channel_required',\n      );\n    }\n\n    try {\n      // `ChatPostMessageArguments` is a discriminated union (text | blocks | attachments | …)\n      // intersected with several other unions, which doesn't accept a conditionally-present\n      // `blocks` key cleanly. We always supply `text` (and a validated `channel`), so the cast\n      // is safe; `blocks` is only attached when provided to satisfy its non-optional variant.\n      const args = {\n        channel,\n        text: input.text,\n        // eslint-disable-next-line camelcase -- Slack API field\n        thread_ts: input.threadTs,\n        // username/icon_emoji/icon_url require the bot's `chat:write.customize` scope.\n        username: input.username ?? this.#defaultUsername,\n        // eslint-disable-next-line camelcase -- Slack API field\n        icon_emoji: input.iconEmoji ?? this.#defaultIconEmoji,\n        // eslint-disable-next-line camelcase -- Slack API field\n        icon_url: input.iconUrl ?? this.#defaultIconUrl,\n        ...(input.blocks ? { blocks: input.blocks } : {}),\n      } as ChatPostMessageArguments;\n\n      const response = await this.#getClient().chat.postMessage(args);\n\n      this.#logger?.info?.('slack message sent', { channel: response.channel, ts: response.ts });\n\n      return {\n        ok: response.ok ?? false,\n        channelId: response.channel ?? '',\n        ts: response.ts ?? '',\n      };\n    } catch (error) {\n      throw this.#wrapError(error);\n    }\n  }\n\n  /** Lazily construct the WebClient, validating the token on first use. */\n  #getClient(): WebClient {\n    if (!this.#token) {\n      throw new SlackNotifierError('Slack bot token is required to send messages', 'missing_token');\n    }\n    this.#client ??= new WebClient(this.#token);\n    return this.#client;\n  }\n\n  /** Translate any thrown value into a typed {@link SlackNotifierError}. */\n  #wrapError(error: unknown): SlackNotifierError {\n    if (error instanceof SlackNotifierError) {\n      return error;\n    }\n\n    // `@slack/web-api` platform errors expose the Slack error string at `data.error`\n    // (e.g. `channel_not_found`); transport errors expose an `ErrorCode` at `code`.\n    const err = error as { code?: string; data?: { error?: string; }; };\n    const code = err?.data?.error ?? err?.code ?? 'unknown_error';\n    const message = `Failed to send Slack message: ${code}`;\n\n    this.#logger?.error?.(message, { code });\n\n    return new SlackNotifierError(message, code, { cause: error });\n  }\n}\n\n/** Convenience factory for {@link SlackNotifier}. */\nexport function createSlackNotifier(config: SlackNotifierConfig): SlackNotifier {\n  return new SlackNotifier(config);\n}\n"],"mappings":"gCAKA,IAAa,EAAb,cAAwC,KAAM,CAI5C,YAAY,EAAiB,EAAc,EAAgC,CACzE,MAAM,EAAQ,CACd,KAAK,KAAO,qBACZ,KAAK,KAAO,EACR,GAAS,QAAU,IAAA,KACpB,KAA8B,MAAQ,EAAQ,SCMxC,EAAb,KAA2B,CACzB,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GAEA,YAAY,EAA6B,CACvC,MAAA,EAAgB,EAAO,SAAW,GAClC,MAAA,EAAc,EAAO,MACrB,MAAA,EAAuB,EAAO,eAC9B,MAAA,EAAwB,EAAO,gBAC/B,MAAA,EAAyB,EAAO,iBAChC,MAAA,EAAuB,EAAO,eAC9B,MAAA,EAAe,EAAO,OAIxB,IAAW,SAAmB,CAC5B,OAAO,MAAA,EAUT,MAAa,YAAY,EAAqD,CAC5E,IAAM,EAAU,EAAM,SAAW,MAAA,EAEjC,GAAI,CAAC,MAAA,EAEH,OADA,MAAA,GAAc,QAAQ,4CAA6C,CAAE,UAAS,CAAC,CACxE,CAAE,GAAI,GAAM,QAAS,GAAM,UAAW,GAAI,GAAI,GAAI,CAG3D,GAAI,CAAC,EACH,MAAM,IAAI,EACR,uDACA,mBACD,CAGH,GAAI,CAKF,IAAM,EAAO,CACX,UACA,KAAM,EAAM,KAEZ,UAAW,EAAM,SAEjB,SAAU,EAAM,UAAY,MAAA,EAE5B,WAAY,EAAM,WAAa,MAAA,EAE/B,SAAU,EAAM,SAAW,MAAA,EAC3B,GAAI,EAAM,OAAS,CAAE,OAAQ,EAAM,OAAQ,CAAG,EAAE,CACjD,CAEK,EAAW,MAAM,MAAA,GAAiB,CAAC,KAAK,YAAY,EAAK,CAI/D,OAFA,MAAA,GAAc,OAAO,qBAAsB,CAAE,QAAS,EAAS,QAAS,GAAI,EAAS,GAAI,CAAC,CAEnF,CACL,GAAI,EAAS,IAAM,GACnB,UAAW,EAAS,SAAW,GAC/B,GAAI,EAAS,IAAM,GACpB,OACM,EAAO,CACd,MAAM,MAAA,EAAgB,EAAM,EAKhC,IAAwB,CACtB,GAAI,CAAC,MAAA,EACH,MAAM,IAAI,EAAmB,+CAAgD,gBAAgB,CAG/F,MADA,OAAA,IAAiB,IAAIU,EAAAA,UAAU,MAAA,EAAY,CACpC,MAAA,EAIT,GAAW,EAAoC,CAC7C,GAAI,aAAiB,EACnB,OAAO,EAKT,IAAM,EAAM,EACN,EAAO,GAAK,MAAM,OAAS,GAAK,MAAQ,gBACxC,EAAU,iCAAiC,IAIjD,OAFA,MAAA,GAAc,QAAQ,EAAS,CAAE,OAAM,CAAC,CAEjC,IAAI,EAAmB,EAAS,EAAM,CAAE,MAAO,EAAO,CAAC,GAKlE,SAAgB,EAAoB,EAA4C,CAC9E,OAAO,IAAI,EAAc,EAAO"}

package/lib/index.d.cts

@@ -0,0 +1,142 @@
+import { Block, KnownBlock } from "@slack/web-api";
+
+//#region src/types.d.ts
+
+/**
+* Minimal structural logger interface — compatible with `@autofleet/logger`'s
+* `LoggerInstanceManager` but without coupling this package to it. Every method is
+* optional so callers can pass a partial logger (or none at all).
+*/
+interface Logger {
+  debug?: (message: string, meta?: Record<string, unknown>) => void;
+  info?: (message: string, meta?: Record<string, unknown>) => void;
+  warn?: (message: string, meta?: Record<string, unknown>) => void;
+  error?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+* Configuration for a {@link SlackNotifier}. The bot token is injected by the caller —
+* the package never reads `process.env` itself.
+*/
+interface SlackNotifierConfig {
+  /** `xoxb-…` bot token, injected by the caller. Validated lazily on first real send. */
+  token: string;
+  /**
+  * Master on/off switch (default `false` — sending is opt-in). When `false`,
+  * {@link SlackNotifier.sendMessage} is a no-op: no network call is made and a token is not
+  * required. Set `enabled: true` to actually post, e.g. per environment with
+  * `enabled: process.env.NODE_ENV === 'production'`.
+  */
+  enabled?: boolean;
+  /** Optional fallback channel used when {@link SendMessageInput.channel} is omitted. */
+  defaultChannel?: string;
+  /**
+  * Optional default sender name shown for every message (overridable per call via
+  * {@link SendMessageInput.username}). Requires the bot's `chat:write.customize` scope.
+  */
+  defaultUsername?: string;
+  /**
+  * Optional default sender emoji icon, e.g. `":robot_face:"` (overridable per call via
+  * {@link SendMessageInput.iconEmoji}). Requires the bot's `chat:write.customize` scope.
+  */
+  defaultIconEmoji?: string;
+  /**
+  * Optional default sender profile picture as an image URL (overridable per call via
+  * {@link SendMessageInput.iconUrl}). Takes precedence over `defaultIconEmoji` when Slack
+  * receives both. Requires the bot's `chat:write.customize` scope.
+  */
+  defaultIconUrl?: string;
+  /** Optional logger for request/skip/error logging. */
+  logger?: Logger;
+}
+/** Input for a single message send. */
+interface SendMessageInput {
+  /**
+  * Channel name or ID, e.g. `"#ops-alerts"` or `"C0123456"`. Optional only when a
+  * `defaultChannel` was configured.
+  */
+  channel?: string;
+  /** Message body. Always sent (also used as the fallback text when `blocks` is set). */
+  text: string;
+  /** Optional: reply inside a thread by its parent message `ts`. */
+  threadTs?: string;
+  /** Optional: Block Kit payload for rich formatting. */
+  blocks?: (KnownBlock | Block)[];
+  /**
+  * Optional: override the sender name shown for this message. Falls back to
+  * {@link SlackNotifierConfig.defaultUsername}. Requires the bot's `chat:write.customize` scope.
+  */
+  username?: string;
+  /**
+  * Optional: override the sender emoji icon for this message, e.g. `":rotating_light:"`.
+  * Falls back to {@link SlackNotifierConfig.defaultIconEmoji}. Requires the bot's
+  * `chat:write.customize` scope.
+  */
+  iconEmoji?: string;
+  /**
+  * Optional: override the sender profile picture for this message as an image URL.
+  * Falls back to {@link SlackNotifierConfig.defaultIconUrl}. Takes precedence over
+  * `iconEmoji` when Slack receives both. Requires the bot's `chat:write.customize` scope.
+  */
+  iconUrl?: string;
+}
+/** Result of a message send. */
+interface SendMessageResult {
+  /** `true` when Slack accepted the message (or when the notifier was disabled). */
+  ok: boolean;
+  /** The resolved channel ID Slack posted to (empty when skipped). */
+  channelId: string;
+  /** The message timestamp / id within the channel (empty when skipped). */
+  ts: string;
+  /** `true` when the notifier was disabled and no API call was made. */
+  skipped?: boolean;
+}
+//#endregion
+//#region src/slack-notifier.d.ts
+/**
+* Posts messages to Slack via the Web API (`chat.postMessage`), using `@slack/web-api`'s
+* `WebClient` (which handles retries, rate limits, and pagination).
+*
+* - The bot token is injected by the caller; the `WebClient` is constructed lazily on the
+*   first real send, so a disabled notifier can be created without a token (e.g. in dev/test).
+* - Sending is opt-in: `enabled` defaults to `false`, so a notifier created without it is a
+*   safe no-op. Set `enabled: true` (e.g. per environment) to actually post to Slack.
+*
+* @example
+* ```typescript
+* const slack = new SlackNotifier({ token: process.env.SLACK_BOT_TOKEN ?? '', enabled: true });
+* await slack.sendMessage({ channel: '#ops-alerts', text: 'Deploy finished ✅' });
+* ```
+*/
+declare class SlackNotifier {
+  #private;
+  constructor(config: SlackNotifierConfig);
+  /** Whether this notifier will actually send messages. */
+  get enabled(): boolean;
+  /**
+  * Send a message to a Slack channel.
+  *
+  * When the notifier is disabled this resolves to `{ ok: true, skipped: true }` without
+  * making any network call. Otherwise it posts via `chat.postMessage` and maps the
+  * response, throwing a {@link SlackNotifierError} on failure.
+  */
+  sendMessage(input: SendMessageInput): Promise<SendMessageResult>;
+}
+/** Convenience factory for {@link SlackNotifier}. */
+declare function createSlackNotifier(config: SlackNotifierConfig): SlackNotifier;
+//#endregion
+//#region src/errors.d.ts
+/**
+* Error thrown when sending a Slack message fails. Carries a machine-readable {@link code}
+* (the Slack platform error string where available, e.g. `channel_not_found`,
+* `not_in_channel`, `invalid_auth`) so callers can branch on it.
+*/
+declare class SlackNotifierError extends Error {
+  /** Slack platform error code (e.g. `channel_not_found`) or a local code (e.g. `missing_token`). */
+  readonly code: string;
+  constructor(message: string, code: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+export { type Logger, type SendMessageInput, type SendMessageResult, SlackNotifier, type SlackNotifierConfig, SlackNotifierError, createSlackNotifier };
+//# sourceMappingURL=index.d.cts.map

package/lib/index.d.ts

@@ -0,0 +1,142 @@
+import { Block, KnownBlock } from "@slack/web-api";
+
+//#region src/types.d.ts
+
+/**
+* Minimal structural logger interface — compatible with `@autofleet/logger`'s
+* `LoggerInstanceManager` but without coupling this package to it. Every method is
+* optional so callers can pass a partial logger (or none at all).
+*/
+interface Logger {
+  debug?: (message: string, meta?: Record<string, unknown>) => void;
+  info?: (message: string, meta?: Record<string, unknown>) => void;
+  warn?: (message: string, meta?: Record<string, unknown>) => void;
+  error?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+* Configuration for a {@link SlackNotifier}. The bot token is injected by the caller —
+* the package never reads `process.env` itself.
+*/
+interface SlackNotifierConfig {
+  /** `xoxb-…` bot token, injected by the caller. Validated lazily on first real send. */
+  token: string;
+  /**
+  * Master on/off switch (default `false` — sending is opt-in). When `false`,
+  * {@link SlackNotifier.sendMessage} is a no-op: no network call is made and a token is not
+  * required. Set `enabled: true` to actually post, e.g. per environment with
+  * `enabled: process.env.NODE_ENV === 'production'`.
+  */
+  enabled?: boolean;
+  /** Optional fallback channel used when {@link SendMessageInput.channel} is omitted. */
+  defaultChannel?: string;
+  /**
+  * Optional default sender name shown for every message (overridable per call via
+  * {@link SendMessageInput.username}). Requires the bot's `chat:write.customize` scope.
+  */
+  defaultUsername?: string;
+  /**
+  * Optional default sender emoji icon, e.g. `":robot_face:"` (overridable per call via
+  * {@link SendMessageInput.iconEmoji}). Requires the bot's `chat:write.customize` scope.
+  */
+  defaultIconEmoji?: string;
+  /**
+  * Optional default sender profile picture as an image URL (overridable per call via
+  * {@link SendMessageInput.iconUrl}). Takes precedence over `defaultIconEmoji` when Slack
+  * receives both. Requires the bot's `chat:write.customize` scope.
+  */
+  defaultIconUrl?: string;
+  /** Optional logger for request/skip/error logging. */
+  logger?: Logger;
+}
+/** Input for a single message send. */
+interface SendMessageInput {
+  /**
+  * Channel name or ID, e.g. `"#ops-alerts"` or `"C0123456"`. Optional only when a
+  * `defaultChannel` was configured.
+  */
+  channel?: string;
+  /** Message body. Always sent (also used as the fallback text when `blocks` is set). */
+  text: string;
+  /** Optional: reply inside a thread by its parent message `ts`. */
+  threadTs?: string;
+  /** Optional: Block Kit payload for rich formatting. */
+  blocks?: (KnownBlock | Block)[];
+  /**
+  * Optional: override the sender name shown for this message. Falls back to
+  * {@link SlackNotifierConfig.defaultUsername}. Requires the bot's `chat:write.customize` scope.
+  */
+  username?: string;
+  /**
+  * Optional: override the sender emoji icon for this message, e.g. `":rotating_light:"`.
+  * Falls back to {@link SlackNotifierConfig.defaultIconEmoji}. Requires the bot's
+  * `chat:write.customize` scope.
+  */
+  iconEmoji?: string;
+  /**
+  * Optional: override the sender profile picture for this message as an image URL.
+  * Falls back to {@link SlackNotifierConfig.defaultIconUrl}. Takes precedence over
+  * `iconEmoji` when Slack receives both. Requires the bot's `chat:write.customize` scope.
+  */
+  iconUrl?: string;
+}
+/** Result of a message send. */
+interface SendMessageResult {
+  /** `true` when Slack accepted the message (or when the notifier was disabled). */
+  ok: boolean;
+  /** The resolved channel ID Slack posted to (empty when skipped). */
+  channelId: string;
+  /** The message timestamp / id within the channel (empty when skipped). */
+  ts: string;
+  /** `true` when the notifier was disabled and no API call was made. */
+  skipped?: boolean;
+}
+//#endregion
+//#region src/slack-notifier.d.ts
+/**
+* Posts messages to Slack via the Web API (`chat.postMessage`), using `@slack/web-api`'s
+* `WebClient` (which handles retries, rate limits, and pagination).
+*
+* - The bot token is injected by the caller; the `WebClient` is constructed lazily on the
+*   first real send, so a disabled notifier can be created without a token (e.g. in dev/test).
+* - Sending is opt-in: `enabled` defaults to `false`, so a notifier created without it is a
+*   safe no-op. Set `enabled: true` (e.g. per environment) to actually post to Slack.
+*
+* @example
+* ```typescript
+* const slack = new SlackNotifier({ token: process.env.SLACK_BOT_TOKEN ?? '', enabled: true });
+* await slack.sendMessage({ channel: '#ops-alerts', text: 'Deploy finished ✅' });
+* ```
+*/
+declare class SlackNotifier {
+  #private;
+  constructor(config: SlackNotifierConfig);
+  /** Whether this notifier will actually send messages. */
+  get enabled(): boolean;
+  /**
+  * Send a message to a Slack channel.
+  *
+  * When the notifier is disabled this resolves to `{ ok: true, skipped: true }` without
+  * making any network call. Otherwise it posts via `chat.postMessage` and maps the
+  * response, throwing a {@link SlackNotifierError} on failure.
+  */
+  sendMessage(input: SendMessageInput): Promise<SendMessageResult>;
+}
+/** Convenience factory for {@link SlackNotifier}. */
+declare function createSlackNotifier(config: SlackNotifierConfig): SlackNotifier;
+//#endregion
+//#region src/errors.d.ts
+/**
+* Error thrown when sending a Slack message fails. Carries a machine-readable {@link code}
+* (the Slack platform error string where available, e.g. `channel_not_found`,
+* `not_in_channel`, `invalid_auth`) so callers can branch on it.
+*/
+declare class SlackNotifierError extends Error {
+  /** Slack platform error code (e.g. `channel_not_found`) or a local code (e.g. `missing_token`). */
+  readonly code: string;
+  constructor(message: string, code: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+export { type Logger, type SendMessageInput, type SendMessageResult, SlackNotifier, type SlackNotifierConfig, SlackNotifierError, createSlackNotifier };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,2 @@
+import{WebClient as e}from"@slack/web-api";var t=class extends Error{constructor(e,t,n){super(e),this.name=`SlackNotifierError`,this.code=t,n?.cause!==void 0&&(this.cause=n.cause)}},n=class{#e;#t;#n;#r;#i;#a;#o;#s;constructor(e){this.#e=e.enabled??!1,this.#t=e.token,this.#n=e.defaultChannel,this.#r=e.defaultUsername,this.#i=e.defaultIconEmoji,this.#a=e.defaultIconUrl,this.#o=e.logger}get enabled(){return this.#e}async sendMessage(e){let n=e.channel??this.#n;if(!this.#e)return this.#o?.debug?.(`slack notifier disabled, skipping message`,{channel:n}),{ok:!0,skipped:!0,channelId:``,ts:``};if(!n)throw new t(`No channel provided and no defaultChannel configured`,`channel_required`);try{let t={channel:n,text:e.text,thread_ts:e.threadTs,username:e.username??this.#r,icon_emoji:e.iconEmoji??this.#i,icon_url:e.iconUrl??this.#a,...e.blocks?{blocks:e.blocks}:{}},r=await this.#c().chat.postMessage(t);return this.#o?.info?.(`slack message sent`,{channel:r.channel,ts:r.ts}),{ok:r.ok??!1,channelId:r.channel??``,ts:r.ts??``}}catch(e){throw this.#l(e)}}#c(){if(!this.#t)throw new t(`Slack bot token is required to send messages`,`missing_token`);return this.#s??=new e(this.#t),this.#s}#l(e){if(e instanceof t)return e;let n=e,r=n?.data?.error??n?.code??`unknown_error`,i=`Failed to send Slack message: ${r}`;return this.#o?.error?.(i,{code:r}),new t(i,r,{cause:e})}};function r(e){return new n(e)}export{n as SlackNotifier,t as SlackNotifierError,r as createSlackNotifier};
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#enabled","#token","#defaultChannel","#defaultUsername","#defaultIconEmoji","#defaultIconUrl","#logger","#getClient","#wrapError","#client"],"sources":["../src/errors.ts","../src/slack-notifier.ts"],"sourcesContent":["/**\n * Error thrown when sending a Slack message fails. Carries a machine-readable {@link code}\n * (the Slack platform error string where available, e.g. `channel_not_found`,\n * `not_in_channel`, `invalid_auth`) so callers can branch on it.\n */\nexport class SlackNotifierError extends Error {\n  /** Slack platform error code (e.g. `channel_not_found`) or a local code (e.g. `missing_token`). */\n  readonly code: string;\n\n  constructor(message: string, code: string, options?: { cause?: unknown; }) {\n    super(message);\n    this.name = 'SlackNotifierError';\n    this.code = code;\n    if (options?.cause !== undefined) {\n      (this as { cause?: unknown; }).cause = options.cause;\n    }\n  }\n}\n","import { WebClient } from '@slack/web-api';\nimport type { ChatPostMessageArguments } from '@slack/web-api';\nimport { SlackNotifierError } from './errors';\nimport type { Logger, SendMessageInput, SendMessageResult, SlackNotifierConfig } from './types';\n\n/**\n * Posts messages to Slack via the Web API (`chat.postMessage`), using `@slack/web-api`'s\n * `WebClient` (which handles retries, rate limits, and pagination).\n *\n * - The bot token is injected by the caller; the `WebClient` is constructed lazily on the\n *   first real send, so a disabled notifier can be created without a token (e.g. in dev/test).\n * - Sending is opt-in: `enabled` defaults to `false`, so a notifier created without it is a\n *   safe no-op. Set `enabled: true` (e.g. per environment) to actually post to Slack.\n *\n * @example\n * ```typescript\n * const slack = new SlackNotifier({ token: process.env.SLACK_BOT_TOKEN ?? '', enabled: true });\n * await slack.sendMessage({ channel: '#ops-alerts', text: 'Deploy finished ✅' });\n * ```\n */\nexport class SlackNotifier {\n  readonly #enabled: boolean;\n  readonly #token: string;\n  readonly #defaultChannel: string | undefined;\n  readonly #defaultUsername: string | undefined;\n  readonly #defaultIconEmoji: string | undefined;\n  readonly #defaultIconUrl: string | undefined;\n  readonly #logger: Logger | undefined;\n  #client: WebClient | undefined;\n\n  constructor(config: SlackNotifierConfig) {\n    this.#enabled = config.enabled ?? false;\n    this.#token = config.token;\n    this.#defaultChannel = config.defaultChannel;\n    this.#defaultUsername = config.defaultUsername;\n    this.#defaultIconEmoji = config.defaultIconEmoji;\n    this.#defaultIconUrl = config.defaultIconUrl;\n    this.#logger = config.logger;\n  }\n\n  /** Whether this notifier will actually send messages. */\n  public get enabled(): boolean {\n    return this.#enabled;\n  }\n\n  /**\n   * Send a message to a Slack channel.\n   *\n   * When the notifier is disabled this resolves to `{ ok: true, skipped: true }` without\n   * making any network call. Otherwise it posts via `chat.postMessage` and maps the\n   * response, throwing a {@link SlackNotifierError} on failure.\n   */\n  public async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {\n    const channel = input.channel ?? this.#defaultChannel;\n\n    if (!this.#enabled) {\n      this.#logger?.debug?.('slack notifier disabled, skipping message', { channel });\n      return { ok: true, skipped: true, channelId: '', ts: '' };\n    }\n\n    if (!channel) {\n      throw new SlackNotifierError(\n        'No channel provided and no defaultChannel configured',\n        'channel_required',\n      );\n    }\n\n    try {\n      // `ChatPostMessageArguments` is a discriminated union (text | blocks | attachments | …)\n      // intersected with several other unions, which doesn't accept a conditionally-present\n      // `blocks` key cleanly. We always supply `text` (and a validated `channel`), so the cast\n      // is safe; `blocks` is only attached when provided to satisfy its non-optional variant.\n      const args = {\n        channel,\n        text: input.text,\n        // eslint-disable-next-line camelcase -- Slack API field\n        thread_ts: input.threadTs,\n        // username/icon_emoji/icon_url require the bot's `chat:write.customize` scope.\n        username: input.username ?? this.#defaultUsername,\n        // eslint-disable-next-line camelcase -- Slack API field\n        icon_emoji: input.iconEmoji ?? this.#defaultIconEmoji,\n        // eslint-disable-next-line camelcase -- Slack API field\n        icon_url: input.iconUrl ?? this.#defaultIconUrl,\n        ...(input.blocks ? { blocks: input.blocks } : {}),\n      } as ChatPostMessageArguments;\n\n      const response = await this.#getClient().chat.postMessage(args);\n\n      this.#logger?.info?.('slack message sent', { channel: response.channel, ts: response.ts });\n\n      return {\n        ok: response.ok ?? false,\n        channelId: response.channel ?? '',\n        ts: response.ts ?? '',\n      };\n    } catch (error) {\n      throw this.#wrapError(error);\n    }\n  }\n\n  /** Lazily construct the WebClient, validating the token on first use. */\n  #getClient(): WebClient {\n    if (!this.#token) {\n      throw new SlackNotifierError('Slack bot token is required to send messages', 'missing_token');\n    }\n    this.#client ??= new WebClient(this.#token);\n    return this.#client;\n  }\n\n  /** Translate any thrown value into a typed {@link SlackNotifierError}. */\n  #wrapError(error: unknown): SlackNotifierError {\n    if (error instanceof SlackNotifierError) {\n      return error;\n    }\n\n    // `@slack/web-api` platform errors expose the Slack error string at `data.error`\n    // (e.g. `channel_not_found`); transport errors expose an `ErrorCode` at `code`.\n    const err = error as { code?: string; data?: { error?: string; }; };\n    const code = err?.data?.error ?? err?.code ?? 'unknown_error';\n    const message = `Failed to send Slack message: ${code}`;\n\n    this.#logger?.error?.(message, { code });\n\n    return new SlackNotifierError(message, code, { cause: error });\n  }\n}\n\n/** Convenience factory for {@link SlackNotifier}. */\nexport function createSlackNotifier(config: SlackNotifierConfig): SlackNotifier {\n  return new SlackNotifier(config);\n}\n"],"mappings":"2CAKA,IAAa,EAAb,cAAwC,KAAM,CAI5C,YAAY,EAAiB,EAAc,EAAgC,CACzE,MAAM,EAAQ,CACd,KAAK,KAAO,qBACZ,KAAK,KAAO,EACR,GAAS,QAAU,IAAA,KACpB,KAA8B,MAAQ,EAAQ,SCMxC,EAAb,KAA2B,CACzB,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GAEA,YAAY,EAA6B,CACvC,MAAA,EAAgB,EAAO,SAAW,GAClC,MAAA,EAAc,EAAO,MACrB,MAAA,EAAuB,EAAO,eAC9B,MAAA,EAAwB,EAAO,gBAC/B,MAAA,EAAyB,EAAO,iBAChC,MAAA,EAAuB,EAAO,eAC9B,MAAA,EAAe,EAAO,OAIxB,IAAW,SAAmB,CAC5B,OAAO,MAAA,EAUT,MAAa,YAAY,EAAqD,CAC5E,IAAM,EAAU,EAAM,SAAW,MAAA,EAEjC,GAAI,CAAC,MAAA,EAEH,OADA,MAAA,GAAc,QAAQ,4CAA6C,CAAE,UAAS,CAAC,CACxE,CAAE,GAAI,GAAM,QAAS,GAAM,UAAW,GAAI,GAAI,GAAI,CAG3D,GAAI,CAAC,EACH,MAAM,IAAI,EACR,uDACA,mBACD,CAGH,GAAI,CAKF,IAAM,EAAO,CACX,UACA,KAAM,EAAM,KAEZ,UAAW,EAAM,SAEjB,SAAU,EAAM,UAAY,MAAA,EAE5B,WAAY,EAAM,WAAa,MAAA,EAE/B,SAAU,EAAM,SAAW,MAAA,EAC3B,GAAI,EAAM,OAAS,CAAE,OAAQ,EAAM,OAAQ,CAAG,EAAE,CACjD,CAEK,EAAW,MAAM,MAAA,GAAiB,CAAC,KAAK,YAAY,EAAK,CAI/D,OAFA,MAAA,GAAc,OAAO,qBAAsB,CAAE,QAAS,EAAS,QAAS,GAAI,EAAS,GAAI,CAAC,CAEnF,CACL,GAAI,EAAS,IAAM,GACnB,UAAW,EAAS,SAAW,GAC/B,GAAI,EAAS,IAAM,GACpB,OACM,EAAO,CACd,MAAM,MAAA,EAAgB,EAAM,EAKhC,IAAwB,CACtB,GAAI,CAAC,MAAA,EACH,MAAM,IAAI,EAAmB,+CAAgD,gBAAgB,CAG/F,MADA,OAAA,IAAiB,IAAI,EAAU,MAAA,EAAY,CACpC,MAAA,EAIT,GAAW,EAAoC,CAC7C,GAAI,aAAiB,EACnB,OAAO,EAKT,IAAM,EAAM,EACN,EAAO,GAAK,MAAM,OAAS,GAAK,MAAQ,gBACxC,EAAU,iCAAiC,IAIjD,OAFA,MAAA,GAAc,QAAQ,EAAS,CAAE,OAAM,CAAC,CAEjC,IAAI,EAAmB,EAAS,EAAM,CAAE,MAAO,EAAO,CAAC,GAKlE,SAAgB,EAAoB,EAA4C,CAC9E,OAAO,IAAI,EAAc,EAAO"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@autofleet/slack-notifier",
+  "version": "0.1.2-beta-740ca7cd.0",
+  "description": "Send messages to Slack channels via the Web API",
+  "type": "module",
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Proprietary",
+  "dependencies": {
+    "@slack/web-api": "^7.8.0"
+  },
+  "peerDependencies": {
+    "@autofleet/logger": ">=4.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@autofleet/logger": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.4",
+    "nock": "^14.0.1",
+    "@autofleet/logger": "^4.6.1"
+  },
+  "scripts": {
+    "test": "vitest",
+    "coverage": "vitest --coverage",
+    "build": "pnpm -w tsdown -W ./packages/slack-notifier"
+  }
+}