@theholocron/holocron-plugin-slack 3.25.1 → 3.26.0

package/README.md

@@ -0,0 +1,51 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-slack`
+
+Slack plugin for [Holocron](../cli). Implements the `notifications`
+capability via the [Slack Web API](https://api.slack.com/web).
+
+## Install
+
+<!-- prettier-ignore -->
+```bash
+pnpm add -D @theholocron/holocron-plugin-slack
+
+```
+
+## Auth
+
+Token resolution order:
+
+1. `--token <TOKEN>` flag on the holocron invocation
+2. `HOLOCRON_SLACK_TOKEN` env var
+3. `SLACK_BOT_TOKEN` env var (the standard Slack variable name)
+
+Create a Slack app at **api.slack.com/apps**, add the `chat:write` bot
+scope, install it to your workspace, and copy the **Bot User OAuth Token**
+(`xoxb-…`). The bot must be invited to any channel it will post to
+(`/invite @YourBotName`).
+
+## Config
+
+<!-- prettier-ignore -->
+```jsonc
+{
+  "providers": {
+    "notifications": ["slack", { "defaultChannel": "C0123456789" }],
+  },
+}
+
+```
+
+- `defaultChannel` (optional) — Slack channel id used when `send()` is
+  called with an empty string.
+
+## What's implemented
+
+| Method | What it does                                                                                                                       |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `send` | Posts a plain-text message to the given channel id via `chat.postMessage`. Falls back to `defaultChannel` when `channel` is empty. |
+
+Slack always returns HTTP 200 with an `ok` field — errors are surfaced as
+`ProviderApiError` from the response body rather than from the HTTP status.

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { AuthError, Notifications, ResolveTokenInput } from "@theholocron/cli";
+//#region src/auth.d.ts
+declare const resolveToken: (input?: ResolveTokenInput) => string;
+//#endregion
+//#region src/rest.d.ts
+interface SlackClientOptions {
+  token: string;
+  /** Override base URL for tests. Default: https://slack.com/api */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface SlackClient {
+  auth: {
+    test(): Promise<{
+      ok: true;
+      team: string;
+      user: string;
+    }>;
+  };
+  chat: {
+    postMessage(channel: string, text: string): Promise<void>;
+  };
+}
+declare function createSlackClient({ token, baseUrl, fetch: fetchImpl }: SlackClientOptions): SlackClient;
+//#endregion
+//#region src/capabilities/notifications.d.ts
+interface SlackNotificationsOptions {
+  /** Default channel id used when `send()` is called without an explicit channel. */
+  defaultChannel?: string;
+}
+declare class SlackNotifications implements Notifications {
+  private readonly client;
+  private readonly opts;
+  readonly key: "notifications";
+  readonly providerName = "slack";
+  constructor(client: SlackClient, opts: SlackNotificationsOptions);
+  send(channel: string, message: string): Promise<void>;
+}
+//#endregion
+//#region src/verify-token.d.ts
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
+//#region src/index.d.ts
+interface SlackPluginOptions extends ResolveTokenInput, SlackNotificationsOptions {
+  /** Override base URL for tests. Default: https://slack.com/api */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: SlackPluginOptions;
+  client: SlackClient;
+}
+declare function createContext(options?: SlackPluginOptions): PluginContext;
+declare function notifications(ctx: PluginContext): Notifications;
+declare function createPlugin(options?: SlackPluginOptions): {
+  name: string;
+  capabilities: {
+    notifications: () => Notifications;
+  };
+};
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, PluginContext, type ResolveTokenInput, type SlackClient, type SlackClientOptions, SlackNotifications, type SlackNotificationsOptions, SlackPluginOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, createSlackClient, notifications, resolveToken, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,99 @@
+import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+//#region src/auth.ts
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_SLACK_TOKEN",
+	vendorEnvName: "SLACK_BOT_TOKEN",
+	keyringService: "slack",
+	errorMessage: "no Slack bot token found. Pass --token <TOKEN>, set HOLOCRON_SLACK_TOKEN / SLACK_BOT_TOKEN, or run: holocron auth set slack <xoxb-TOKEN>"
+});
+//#endregion
+//#region src/capabilities/notifications.ts
+var SlackNotifications = class {
+	client;
+	opts;
+	key = "notifications";
+	providerName = "slack";
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
+	}
+	async send(channel, message) {
+		const ch = channel || this.opts.defaultChannel;
+		if (!ch) throw new Error("SlackNotifications.send: channel required (pass a channel id or set defaultChannel)");
+		await this.client.chat.postMessage(ch, message);
+	}
+};
+//#endregion
+//#region src/rest.ts
+function createSlackClient({ token, baseUrl, fetch: fetchImpl }) {
+	const base = baseUrl ?? "https://slack.com/api";
+	const f = fetchImpl ?? globalThis.fetch;
+	async function call(method, body) {
+		const res = await f(`${base}/${method}`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json; charset=utf-8",
+				authorization: `Bearer ${token}`
+			},
+			body: JSON.stringify(body)
+		});
+		const data = await res.json();
+		if (!data.ok) throw new ProviderApiError(data.error ?? "unknown Slack error", res.status, data);
+		return data;
+	}
+	return {
+		auth: { test: () => call("auth.test", {}) },
+		chat: { postMessage: async (channel, text) => {
+			await call("chat.postMessage", {
+				channel,
+				text
+			});
+		} }
+	};
+}
+//#endregion
+//#region src/verify-token.ts
+async function verifyToken(token, opts = {}) {
+	const client = createSlackClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
+	try {
+		const res = await client.auth.test();
+		return {
+			ok: true,
+			subject: `${res.user} @ ${res.team}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options = {}) {
+	return {
+		options,
+		client: createSlackClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
+	};
+}
+function notifications(ctx) {
+	return new SlackNotifications(ctx.client, ctx.options);
+}
+function createPlugin(options = {}) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-slack",
+		capabilities: { notifications: () => notifications(ctx) }
+	};
+}
+const AUTH_HINT = "create a Slack app at https://api.slack.com/apps, add the chat:write bot scope, install it to your workspace, copy the Bot User OAuth Token (xoxb-...), then run: holocron auth set slack <xoxb-TOKEN>";
+//#endregion
+export { AUTH_HINT, AuthError, SlackNotifications, createContext, createPlugin, createSlackClient, notifications, resolveToken, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-slack",
-  "version": "3.25.1",
+  "version": "3.26.0",
   "description": "Holocron plugin for Slack. Implements the notifications capability via Slack's bot API.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-slack#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -21,7 +21,7 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "3.25.1"
+    "@theholocron/cli": "3.26.0"
   },
   "devDependencies": {
     "@theholocron/eslint-config": "^7.19.1",
@@ -39,7 +39,7 @@
     "tsx": "4.22.4",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@theholocron/cli": "3.25.1"
+    "@theholocron/cli": "3.26.0"
   },
   "publishConfig": {
     "access": "public"