@spectrum-ts/whatsapp-business 11.2.0 → 12.1.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { WhatsAppClient } from "@photon-ai/whatsapp-business";
-import { SchemaMessage } from "@spectrum-ts/core";
+import { ContentBuilder, SchemaMessage } from "@spectrum-ts/core";
+import { ProviderMessageRecord } from "@spectrum-ts/core/authoring";
 import z from "zod";
 
 //#region src/types.d.ts
@@ -10,8 +11,49 @@ declare const spaceSchema: z.ZodObject<{
 }, z.core.$strip>;
 type WhatsAppMessage = SchemaMessage<typeof userSchema, typeof spaceSchema>;
 //#endregion
+//#region src/content/template.d.ts
+/**
+ * WhatsApp-only template message content. Lives entirely under the WhatsApp
+ * Business provider — never enters the universal `Content` discriminated
+ * union. The framework recognizes it via the generic content-level platform
+ * contract: `__platform: "whatsapp_business"` lets
+ * `findUnsupportedPlatformContent` warn-and-skip when a different platform
+ * receives it.
+ *
+ * Templates are the only message type Meta accepts outside the 24-hour
+ * customer-service window (free-form sends fail with error 131047), so this
+ * is the escape hatch for re-engaging stale conversations. v1 covers the
+ * common case: a pre-approved template addressed by name + language, with
+ * positional `{{1}}..{{n}}` body text parameters. Header/button components
+ * can be added later without breaking this shape.
+ */
+declare const whatsappTemplateSchema: z.ZodObject<{
+  type: z.ZodLiteral<"whatsapp-template">;
+  __platform: z.ZodLiteral<"whatsapp_business">;
+  name: z.ZodString;
+  languageCode: z.ZodString;
+  bodyParams: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type WhatsAppTemplate = z.infer<typeof whatsappTemplateSchema>;
+type WhatsAppTemplateInput = Omit<WhatsAppTemplate, "type" | "__platform">;
+declare const isWhatsAppTemplate: (value: unknown) => value is WhatsAppTemplate;
+declare const asWhatsAppTemplate: (input: WhatsAppTemplateInput) => WhatsAppTemplate;
+declare function whatsappTemplate(input: WhatsAppTemplateInput): ContentBuilder;
+//#endregion
+//#region src/errors/partial-send.d.ts
+declare class WhatsAppPartialSendError extends Error {
+  readonly sent: ProviderMessageRecord[];
+  readonly failedIndex: number;
+  constructor(input: {
+    sent: ProviderMessageRecord[];
+    failedIndex: number;
+    total: number;
+    cause: unknown;
+  });
+}
+//#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<{
+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;
@@ -23,4 +65,4 @@ declare const whatsappBusiness: import("@spectrum-ts/core").Platform<import("@sp
   id: string;
 }, undefined, WhatsAppMessage, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
 //#endregion
-export { whatsappBusiness };
+export { WhatsAppPartialSendError, type WhatsAppTemplate, type WhatsAppTemplateInput, asWhatsAppTemplate, isWhatsAppTemplate, whatsappBusiness, whatsappTemplate, whatsappTemplateSchema };

package/dist/index.js

@@ -1,24 +1,15 @@
 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, asGroup, asPollOption, asReaction, asText, asUnsend, createLogger, errorAttrs, tracedFetch } from "@spectrum-ts/core/authoring";
+import { asAttachment, asContact, asCustom, asGroup, asPollOption, asReaction, asReply, asText, asUnsend, asVoice, createLogger, createTokenRenewal, errorAttrs, tracedFetch } 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$1 = createLogger("spectrum.whatsapp.stream");
-const RENEWAL_RATIO = .8;
-const EXPIRY_BUFFER_MS = 3e4;
-const RETRY_DELAY_MS = 3e4;
 const RESUBSCRIBE_BACKOFF_MS = 500;
 const ignoreCleanupError = () => void 0;
 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;
