@spectrum-ts/whatsapp-business 11.2.0 → 12.0.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,6 +11,47 @@ 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<{
   accessToken: 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,6 +1,6 @@
 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, errorAttrs, tracedFetch } from "@spectrum-ts/core/authoring";
 import { extension } from "mime-types";
 import z from "zod";
 //#region src/auth.ts
@@ -251,6 +251,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 +366,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 +476,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 +521,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 +583,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 +594,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 +693,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 +834,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 +863,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 +917,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);
 	}
 };
@@ -811,4 +982,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.0.0",
   "description": "WhatsApp Business provider for spectrum-ts.",
   "repository": {
     "type": "git",
@@ -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"