@segmentstream/ontology 0.92.1 → 0.93.0

package/dist/service/chat/delivery.js

@@ -1,4 +1,4 @@
-import { telegramMarkdownLinks, telegramTextLinks, validateTelegramPreviews, } from "../../telegram.js";
+import { validateTelegramPreviews } from "../../telegram.js";
 import { randomUUID } from "node:crypto";
 import { Cause, Effect } from "effect";
 import { chatOperationId, chatPreviewDigest, } from "../../chat.js";
@@ -7,14 +7,34 @@ import { isAllowed } from "../../permissions.js";
 import { describeChatError } from "./diagnostics.js";
 import { deliveryRequester } from "./attribution.js";
 import { deliveryFingerprint, deliveryKeyDigest, deliveryScopeDigest } from "./idempotency.js";
-import { renderTelegram, sendTelegram, TELEGRAM_MESSAGE_LIMIT } from "./providers/telegram.js";
+import { chatConnection, chatProvider, listedChatProviders } from "./providers/index.js";
 import { chatResolver } from "./resolve.js";
+/** The channels a runtime source can name, which a verified pairing's provider is one of. */
+const CHANNEL_PROVIDERS = new Set(["telegram", "slack", "whatsapp"]);
+/**
+ * Whether a post would land in the conversation it was asked from. A private destination names the
+ * person, not the conversation: a Slack direct message is `D…` while the person is `U…`, so a
+ * private source matches a private destination on the same provider by its `peer`.
+ */
+export function sameChat(source, target) {
+    if (source.provider !== target.provider) {
+        return false;
+    }
+    if (source.chat_id === target.external_id) {
+        return true;
+    }
+    return (source.provider !== "telegram" &&
+        source.kind === "private" &&
+        target.kind === "private" &&
+        source.peer === target.external_id);
+}
 export function makeChatDelivery(ontology, connections, archive, previews = {}) {
     if (previews.settings) {
         validateTelegramPreviews(previews.settings);
     }
     const attribution = ontology.config.chat?.attribution;
     const separator = attribution?.separator ?? "\n\n";
+    const providers = listedChatProviders(ontology.manifest.chat);
     const destination = ontology.manifest.chat?.telegram?.connection;
     const destinationPreviews = previews.settings?.connection === destination ? previews : { ownOrigins: previews.ownOrigins };
     return (context) => {
@@ -37,25 +57,25 @@ export function makeChatDelivery(ontology, connections, archive, previews = {})
                     message: "The requester must still be paired and active.",
                 });
             }
-            const target = yield* chatResolver(context.backend, context.principal).resolve(input.chat);
-            const connection = ontology.manifest.chat?.telegram?.connection;
+            const target = yield* chatResolver(context.backend, context.principal, providers).resolve(input.chat);
+            // A chat is a destination only on a provider the ontology declares a connection for.
+            const provider = chatProvider(target.provider);
+            const connection = chatConnection(ontology.manifest.chat, target.provider);
             const replyTo = input.replyTo ?? null;