-	let refreshInFlight;
 	const lines = /* @__PURE__ */ new Map();
 	const buildRawClient = (phoneNumberId) => {
 		const accessToken = tokenData.auth[phoneNumberId];
@@ -31,7 +22,6 @@ async function createCloudClients(projectId, projectSecret) {
 	};
 	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;
@@ -40,69 +30,21 @@ async function createCloudClients(projectId, projectSecret) {
 			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 refreshNow = async () => {
-		await refreshTokens();
-		onRefreshSuccess();
-		scheduleRenewal();
-	};
-	const coalescedRefresh = () => {
-		if (!refreshInFlight) refreshInFlight = refreshNow().finally(() => {
-			refreshInFlight = void 0;
-		});
-		return refreshInFlight;
-	};
-	const scheduleRenewal = () => {
-		if (disposed) return;
-		clearRenewalTimer();
-		const ttlMs = tokenData.expiresIn * 1e3;
-		const renewInMs = Math.max(ttlMs * RENEWAL_RATIO, 5e3);
-		const runScheduledRefresh = () => {
-			coalescedRefresh().catch((err) => {
-				onRefreshFailure(err);
-				if (disposed) return;
-				renewalTimer = setTimeout(runScheduledRefresh, RETRY_DELAY_MS);
-				renewalTimer?.unref?.();
-			});
-		};
-		renewalTimer = setTimeout(runScheduledRefresh, renewInMs);
-		renewalTimer?.unref?.();
-	};
-	const refreshIfNeeded = async () => {
-		if (Date.now() < tokenExpiresAt - EXPIRY_BUFFER_MS) return;
-		await coalescedRefresh();
-	};
-	scheduleRenewal();
+	const renewal = createTokenRenewal({
+		expiresInSeconds: () => tokenData.expiresIn,
+		name: "whatsapp",
+		refresh: refreshTokens
+	});
 	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);
+		return buildClientProxy(state, renewal.refreshIfNeeded);
 	});
 	cloudAuthState.set(clients, { dispose: async () => {
-		disposed = true;
-		clearRenewalTimer();
+		renewal.dispose();
 		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();
@@ -251,6 +193,51 @@ const resubscribableStream = (state, options) => {
 	});
 };
 //#endregion
+//#region src/content/template.ts
+/**
+* WhatsApp-only template message content. Lives entirely under the WhatsApp
+* Business provider — never enters the universal `Content` discriminated
+* union. The framework recognizes it via the generic content-level platform
+* contract: `__platform: "whatsapp_business"` lets
+* `findUnsupportedPlatformContent` warn-and-skip when a different platform
+* receives it.
+*
+* Templates are the only message type Meta accepts outside the 24-hour
+* customer-service window (free-form sends fail with error 131047), so this
+* is the escape hatch for re-engaging stale conversations. v1 covers the
+* common case: a pre-approved template addressed by name + language, with
+* positional `{{1}}..{{n}}` body text parameters. Header/button components
+* can be added later without breaking this shape.
+*/
+const whatsappTemplateSchema = z.object({
+	type: z.literal("whatsapp-template"),
+	__platform: z.literal("whatsapp_business"),
+	name: z.string().min(1),
+	languageCode: z.string().min(1),
+	bodyParams: z.array(z.string()).optional()
+});
+const isWhatsAppTemplate = (value) => whatsappTemplateSchema.safeParse(value).success;
+const asWhatsAppTemplate = (input) => whatsappTemplateSchema.parse({
+	type: "whatsapp-template",
+	__platform: "whatsapp_business",
+	...input
+});
+function whatsappTemplate(input) {
+	return { build: async () => asWhatsAppTemplate(input) };
+}
+//#endregion
+//#region src/errors/partial-send.ts
+var WhatsAppPartialSendError = class extends Error {
+	sent;
+	failedIndex;
+	constructor(input) {
+		super(`WhatsApp group send failed at part ${input.failedIndex + 1}/${input.total}; ${input.sent.length} earlier part(s) were already delivered and cannot be retracted`, { cause: input.cause });
+		this.name = "WhatsAppPartialSendError";
+		this.sent = input.sent;
+		this.failedIndex = input.failedIndex;
+	}
+};
+//#endregion
 //#region src/poll.ts
 const MAX_BUTTON_OPTIONS = 3;
 const LIST_BUTTON_TEXT = "View options";
@@ -321,6 +308,26 @@ const reactionTargetStub = (reactedId) => ({
 		stub: true
 	})
 });
