@spectrum-ts/whatsapp-business 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/whatsapp-business
+
+WhatsApp Business provider for [spectrum-ts](https://github.com/photon-hq/spectrum-ts).
+
+## Install
+
+```sh
+bun add spectrum-ts @spectrum-ts/whatsapp-business
+```
+
+## Use
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { whatsappBusiness } from "@spectrum-ts/whatsapp-business";
+
+const spectrum = Spectrum({
+  providers: [whatsappBusiness.config({ /* ... */ })],
+});
+```
+
+See the [spectrum-ts documentation](https://photon.codes/spectrum) for the full guide.

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { WhatsAppClient } from "@photon-ai/whatsapp-business";
+import { SchemaMessage } from "@spectrum-ts/core";
+import z from "zod";
+
+//#region src/types.d.ts
+type WhatsAppClients = WhatsAppClient[];
+declare const userSchema: z.ZodObject<{}, z.core.$strip>;
+declare const spaceSchema: z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strip>;
+type WhatsAppMessage = SchemaMessage<typeof userSchema, typeof spaceSchema>;
+//#endregion
+//#region src/index.d.ts
+declare const whatsappBusiness: import("@spectrum-ts/core").Platform<import("@spectrum-ts/core").PlatformDef<"WhatsApp Business", import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+  accessToken: import("zod").ZodString;
+  appSecret: import("zod").ZodOptional<import("zod").ZodString>;
+  phoneNumberId: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{}, import("zod/v4/core").$strict>]>, import("zod").ZodType<object, unknown, import("zod/v4/core").$ZodTypeInternals<object, unknown>> | undefined, import("zod").ZodObject<{
+  id: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodType<object, unknown, import("zod/v4/core").$ZodTypeInternals<object, unknown>> | undefined, WhatsAppClients, {
+  id: string;
+}, {
+  id: string;
+}, undefined, WhatsAppMessage, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
+//#endregion
+export { whatsappBusiness };

package/dist/index.js

@@ -0,0 +1,666 @@
+import { TypedEventStream, button, buttons, createClient, list } from "@photon-ai/whatsapp-business";
+import { UnsupportedError, cloud, definePlatform, mergeStreams, stream } from "@spectrum-ts/core";
+import { asAttachment, asContact, asCustom, asPollOption, asReaction, asText, createLogger, errorAttrs } from "@spectrum-ts/core/authoring";
+import { extension } from "mime-types";
+import z from "zod";
+//#region src/auth.ts
+const log = createLogger("spectrum.whatsapp.auth");
+const streamLog = createLogger("spectrum.whatsapp.stream");
+const RENEWAL_RATIO = .8;
+const EXPIRY_BUFFER_MS = 3e4;
+const RETRY_DELAY_MS = 3e4;
+const RESUBSCRIBE_BACKOFF_MS = 500;
+const cloudAuthState = /* @__PURE__ */ new WeakMap();
+async function createCloudClients(projectId, projectSecret) {
+	let tokenData = await cloud.issueWhatsappBusinessTokens(projectId, projectSecret);
+	let tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
+	let disposed = false;
+	let renewalTimer;
+	let refreshFailures = 0;
+	const lines = /* @__PURE__ */ new Map();
+	const buildRawClient = (phoneNumberId) => {
+		const accessToken = tokenData.auth[phoneNumberId];
+		if (!accessToken) throw new Error(`WhatsApp Business line ${phoneNumberId} missing from token response`);
+		return createClient({
+			accessToken,
+			appSecret: "",
+			phoneNumberId
+		});
+	};
+	const refreshTokens = async () => {
+		tokenData = await cloud.issueWhatsappBusinessTokens(projectId, projectSecret);
+		tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
+		for (const [phoneNumberId, state] of lines) {
+			if (!tokenData.auth[phoneNumberId]) continue;
+			const old = state.current;
+			state.current = buildRawClient(phoneNumberId);
+			for (const sub of state.subscriptions) sub.swap();
+			await old.close().catch(() => void 0);
+		}
+	};
+	const onRefreshSuccess = () => {
+		if (refreshFailures > 0) {
+			log.info("whatsapp token refresh recovered", { "spectrum.whatsapp.auth.attempt": refreshFailures });
+			refreshFailures = 0;
+		}
+	};
+	const onRefreshFailure = (error) => {
+		refreshFailures += 1;
+		log.warn("whatsapp token refresh failed; retrying", {
+			"spectrum.whatsapp.auth.attempt": refreshFailures,
+			"spectrum.whatsapp.auth.retry_in_ms": RETRY_DELAY_MS,
+			...errorAttrs(error)
+		}, error);
+	};
+	const clearRenewalTimer = () => {
+		if (renewalTimer !== void 0) {
+			clearTimeout(renewalTimer);
+			renewalTimer = void 0;
+		}
+	};
+	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);
+				clearRenewalTimer();
+				renewalTimer = setTimeout(() => scheduleRenewal(), RETRY_DELAY_MS);
+				renewalTimer?.unref?.();
+			}
+		}, renewInMs);
+		renewalTimer?.unref?.();
+	};
+	const refreshIfNeeded = async () => {
+		if (Date.now() < tokenExpiresAt - EXPIRY_BUFFER_MS) return;
+		await refreshTokens();
+		onRefreshSuccess();
+		scheduleRenewal();
+	};
+	scheduleRenewal();
+	const clients = Object.keys(tokenData.auth).map((phoneNumberId) => {
+		const state = {
+			current: buildRawClient(phoneNumberId),
+			subscriptions: /* @__PURE__ */ new Set()
+		};
+		lines.set(phoneNumberId, state);
+		return buildClientProxy(state, refreshIfNeeded);
+	});
+	cloudAuthState.set(clients, { dispose: async () => {
+		disposed = true;
+		clearRenewalTimer();
+		for (const state of lines.values()) for (const sub of state.subscriptions) sub.close();
+		await Promise.allSettled(Array.from(lines.values()).map((s) => s.current.close()));
+		lines.clear();
+	} });
+	return clients;
+}
+async function disposeCloudAuth(clients) {
+	const auth = cloudAuthState.get(clients);
+	if (!auth) return;
+	await auth.dispose();
+	cloudAuthState.delete(clients);
+}
+const buildClientProxy = (state, refresh) => {
+	const forwarder = (pick) => new Proxy({}, { get: (_, prop) => async (...args) => {
+		await refresh();
+		const fn = pick(state.current)[prop];
+		return Reflect.apply(fn, pick(state.current), args);
+	} });
+	return {
+		events: {
+			fetchMissed: async (opts) => {
+				await refresh();
+				return state.current.events.fetchMissed(opts);
+			},
+			subscribe: (options) => resubscribableStream(state, options)
+		},
+		media: forwarder((c) => c.media),
+		messages: forwarder((c) => c.messages),
+		close: async () => {
+			for (const sub of state.subscriptions) sub.close();
+			await state.current.close();
+		},
+		[Symbol.asyncDispose]: async () => {
+			for (const sub of state.subscriptions) sub.close();
+			await state.current.close();
+		}
+	};
+};
+const pumpOnce = async (ctx) => {
+	const sub = ctx.getCurrent().events.subscribe(ctx.options);
+	ctx.setActive(sub);
+	try {
+		for await (const event of sub) await ctx.emit(event);
+		return true;
+	} catch (error) {
+		streamLog.warn("whatsapp event stream interrupted; resubscribing", {
+			"spectrum.whatsapp.resubscribe_in_ms": RESUBSCRIBE_BACKOFF_MS,
+			...errorAttrs(error)
+		}, error);
+		return false;
+	} finally {
+		ctx.setActive(void 0);
+	}
+};
+const resubscribableStream = (state, options) => {
+	let closed = false;
+	let active;
+	const source = stream((emit, end) => {
+		const ctx = {
+			emit,
+			getCurrent: () => state.current,
+			options,
+			setActive: (s) => {
+				active = s;
+			}
+		};
+		const pump = (async () => {
+			while (!closed) {
+				await pumpOnce(ctx);
+				if (!closed) await new Promise((r) => setTimeout(r, RESUBSCRIBE_BACKOFF_MS));
+			}
+			end();
+		})();
+		return async () => {
+			closed = true;
+			active?.close().catch(() => void 0);
+			active = void 0;
+			state.subscriptions.delete(subscription);
+			await pump;
+		};
+	});
+	const subscription = {
+		close: () => {
+			closed = true;
+			active?.close().catch(() => void 0);
+		},
+		swap: () => {
+			active?.close().catch(() => void 0);
+		}
+	};
+	state.subscriptions.add(subscription);
+	return new TypedEventStream(source, async () => {
+		closed = true;
+		active?.close().catch(() => void 0);
+		state.subscriptions.delete(subscription);
+		await source.close();
+	});
+};
+//#endregion
+//#region src/poll.ts
+const MAX_BUTTON_OPTIONS = 3;
+const LIST_BUTTON_TEXT = "View options";
+const LIST_SECTION_TITLE = "Options";
+const pollOptionId = (index) => `opt_${index}`;
+const pollToInteractive = (content) => {
+	if (content.options.length <= MAX_BUTTON_OPTIONS) return buttons(content.title, ...content.options.map((o, i) => button(pollOptionId(i), o.title)));
+	return list(content.title, LIST_BUTTON_TEXT).section(LIST_SECTION_TITLE, content.options.map((o, i) => ({
+		id: pollOptionId(i),
+		title: o.title
+	})));
+};
+//#endregion
+//#region src/messages.ts
+const primary = (clients) => {
+	const client = clients[0];
+	if (!client) throw new Error("No WhatsApp Business client available");
+	return client;
+};
+const toRecord = (result, spaceId, content) => ({
+	id: result.messageId,
+	content,
+	space: { id: spaceId },
+	timestamp: /* @__PURE__ */ new Date()
+});
+const MAX_POLL_CACHE_SIZE = 1e3;
+const OPTION_ID_PREFIX = "opt_";
+const pollCaches = /* @__PURE__ */ new WeakMap();
+const getPollCache = (client) => {
+	let cache = pollCaches.get(client);
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		pollCaches.set(client, cache);
+	}
+	return cache;
+};
+const cachePoll = (client, messageId, poll) => {
+	const cache = getPollCache(client);
+	if (cache.has(messageId)) cache.delete(messageId);
+	cache.set(messageId, poll);
+	if (cache.size > MAX_POLL_CACHE_SIZE) {
+		const first = cache.keys().next().value;
+		if (first !== void 0) cache.delete(first);
+	}
+};
+const optionIndexFromId = (id) => {
+	if (!id.startsWith(OPTION_ID_PREFIX)) return;
+	const index = Number(id.slice(4));
+	if (!Number.isInteger(index) || index < 0 || pollOptionId(index) !== id) return;
+	return index;
+};
+const mapWaPhoneType = (type) => {
+	if (!type) return;
+	const upper = type.toUpperCase();
+	if (upper === "CELL" || upper === "MOBILE" || upper === "IPHONE") return "mobile";
+	if (upper === "HOME") return "home";
+	if (upper === "WORK" || upper === "BUSINESS") return "work";
+	return "other";
+};
+const mapWaSimpleType = (type) => {
+	if (!type) return;
+	const upper = type.toUpperCase();
+	if (upper === "HOME") return "home";
+	if (upper === "WORK" || upper === "BUSINESS") return "work";
+	return "other";
+};
+const waNameToSpectrum = (name) => {
+	const result = { formatted: name.formattedName };
+	if (name.firstName) result.first = name.firstName;
+	if (name.lastName) result.last = name.lastName;
+	if (name.middleName) result.middle = name.middleName;
+	if (name.prefix) result.prefix = name.prefix;
+	if (name.suffix) result.suffix = name.suffix;
+	return result;
+};
+const waPhoneToSpectrum = (phone) => {
+	const entry = { value: phone.phone };
+	const type = mapWaPhoneType(phone.type);
+	if (type) entry.type = type;
+	return entry;
+};
+const waEmailToSpectrum = (email) => {
+	const entry = { value: email.email };
+	const type = mapWaSimpleType(email.type);
+	if (type) entry.type = type;
+	return entry;
+};
+const waAddressToSpectrum = (address) => {
+	const entry = {};
+	if (address.street) entry.street = address.street;
+	if (address.city) entry.city = address.city;
+	if (address.state) entry.region = address.state;
+	if (address.zip) entry.postalCode = address.zip;
+	if (address.country) entry.country = address.country;
+	const type = mapWaSimpleType(address.type);
+	if (type) entry.type = type;
+	return entry;
+};
+const waOrgToSpectrum = (org) => {
+	const entry = {};
+	if (org.company) entry.name = org.company;
+	if (org.title) entry.title = org.title;
+	if (org.department) entry.department = org.department;
+	return entry;
+};
+const waContactToSpectrum = (card) => {
+	const input = { raw: card };
+	input.name = waNameToSpectrum(card.name);
+	if (card.phones.length > 0) input.phones = card.phones.map(waPhoneToSpectrum);
+	if (card.emails.length > 0) input.emails = card.emails.map(waEmailToSpectrum);
+	if (card.addresses.length > 0) input.addresses = card.addresses.map(waAddressToSpectrum);
+	if (card.org) input.org = waOrgToSpectrum(card.org);
+	if (card.urls.length > 0) input.urls = card.urls.map((u) => u.url);
+	if (card.birthday) input.birthday = card.birthday;
+	return asContact(input);
+};
+const toMessages = (client, msg) => {
+	const base = {
+		sender: { id: msg.from },
+		space: { id: msg.from },
+		timestamp: msg.timestamp
+	};
+	if (msg.content.type === "contacts") {
+		const multi = msg.content.contacts.length > 1;
+		return msg.content.contacts.map((card, index) => ({
+			...base,
+			id: multi ? `${msg.id}:${index}` : msg.id,
+			content: waContactToSpectrum(card)
+		}));
+	}
+	return [{
+		...base,
+		id: msg.id,
+		content: mapContent(client, msg)
+	}];
+};
+const mapContent = (client, msg) => {
+	const { content } = msg;
+	switch (content.type) {
+		case "text": return asText(content.body);
+		case "image":
+		case "video":
+		case "audio":
+		case "document": return lazyMedia(client, content.media);
+		case "sticker": return asCustom({
+			whatsapp_type: "sticker",
+			...content.sticker
+		});
+		case "location": return asCustom({
+			whatsapp_type: "location",
+			...content.location
+		});
+		case "reaction": {
+			const stubTarget = {
+				id: content.reaction.messageId,
+				content: asCustom({
+					whatsapp_type: "reaction-target",
+					stub: true
+				})
+			};
+			return asReaction({
+				emoji: content.reaction.emoji,
+				target: stubTarget
+			});
+		}
+		case "interactive": {
+			const inter = content.interactive;
+			if (inter.type === "button_reply" || inter.type === "list_reply") {
+				const poll = msg.context?.id === void 0 ? void 0 : getPollCache(client).get(msg.context.id);
+				const optionIndex = optionIndexFromId(inter.reply.id);
+				const option = optionIndex === void 0 ? void 0 : poll?.options[optionIndex];
+				if (poll && option) return asPollOption({
+					poll,
+					option,
+					selected: true
+				});
+			}
+			return asCustom({
+				whatsapp_type: "interactive",
+				...inter
+			});
+		}
+		case "button": return asCustom({
+			whatsapp_type: "button",
+			...content.button
+		});
+		case "order": return asCustom({
+			whatsapp_type: "order",
+			...content.order
+		});
+		case "system": return asCustom({
+			whatsapp_type: "system",
+			...content.system
+		});
+		default: return asCustom({ whatsapp_type: "unknown" });
+	}
+};
+const fetchMedia = async (client, mediaId) => {
+	const { url } = await client.media.getUrl(mediaId);
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Media download failed: ${response.status}`);
+	return response;
+};
+const lazyMedia = (client, media) => asAttachment({
+	id: media.id,
+	name: media.filename ?? `media-${media.id}`,
+	mimeType: media.mimeType,
+	read: async () => Buffer.from(await (await fetchMedia(client, media.id)).arrayBuffer()),
+	stream: async () => {
+		const response = await fetchMedia(client, media.id);
+		if (!response.body) throw new Error("Media response missing body");
+		return response.body;
+	}
+});
+const mimeToMediaType = (mimeType) => {
+	if (mimeType.startsWith("image/")) return "image";
+	if (mimeType.startsWith("video/")) return "video";
+	if (mimeType.startsWith("audio/")) return "audio";
+	return "document";
+};
+const voiceFilename = (content) => {
+	if (content.name) return content.name;
+	const ext = extension(content.mimeType);
+	return ext ? `voice.${ext}` : "voice";
+};
+const spectrumPhoneTypeToWa = (type) => {
+	if (type === "mobile") return "CELL";
+	if (type === "home" || type === "work" || type === "other") return type.toUpperCase();
+};
+const spectrumSimpleTypeToWa = (type) => type ? type.toUpperCase() : void 0;
+const spectrumNameToWa = (name) => ({
+	formattedName: name?.formatted ?? ([
+		name?.first,
+		name?.middle,
+		name?.last
+	].filter((p) => Boolean(p)).join(" ") || "Unknown"),
+	firstName: name?.first,
+	lastName: name?.last,
+	middleName: name?.middle,
+	prefix: name?.prefix,
+	suffix: name?.suffix
+});
+const isWhatsAppContactCard = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const raw = value;
+	const name = raw.name;
+	if (!name || typeof name !== "object" || typeof name.formattedName !== "string") return false;
+	return Array.isArray(raw.phones) && Array.isArray(raw.emails) && Array.isArray(raw.addresses) && Array.isArray(raw.urls);
+};
+const contactToWa = (contact) => {
+	if (isWhatsAppContactCard(contact.raw)) return contact.raw;
+	return {
+		name: spectrumNameToWa(contact.name),
+		phones: (contact.phones ?? []).map((p) => ({
+			phone: p.value,
+			type: spectrumPhoneTypeToWa(p.type)
+		})),
+		emails: (contact.emails ?? []).map((e) => ({
+			email: e.value,
+			type: spectrumSimpleTypeToWa(e.type)
+		})),
+		addresses: (contact.addresses ?? []).map((a) => ({
+			street: a.street,
+			city: a.city,
+			state: a.region,
+			zip: a.postalCode,
+			country: a.country,
+			type: spectrumSimpleTypeToWa(a.type)
+		})),
+		urls: (contact.urls ?? []).map((url) => ({ url })),
+		org: contact.org?.name || contact.org?.department || contact.org?.title ? {
+			company: contact.org.name,
+			department: contact.org.department,
+			title: contact.org.title
+		} : void 0,
+		birthday: contact.birthday
+	};
+};
+const clientStream = (client) => {
+	const eventStream = client.events.subscribe().filter((e) => e.type === "message");
+	return stream((emit, end) => {
+		const pump = (async () => {
+			try {
+				for await (const event of eventStream) for (const m of toMessages(client, event.message)) await emit(m);
+				end();
+			} catch (e) {
+				end(e);
+			}
+		})();
+		return async () => {
+			await eventStream.close();
+			await pump;
+		};
+	});
+};
+const messages = (clients) => mergeStreams(clients.map(clientStream));
+const send = async (clients, spaceId, content) => {
+	if (content.type === "reply") return await replyToMessage(clients, spaceId, content.target.id, content.content);
+	if (content.type === "reaction") return await reactToMessage(clients, spaceId, content);
+	if (content.type === "typing") return;
+	if (content.type === "read") {
+		await primary(clients).messages.markRead(content.target.id);
+		return;
+	}
+	const client = primary(clients);
+	switch (content.type) {
+		case "text": return toRecord(await client.messages.send({
+			to: spaceId,
+			text: content.text
+		}), spaceId, content);
+		case "attachment": {
+			const { mediaId } = await client.media.upload({
+				file: await content.read(),
+				mimeType: content.mimeType,
+				filename: content.name
+			});
+			const mediaType = mimeToMediaType(content.mimeType);
+			const mediaPayload = mediaType === "document" ? {
+				id: mediaId,
+				filename: content.name
+			} : { id: mediaId };
+			return toRecord(await client.messages.send({
+				to: spaceId,
+				[mediaType]: mediaPayload
+			}), spaceId, content);
+		}
+		case "contact": return toRecord(await client.messages.send({
+			to: spaceId,
+			contacts: [contactToWa(content)]
+		}), spaceId, content);
+		case "voice": {
+			const { mediaId } = await client.media.upload({
+				file: await content.read(),
+				mimeType: content.mimeType,
+				filename: voiceFilename(content)
+			});
+			return toRecord(await client.messages.send({
+				to: spaceId,
+				audio: { id: mediaId }
+			}), spaceId, content);
+		}
+		case "poll": {
+			const result = await client.messages.send({
+				to: spaceId,
+				interactive: pollToInteractive(content)
+			});
+			cachePoll(client, result.messageId, content);
+			return toRecord(result, spaceId, content);
+		}
+		case "app": return toRecord(await client.messages.send({
+			to: spaceId,
+			text: await content.url()
+		}), spaceId, content);
+		default: throw UnsupportedError.content(content.type);
+	}
+};
+const reactToMessage = async (clients, spaceId, content) => {
+	return toRecord(await primary(clients).messages.send({
+		to: spaceId,
+		reaction: {
+			messageId: content.target.id,
+			emoji: content.emoji
+		}
+	}), spaceId, content);
+};
+const replyToMessage = async (clients, spaceId, messageId, content) => {
+	const client = primary(clients);
+	switch (content.type) {
+		case "text": return toRecord(await client.messages.send({
+			to: spaceId,
+			replyTo: messageId,
+			text: content.text
+		}), spaceId, content);
+		case "attachment": {
+			const { mediaId } = await client.media.upload({
+				file: await content.read(),
+				mimeType: content.mimeType,
+				filename: content.name
+			});
+			const mediaType = mimeToMediaType(content.mimeType);
+			const mediaPayload = mediaType === "document" ? {
+				id: mediaId,
+				filename: content.name
+			} : { id: mediaId };
+			return toRecord(await client.messages.send({
+				to: spaceId,
+				replyTo: messageId,
+				[mediaType]: mediaPayload
+			}), spaceId, content);
+		}
+		case "contact": return toRecord(await client.messages.send({
+			to: spaceId,
+			replyTo: messageId,
+			contacts: [contactToWa(content)]
+		}), spaceId, content);
+		case "voice": {
+			const { mediaId } = await client.media.upload({
+				file: await content.read(),
+				mimeType: content.mimeType,
+				filename: voiceFilename(content)
+			});
+			return toRecord(await client.messages.send({
+				to: spaceId,
+				replyTo: messageId,
+				audio: { id: mediaId }
+			}), spaceId, content);
+		}
+		case "poll": {
+			const result = await client.messages.send({
+				to: spaceId,
+				replyTo: messageId,
+				interactive: pollToInteractive(content)
+			});
+			cachePoll(client, result.messageId, content);
+			return toRecord(result, spaceId, content);
+		}
+		case "app": return toRecord(await client.messages.send({
+			to: spaceId,
+			replyTo: messageId,
+			text: await content.url()
+		}), spaceId, content);
+		default: throw UnsupportedError.content(content.type);
+	}
+};
+//#endregion
+//#region src/types.ts
+const directConfig = z.object({
+	accessToken: z.string().min(1),
+	appSecret: z.string().optional(),
+	phoneNumberId: z.string().min(1)
+});
+const cloudConfig = z.object({}).strict();
+const configSchema = z.union([directConfig, cloudConfig]);
+const isCloudConfig = (config) => !("accessToken" in config);
+z.object({});
+//#endregion
+//#region src/index.ts
+const whatsappBusiness = definePlatform("WhatsApp Business", {
+	config: configSchema,
+	lifecycle: {
+		createClient: async ({ config, projectId, projectSecret }) => {
+			if (!isCloudConfig(config)) return [createClient({
+				accessToken: config.accessToken,
+				appSecret: config.appSecret ?? "",
+				phoneNumberId: config.phoneNumberId
+			})];
+			if (!(projectId && projectSecret)) throw new Error("WhatsApp Business cloud mode requires projectId and projectSecret. Either pass credentials to Spectrum(), or provide direct credentials: whatsappBusiness.config({ accessToken, phoneNumberId })");
+			return await createCloudClients(projectId, projectSecret);
+		},
+		destroyClient: async ({ client }) => {
+			await disposeCloudAuth(client);
+			await Promise.allSettled(client.map((c) => c.close()));
+		}
+	},
+	user: { resolve: async ({ input }) => ({ id: input.userID }) },
+	space: {
+		schema: z.object({ id: z.string() }),
+		create: async ({ input }) => {
+			if (input.users.length === 0) throw new Error("WhatsApp space creation requires at least one user");
+			if (input.users.length > 1) throw UnsupportedError.action("space.create", "WhatsApp Business", "only 1:1 conversations are supported");
+			const user = input.users[0];
+			if (!user) throw new Error("WhatsApp space creation requires a user");
+			return { id: user.id };
+		}
+	},
+	messages: ({ client }) => messages(client),
+	send: async ({ space, content, client }) => await send(client, space.id, content)
+});
+//#endregion
+export { whatsappBusiness };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@spectrum-ts/whatsapp-business",
+  "version": "5.0.0",
+  "description": "WhatsApp Business provider for spectrum-ts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photon-hq/spectrum-ts.git",
+    "directory": "packages/whatsapp-business"
+  },
+  "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": "whatsapp-business",
+    "import": "whatsappBusiness",
+    "label": "WhatsApp Business"
+  },
+  "dependencies": {
+    "@photon-ai/whatsapp-business": "^0.1.1",
+    "mime-types": "^3.0.1",
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@spectrum-ts/core": "^5.0.0",
+    "typescript": "^5 || ^6.0.0"
+  },
+  "license": "MIT"
+}