@spectrum-ts/slack 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Photon AI
+
+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
+(including the next paragraph) 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,22 @@
+# @spectrum-ts/slack
+
+Slack provider for [spectrum-ts](https://github.com/photon-hq/spectrum-ts).
+
+## Install
+
+```sh
+bun add spectrum-ts @spectrum-ts/slack
+```
+
+## Use
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { slack } from "@spectrum-ts/slack";
+
+const spectrum = Spectrum({
+  providers: [slack.config({ tokens: { T012ABCDE: "xoxb-..." } })],
+});
+```
+
+See the [spectrum-ts documentation](https://photon.codes/spectrum) for the full guide.

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { SchemaMessage } from "@spectrum-ts/core";
+import z from "zod";
+
+//#region src/types.d.ts
+declare const userSchema: z.ZodObject<{}, z.core.$strip>;
+declare const spaceSchema: z.ZodObject<{
+  id: z.ZodString;
+  teamId: z.ZodString;
+}, z.core.$strip>;
+type SlackMessage = SchemaMessage<typeof userSchema, typeof spaceSchema> & {
+  isFromMe: boolean;
+  subtype?: string;
+  threadTs?: string;
+  ts?: string;
+};
+//#endregion
+//#region src/index.d.ts
+declare const slack: import("@spectrum-ts/core").Platform<import("@spectrum-ts/core").PlatformDef<"Slack", import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+  endpoint: import("zod").ZodOptional<import("zod").ZodString>;
+  teams: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
+    appId: import("zod").ZodString;
+    botUserId: import("zod").ZodString;
+    grantedScopes: import("zod").ZodArray<import("zod").ZodString>;
+    teamName: import("zod").ZodString;
+  }, import("zod/v4/core").$strip>>>;
+  tokens: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{}, import("zod/v4/core").$strict>]>, import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+  id: import("zod").ZodString;
+  teamId: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+  teamId: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("@photon-ai/slack").SlackClient, {
+  id: string;
+}, {
+  id: string;
+  teamId: string;
+}, import("zod").ZodObject<{
+  isFromMe: import("zod").ZodBoolean;
+  subtype: import("zod").ZodOptional<import("zod").ZodString>;
+  threadTs: import("zod").ZodOptional<import("zod").ZodString>;
+  ts: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, SlackMessage, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
+//#endregion
+export { slack };

package/dist/index.js

@@ -0,0 +1,466 @@
+import { createClient, staticTokens } from "@photon-ai/slack";
+import { UnsupportedError, cloud, definePlatform, mergeStreams, stream } from "@spectrum-ts/core";
+import { asAttachment, asCustom, asReaction, asText, createLogger, errorAttrs } from "@spectrum-ts/core/authoring";
+import z from "zod";
+//#region src/auth.ts
+const log = createLogger("spectrum.slack.auth");
+const RENEWAL_RATIO = .8;
+const EXPIRY_BUFFER_MS = 3e4;
+const RETRY_DELAY_MS = 3e4;
+const cloudAuthState = /* @__PURE__ */ new WeakMap();
+const toTeamMetadata = (meta) => ({
+	appId: meta.appId,
+	botUserId: meta.botUserId,
+	grantedScopes: meta.grantedScopes,
+	teamName: meta.teamName
+});
+/**
+* Build a {@link SlackClient} backed by a {@link TokenProvider} that lazily
+* refreshes its tokens against `POST /projects/:id/slack/tokens` on TTL or on
+* an UNAUTHENTICATED bounce (slack-ts middleware calls `invalidate(teamId)`).
+*
+* Token + team metadata are kept in a single snapshot, refreshed atomically.
+* `listTeams()` returns the latest snapshot so `client.teams()` always
+* reflects active installations — used by the slack provider's message stream
+* to discover which workspaces to subscribe to.
+*/
+async function createCloudClients(projectId, projectSecret, endpoint) {
+	let tokenData = await cloud.issueSlackTokens(projectId, projectSecret);
+	let tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
+	let disposed = false;
+	let renewalTimer;
+	let refreshFailures = 0;
+	const clearRenewalTimer = () => {
+		if (renewalTimer !== void 0) {
+			clearTimeout(renewalTimer);
+			renewalTimer = void 0;
+		}
+	};
+	const refreshTokens = async () => {
+		tokenData = await cloud.issueSlackTokens(projectId, projectSecret);
+		tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
+	};
+	const onRefreshSuccess = () => {
+		if (refreshFailures > 0) {
+			log.info("slack token refresh recovered", { "spectrum.slack.auth.attempt": refreshFailures });
+			refreshFailures = 0;
+		}
+	};
+	const onRefreshFailure = (error) => {
+		refreshFailures += 1;
+		log.warn("slack token refresh failed; retrying", {
+			"spectrum.slack.auth.attempt": refreshFailures,
+			"spectrum.slack.auth.retry_in_ms": RETRY_DELAY_MS,
+			...errorAttrs(error)
+		}, error);
+	};
+	const scheduleRetry = () => {
+		if (disposed) return;
+		clearRenewalTimer();
+		renewalTimer = setTimeout(async () => {
+			if (disposed) return;
+			try {
+				await refreshTokens();
+				onRefreshSuccess();
+				scheduleRenewal();
+			} catch (retryErr) {
+				onRefreshFailure(retryErr);
+				scheduleRetry();
+			}
+		}, RETRY_DELAY_MS);
+		renewalTimer?.unref?.();
+	};
+	const scheduleRenewal = () => {
+		if (disposed) return;
+		clearRenewalTimer();
+		const ttlMs = tokenData.expiresIn * 1e3;
+		const renewInMs = Math.max(ttlMs * RENEWAL_RATIO, 5e3);
+		renewalTimer = setTimeout(async () => {
+			try {
+				await refreshTokens();
+				onRefreshSuccess();
+				scheduleRenewal();
+			} catch (err) {
+				onRefreshFailure(err);
+				scheduleRetry();
+			}
+		}, renewInMs);
+		renewalTimer?.unref?.();
+	};
+	const refreshIfNeeded = async () => {
+		if (Date.now() < tokenExpiresAt - EXPIRY_BUFFER_MS) return;
+		await refreshTokens();
+		onRefreshSuccess();
+		scheduleRenewal();
+	};
+	scheduleRenewal();
+	const client = createClient({
+		spectrumSlackEndpoint: endpoint,
+		tokenProvider: {
+			async getAccessToken(teamId) {
+				await refreshIfNeeded();
+				const token = tokenData.auth[teamId];
+				if (!token) throw new Error(`Slack team ${teamId} has no active installation in this project`);
+				return token;
+			},
+			invalidate(_teamId) {
+				tokenExpiresAt = 0;
+			},
+			async listTeams() {
+				await refreshIfNeeded();
+				const entries = Object.entries(tokenData.teams).map(([teamId, meta]) => [teamId, toTeamMetadata(meta)]);
+				return new Map(entries);
+			}
+		}
+	});
+	cloudAuthState.set(client, { dispose: async () => {
+		disposed = true;
+		clearRenewalTimer();
+	} });
+	return client;
+}
+async function disposeCloudAuth(client) {
+	const auth = cloudAuthState.get(client);
+	if (!auth) return;
+	await auth.dispose();
+	cloudAuthState.delete(client);
+}
+//#endregion
+//#region src/messages.ts
+const toRecord = (result, space, content) => ({
+	id: result.ts,
+	content,
+	space: {
+		id: result.channel,
+		teamId: space.teamId
+	},
+	timestamp: tsToDate(result.ts),
+	ts: result.ts,
+	isFromMe: true
+});
+const toUploadRecord = (result, space, content) => {
+	const shareTs = result.shares.find((s) => s.channel === space.id)?.ts;
+	return {
+		id: shareTs ?? result.file.id,
+		content,
+		space: {
+			id: space.id,
+			teamId: space.teamId
+		},
+		timestamp: shareTs ? tsToDate(shareTs) : /* @__PURE__ */ new Date(),
+		ts: shareTs,
+		isFromMe: true
+	};
+};
+const tsToDate = (ts) => {
+	if (!ts) return /* @__PURE__ */ new Date();
+	const seconds = Number.parseFloat(ts);
+	if (!Number.isFinite(seconds)) return /* @__PURE__ */ new Date();
+	return /* @__PURE__ */ new Date(seconds * 1e3);
+};
+const lazySlackFile = (client, teamId, file) => asAttachment({
+	id: file.id,
+	name: file.name,
+	mimeType: file.mimeType,
+	size: file.size,
+	read: async () => {
+		const { bytes } = await client.team(teamId).files.getContentBuffer(file.id);
+		return Buffer.from(bytes);
+	},
+	stream: async () => {
+		const { content } = await client.team(teamId).files.getContent(file.id);
+		return new ReadableStream({ async start(controller) {
+			try {
+				for await (const chunk of content) controller.enqueue(chunk);
+				controller.close();
+			} catch (err) {
+				controller.error(err);
+			}
+		} });
+	}
+});
+const toMessages = (client, event) => {
+	if (event.type === "message") return messageToMessages(client, event.teamId, event.message);
+	if (event.type === "reaction") return [reactionToMessage(event.teamId, event.reaction)];
+	if (event.type === "mention") return [{
+		id: event.mention.ts,
+		content: asText(event.mention.text),
+		sender: { id: event.mention.user },
+		space: {
+			id: event.mention.channel,
+			teamId: event.teamId
+		},
+		timestamp: tsToDate(event.mention.ts),
+		ts: event.mention.ts,
+		isFromMe: event.mention.isFromMe
+	}];
+	return [];
+};
+const messageToMessages = (client, teamId, msg) => {
+	const base = {
+		sender: { id: msg.user },
+		space: {
+			id: msg.channel,
+			teamId
+		},
+		timestamp: tsToDate(msg.ts),
+		ts: msg.ts,
+		threadTs: msg.threadTs,
+		subtype: msg.subtype,
+		isFromMe: msg.isFromMe
+	};
+	const results = [];
+	if (msg.text) results.push({
+		...base,
+		id: msg.files.length > 0 ? `${msg.ts}:text` : msg.ts,
+		content: asText(msg.text)
+	});
+	for (const [index, file] of msg.files.entries()) {
+		const singleFile = msg.files.length === 1 && !msg.text;
+		results.push({
+			...base,
+			id: singleFile ? msg.ts : `${msg.ts}:file:${index}`,
+			content: lazySlackFile(client, teamId, file)
+		});
+	}
+	if (results.length === 0) results.push({
+		...base,
+		id: msg.ts,
+		content: asCustom({ slack_type: "empty" })
+	});
+	return results;
+};
+const reactionToMessage = (teamId, reaction) => {
+	const stubTarget = {
+		id: reaction.itemTs,
+		content: asCustom({
+			slack_type: "reaction-target",
+			stub: true
+		}),
+		sender: { id: "" },
+		space: {
+			id: reaction.itemChannel,
+			teamId
+		}
+	};
+	return {
+		id: `${reaction.itemTs}:reaction:${reaction.user}:${reaction.name}`,
+		content: asReaction({
+			emoji: reaction.name,
+			target: stubTarget
+		}),
+		sender: { id: reaction.user },
+		space: {
+			id: reaction.itemChannel,
+			teamId
+		},
+		timestamp: /* @__PURE__ */ new Date(),
+		ts: reaction.itemTs,
+		subtype: reaction.removed ? "reaction_removed" : "reaction_added",
+		isFromMe: reaction.isFromMe
+	};
+};
+const teamStream = (client, teamId) => {
+	const eventStream = client.team(teamId).events.subscribe();
+	return stream((emit, end) => {
+		const pump = (async () => {
+			try {
+				for await (const event of eventStream) for (const m of toMessages(client, event)) await emit(m);
+				end();
+			} catch (e) {
+				end(e);
+			}
+		})();
+		return async () => {
+			await eventStream.close();
+			await pump;
+		};
+	});
+};
+const messages = (client, resolveTeamIds) => stream(async (emit, end) => {
+	let teamIds;
+	try {
+		teamIds = await resolveTeamIds();
+	} catch (err) {
+		end(err);
+		return;
+	}
+	const merged = mergeStreams(teamIds.map((id) => teamStream(client, id)));
+	const pump = (async () => {
+		try {
+			for await (const value of merged) await emit(value);
+			end();
+		} catch (e) {
+			end(e);
+		}
+	})();
+	return async () => {
+		await merged.close();
+		await pump;
+	};
+});
+const mimeToMediaName = (mimeType, fallback) => {
+	const slash = mimeType.indexOf("/");
+	if (slash < 0) return fallback;
+	return `${fallback}.${mimeType.slice(slash + 1)}`;
+};
+const send = async (client, space, content) => {
+	if (content.type === "reply") return await replyToMessage(client, space, content.target.ts ?? content.target.id, content.content);
+	if (content.type === "reaction") return await reactToMessage(client, space, content.target.ts ?? content.target.id, content);
+	if (content.type === "typing") return;
+	if (content.type === "read") return;
+	return await sendContent(client, space, content);
+};
+const sendContent = async (client, space, content, threadTs) => {
+	const team = client.team(space.teamId);
+	switch (content.type) {
+		case "text": return toRecord(await team.messages.send({
+			channel: space.id,
+			text: content.text,
+			threadTs
+		}), space, content);
+		case "attachment": return toUploadRecord(await team.files.upload({
+			channel: space.id,
+			content: await content.read(),
+			filename: content.name,
+			mimeType: content.mimeType,
+			threadTs
+		}), space, content);
+		case "voice": return toUploadRecord(await team.files.upload({
+			channel: space.id,
+			content: await content.read(),
+			filename: content.name ?? mimeToMediaName(content.mimeType, "voice"),
+			mimeType: content.mimeType,
+			threadTs
+		}), space, content);
+		case "app": return toRecord(await team.messages.send({
+			channel: space.id,
+			text: await content.url(),
+			threadTs
+		}), space, content);
+		default: throw UnsupportedError.content(content.type);
+	}
+};
+const reactToMessage = async (client, space, targetTs, content) => {
+	await client.team(space.teamId).messages.send({
+		channel: space.id,
+		reaction: {
+			emoji: content.emoji,
+			itemChannel: space.id,
+			itemTs: targetTs
+		}
+	});
+	return {
+		id: `${targetTs}:reaction:self:${content.emoji}`,
+		content,
+		space: {
+			id: space.id,
+			teamId: space.teamId
+		},
+		timestamp: /* @__PURE__ */ new Date(),
+		ts: targetTs,
+		isFromMe: true
+	};
+};
+const replyToMessage = async (client, space, targetTs, content) => await sendContent(client, space, content, targetTs);
+//#endregion
+//#region src/types.ts
+const teamMetadataSchema = z.object({
+	appId: z.string(),
+	botUserId: z.string(),
+	grantedScopes: z.array(z.string()),
+	teamName: z.string()
+});
+const directConfig = z.object({
+	endpoint: z.string().optional(),
+	teams: z.record(z.string(), teamMetadataSchema).optional(),
+	tokens: z.record(z.string(), z.string().min(1)).refine((t) => Object.keys(t).length > 0, { message: "at least one token entry is required" })
+});
+const cloudConfig = z.object({}).strict();
+const configSchema = z.union([directConfig, cloudConfig]);
+const isCloudConfig = (config) => !("tokens" in config);
+const userSchema = z.object({});
+const spaceSchema = z.object({
+	id: z.string(),
+	teamId: z.string()
+});
+const spaceParamsSchema = z.object({ teamId: z.string() });
+/**
+* Slack-specific per-message metadata surfaced on `SlackMessage`.
+* - `isFromMe`: server-stamped by spectrum-slack — `true` when `sender.id` is
+*   this installation's bot user id. Use this to filter self-echo without
+*   plumbing `bot_user_id` from `client.teams()` into the consumer.
+* - `ts`: the canonical Slack message timestamp id (mirrors `id` for messages
+*   sourced from the events stream; useful when constructing replies that
+*   target the same thread).
+* - `threadTs`: the parent message ts when the row is itself a threaded reply.
+* - `subtype`: Slack's subtype, e.g. `bot_message`, `message_changed`, etc.
+*/
+const messageSchema = z.object({
+	isFromMe: z.boolean(),
+	subtype: z.string().optional(),
+	threadTs: z.string().optional(),
+	ts: z.string().optional()
+});
+//#endregion
+//#region src/index.ts
+const slack = definePlatform("Slack", {
+	config: configSchema,
+	lifecycle: {
+		createClient: async ({ config, projectId, projectSecret }) => {
+			if (!isCloudConfig(config)) return createClient({
+				spectrumSlackEndpoint: config.endpoint,
+				tokenProvider: staticTokens({
+					tokens: config.tokens,
+					teams: config.teams
+				})
+			});
+			if (!(projectId && projectSecret)) throw new Error("Slack cloud mode requires projectId and projectSecret. Either pass credentials to Spectrum(), or provide direct credentials: slack.config({ tokens: { T012ABCDE: 'jwt...' } })");
+			return await createCloudClients(projectId, projectSecret, process.env.SPECTRUM_SLACK_ENDPOINT);
+		},
+		destroyClient: async ({ client }) => {
+			await disposeCloudAuth(client);
+			await client.close();
+		}
+	},
+	user: {
+		schema: userSchema,
+		resolve: async ({ input }) => ({ id: input.userID })
+	},
+	space: {
+		schema: spaceSchema,
+		params: spaceParamsSchema,
+		create: async ({ input }) => {
+			const teamId = input.params?.teamId;
+			if (!teamId) throw new Error("Slack space creation requires a teamId param. Pass it via space.create(user, { teamId }).");
+			if (input.users.length > 1) throw UnsupportedError.action("space.create", "Slack", "group DMs require an explicit channel id (Slack's conversations.open is not exposed); use space.get(channelId, { teamId })");
+			const user = input.users[0];
+			if (!user) throw new Error("Slack space creation requires a user");
+			return {
+				id: user.id,
+				teamId
+			};
+		},
+		get: async ({ input }) => {
+			const teamId = input.params?.teamId;
+			if (!teamId) throw new Error("Slack spaces require a teamId param. Pass it via space.get(channelId, { teamId }).");
+			return {
+				id: input.id,
+				teamId
+			};
+		}
+	},
+	message: { schema: messageSchema },
+	messages: ({ client, config }) => messages(client, async () => {
+		const teams = await client.teams();
+		if (teams.size > 0) return Array.from(teams.keys());
+		if (isCloudConfig(config)) return [];
+		return Object.keys(config.tokens);
+	}),
+	send: async ({ space, content, client }) => await send(client, {
+		id: space.id,
+		teamId: space.teamId
+	}, content)
+});
+//#endregion
+export { slack };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@spectrum-ts/slack",
+  "version": "5.0.0",
+  "description": "Slack provider for spectrum-ts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photon-hq/spectrum-ts.git",
+    "directory": "packages/slack"
+  },
+  "homepage": "https://photon.codes/spectrum",
+  "bugs": {
+    "url": "https://github.com/photon-hq/spectrum-ts/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "spectrum": {
+    "key": "slack",
+    "import": "slack",
+    "label": "Slack"
+  },
+  "dependencies": {
+    "@photon-ai/slack": "^0.2.0",
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@spectrum-ts/core": "^5.0.0",
+    "typescript": "^5 || ^6.0.0"
+  },
+  "license": "MIT"
+}