-            const plainText = `${input.text}${separator}${requester.attribution}`;
-            if (target.provider !== "telegram" || !connection) {
+            if (provider === undefined || !connection) {
                 return yield* new ActionRejected({
-                    message: "Chat posting requires a configured Telegram provider connection.",
+                    message: "Chat posting requires a configured connection for the chat's provider.",
                 });
             }
-            const finalText = yield* Effect.try({
-                try: () => renderTelegram(input.text, requester.attribution, separator),
+            const { finalText, plainText } = yield* Effect.try({
+                try: () => provider.render(input.text, requester.attribution, separator),
                 catch: (cause) => new ActionRejected({ message: "The Markdown could not be rendered.", cause }),
             });
             if (!input.text.trim() ||
-                finalText.length > TELEGRAM_MESSAGE_LIMIT ||
-                plainText.length > TELEGRAM_MESSAGE_LIMIT ||
-                !/^-?[1-9][0-9]*$/.test(target.external_id) ||
-                (replyTo !== null &&
-                    (!/^[1-9][0-9]*$/.test(replyTo) || !Number.isSafeInteger(Number(replyTo)))) ||
+                finalText.length > provider.limit ||
+                plainText.length > provider.limit ||
+                !provider.isTargetId(target.external_id, target.kind) ||
+                (replyTo !== null && !provider.isReplyId(replyTo)) ||
                 !input.idempotencyKey ||
                 input.idempotencyKey.length > 512) {
                 return yield* new ActionRejected({
@@ -81,14 +101,18 @@ export function makeChatDelivery(ontology, connections, archive, previews = {})
                     input.idempotencyKey !== envelope.operation_id ||
                     envelope.expected.chat_id !== target.id ||
                     envelope.expected.digest !== chatPreviewDigest(preview) ||
-                    (envelope.source.provider === target.provider &&
-                        envelope.source.chat_id === target.external_id)) {
+                    // The source is the channel the member's verified pairing acts through, when the
+                    // agent named that channel; without one the pairing is checked on any channel.
+                    (context.principal.authenticatedVia !== undefined &&
+                        CHANNEL_PROVIDERS.has(context.principal.authenticatedVia) &&
+                        envelope.source.provider !== context.principal.authenticatedVia) ||
+                    sameChat(envelope.source, target)) {
                     return yield* new ActionRejected({
                         message: "A frozen approved cross-chat preview matching this call is required.",
                     });
                 }
             }
-            return { target, requester, connection, preview };
+            return { target, requester, connection, provider, preview };
         });
         const report = (phase, cause) => Effect.logWarning("ontology.chat.delivery_diagnostic").pipe(Effect.annotateLogs({
             phase,
@@ -99,7 +123,7 @@ export function makeChatDelivery(ontology, connections, archive, previews = {})
             preview: (input) => check(input, false).pipe(Effect.map(({ preview }) => preview)),
             validate: (input) => check(input).pipe(Effect.asVoid),
             post: (input) => Effect.gen(function* () {
-                const { target, requester, connection, preview } = yield* check(input);
+                const { target, requester, connection, provider, preview } = yield* check(input);
                 const operationId = context.envelope?.operation_id ?? randomUUID();
                 const scope = deliveryScopeDigest({
                     via: requester.via,
@@ -131,7 +155,7 @@ export function makeChatDelivery(ontology, connections, archive, previews = {})
                     reason: null,
                     toolCallId: null,
                     toolName: null,
-                    argsSummary: JSON.stringify({ text: preview.finalText, parse_mode: "MarkdownV2" }),
+                    argsSummary: JSON.stringify(provider.payload(preview.finalText)),
                     status: "requested",
                     attachments: [],
                     requestedBy: requester,
@@ -180,15 +204,13 @@ export function makeChatDelivery(ontology, connections, archive, previews = {})
                         message: "The archive did not grant a fresh delivery claim.",
                     });
                 }
-                const outcome = yield* sendTelegram({
+                const outcome = yield* provider.send({
                     destination: target,
                     connection,
+                    text: preview.text,
+                    separator,
+                    attribution: preview.attribution,
                     finalText: preview.finalText,
-                    formattedLinks: [
-                        ...telegramMarkdownLinks(preview.text),
-                        ...telegramTextLinks(separator),
-                        ...telegramTextLinks(preview.attribution),
-                    ],
                     previews: destinationPreviews,
                     plainText: event.text,
                     replyTo: preview.replyTo,

package/dist/service/chat/envelope.d.ts

@@ -6,7 +6,7 @@ declare const RuntimeEnvelope: Schema.Struct<{
     readonly session_id: Schema.String;
     readonly call_id: Schema.String;
     readonly operation_id: Schema.optionalKey<Schema.String>;
-    readonly source: Schema.optionalKey<Schema.Struct<{
+    readonly source: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
         readonly provider: Schema.Literal<"telegram">;
         readonly chat_id: Schema.String;
         readonly thread_id: Schema.String;
@@ -21,7 +21,15 @@ declare const RuntimeEnvelope: Schema.Struct<{
             readonly media_type: Schema.optionalKey<Schema.String>;
             readonly staged_id: Schema.String;
         }>>>;
-    }>>;
+    }>, Schema.Struct<{
+        readonly provider: Schema.Literals<readonly ["slack", "whatsapp"]>;
+        readonly chat_id: Schema.String;
+        readonly thread_id: Schema.String;
+        readonly kind: Schema.Literals<readonly ["private", "group"]>;
+        readonly peer: Schema.optionalKey<Schema.String>;
+        readonly message_id: Schema.optionalKey<Schema.String>;
+        readonly sender: Schema.optionalKey<Schema.String>;
+    }>]>>;
     readonly expected: Schema.optionalKey<Schema.Struct<{
         readonly chat_id: Schema.String;
         readonly digest: Schema.String;
@@ -47,6 +55,14 @@ declare const CurrentChatCall_base: Context.ServiceClass<CurrentChatCall, "@segm
             readonly file_unique_id?: string | undefined;
             readonly media_type?: string | undefined;
         }[] | undefined;
+    } | {
+        readonly kind: "group" | "private";
+        readonly provider: "slack" | "whatsapp";
+        readonly chat_id: string;
+        readonly thread_id: string;
+        readonly message_id?: string | undefined;
+        readonly sender?: string | undefined;
+        readonly peer?: string | undefined;
     } | undefined;
     readonly operation_id?: string | undefined;
     readonly expected?: {
@@ -85,6 +101,14 @@ export declare function consumeChatEnvelope(args: Readonly<Record<string, unknow
                 readonly file_unique_id?: string | undefined;
                 readonly media_type?: string | undefined;
             }[] | undefined;
+        } | {
+            readonly kind: "group" | "private";
+            readonly provider: "slack" | "whatsapp";
+            readonly chat_id: string;
+            readonly thread_id: string;
+            readonly message_id?: string | undefined;
+            readonly sender?: string | undefined;
+            readonly peer?: string | undefined;
         } | undefined;
         readonly operation_id?: string | undefined;
         readonly expected?: {

package/dist/service/chat/providers/index.d.ts

@@ -0,0 +1,22 @@
+import type { OntologyManifest } from "../../../manifest.js";
+import type { ChatProvider } from "./provider.js";
+export type { ChatProvider, ChatSend, ProviderOutcome } from "./provider.js";
+/** Every provider the platform posts exact chat messages to, by the name the `chat` config uses. */
+export declare const CHAT_PROVIDERS: {
+    readonly telegram: ChatProvider;
+    readonly slack: ChatProvider;
+    readonly whatsapp: ChatProvider;
+};
+export type ChatProviderName = keyof typeof CHAT_PROVIDERS;
+/** The provider a destination's chat is on, when the platform posts to it. */
+export declare function chatProvider(name: string): ChatProvider | undefined;
+/** The connection the ontology declares for posting to a provider's chats, if it declares one. */
+export declare function chatConnection(chat: OntologyManifest["chat"], provider: string): string | undefined;
+/** The providers the ontology declares a posting connection for: the destinations it posts to. */
+export declare function declaredChatProviders(chat: OntologyManifest["chat"]): ReadonlyArray<ChatProviderName>;
+/**
+ * The providers whose chats the chat tools list, read and resolve: Telegram's, whose chats the
+ * tools always listed, and each declared one. Posting still requires the target's provider to
+ * be declared.
+ */
+export declare function listedChatProviders(chat: OntologyManifest["chat"]): ReadonlyArray<string>;

package/dist/service/chat/providers/index.js

@@ -0,0 +1,31 @@
+import { slackProvider } from "./slack.js";
+import { telegramProvider } from "./telegram.js";
+import { whatsappProvider } from "./whatsapp.js";
+/** Every provider the platform posts exact chat messages to, by the name the `chat` config uses. */
+export const CHAT_PROVIDERS = {
+    telegram: telegramProvider,
+    slack: slackProvider,
+    whatsapp: whatsappProvider,
+};
+const NAMES = Object.keys(CHAT_PROVIDERS);
+const isChatProvider = (name) => Object.hasOwn(CHAT_PROVIDERS, name);
+/** The provider a destination's chat is on, when the platform posts to it. */
+export function chatProvider(name) {
+    return isChatProvider(name) ? CHAT_PROVIDERS[name] : undefined;
+}
+/** The connection the ontology declares for posting to a provider's chats, if it declares one. */
+export function chatConnection(chat, provider) {
+    return isChatProvider(provider) ? chat?.[provider]?.connection : undefined;
+}
+/** The providers the ontology declares a posting connection for: the destinations it posts to. */
+export function declaredChatProviders(chat) {
+    return NAMES.filter((name) => chat?.[name] !== undefined);
+}
+/**
+ * The providers whose chats the chat tools list, read and resolve: Telegram's, whose chats the
+ * tools always listed, and each declared one. Posting still requires the target's provider to
+ * be declared.
+ */
+export function listedChatProviders(chat) {
+    return [...new Set(["telegram", ...declaredChatProviders(chat)])];
+}

package/dist/service/chat/providers/provider.d.ts

@@ -0,0 +1,61 @@
+import { type Effect, type Exit } from "effect";
+import type { TelegramPreviewContext } from "../../../telegram.js";
+import { ConnectionError, type ConnectionReply, type ConnectionTransport } from "../../../connection.js";
+import type { Destination } from "../resolve.js";
+/** One delivery attempt's result. A `failed` attempt definitely sent nothing; `uncertain` may have. */
+export interface ProviderOutcome {
+    /** The text and its format as the provider received them, for the delivery's history. */
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly status: "sent" | "uncertain" | "failed";
+    readonly messageId: string | null;
+    readonly url: string | null;
+    readonly cause?: unknown;
+}
+/** What a provider sends: the exact text its `render` gave, to one resolved destination. */
+export interface ChatSend {
+    readonly transport: ConnectionTransport["Service"];
+    readonly connection: string;
+    readonly destination: Destination;
+    /** The member's exact Markdown, and the separator and attribution the platform added to it. */
+    readonly text: string;
+    readonly separator: string;
+    readonly attribution: string;
+    readonly finalText: string;
+    readonly plainText: string;
+    readonly replyTo: string | null;
+    /** Telegram's link preview settings for its destination connection; others ignore them. */
+    readonly previews?: TelegramPreviewContext;
+}
+/**
+ * A channel the platform posts exact chat messages to. Each provider names its own ids, renders
+ * the member's Markdown with the attribution after it, and sends it in one attempt that is never
+ * retried on an unknown outcome, chunked or truncated.
+ */
+export interface ChatProvider {
+    /** The provider name destinations, identities and the ontology's `chat` config use. */
+    readonly provider: string;
+    /** The most characters the provider accepts in one message, for the rendered and plain text. */
+    readonly limit: number;
+    /** Whether an id names a chat of this kind on the provider. */
+    readonly isTargetId: (externalId: string, kind: Destination["kind"]) => boolean;
+    /** Whether an id names a message on the provider that a post may reply to. */
+    readonly isReplyId: (replyTo: string) => boolean;
+    /**
+     * The exact text sent and the same message without formatting. Throws when the Markdown cannot
+     * be rendered.
+     */
+    readonly render: (markdown: string, attribution: string, separator: string) => {
+        readonly finalText: string;
+        readonly plainText: string;
+    };
+    /** The payload a delivery records before the provider answers. */
+    readonly payload: (finalText: string) => Readonly<Record<string, unknown>>;
+    /** One attempt: `sent` only when the provider's answer proves it. */
+    readonly send: (input: ChatSend) => Effect.Effect<ProviderOutcome>;
+}
+/**
+ * The outcome of a request the connection transport failed: `failed` when the proxy refused it
+ * before the provider saw it, otherwise `uncertain`, since the provider may have acted on it.
+ */
+export declare function transportFailure(payload: ProviderOutcome["payload"], result: Exit.Failure<ConnectionReply, ConnectionError>): ProviderOutcome;
+export declare const record: (value: unknown) => Record<string, unknown>;

package/dist/service/chat/providers/provider.js

@@ -0,0 +1,28 @@
+import { Cause } from "effect";
+import { ConnectionError, } from "../../../connection.js";
+/** The connection failures that prove the request never reached the provider. */
+const DEFINITE_CONNECTION_FAILURES = new Set([
+    "authorization_required",
+    "not_deployed",
+    "not_granted",
+    "invalid_request",
+    "refused",
+]);
+/**
+ * The outcome of a request the connection transport failed: `failed` when the proxy refused it
+ * before the provider saw it, otherwise `uncertain`, since the provider may have acted on it.
+ */
+export function transportFailure(payload, result) {
+    const cause = Cause.squash(result.cause);
+    const definite = cause instanceof ConnectionError && DEFINITE_CONNECTION_FAILURES.has(cause.reason);
+    return {
+        payload,
+        status: definite ? "failed" : "uncertain",
+        messageId: null,
+        url: null,
+        cause,
+    };
+}
+export const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};

package/dist/service/chat/providers/slack.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import { type ChatProvider, type ChatSend, type ProviderOutcome } from "./provider.js";
+/**
+ * One `chat.postMessage` through the connection's `web` API, never retried. Slack's own refusal
+ * (`ok: false` with an error code) is definite; a timeout, a 5xx, an unparseable answer or a
+ * success that does not name the message is uncertain.
+ */
+export declare function sendSlack(input: ChatSend): Effect.Effect<ProviderOutcome>;
+/** Slack: the member's Markdown as `markdown_text`, in a channel or a member's direct message. */
+export declare const slackProvider: ChatProvider;

package/dist/service/chat/providers/slack.js

@@ -0,0 +1,93 @@
+import { Effect } from "effect";
+import { renderSlack, SLACK_MESSAGE_LIMIT } from "../../../slack.js";
+import { record, transportFailure, } from "./provider.js";
+/** A message's `ts`, which also names the thread it starts. */
+const SLACK_TS = /^[0-9]+\.[0-9]+$/;
+/**
+ * Slack's `ok: false` codes that do not prove the message was not posted: Slack says some of the
+ * operation may have succeeded before the error.
+ */
+const POSSIBLY_POSTED = new Set([
+    "internal_error",
+    "fatal_error",
+    "service_unavailable",
+]);
+/**
+ * One `chat.postMessage` through the connection's `web` API, never retried. Slack's own refusal
+ * (`ok: false` with an error code) is definite; a timeout, a 5xx, an unparseable answer or a
+ * success that does not name the message is uncertain.
+ */
+export function sendSlack(input) {
+    return Effect.gen(function* () {
+        const payload = { markdown_text: input.finalText };
+        const result = yield* input.transport
+            .request({
+            connection: input.connection,
+            api: "web",
+            method: "POST",
+            path: "/chat.postMessage",
+            headers: [["content-type", "application/json; charset=utf-8"]],
+            body: new TextEncoder().encode(JSON.stringify({
+                channel: input.destination.external_id,
+                ...payload,
+                ...(input.replyTo === null ? {} : { thread_ts: input.replyTo }),
+            })),
+        })
+            .pipe(Effect.exit);
+        if (result._tag === "Failure") {
+            return transportFailure(payload, result);
+        }
+        const uncertain = (cause) => ({
+            payload,
+            status: "uncertain",
+            messageId: null,
+            url: null,
+            cause,
+        });
+        if (result.value.status >= 500) {
+            return uncertain(new Error(`Slack answered with status ${result.value.status}.`));
+        }
+        let body;
+        try {
+            body = record(JSON.parse(new TextDecoder().decode(result.value.body)));
+        }
+        catch (cause) {
+            return uncertain(cause);
+        }
+        if (body.ok === false && typeof body.error === "string" && body.error !== "") {
+            const cause = new Error(`Slack refused the message: ${body.error}.`);
+            return POSSIBLY_POSTED.has(body.error)
+                ? uncertain(cause)
+                : { payload, status: "failed", messageId: null, url: null, cause };
+        }
+        const message = record(body.message);
+        if (result.value.status < 200 ||
+            result.value.status >= 300 ||
+            body.ok !== true ||
+            typeof body.ts !== "string" ||
+            !SLACK_TS.test(body.ts) ||
+            typeof body.channel !== "string" ||
+            body.channel === "" ||
+            // A member's direct message is posted to their user id and answers with its `D…` channel.
+            (input.destination.kind === "group" && body.channel !== input.destination.external_id) ||
+            (input.replyTo !== null && message.thread_ts !== input.replyTo)) {
+            return uncertain(new Error("Slack success could not be verified."));
+        }
+        return { payload, status: "sent", messageId: body.ts, url: null };
+    });
+}
+/** Slack: the member's Markdown as `markdown_text`, in a channel or a member's direct message. */
+export const slackProvider = {
+    provider: "slack",
+    limit: SLACK_MESSAGE_LIMIT,
+    // Channels are `C…`, older private channels `G…`; a private destination is its member's user
+    // id, `U…`, or `W…` in an Enterprise Grid organization.
+    isTargetId: (externalId, kind) => (kind === "group" ? /^[CG][A-Z0-9]{2,32}$/ : /^[UW][A-Z0-9]{2,32}$/).test(externalId),
+    isReplyId: (replyTo) => SLACK_TS.test(replyTo),
+    render: (markdown, attribution, separator) => ({
+        finalText: renderSlack(markdown, attribution, separator),
+        plainText: `${markdown}${separator}${attribution}`,
+    }),
+    payload: (finalText) => ({ markdown_text: finalText }),
+    send: sendSlack,
+};

package/dist/service/chat/providers/telegram.d.ts

@@ -1,21 +1,11 @@
 import { type TelegramPreviewContext } from "../../../telegram.js";
 import { Effect } from "effect";
-import { type ConnectionTransport } from "../../../connection.js";
+import type { ConnectionTransport } from "../../../connection.js";
 import type { Destination } from "../resolve.js";
+import { type ChatProvider, type ProviderOutcome } from "./provider.js";
 export declare const TELEGRAM_MESSAGE_LIMIT = 4096;
 /** Render source independently so user Markdown cannot open an entity around the footer. */
 export declare function renderTelegram(markdown: string, attribution: string, separator?: string): string;
-interface TelegramPayload {
-    readonly text: string;
-    readonly parse_mode?: "MarkdownV2";
-}
-export interface ProviderOutcome {
-    readonly payload: TelegramPayload;
-    readonly status: "sent" | "uncertain" | "failed";
-    readonly messageId: string | null;
-    readonly url: string | null;
-    readonly cause?: unknown;
-}
 interface TelegramSend {
     readonly transport: ConnectionTransport["Service"];
     readonly connection: string;
@@ -33,4 +23,6 @@ interface TelegramSend {
  * Never retry an unknown outcome; never chunk, truncate or invoke an agent.
  */
 export declare function sendTelegram(input: TelegramSend): Effect.Effect<ProviderOutcome>;
+/** Telegram: MarkdownV2 with one plain retry after a definite entity parse refusal. */
+export declare const telegramProvider: ChatProvider;
 export {};

package/dist/service/chat/providers/telegram.js

@@ -1,16 +1,13 @@
 import { telegramMarkdownLinks, telegramTextLinks, telegramPreviewOptions, } from "../../../telegram.js";
 import { escapeMarkdownV2, TelegramFormatConverter } from "@chat-adapter/telegram";
-import { Cause, Effect } from "effect";
-import { ConnectionError } from "../../../connection.js";
+import { Effect } from "effect";
+import { record, transportFailure } from "./provider.js";
 export const TELEGRAM_MESSAGE_LIMIT = 4096;
 const converter = new TelegramFormatConverter();
 /** Render source independently so user Markdown cannot open an entity around the footer. */
 export function renderTelegram(markdown, attribution, separator = "\n\n") {
     return `${converter.fromMarkdown(markdown)}${escapeMarkdownV2(separator)}_${escapeMarkdownV2(attribution)}_`;
 }
-const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
-    ? value
-    : {};
 /** One proxy POST, except one plain retry after a definite 400 entity parse refusal.
  * Never retry an unknown outcome; never chunk, truncate or invoke an agent.
  */
@@ -62,22 +59,7 @@ function attemptTelegram(input, payload) {
         })
             .pipe(Effect.exit);
         if (result._tag === "Failure") {
-            const cause = Cause.squash(result.cause);
-            const definite = cause instanceof ConnectionError &&
-                [
-                    "authorization_required",
-                    "not_deployed",
-                    "not_granted",
-                    "invalid_request",
-                    "refused",
-                ].includes(cause.reason);
-            return {
-                payload,
-                status: definite ? "failed" : "uncertain",
-                messageId: null,
-                url: null,
-                cause,
-            };
+            return transportFailure(payload, result);
         }
         let body;
         try {
@@ -131,3 +113,29 @@ function attemptTelegram(input, payload) {
         return { payload, status: "sent", messageId, url };
     });
 }
+/** Telegram: MarkdownV2 with one plain retry after a definite entity parse refusal. */
+export const telegramProvider = {
+    provider: "telegram",
+    limit: TELEGRAM_MESSAGE_LIMIT,
+    isTargetId: (externalId) => /^-?[1-9][0-9]*$/.test(externalId),
+    isReplyId: (replyTo) => /^[1-9][0-9]*$/.test(replyTo) && Number.isSafeInteger(Number(replyTo)),
+    render: (markdown, attribution, separator) => ({
+        finalText: renderTelegram(markdown, attribution, separator),
+        plainText: `${markdown}${separator}${attribution}`,
+    }),
+    payload: (finalText) => ({ text: finalText, parse_mode: "MarkdownV2" }),
+    send: (input) => sendTelegram({
+        transport: input.transport,
+        connection: input.connection,
+        destination: input.destination,
+        finalText: input.finalText,
+        formattedLinks: [
+            ...telegramMarkdownLinks(input.text),
+            ...telegramTextLinks(input.separator),
+            ...telegramTextLinks(input.attribution),
+        ],
+        ...(input.previews === undefined ? {} : { previews: input.previews }),
+        plainText: input.plainText,
+        replyTo: input.replyTo,
+    }),
+};

package/dist/service/chat/providers/whatsapp.d.ts

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+import { type ChatProvider, type ChatSend, type ProviderOutcome } from "./provider.js";
+/**
+ * One text message from the workspace's number, `POST /phone/messages` on the connection's
+ * `graph` API, never retried. A Graph refusal with an error code, such as 131047 outside the
+ * 24-hour customer-service window, is definite; a timeout, a 5xx, an unparseable answer or a
+ * success without the message's id is uncertain. `sent` means Meta accepted the message.
+ */
+export declare function sendWhatsApp(input: ChatSend): Effect.Effect<ProviderOutcome>;
+/**
+ * WhatsApp: a paired member's chat with the workspace's number, by their WhatsApp id. WhatsApp
+ * has no group destinations, and a post cannot reply to a message.
+ */
+export declare const whatsappProvider: ChatProvider;

package/dist/service/chat/providers/whatsapp.js

@@ -0,0 +1,91 @@
+import { Effect } from "effect";
+import { renderWhatsApp, WHATSAPP_MESSAGE_LIMIT } from "../../../whatsapp.js";
+import { record, transportFailure, } from "./provider.js";
+/** A WhatsApp id: the member's number, digits only. */
+const WA_ID = /^[1-9][0-9]{5,19}$/;
+/** The id Meta gives an accepted message. */
+const WAMID = /^wamid\.[A-Za-z0-9+/=_-]{1,512}$/;
+/**
+ * One text message from the workspace's number, `POST /phone/messages` on the connection's
+ * `graph` API, never retried. A Graph refusal with an error code, such as 131047 outside the
+ * 24-hour customer-service window, is definite; a timeout, a 5xx, an unparseable answer or a
+ * success without the message's id is uncertain. `sent` means Meta accepted the message.
+ */
+export function sendWhatsApp(input) {
+    return Effect.gen(function* () {
+        const payload = { type: "text", text: { body: input.finalText, preview_url: false } };
+        const result = yield* input.transport
+            .request({
+            connection: input.connection,
+            api: "graph",
+            method: "POST",
+            path: "/phone/messages",
+            headers: [["content-type", "application/json"]],
+            body: new TextEncoder().encode(JSON.stringify({
+                messaging_product: "whatsapp",
+                recipient_type: "individual",
+                to: input.destination.external_id,
+                ...payload,
+            })),
+        })
+            .pipe(Effect.exit);
+        if (result._tag === "Failure") {
+            return transportFailure(payload, result);
+        }
+        const { status } = result.value;
+        const uncertain = (cause) => ({
+            payload,
+            status: "uncertain",
+            messageId: null,
+            url: null,
+            cause,
+        });
+        if (status >= 500) {
+            return uncertain(new Error(`WhatsApp answered with status ${status}.`));
+        }
+        let body;
+        try {
+            body = record(JSON.parse(new TextDecoder().decode(result.value.body)));
+        }
+        catch (cause) {
+            return uncertain(cause);
+        }
+        const error = record(body.error);
+        if (status >= 400 && Number.isInteger(error.code)) {
+            const code = [error.code, error.error_subcode].filter(Number.isInteger).join("/");
+            // Meta's own explanation stays in the operator diagnostic, with its code.
+            const explanation = [error.message, record(error.error_data).details]
+                .filter((text) => typeof text === "string" && text !== "")
+                .join(" ");
+            return {
+                payload,
+                status: "failed",
+                messageId: null,
+                url: null,
+                cause: new Error(`WhatsApp refused the message with code ${code}.` +
+                    (explanation === "" ? "" : ` ${explanation}`)),
+            };
+        }
+        const id = record(Array.isArray(body.messages) ? body.messages[0] : undefined).id;
+        if (status < 200 || status >= 300 || typeof id !== "string" || !WAMID.test(id)) {
+            return uncertain(new Error("WhatsApp success could not be verified."));
+        }
+        return { payload, status: "sent", messageId: id, url: null };
+    });
+}
+/**
+ * WhatsApp: a paired member's chat with the workspace's number, by their WhatsApp id. WhatsApp
+ * has no group destinations, and a post cannot reply to a message.
+ */
+export const whatsappProvider = {
+    provider: "whatsapp",
+    limit: WHATSAPP_MESSAGE_LIMIT,
+    isTargetId: (externalId, kind) => kind === "private" && WA_ID.test(externalId),
+    isReplyId: () => false,
+    render: (text, attribution, separator) => ({
+        finalText: renderWhatsApp(text, attribution, separator),
+        plainText: `${text}${separator}${attribution}`,
+    }),
+    payload: (finalText) => ({ type: "text", text: { body: finalText, preview_url: false } }),
+    send: sendWhatsApp,
+};