@betternotify/slack 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Better-Notify contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @betternotify/slack
+
+Slack channel for [Better-Notify](https://github.com/better-notify/better-notify). Provides `slackChannel()`, a `mockSlackTransport` for tests, and a `slackTransport` that posts to Slack via incoming webhooks or the Web API.
+
+<p>
+  <a href="https://better-notify.com">Website</a> ·
+  <a href="https://better-notify.com/docs">Docs</a> ·
+  <a href="https://github.com/better-notify/better-notify">GitHub</a> ·
+  <a href="https://x.com/better_notify">X</a>
+</p>
+
+## Install
+
+```sh
+npm install @betternotify/slack @betternotify/core
+```
+
+## Usage
+
+```ts
+import { createNotify, createClient } from '@betternotify/core';
+import { slackChannel, mockSlackTransport } from '@betternotify/slack';
+import { z } from 'zod';
+
+const slack = slackChannel();
+const rpc = createNotify({ channels: { slack } });
+
+const catalog = rpc.catalog({
+  deployAlert: rpc
+    .slack()
+    .input(z.object({ service: z.string(), version: z.string() }))
+    .text(({ input }) => `*${input.service}* deployed v${input.version}`)
+    .blocks(({ input }) => [
+      { type: 'header', text: { type: 'plain_text', text: 'Deployment' } },
+      {
+        type: 'section',
+        fields: [
+          { type: 'mrkdwn', text: `*Service:* ${input.service}` },
+          { type: 'mrkdwn', text: `*Version:* ${input.version}` },
+        ],
+      },
+    ]),
+});
+
+const notify = createClient({
+  catalog,
+  channels: { slack },
+  transportsByChannel: { slack: mockSlackTransport() },
+});
+
+await notify.deployAlert.send({
+  to: 'https://hooks.slack.com/services/...',
+  input: { service: 'api', version: '2.1.0' },
+});
+```
+
+## Builder slots
+
+| Slot     | Required | Type                                        |
+| -------- | -------- | ------------------------------------------- |
+| `text`   | yes      | `string \| ({input}) => string`             |
+| `blocks` | no       | `SlackBlock[] \| ({input}) => SlackBlock[]` |
+| `file`   | no       | `SlackFile \| ({input}) => SlackFile`       |
+
+Plus `.input(schema)` and `.use(mw)`.
+
+## Send args
+
+```ts
+notify.deployAlert.send({
+  to: string, // Slack webhook URL or channel ID
+  input: TInput,
+});
+```
+
+## Transports
+
+```ts
+import { slackTransport, mockSlackTransport } from '@betternotify/slack';
+
+const transport = slackTransport({
+  botToken: process.env.SLACK_BOT_TOKEN!,
+});
+```
+
+- `mockSlackTransport()` — records sent messages for tests.
+- `slackTransport({ botToken })` — sends via Slack Web API / incoming webhooks.
+
+Custom transport contract: `Transport<RenderedSlack, SlackTransportData>`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,319 @@
+import * as _betternotify_core0 from "@betternotify/core";
+import { LoggerLike, Transport as Transport$1 } from "@betternotify/core";
+import { HttpClientBehaviorOptions, MockTransport } from "@betternotify/core/transports";
+
+//#region src/types.d.ts
+type SlackPlainText = {
+  type: 'plain_text';
+  text: string;
+  emoji?: boolean;
+};
+type SlackMrkdwn = {
+  type: 'mrkdwn';
+  text: string;
+  verbatim?: boolean;
+};
+type SlackText = SlackPlainText | SlackMrkdwn;
+type SlackOption = {
+  text: SlackText;
+  value: string;
+  description?: SlackPlainText;
+};
+type SlackOptionGroup = {
+  label: SlackPlainText;
+  options: SlackOption[];
+};
+type SlackConfirmDialog = {
+  title: SlackPlainText;
+  text: SlackText;
+  confirm: SlackPlainText;
+  deny: SlackPlainText;
+  style?: 'primary' | 'danger';
+};
+type SlackButtonElement = {
+  type: 'button';
+  text: SlackPlainText;
+  action_id: string;
+  url?: string;
+  value?: string;
+  style?: 'primary' | 'danger';
+  confirm?: SlackConfirmDialog;
+};
+type SlackImageElement = {
+  type: 'image';
+  image_url: string;
+  alt_text: string;
+};
+type SlackOverflowElement = {
+  type: 'overflow';
+  action_id: string;
+  options: SlackOption[];
+  confirm?: SlackConfirmDialog;
+};
+type SlackDatepickerElement = {
+  type: 'datepicker';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  initial_date?: string;
+  confirm?: SlackConfirmDialog;
+};
+type SlackTimepickerElement = {
+  type: 'timepicker';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  initial_time?: string;
+  confirm?: SlackConfirmDialog;
+};
+type SlackStaticSelectElement = {
+  type: 'static_select';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  options: SlackOption[];
+  option_groups?: SlackOptionGroup[];
+  initial_option?: SlackOption;
+  confirm?: SlackConfirmDialog;
+};
+type SlackMultiStaticSelectElement = {
+  type: 'multi_static_select';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  options: SlackOption[];
+  option_groups?: SlackOptionGroup[];
+  initial_options?: SlackOption[];
+  max_selected_items?: number;
+  confirm?: SlackConfirmDialog;
+};
+type SlackCheckboxesElement = {
+  type: 'checkboxes';
+  action_id: string;
+  options: SlackOption[];
+  initial_options?: SlackOption[];
+  confirm?: SlackConfirmDialog;
+};
+type SlackRadioButtonsElement = {
+  type: 'radio_buttons';
+  action_id: string;
+  options: SlackOption[];
+  initial_option?: SlackOption;
+  confirm?: SlackConfirmDialog;
+};
+type SlackPlainTextInputElement = {
+  type: 'plain_text_input';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  initial_value?: string;
+  multiline?: boolean;
+  min_length?: number;
+  max_length?: number;
+};
+type SlackNumberInputElement = {
+  type: 'number_input';
+  action_id: string;
+  is_decimal_allowed: boolean;
+  placeholder?: SlackPlainText;
+  initial_value?: string;
+  min_value?: string;
+  max_value?: string;
+};
+type SlackUrlInputElement = {
+  type: 'url_text_input';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  initial_value?: string;
+};
+type SlackEmailInputElement = {
+  type: 'email_text_input';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  initial_value?: string;
+};
+type SlackRichTextInputElement = {
+  type: 'rich_text_input';
+  action_id: string;
+  placeholder?: SlackPlainText;
+  initial_value?: Record<string, unknown>;
+};
+type SlackInteractiveElement = SlackButtonElement | SlackOverflowElement | SlackDatepickerElement | SlackTimepickerElement | SlackStaticSelectElement | SlackMultiStaticSelectElement | SlackCheckboxesElement | SlackRadioButtonsElement;
+type SlackInputElement = SlackPlainTextInputElement | SlackNumberInputElement | SlackUrlInputElement | SlackEmailInputElement | SlackRichTextInputElement | SlackStaticSelectElement | SlackMultiStaticSelectElement | SlackCheckboxesElement | SlackRadioButtonsElement | SlackDatepickerElement | SlackTimepickerElement;
+type SlackAccessoryElement = SlackInteractiveElement | SlackImageElement;
+type SlackHeaderBlock = {
+  type: 'header';
+  text: SlackPlainText;
+  block_id?: string;
+};
+type SlackSectionBlock = {
+  type: 'section';
+  text?: SlackText;
+  fields?: SlackText[];
+  accessory?: SlackAccessoryElement;
+  expand?: boolean;
+  block_id?: string;
+};
+type SlackImageBlock = {
+  type: 'image';
+  image_url: string;
+  alt_text: string;
+  title?: SlackPlainText;
+  block_id?: string;
+};
+type SlackVideoBlock = {
+  type: 'video';
+  alt_text: string;
+  title: SlackPlainText;
+  thumbnail_url: string;
+  video_url: string;
+  description?: SlackPlainText;
+  title_url?: string;
+  author_name?: string;
+  provider_name?: string;
+  provider_icon_url?: string;
+  block_id?: string;
+};
+type SlackDividerBlock = {
+  type: 'divider';
+  block_id?: string;
+};
+type SlackActionsBlock = {
+  type: 'actions';
+  elements: SlackInteractiveElement[];
+  block_id?: string;
+};
+type SlackContextBlock = {
+  type: 'context';
+  elements: (SlackText | SlackImageElement)[];
+  block_id?: string;
+};
+type SlackInputBlock = {
+  type: 'input';
+  label: SlackPlainText;
+  element: SlackInputElement;
+  hint?: SlackPlainText;
+  optional?: boolean;
+  dispatch_action?: boolean;
+  block_id?: string;
+};
+type SlackFileBlock = {
+  type: 'file';
+  external_id: string;
+  source: 'remote';
+  block_id?: string;
+};
+type SlackRichTextBlock = {
+  type: 'rich_text';
+  elements: Record<string, unknown>[];
+  block_id?: string;
+};
+type SlackBlock = SlackHeaderBlock | SlackSectionBlock | SlackImageBlock | SlackVideoBlock | SlackDividerBlock | SlackActionsBlock | SlackContextBlock | SlackInputBlock | SlackFileBlock | SlackRichTextBlock;
+type SlackFile = {
+  data: Buffer | Uint8Array;
+  filename: string;
+  title?: string;
+  altText?: string;
+};
+type SlackSendArgs<TInput = unknown> = {
+  to?: string;
+  threadTs?: string;
+  input: TInput;
+};
+type RenderedSlack = {
+  text: string;
+  to?: string;
+  blocks?: SlackBlock[];
+  threadTs?: string;
+  file?: SlackFile;
+};
+//#endregion
+//#region src/channel.d.ts
+type TextResolver<TInput> = string | ((args: {
+  input: TInput;
+  ctx: unknown;
+}) => string);
+type BlocksResolver<TInput> = SlackBlock[] | ((args: {
+  input: TInput;
+  ctx: unknown;
+}) => SlackBlock[]);
+type FileResolver<TInput> = SlackFile | ((args: {
+  input: TInput;
+  ctx: unknown;
+}) => SlackFile);
+/**
+ * Slack notification channel.
+ *
+ * Slots:
+ * - `.text()` — Required fallback string. Shown in push notifications,
+ *   desktop alerts, and screen readers. Always sent even when blocks are present.
+ * - `.blocks()` — Optional rich layout (sections, headers, images, actions).
+ *   This is what renders in the Slack client UI. Falls back to `text` if blocks
+ *   cannot render.
+ * - `.file()` — Optional file attachment uploaded alongside the message.
+ */
+declare const slackChannel: () => _betternotify_core0.Channel<"slack", _betternotify_core0.ChannelBuilder<unknown, {
+  text: string;
+  blocks: SlackBlock[];
+  file: SlackFile;
+}, {
+  /** Required fallback text for notifications, alerts, and accessibility. */
+  text: _betternotify_core0.SlotConfig<"resolver"> & {
+    required: true;
+    __value?: string | undefined;
+    optional: () => _betternotify_core0.SlotConfig<"resolver"> & {
+      required: false;
+      __value?: string | undefined;
+      optional: /*elided*/any;
+    };
+  };
+  /** Rich Block Kit layout rendered in the Slack client; falls back to `text`. */
+  blocks: _betternotify_core0.SlotConfig<"resolver"> & {
+    required: false;
+    __value?: SlackBlock[] | undefined;
+    optional: () => _betternotify_core0.SlotConfig<"resolver"> & /*elided*/any;
+  };
+  /** File attachment uploaded with the message. */
+  file: _betternotify_core0.SlotConfig<"resolver"> & {
+    required: false;
+    __value?: SlackFile | undefined;
+    optional: () => _betternotify_core0.SlotConfig<"resolver"> & /*elided*/any;
+  };
+}, Omit<{
+  input: unknown;
+  to?: string | undefined;
+  threadTs?: string | undefined;
+}, "input">, RenderedSlack>, {
+  input: unknown;
+  to?: string | undefined;
+  threadTs?: string | undefined;
+}, RenderedSlack, _betternotify_core0.Transport<RenderedSlack, unknown>>;
+//#endregion
+//#region src/is-retriable.d.ts
+declare const isSlackRetriable: (err: unknown) => boolean;
+//#endregion
+//#region src/transports/types.d.ts
+type SlackTransportData = {
+  ts: string;
+  channel: string;
+};
+type SlackTransportResult = SlackTransportData;
+type Transport = Transport$1<RenderedSlack, SlackTransportData>;
+//#endregion
+//#region src/transports/mock.d.ts
+type MockSlackTransport = MockTransport<RenderedSlack, SlackTransportData> & {
+  readonly messages: ReadonlyArray<RenderedSlack & {
+    id: string;
+  }>;
+};
+declare const mockSlackTransport: () => MockSlackTransport;
+//#endregion
+//#region src/transports/slack.types.d.ts
+/** Configuration options for the Slack transport. */
+type SlackTransportOptions = {
+  token: string;
+  defaultChannel?: string;
+  baseUrl?: string;
+  logger?: LoggerLike;
+  http?: HttpClientBehaviorOptions;
+};
+//#endregion
+//#region src/transports/slack.d.ts
+declare const slackTransport: (opts: SlackTransportOptions) => Transport;
+//#endregion
+export { type BlocksResolver, type FileResolver, type MockSlackTransport, type RenderedSlack, type SlackAccessoryElement, type SlackActionsBlock, type SlackBlock, type SlackButtonElement, type SlackCheckboxesElement, type SlackConfirmDialog, type SlackContextBlock, type SlackDatepickerElement, type SlackDividerBlock, type SlackEmailInputElement, type SlackFile, type SlackFileBlock, type SlackHeaderBlock, type SlackImageBlock, type SlackImageElement, type SlackInputBlock, type SlackInputElement, type SlackInteractiveElement, type SlackMrkdwn, type SlackMultiStaticSelectElement, type SlackNumberInputElement, type SlackOption, type SlackOptionGroup, type SlackOverflowElement, type SlackPlainText, type SlackPlainTextInputElement, type SlackRadioButtonsElement, type SlackRichTextBlock, type SlackRichTextInputElement, type SlackSectionBlock, type SlackSendArgs, type SlackStaticSelectElement, type SlackText, type SlackTimepickerElement, type SlackTransportData, type SlackTransportOptions, type SlackTransportResult, type SlackUrlInputElement, type SlackVideoBlock, type TextResolver, type Transport, isSlackRetriable, mockSlackTransport, slackChannel, slackTransport };