stageflow 0.33.0 → 0.36.0

package/dist/channels/index.d.ts

@@ -0,0 +1,10 @@
+export { ChannelError, type ChannelErrorCode, type ChannelErrorDetail } from "./errors.js";
+export { CONNECTIONS_FILE_NAME, ChannelRegistry, type ChannelRegistryOptions } from "./registry.js";
+export { loadConnectionsFile, parseConnectionsYaml, type ConnectionsFile } from "./config.js";
+export { isSecretRef, redactSecrets, resolveSecretRef, resolveSecrets } from "./secrets.js";
+export type * from "./types.js";
+export { MAX_CHANNEL_TARGETS, MAX_CHANNELS_PER_STAGE, MAX_STAGE_CHANNELS, channelLimitMessage, setStageChannelLimitForTests, stageChannelLimit, channelKey, channelTarget, mergeChannelDefaults, parseChannels, validateStageChannels, type ParsedChannels, type StageChannelIssue, } from "./stageChannels.js";
+export { ChannelHost, MAX_MESSAGE_TEXT, channelFault, channelHostFor, channelsWorkerEnvironment, releaseChannelHost, stageChannels, validateStageChannelConnections, workerStageChannels, type ChannelSendInput, type ChannelSendResult, type StageChannels, } from "./host.js";
+export { ChannelSends, type ChannelSendRecord } from "./ledger.js";
+export { channelProviders, registerChannelProvider, unregisterChannelProvider } from "./providers.js";
+export { ChannelHealthMonitor, DEFAULT_HEALTH_INTERVAL_MS, type ChannelHealthOptions } from "./health.js";

package/dist/channels/index.js

@@ -0,0 +1,9 @@
+export { ChannelError } from "./errors.js";
+export { CONNECTIONS_FILE_NAME, ChannelRegistry } from "./registry.js";
+export { loadConnectionsFile, parseConnectionsYaml } from "./config.js";
+export { isSecretRef, redactSecrets, resolveSecretRef, resolveSecrets } from "./secrets.js";
+export { MAX_CHANNEL_TARGETS, MAX_CHANNELS_PER_STAGE, MAX_STAGE_CHANNELS, channelLimitMessage, setStageChannelLimitForTests, stageChannelLimit, channelKey, channelTarget, mergeChannelDefaults, parseChannels, validateStageChannels, } from "./stageChannels.js";
+export { ChannelHost, MAX_MESSAGE_TEXT, channelFault, channelHostFor, channelsWorkerEnvironment, releaseChannelHost, stageChannels, validateStageChannelConnections, workerStageChannels, } from "./host.js";
+export { ChannelSends } from "./ledger.js";
+export { channelProviders, registerChannelProvider, unregisterChannelProvider } from "./providers.js";
+export { ChannelHealthMonitor, DEFAULT_HEALTH_INTERVAL_MS } from "./health.js";

package/dist/channels/ledger.d.ts

@@ -0,0 +1,37 @@
+import { type ChannelErrorCode } from "./errors.js";
+import type { SendReceipt } from "./types.js";
+export type ChannelSendRecord = {
+    operationId: string;
+    connectionId: string;
+    operationKey: string;
+    hash: string;
+    state: "pending" | "submitted" | "failed" | "unknown";
+    createdAt: string;
+    receipt?: SendReceipt;
+    error?: {
+        code: ChannelErrorCode;
+        retryable: boolean;
+    };
+};
+export type ChannelSendIdentity = {
+    connectionId: string;
+    operationKey: string;
+    hash: string;
+};
+/**
+ * Durable record of send attempts, so a retried tool call or a resumed stage never sends twice.
+ * It stores a hash of the request, never the message text. The host is the single writer.
+ * A pending record that survives a crash becomes an uncertain outcome, never a resend.
+ */
+export declare class ChannelSends {
+    private readonly file;
+    private records;
+    private readonly active;
+    private accepting;
+    constructor(scope: string);
+    list(): ChannelSendRecord[];
+    drain(): Promise<void>;
+    setAccepting(accepting: boolean): void;
+    send(identity: ChannelSendIdentity, submit: () => Promise<SendReceipt>): Promise<SendReceipt>;
+    private persist;
+}