+const replyTargetStub = (quotedId) => ({
+	id: quotedId,
+	content: asCustom({
+		whatsapp_type: "reply-target",
+		stub: true
+	})
+});
+const REPLY_EXEMPT_TYPES = new Set([
+	"interactive",
+	"button",
+	"reaction"
+]);
+const withReplyContext = (msg, content) => {
+	const quotedId = msg.context?.id;
+	if (quotedId === void 0 || REPLY_EXEMPT_TYPES.has(msg.content.type)) return content;
+	return asReply({
+		content,
+		target: replyTargetStub(quotedId)
+	});
+};
 const optionIndexFromId = (id) => {
 	if (!id.startsWith(OPTION_ID_PREFIX)) return;
 	const index = Number(id.slice(4));
@@ -411,13 +418,13 @@ const toMessages = (client, msg) => {
 		return msg.content.contacts.map((card, index) => ({
 			...base,
 			id: multi ? `${msg.id}:${index}` : msg.id,
-			content: waContactToSpectrum(card)
+			content: withReplyContext(msg, waContactToSpectrum(card))
 		}));
 	}
 	return [{
 		...base,
 		id: msg.id,
-		content: mapContent(client, msg)
+		content: withReplyContext(msg, mapContent(client, msg))
 	}];
 };
 const mapReactionContent = (client, msg, reaction) => {
@@ -456,7 +463,7 @@ const mapContent = (client, msg) => {
 		case "video":
 		case "audio":
 		case "document": {
-			const media = lazyMedia(client, content.media);
+			const media = content.type === "audio" && content.media.voice ? lazyVoice(client, content.media) : lazyMedia(client, content.media);
 			const caption = content.media.caption?.trim();
 			if (!caption) return media;
 			return asGroup({ items: [groupItem(msg, 0, media), groupItem(msg, 1, asText(caption))] });
@@ -518,7 +525,7 @@ const fetchMedia = async (client, mediaId) => {
 	if (!response.ok) throw new Error(`Media download failed: ${response.status}`);
 	return response;
 };
-const lazyMedia = (client, media) => asAttachment({
+const lazyMediaSource = (client, media) => ({
 	id: media.id,
 	name: media.filename ?? `media-${media.id}`,
 	mimeType: media.mimeType,
@@ -529,6 +536,8 @@ const lazyMedia = (client, media) => asAttachment({
 		return response.body;
 	}
 });
+const lazyMedia = (client, media) => asAttachment(lazyMediaSource(client, media));
+const lazyVoice = (client, media) => asVoice(lazyMediaSource(client, media));
 const mimeToMediaType = (mimeType) => {
 	if (mimeType.startsWith("image/")) return "image";
 	if (mimeType.startsWith("video/")) return "video";
@@ -626,7 +635,83 @@ const clientStream = (client) => {
 	});
 };
 const messages = (clients) => mergeStreams(clients.map(clientStream));
+const MAX_CAPTION_LENGTH = 1024;
+const captionablePair = (group) => {
+	if (group.items.length !== 2) return;
+	const contents = group.items.map((item) => item.content);
+	const attachment = contents.find((c) => c.type === "attachment");
+	const text = contents.find((c) => c.type === "text");
+	return attachment && text && mimeToMediaType(attachment.mimeType) !== "audio" && text.text.length <= MAX_CAPTION_LENGTH ? {
+		attachment,
+		caption: text.text
+	} : void 0;
+};
+const sendGroupParts = async (clients, spaceId, group, replyTo) => {
+	const pair = captionablePair(group);
+	if (pair) {
+		const client = primary(clients);
+		const { attachment, caption } = pair;
+		const { mediaId } = await client.media.upload({
+			file: await attachment.read(),
+			mimeType: attachment.mimeType,
+			filename: attachment.name
+		});
+		const mediaType = mimeToMediaType(attachment.mimeType);
+		const mediaPayload = mediaType === "document" ? {
+			id: mediaId,
+			filename: attachment.name,
+			caption
+		} : {
+			id: mediaId,
+			caption
+		};
+		return toRecord(await client.messages.send({
+			to: spaceId,
+			...replyTo === void 0 ? {} : { replyTo },
+			[mediaType]: mediaPayload
+		}), spaceId, group);
+	}
+	const sent = [];
+	let first;
+	for (const [index, item] of group.items.entries()) {
+		const itemContent = item.content;
+		let record;
+		try {
+			record = index === 0 && replyTo !== void 0 ? await replyToMessage(clients, spaceId, replyTo, itemContent) : await send(clients, spaceId, itemContent);
+		} catch (error) {
+			if (sent.length === 0) throw error;
+			throw new WhatsAppPartialSendError({
+				sent,
+				failedIndex: index,
+				total: group.items.length,
+				cause: error
+			});
+		}
+		if (record) sent.push(record);
+		first ??= record;
+	}
+	if (!first) throw UnsupportedError.content(group.type);
+	return {
+		...first,
+		content: group
+	};
+};
+const toTemplateInput = (content) => ({
+	name: content.name,
+	languageCode: content.languageCode,
+	components: content.bodyParams?.length ? [{
+		type: "body",
+		parameters: content.bodyParams.map((text) => ({
+			type: "text",
+			text
+		}))
+	}] : []
+});
 const send = async (clients, spaceId, content) => {
+	if (isWhatsAppTemplate(content)) return toRecord(await primary(clients).messages.send({
+		to: spaceId,
+		template: toTemplateInput(content)
+	}), spaceId, content);
 	if (content.type === "reply") return await replyToMessage(clients, spaceId, parentWamid(content.target.id), content.content);
 	if (content.type === "reaction") return await reactToMessage(clients, spaceId, content);
 	if (content.type === "typing") return;
@@ -691,10 +776,21 @@ const send = async (clients, spaceId, content) => {
 			cachePoll(client, result.messageId, content);
 			return toRecord(result, spaceId, content);
 		}
+		case "richlink": return toRecord(await client.messages.send({
+			to: spaceId,
+			text: {
+				body: content.url,
+				previewUrl: true
+			}
+		}), spaceId, content);
 		case "app": return toRecord(await client.messages.send({
 			to: spaceId,
-			text: await content.url()
+			text: {
+				body: await content.url(),
+				previewUrl: true
+			}
 		}), spaceId, content);
+		case "group": return await sendGroupParts(clients, spaceId, content);
 		default: throw UnsupportedError.content(content.type);
 	}
 };
@@ -709,6 +805,11 @@ const reactToMessage = async (clients, spaceId, content) => {
 };
 const replyToMessage = async (clients, spaceId, messageId, content) => {
 	const client = primary(clients);
+	if (isWhatsAppTemplate(content)) return toRecord(await client.messages.send({
+		to: spaceId,
+		replyTo: messageId,
+		template: toTemplateInput(content)
+	}), spaceId, content);
 	switch (content.type) {
 		case "text": return toRecord(await client.messages.send({
 			to: spaceId,
@@ -758,11 +859,23 @@ const replyToMessage = async (clients, spaceId, messageId, content) => {
 			cachePoll(client, result.messageId, content);
 			return toRecord(result, spaceId, content);
 		}
+		case "richlink": return toRecord(await client.messages.send({
+			to: spaceId,
+			replyTo: messageId,
+			text: {
+				body: content.url,
+				previewUrl: true
+			}
+		}), spaceId, content);
 		case "app": return toRecord(await client.messages.send({
 			to: spaceId,
 			replyTo: messageId,
-			text: await content.url()
+			text: {
+				body: await content.url(),
+				previewUrl: true
+			}
 		}), spaceId, content);
+		case "group": return await sendGroupParts(clients, spaceId, content, messageId);
 		default: throw UnsupportedError.content(content.type);
 	}
 };
@@ -777,9 +890,11 @@ const cloudConfig = z.object({}).strict();
 const configSchema = z.union([directConfig, cloudConfig]);
 const isCloudConfig = (config) => !("accessToken" in config);
 z.object({});
+const spaceSchema = z.object({ id: z.string() });
 //#endregion
 //#region src/index.ts
-const whatsappBusiness = definePlatform("WhatsApp Business", {
+const PLATFORM_ID = "whatsapp_business";
+const whatsappBusiness = definePlatform(PLATFORM_ID, {
 	config: configSchema,
 	lifecycle: {
 		createClient: async ({ config, projectId, projectSecret }) => {
@@ -798,10 +913,10 @@ const whatsappBusiness = definePlatform("WhatsApp Business", {
 	},
 	user: { resolve: async ({ input }) => ({ id: input.userID }) },
 	space: {
-		schema: z.object({ id: z.string() }),
+		schema: spaceSchema,
 		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");
+			if (input.users.length > 1) throw UnsupportedError.action("space.create", PLATFORM_ID, "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 };
@@ -811,4 +926,4 @@ const whatsappBusiness = definePlatform("WhatsApp Business", {
 	send: async ({ space, content, client }) => await send(client, space.id, content)
 });
 //#endregion
-export { whatsappBusiness };
+export { WhatsAppPartialSendError, asWhatsAppTemplate, isWhatsAppTemplate, whatsappBusiness, whatsappTemplate, whatsappTemplateSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-ts/whatsapp-business",
-  "version": "11.2.0",
+  "version": "12.1.0",
   "description": "WhatsApp Business provider for spectrum-ts.",
   "repository": {
     "type": "git",
@@ -26,9 +26,9 @@
     "access": "public"
   },
   "spectrum": {
-    "key": "whatsapp-business",
+    "key": "whatsapp_business",
     "import": "whatsappBusiness",
-    "label": "WhatsApp Business"
+    "label": "whatsapp_business"
   },
   "dependencies": {
     "@photon-ai/whatsapp-business": "^0.2.0",
@@ -36,7 +36,7 @@
     "zod": "^4.2.1"
   },
   "peerDependencies": {
-    "@spectrum-ts/core": "^11.0.0",
+    "@spectrum-ts/core": "^12.0.0",
     "typescript": "^5 || ^6.0.0"
   },
   "license": "MIT"