package/dist/channels/ledger.js

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { storeRootFor } from "../runstore/paths.js";
+import { ChannelError } from "./errors.js";
+const RETENTION_MS = 30 * 86400000;
+const MAX_RECORDS = 10000;
+/**
+ * Durable record of send attempts, so a retried tool call or a resumed stage never sends twice.
+ * It stores a hash of the request, never the message text. The host is the single writer.
+ * A pending record that survives a crash becomes an uncertain outcome, never a resend.
+ */
+export class ChannelSends {
+    file;
+    records;
+    active = new Map();
+    accepting = true;
+    constructor(scope) {
+        this.file = path.join(storeRootFor(scope), "channel-sends.json");
+        this.records = existsSync(this.file) ? JSON.parse(readFileSync(this.file, "utf8")) : [];
+        for (const record of this.records)
+            if (record.state === "pending")
+                record.state = "unknown";
+    }
+    list() {
+        return structuredClone(this.records);
+    }
+    async drain() {
+        await Promise.allSettled(this.active.values());
+    }
+    setAccepting(accepting) {
+        this.accepting = accepting;
+    }
+    async send(identity, submit) {
+        if (!this.accepting)
+            throw new ChannelError("CHANNEL_CONNECTION_FAILED", true, { connectionId: identity.connectionId });
+        const key = `${identity.connectionId}\0${identity.operationKey}`;
+        const found = this.records.find(record => record.connectionId === identity.connectionId && record.operationKey === identity.operationKey);
+        if (found) {
+            if (found.hash !== identity.hash)
+                throw new ChannelError("CHANNEL_OPERATION_CONFLICT", false, { connectionId: identity.connectionId });
+            const active = this.active.get(key);
+            if (active)
+                return active;
+            if (found.receipt)
+                return structuredClone(found.receipt);
+            if (found.state === "failed" && found.error)
+                throw new ChannelError(found.error.code, found.error.retryable, { connectionId: identity.connectionId });
+            throw new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: identity.connectionId });
+        }
+        const cutoff = Date.now() - RETENTION_MS;
+        this.records = this.records.filter(record => !["submitted", "failed"].includes(record.state) || Date.parse(record.createdAt) >= cutoff);
+        if (this.records.length >= MAX_RECORDS)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT", false, { connectionId: identity.connectionId });
+        const record = {
+            operationId: randomUUID(), connectionId: identity.connectionId, operationKey: identity.operationKey,
+            hash: identity.hash, state: "pending", createdAt: new Date().toISOString(),
+        };
+        this.records.push(record);
+        this.persist();
+        const work = Promise.resolve().then(submit).then(receipt => {
+            record.state = "submitted";
+            record.receipt = receipt;
+            try {
+                this.persist();
+            }
+            catch {
+                return { ...structuredClone(receipt), warnings: [...(receipt.warnings ?? []), "CHANNEL_STORAGE_FAILED"] };
+            }
+            return structuredClone(receipt);
+        }).catch(error => {
+            if (record.state === "submitted")
+                throw error;
+            const fault = error instanceof ChannelError ? error : new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: identity.connectionId });
+            record.state = fault.code === "CHANNEL_SEND_OUTCOME_UNKNOWN" ? "unknown" : "failed";
+            record.error = { code: fault.code, retryable: fault.retryable };
+            try {
+                this.persist();
+            }
+            catch {
+                record.state = "unknown";
+                throw new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: identity.connectionId });
+            }
+            throw new ChannelError(fault.code, fault.retryable, { connectionId: identity.connectionId });
+        }).finally(() => { this.active.delete(key); });
+        this.active.set(key, work);
+        return work;
+    }
+    persist() {
+        mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+        const temporary = `${this.file}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify(this.records), { mode: 0o600 });
+        renameSync(temporary, this.file);
+    }
+}

package/dist/channels/providers/agentmail.d.ts

@@ -0,0 +1,26 @@
+import type { ChannelProvider, ProviderMeta } from "../types.js";
+export type AgentMailConfig = {
+    inbox: string;
+    region: "us" | "eu";
+};
+export type AgentMailTarget = {
+    to: string[];
+    cc?: string[];
+};
+export declare const AGENTMAIL_BASE_URLS: {
+    readonly us: "https://api.agentmail.to";
+    readonly eu: "https://api.agentmail.eu";
+};
+export declare const AGENTMAIL_DEFAULT_SUBJECT = "Message from Stageflow";
+export declare const AGENTMAIL_META: ProviderMeta;
+export type AgentMailOptions = {
+    fetch?: typeof fetch;
+    baseUrls?: Partial<Record<"us" | "eu", string>>;
+    sendTimeoutMs?: number;
+    checkTimeoutMs?: number;
+};
+/**
+ * Sends mail from one existing AgentMail inbox through the REST API. Needs a key that can
+ * read the inbox and send messages. Receiving is not part of this phase.
+ */
+export declare function createAgentMailProvider(options?: AgentMailOptions): ChannelProvider<AgentMailConfig, AgentMailTarget>;

package/dist/channels/providers/agentmail.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { ChannelError } from "../errors.js";
+import { httpCall, parseJson, statusFailure } from "../http.js";
+import { healthOf, receiptFor, zodValidator } from "./kit.js";
+export const AGENTMAIL_BASE_URLS = { us: "https://api.agentmail.to", eu: "https://api.agentmail.eu" };
+export const AGENTMAIL_DEFAULT_SUBJECT = "Message from Stageflow";
+export const AGENTMAIL_META = {
+    label: "AgentMail",
+    blurb: "Not connected · send email from an inbox",
+    icon: "mail",
+    fields: [
+        { key: "inbox", label: "Inbox address", hint: "An existing AgentMail inbox. Stageflow does not create one.", target: "config", input: "text", required: true, placeholder: "research@agentmail.to" },
+        { key: "region", label: "Region", target: "config", input: "select", required: false, defaultValue: "us", options: [{ value: "us", label: "United States" }, { value: "eu", label: "Europe" }] },
+        { key: "apiKey", label: "API key", hint: "Needs to read the inbox and send messages.", target: "secret", input: "password", required: true, placeholder: "am_..." },
+    ],
+    recipient: { label: "To", placeholder: "oncall@acme.com, lead@acme.com", multiple: true, cc: true, template: false },
+    envNames: ["AGENTMAIL_API_KEY"],
+    yamlExample: `connections:
+  - id: support-inbox
+    provider: agentmail
+    config:
+      inbox: support@agentmail.to
+    secrets:
+      apiKey: env:AGENTMAIL_API_KEY
+`,
+    stageExample: "    to: [oncall@acme.com]",
+};
+const address = z.string().min(3).max(320).regex(/^[^\s@<>,;]+@[^\s@<>,;]+$/);
+const configSchema = z.object({ inbox: address, region: z.enum(["us", "eu"]).default("us") }).strict();
+const targetSchema = z.object({
+    to: z.union([address, z.array(address).min(1).max(20)]),
+    cc: z.array(address).min(1).max(20).optional(),
+}).strict();
+const validateConfig = zodValidator(configSchema, "config");
+const validateTarget = zodValidator(targetSchema, "target", (data) => ({
+    to: Array.isArray(data.to) ? data.to : [data.to],
+    ...(data.cc !== undefined ? { cc: data.cc } : {}),
+}));
+/**
+ * Sends mail from one existing AgentMail inbox through the REST API. Needs a key that can
+ * read the inbox and send messages. Receiving is not part of this phase.
+ */
+export function createAgentMailProvider(options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const baseUrl = (config) => options.baseUrls?.[config.region] ?? AGENTMAIL_BASE_URLS[config.region];
+    const inboxUrl = (connection) => `${baseUrl(connection.config)}/v0/inboxes/${encodeURIComponent(connection.config.inbox)}`;
+    const auth = (connection) => ({ authorization: `Bearer ${connection.secrets.apiKey}`, accept: "application/json" });
+    return {
+        id: "agentmail",
+        meta: AGENTMAIL_META,
+        operations: ["send"],
+        secrets: { required: ["apiKey"] },
+        validateConfig,
+        validateTarget,
+        describe: config => ({ identity: config.inbox }),
+        check: (connection, signal) => healthOf(async () => {
+            const result = await httpCall({
+                fetch: doFetch, url: inboxUrl(connection), method: "GET", headers: auth(connection),
+                timeoutMs: options.checkTimeoutMs ?? 10000, signal, mode: "check", connectionId: connection.id,
+            });
+            if (result.status >= 200 && result.status < 300)
+                return;
+            throw result.status === 404 ? new ChannelError("CHANNEL_INVALID_INPUT") : statusFailure(result.status, "check", connection.id);
+        }),
+        async send(connection, target, message, _context) {
+            const result = await httpCall({
+                fetch: doFetch, url: `${inboxUrl(connection)}/messages/send`, method: "POST", headers: auth(connection),
+                body: {
+                    to: target.to, ...(target.cc !== undefined ? { cc: target.cc } : {}),
+                    subject: message.subject ?? AGENTMAIL_DEFAULT_SUBJECT, text: message.text,
+                },
+                timeoutMs: options.sendTimeoutMs ?? 30000, mode: "send", connectionId: connection.id,
+            });
+            if (result.status < 200 || result.status >= 300) {
+                throw result.status === 404 ? new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: connection.id }) : statusFailure(result.status, "send", connection.id);
+            }
+            const body = parseJson(result.text);
+            return receiptFor(typeof body?.message_id === "string" ? body.message_id : undefined);
+        },
+    };
+}

package/dist/channels/providers/kit.d.ts

@@ -0,0 +1,40 @@
+import type { z } from "zod";
+import type { ConnectionHealth, SendReceipt, ValidationResult } from "../types.js";
+/**
+ * Adapter helpers that every provider shares. Each one owns a rule that used to be copied into
+ * each adapter and had started to drift (for example how an unexpected error in a check is
+ * retried). Adapters keep only what makes them different: the protocol of their own send.
+ */
+/** Turns a zod schema into a `ValidationResult`, naming the failing paths or `root` when there is none. */
+export declare function zodValidator<S extends z.ZodType, V = z.infer<S>>(schema: S, root: string, normalize?: (data: z.infer<S>) => V): (input: unknown) => ValidationResult<V>;
+/**
+ * Runs a live check. `run` returns when the connection works and throws a `ChannelError` for a
+ * definite failure. Any other error is treated as a transient connection failure, for every
+ * provider alike, because run start retries only failures marked retryable.
+ */
+export declare function healthOf(run: () => Promise<void>): Promise<ConnectionHealth>;
+/** The receipt for an accepted send. A provider that accepted it but returned no id still counts as accepted, with a warning. */
+export declare function receiptFor(messageId: string | undefined): SendReceipt;
+/** Bounds a send that has no timeout of its own. Expiry is an unknown outcome: the send may have gone out. */
+export declare function withSendTimeout<T>(ms: number, connectionId: string, work: Promise<T>): Promise<T>;
+export type SpectrumImporter = (specifier: string) => Promise<any>;
+export declare const importModule: SpectrumImporter;
+export type SpectrumPlatformRef = {
+    /** npm package of the platform, such as `@spectrum-ts/imessage`. */
+    pkg: string;
+    /** Name of its export, such as `imessage`. */
+    exportName: string;
+};
+/**
+ * The Spectrum SDK lifecycle for one send: load the packages on first use (so a host that never
+ * sends over Photon does not need them), create the app, hand the platform to `run`, and always
+ * stop the app. Nothing stays connected between sends. A missing package is
+ * `CHANNEL_PROVIDER_UNSUPPORTED`; a failure to stop never hides the send's own result.
+ */
+export declare function withSpectrumApp<T>(importer: SpectrumImporter, credentials: {
+    projectId: string;
+    projectSecret: string;
+}, platform: SpectrumPlatformRef, run: (app: {
+    platform: any;
+    module: any;
+}) => Promise<T>): Promise<T>;

package/dist/channels/providers/kit.js

@@ -0,0 +1,78 @@
+import { ChannelError } from "../errors.js";
+/**
+ * Adapter helpers that every provider shares. Each one owns a rule that used to be copied into
+ * each adapter and had started to drift (for example how an unexpected error in a check is
+ * retried). Adapters keep only what makes them different: the protocol of their own send.
+ */
+/** Turns a zod schema into a `ValidationResult`, naming the failing paths or `root` when there is none. */
+export function zodValidator(schema, root, normalize) {
+    return input => {
+        const parsed = schema.safeParse(input);
+        if (!parsed.success)
+            return { ok: false, issues: parsed.error.issues.map(issue => issue.path.join(".") || root) };
+        return { ok: true, value: normalize ? normalize(parsed.data) : parsed.data };
+    };
+}
+/**
+ * Runs a live check. `run` returns when the connection works and throws a `ChannelError` for a
+ * definite failure. Any other error is treated as a transient connection failure, for every
+ * provider alike, because run start retries only failures marked retryable.
+ */
+export async function healthOf(run) {
+    const checkedAt = new Date().toISOString();
+    try {
+        await run();
+        return { state: "ok", checkedAt };
+    }
+    catch (error) {
+        const failure = error instanceof ChannelError ? error : new ChannelError("CHANNEL_CONNECTION_FAILED", true);
+        return { state: "failed", checkedAt, error: { code: failure.code, retryable: failure.retryable } };
+    }
+}
+/** The receipt for an accepted send. A provider that accepted it but returned no id still counts as accepted, with a warning. */
+export function receiptFor(messageId) {
+    return {
+        ...(messageId !== undefined ? { providerMessageId: messageId } : {}),
+        submittedAt: new Date().toISOString(),
+        ...(messageId === undefined ? { warnings: ["CHANNEL_RESPONSE_UNPARSEABLE"] } : {}),
+    };
+}
+/** Bounds a send that has no timeout of its own. Expiry is an unknown outcome: the send may have gone out. */
+export async function withSendTimeout(ms, connectionId, work) {
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId })), ms);
+    });
+    try {
+        return await Promise.race([work, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const importModule = specifier => import(specifier);
+/**
+ * The Spectrum SDK lifecycle for one send: load the packages on first use (so a host that never
+ * sends over Photon does not need them), create the app, hand the platform to `run`, and always
+ * stop the app. Nothing stays connected between sends. A missing package is
+ * `CHANNEL_PROVIDER_UNSUPPORTED`; a failure to stop never hides the send's own result.
+ */
+export async function withSpectrumApp(importer, credentials, platform, run) {
+    let core;
+    let module;
+    try {
+        core = await importer("@spectrum-ts/core");
+        module = await importer(platform.pkg);
+    }
+    catch {
+        throw new ChannelError("CHANNEL_PROVIDER_UNSUPPORTED");
+    }
+    const exported = module[platform.exportName];
+    const app = await core.Spectrum({ projectId: credentials.projectId, projectSecret: credentials.projectSecret, providers: [exported.config()] });
+    try {
+        return await run({ platform: exported(app), module });
+    }
+    finally {
+        await app.stop().catch(() => undefined);
+    }
+}

package/dist/channels/providers/photonImessage.d.ts

@@ -0,0 +1,45 @@
+import { ChannelError } from "../errors.js";
+import { type SpectrumImporter } from "./kit.js";
+import type { ChannelProvider, ProviderField, ProviderMeta, ResolvedConnection } from "../types.js";
+export type PhotonImessageConfig = Record<string, never>;
+export type PhotonImessageTarget = {
+    recipient: string;
+};
+export type PhotonCredentials = {
+    projectId: string;
+    projectSecret: string;
+};
+/** Sends one iMessage text. Implementations throw `ChannelError` for failures they can classify. */
+export interface PhotonImessageTransport {
+    sendText(credentials: PhotonCredentials, recipient: string, text: string): Promise<{
+        messageId?: string;
+    }>;
+}
+export declare const PHOTON_BASE_URL = "https://spectrum.photon.codes";
+export declare const PHOTON_FIELDS: ProviderField[];
+export declare const PHOTON_CREDENTIAL_YAML = "credentials:\n  - id: photon-main\n    provider: photon\n    secrets:\n      projectId: env:PHOTON_PROJECT_ID\n      projectSecret: env:PHOTON_PROJECT_SECRET\n";
+export declare const IMESSAGE_META: ProviderMeta;
+export type PhotonImessageOptions = {
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    transport?: PhotonImessageTransport;
+    sendTimeoutMs?: number;
+    checkTimeoutMs?: number;
+};
+export declare function credentialsOf(connection: ResolvedConnection<unknown>): PhotonCredentials;
+export declare function photonHeaders({ projectId, projectSecret }: PhotonCredentials): Record<string, string>;
+/** Photon wraps responses as `{ succeed, data }`. Older shapes without the wrapper are still read. */
+export declare function photonData(body: unknown): Record<string, unknown> | undefined;
+/** Maps what the Spectrum SDK throws. Unclassified errors may have happened after the send, so they are unknown. */
+export declare function classifySdkError(error: unknown, connectionId: string): ChannelError;
+/**
+ * The Spectrum SDK send for iMessage. The lifecycle (lazy import, create, stop) is shared with
+ * WhatsApp in `withSpectrumApp`.
+ */
+export declare function spectrumTransport(importer?: SpectrumImporter): PhotonImessageTransport;
+/**
+ * iMessage through a Photon (Spectrum) project, DM only. Credentials come from a shared `photon`
+ * credential. Free and Pro projects can message only users registered in the project, which the
+ * target check looks up; Stageflow never registers users. Receiving is not part of this phase.
+ */
+export declare function createPhotonImessageProvider(options?: PhotonImessageOptions): ChannelProvider<PhotonImessageConfig, PhotonImessageTarget>;

package/dist/channels/providers/photonImessage.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { ChannelError } from "../errors.js";
+import { httpCall, parseJson, statusFailure } from "../http.js";
+import { healthOf, importModule, receiptFor, withSendTimeout, withSpectrumApp, zodValidator } from "./kit.js";
+export const PHOTON_BASE_URL = "https://spectrum.photon.codes";
+export const PHOTON_FIELDS = [
+    { key: "projectId", label: "Photon project ID", hint: "Project settings in app.photon.codes", target: "credential", input: "password", required: true, placeholder: "3f9c21aa-..." },
+    { key: "projectSecret", label: "Photon project secret", hint: "Stored on this host. Never written to connections.yaml.", target: "credential", input: "password", required: true },
+];
+export const PHOTON_CREDENTIAL_YAML = `credentials:
+  - id: photon-main
+    provider: photon
+    secrets:
+      projectId: env:PHOTON_PROJECT_ID
+      projectSecret: env:PHOTON_PROJECT_SECRET
+`;
+export const IMESSAGE_META = {
+    label: "iMessage",
+    blurb: "Not connected · via Photon",
+    icon: "message-circle",
+    via: "Photon",
+    note: "Sending iMessage uses the Spectrum SDK packages (optional dependencies). On a Free or Pro Photon project, each recipient must be a project user and must text their assigned line once before Stageflow can message them.",
+    fields: PHOTON_FIELDS,
+    recipient: { label: "Recipient", placeholder: "+14155550123 or an Apple ID email", multiple: false, cc: false, template: false },
+    envNames: ["PHOTON_PROJECT_ID", "PHOTON_PROJECT_SECRET"],
+    yamlExample: `${PHOTON_CREDENTIAL_YAML}connections:
+  - id: alerts-imessage
+    provider: imessage
+    credential: photon-main
+`,
+    stageExample: '    to: "+14155550123"',
+};
+const e164 = /^\+[1-9]\d{6,14}$/;
+const email = /^[^\s@<>,;]+@[^\s@<>,;]+$/;
+const targetSchema = z.object({ to: z.string().max(320).refine(value => e164.test(value) || email.test(value)) }).strict();
+const validateConfig = zodValidator(z.object({}).strict(), "config", () => ({}));
+const validateTarget = zodValidator(targetSchema, "target", (data) => ({ recipient: data.to }));
+export function credentialsOf(connection) {
+    const secrets = connection.credential?.secrets;
+    if (!secrets?.projectId || !secrets.projectSecret)
+        throw new ChannelError("CHANNEL_SECRET_UNAVAILABLE", false, { connectionId: connection.id });
+    return { projectId: secrets.projectId, projectSecret: secrets.projectSecret };
+}
+export function photonHeaders({ projectId, projectSecret }) {
+    return { authorization: `Basic ${Buffer.from(`${projectId}:${projectSecret}`).toString("base64")}`, accept: "application/json" };
+}
+/** Photon wraps responses as `{ succeed, data }`. Older shapes without the wrapper are still read. */
+export function photonData(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const wrapped = body.data;
+    return wrapped && typeof wrapped === "object" ? wrapped : body;
+}
+function containsString(value, wanted) {
+    if (typeof value === "string")
+        return value.toLowerCase() === wanted.toLowerCase();
+    if (Array.isArray(value))
+        return value.some(item => containsString(item, wanted));
+    if (value && typeof value === "object")
+        return Object.values(value).some(item => containsString(item, wanted));
+    return false;
+}
+/** Maps what the Spectrum SDK throws. Unclassified errors may have happened after the send, so they are unknown. */
+export function classifySdkError(error, connectionId) {
+    if (error instanceof ChannelError)
+        return error;
+    const detail = { connectionId };
+    const status = error?.status;
+    const message = error instanceof Error ? error.message : "";
+    if (/target not allowed/i.test(message))
+        return new ChannelError("CHANNEL_RECIPIENT_REJECTED", false, detail);
+    if (status === 401)
+        return new ChannelError("CHANNEL_AUTH_FAILED", false, detail);
+    if (status === 403)
+        return new ChannelError("CHANNEL_UNAUTHORIZED", false, detail);
+    if (status === 429)
+        return new ChannelError("CHANNEL_RATE_LIMIT", true, detail);
+    return new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, detail);
+}
+/**
+ * The Spectrum SDK send for iMessage. The lifecycle (lazy import, create, stop) is shared with
+ * WhatsApp in `withSpectrumApp`.
+ */
+export function spectrumTransport(importer = importModule) {
+    return {
+        sendText: (credentials, recipient, text) => withSpectrumApp(importer, credentials, { pkg: "@spectrum-ts/imessage", exportName: "imessage" }, async ({ platform }) => {
+            const user = await platform.user(recipient);
+            const space = await platform.space.create(user);
+            const sent = await space.send(text);
+            return typeof sent?.id === "string" ? { messageId: sent.id } : {};
+        }),
+    };
+}
+/**
+ * iMessage through a Photon (Spectrum) project, DM only. Credentials come from a shared `photon`
+ * credential. Free and Pro projects can message only users registered in the project, which the
+ * target check looks up; Stageflow never registers users. Receiving is not part of this phase.
+ */
+export function createPhotonImessageProvider(options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const base = options.baseUrl ?? PHOTON_BASE_URL;
+    const transport = options.transport ?? spectrumTransport();
+    return {
+        id: "imessage",
+        meta: IMESSAGE_META,
+        operations: ["send"],
+        secrets: { required: [] },
+        credentialProvider: "photon",
+        validateConfig,
+        validateTarget,
+        check: (connection, signal) => healthOf(async () => {
+            const credentials = credentialsOf(connection);
+            const result = await httpCall({
+                fetch: doFetch, url: `${base}/projects/${encodeURIComponent(credentials.projectId)}/imessage/tokens`, method: "POST",
+                headers: photonHeaders(credentials), body: {}, timeoutMs: options.checkTimeoutMs ?? 10000, signal, mode: "check", connectionId: connection.id,
+            });
+            if (result.status < 200 || result.status >= 300)
+                throw statusFailure(result.status, "check", connection.id);
+        }),
+        checkTargets: (connection, targets, signal) => healthOf(async () => {
+            const credentials = credentialsOf(connection);
+            const project = encodeURIComponent(credentials.projectId);
+            const call = (url, init) => httpCall({
+                fetch: doFetch, url, method: init.method, headers: photonHeaders(credentials), ...(init.body !== undefined ? { body: init.body } : {}),
+                timeoutMs: options.checkTimeoutMs ?? 10000, signal, mode: "check", connectionId: connection.id,
+            });
+            const tokens = await call(`${base}/projects/${project}/imessage/tokens`, { method: "POST", body: {} });
+            if (tokens.status < 200 || tokens.status >= 300)
+                throw statusFailure(tokens.status, "check", connection.id);
+            if (photonData(parseJson(tokens.text))?.type === "dedicated")
+                return;
+            for (const target of targets) {
+                const found = await call(`${base}/projects/${project}/users/?search=${encodeURIComponent(target.recipient)}`, { method: "GET" });
+                if (found.status < 200 || found.status >= 300)
+                    throw statusFailure(found.status, "check", connection.id);
+                if (!containsString(parseJson(found.text), target.recipient))
+                    throw new ChannelError("CHANNEL_RECIPIENT_REJECTED", false, { connectionId: connection.id });
+            }
+        }),
+        async send(connection, target, message, _context) {
+            const credentials = credentialsOf(connection);
+            const text = message.subject ? `${message.subject}\n\n${message.text}` : message.text;
+            try {
+                const sent = await withSendTimeout(options.sendTimeoutMs ?? 45000, connection.id, transport.sendText(credentials, target.recipient, text));
+                return receiptFor(sent.messageId);
+            }
+            catch (error) {
+                throw classifySdkError(error, connection.id);
+            }
+        },
+    };
+}

package/dist/channels/providers/photonWhatsapp.d.ts

@@ -0,0 +1,49 @@
+import { ChannelError } from "../errors.js";
+import { type SpectrumImporter } from "./kit.js";
+import type { ChannelProvider, OutboundMessage, ProviderMeta } from "../types.js";
+import { type PhotonCredentials } from "./photonImessage.js";
+export type WhatsappTemplate = {
+    name: string;
+    languageCode: string;
+    bodyParams?: string[];
+};
+export type WhatsappTarget = {
+    recipient: string;
+    template?: WhatsappTemplate;
+};
+export type WhatsappConfig = Record<string, never>;
+export declare const WHATSAPP_META: ProviderMeta;
+export declare const MESSAGE_PLACEHOLDER = "{{message}}";
+export declare const MAX_TEMPLATE_PARAM = 1024;
+/** One outbound message. `template` is sent as an approved template, otherwise `text` is free-form. */
+export type WhatsappOutbound = {
+    text: string;
+} | {
+    template: WhatsappTemplate;
+};
+export interface PhotonWhatsappTransport {
+    send(credentials: PhotonCredentials, recipient: string, outbound: WhatsappOutbound): Promise<{
+        messageId?: string;
+    }>;
+}
+export type PhotonWhatsappOptions = {
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    transport?: PhotonWhatsappTransport;
+    sendTimeoutMs?: number;
+    checkTimeoutMs?: number;
+};
+/** Template parameters cannot hold newlines, tabs or long runs of spaces. */
+export declare function templateParam(text: string): string;
+/** Fills `{{message}}` in the pinned parameters. Fails before sending if a result is empty or too long. */
+export declare function fillTemplate(template: WhatsappTemplate, message: OutboundMessage, connectionId: string): WhatsappTemplate;
+/** Maps SDK and Meta errors. Unclassified errors may have happened after the send, so they are unknown. */
+export declare function classifyWhatsappError(error: unknown, connectionId: string): ChannelError;
+/** The Spectrum SDK send for WhatsApp, on the same shared lifecycle as iMessage. */
+export declare function spectrumWhatsappTransport(importer?: SpectrumImporter): PhotonWhatsappTransport;
+/**
+ * WhatsApp Business through a Photon project (cloud mode), 1:1 only. Free-form text works only
+ * inside the 24-hour window after the recipient last wrote to the business, so a stage that
+ * writes first must pin an approved `template`. Receiving is not part of this phase.
+ */
+export declare function createPhotonWhatsappProvider(options?: PhotonWhatsappOptions): ChannelProvider<WhatsappConfig, WhatsappTarget>;