openclaw-imessage-photon 0.1.0

package/dist/src/channel.js

@@ -0,0 +1,247 @@
+import { createChatChannelPlugin, } from "openclaw/plugin-sdk/channel-core";
+import { connectSpectrum, resetSpectrum, rememberSpace, rememberMessage } from "./spectrum.js";
+import { handleInbound } from "./inbound.js";
+import { createMessageActions } from "./actions.js";
+function channelSection(cfg) {
+    return cfg.channels?.["imessage-photon"];
+}
+function readAllowFrom(section) {
+    const fromConfig = section?.allowFrom;
+    if (Array.isArray(fromConfig))
+        return fromConfig.map(String);
+    const fromEnv = process.env.SPECTRUM_ALLOWED_NUMBERS ?? "";
+    return fromEnv.split(",").map((s) => s.trim()).filter(Boolean);
+}
+export function resolveAccount(cfg, accountId) {
+    const section = channelSection(cfg);
+    const projectId = section?.projectId ?? process.env.SPECTRUM_PROJECT_ID ?? "";
+    const projectSecret = section?.projectSecret ?? process.env.SPECTRUM_PROJECT_SECRET ?? "";
+    if (!projectId || !projectSecret) {
+        throw new Error("imessage-photon: SPECTRUM_PROJECT_ID and SPECTRUM_PROJECT_SECRET are required " +
+            "(set channels.imessage-photon.projectId/projectSecret or the env vars)");
+    }
+    return {
+        accountId: accountId ?? null,
+        projectId,
+        projectSecret,
+        allowFrom: readAllowFrom(section),
+        dmPolicy: section?.dmSecurity,
+        ackReaction: section?.ackReaction ?? "👀",
+        tapbackNotifications: section?.tapbackNotifications ?? "all",
+        enableMedia: Boolean(section?.enableMedia),
+        enablePoll: Boolean(section?.enablePoll),
+        enableEffects: Boolean(section?.enableEffects),
+        enableContact: Boolean(section?.enableContact),
+        enableVoice: Boolean(section?.enableVoice),
+        enableGroups: Boolean(section?.enableGroups),
+        enableTyping: Boolean(section?.enableTyping),
+        enableReadReceipts: Boolean(section?.enableReadReceipts),
+    };
+}
+const setupWizard = {
+    channel: "imessage-photon",
+    status: {
+        configuredLabel: "Connected",
+        unconfiguredLabel: "Not configured",
+        resolveConfigured: ({ cfg }) => {
+            const s = channelSection(cfg);
+            if (s?.projectId && s?.projectSecret)
+                return true;
+            return Boolean(process.env.SPECTRUM_PROJECT_ID && process.env.SPECTRUM_PROJECT_SECRET);
+        },
+    },
+    credentials: [
+        {
+            inputKey: "token",
+            providerHint: "imessage-photon",
+            credentialLabel: "Photon project ID",
+            preferredEnvVar: "SPECTRUM_PROJECT_ID",
+            envPrompt: "Use SPECTRUM_PROJECT_ID from the environment?",
+            keepPrompt: "Keep the current project ID?",
+            inputPrompt: "Paste your Photon project ID:",
+            helpTitle: "Where do I find this?",
+            helpLines: [
+                "1. Sign up at https://photon.codes",
+                "2. Create a project and select the iMessage provider",
+                "3. Copy the Project ID from the project settings page",
+            ],
+            inspect: ({ cfg }) => {
+                const s = channelSection(cfg);
+                const v = s?.projectId ?? process.env.SPECTRUM_PROJECT_ID;
+                return {
+                    accountConfigured: Boolean(s?.projectId),
+                    hasConfiguredValue: Boolean(v),
+                    resolvedValue: v,
+                };
+            },
+            applySet: ({ cfg, value }) => ({
+                ...cfg,
+                channels: {
+                    ...cfg.channels,
+                    "imessage-photon": { ...channelSection(cfg), projectId: String(value) },
+                },
+            }),
+        },
+        {
+            inputKey: "secret",
+            providerHint: "imessage-photon",
+            credentialLabel: "Photon project secret",
+            preferredEnvVar: "SPECTRUM_PROJECT_SECRET",
+            envPrompt: "Use SPECTRUM_PROJECT_SECRET from the environment?",
+            keepPrompt: "Keep the current project secret?",
+            inputPrompt: "Paste your Photon project secret:",
+            helpTitle: "Where do I find this?",
+            helpLines: [
+                "The project secret is only shown once when you create the project.",
+                "If you lost it, rotate it from the project settings page.",
+            ],
+            inspect: ({ cfg }) => {
+                const s = channelSection(cfg);
+                const v = s?.projectSecret ?? process.env.SPECTRUM_PROJECT_SECRET;
+                return {
+                    accountConfigured: Boolean(s?.projectSecret),
+                    hasConfiguredValue: Boolean(v),
+                    resolvedValue: v,
+                };
+            },
+            applySet: ({ cfg, value }) => ({
+                ...cfg,
+                channels: {
+                    ...cfg.channels,
+                    "imessage-photon": { ...channelSection(cfg), projectSecret: String(value) },
+                },
+            }),
+        },
+    ],
+    textInputs: [
+        {
+            inputKey: "dmAllowlist",
+            message: "Allowed sender phone numbers (comma-separated, E.164 like +8613800138000). Leave empty to allow everyone:",
+            placeholder: "+8613800138000,+14155550123",
+            required: false,
+            helpTitle: "Who can message the agent?",
+            helpLines: [
+                "Enter phone numbers in E.164 form. Empty = anyone can DM the agent.",
+                "This is the same as channels.imessage-photon.allowFrom.",
+            ],
+            currentValue: ({ cfg }) => {
+                const s = channelSection(cfg);
+                if (Array.isArray(s?.allowFrom))
+                    return s.allowFrom.join(",");
+                return process.env.SPECTRUM_ALLOWED_NUMBERS ?? "";
+            },
+            applySet: ({ cfg, value }) => ({
+                ...cfg,
+                channels: {
+                    ...cfg.channels,
+                    "imessage-photon": {
+                        ...channelSection(cfg),
+                        allowFrom: value.split(",").map((s) => s.trim()).filter(Boolean),
+                    },
+                },
+            }),
+        },
+    ],
+};
+export const imessagePhotonPlugin = createChatChannelPlugin({
+    base: {
+        id: "imessage-photon",
+        meta: {
+            id: "imessage-photon",
+            label: "iMessage (Photon)",
+            selectionLabel: "iMessage via Photon Spectrum Cloud",
+            docsPath: "https://github.com/ethanjtch/openclaw-imessage-photon",
+            blurb: "iMessage through Photon Spectrum Cloud — no Mac required.",
+            markdownCapable: false,
+        },
+        capabilities: {
+            chatTypes: ["direct"],
+            reactions: true,
+            reply: true,
+        },
+        actions: createMessageActions(),
+        setupWizard,
+        config: {
+            listAccountIds: () => ["default"],
+            resolveAccount,
+            inspectAccount(cfg, _accountId) {
+                const s = channelSection(cfg);
+                const hasCfg = Boolean(s?.projectId && s?.projectSecret);
+                const hasEnv = Boolean(process.env.SPECTRUM_PROJECT_ID && process.env.SPECTRUM_PROJECT_SECRET);
+                return {
+                    enabled: hasCfg || hasEnv,
+                    configured: hasCfg || hasEnv,
+                    projectIdStatus: s?.projectId || process.env.SPECTRUM_PROJECT_ID ? "available" : "missing",
+                    projectSecretStatus: s?.projectSecret || process.env.SPECTRUM_PROJECT_SECRET ? "available" : "missing",
+                };
+            },
+        },
+        setup: {
+            applyAccountConfig: ({ cfg, input }) => ({
+                ...cfg,
+                channels: {
+                    ...cfg.channels,
+                    "imessage-photon": { ...channelSection(cfg), ...input },
+                },
+            }),
+        },
+        gateway: {
+            startAccount: async (ctx) => {
+                const log = (msg) => ctx.log?.info?.(msg);
+                const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+                const channelRuntime = ctx.channelRuntime;
+                // Reconnect loop: if the Spectrum stream ever ends (transport drop,
+                // transient error), back off and re-create the connection instead of
+                // leaving the channel dead until a manual gateway restart.
+                let backoffMs = 1_000;
+                while (!ctx.abortSignal.aborted) {
+                    try {
+                        log("[imessage-photon] connecting to Spectrum Cloud...");
+                        const app = await connectSpectrum(ctx.account.projectId, ctx.account.projectSecret);
+                        log(`[imessage-photon] connected to Spectrum Cloud (allowlist: ${ctx.account.allowFrom.length ? ctx.account.allowFrom.join(", ") : "ALL"})`);
+                        backoffMs = 1_000;
+                        for await (const [space, message] of app.messages) {
+                            if (ctx.abortSignal.aborted)
+                                break;
+                            rememberSpace(space);
+                            rememberMessage(message);
+                            handleInbound(channelRuntime, ctx.cfg, space, message, log).catch((err) => {
+                                ctx.log?.error?.(`[imessage-photon] inbound error: ${String(err)}`);
+                            });
+                        }
+                        if (ctx.abortSignal.aborted)
+                            break;
+                        log("[imessage-photon] message stream ended; reconnecting...");
+                    }
+                    catch (err) {
+                        ctx.log?.error?.(`[imessage-photon] stream failed: ${String(err)}`);
+                    }
+                    if (ctx.abortSignal.aborted)
+                        break;
+                    await resetSpectrum();
+                    await sleep(backoffMs + Math.random() * backoffMs * 0.2);
+                    backoffMs = Math.min(backoffMs * 2, 30_000);
+                }
+                log("[imessage-photon] stopped");
+            },
+            stopAccount: async () => {
+                await resetSpectrum();
+            },
+        },
+    },
+    security: {
+        dm: {
+            channelKey: "imessage-photon",
+            resolvePolicy: (account) => account.dmPolicy,
+            resolveAllowFrom: (account) => account.allowFrom,
+            defaultPolicy: "allowlist",
+        },
+    },
+    threading: { topLevelReplyToMode: "reply" },
+    outbound: {
+        // Outbound delivery runs inside the gateway via our message actions
+        // (handleAction). Declaring deliveryMode "gateway" makes the shared
+        // message tool treat this channel as send-capable.
+        deliveryMode: "gateway",
+    },
+});

package/dist/src/inbound.js

@@ -0,0 +1,280 @@
+import { createChannelMessageReplyPipeline } from "openclaw/plugin-sdk/channel-outbound";
+import { sendText, phoneFromSpaceId, normalizePhone } from "./spectrum.js";
+import { resolveAccount } from "./channel.js";
+const CHANNEL = "imessage-photon";
+const AGENT_ID = "main";
+function senderPhone(space, message) {
+    const sender = message.sender?.id;
+    return normalizePhone(sender) ?? phoneFromSpaceId(space.id);
+}
+function isAllowed(space, message, allowFrom) {
+    if (allowFrom.length === 0)
+        return true;
+    const phone = senderPhone(space, message);
+    return Boolean(phone && allowFrom.includes(phone));
+}
+/** Handle one inbound Spectrum message: text -> agent turn, reaction -> tapback. */
+export async function handleInbound(runtime, cfg, space, message, log) {
+    const account = resolveAccount(cfg);
+    if (!isAllowed(space, message, account.allowFrom)) {
+        log?.(`[imessage-photon] blocked (not allowlisted): ${space.id}`);
+        return;
+    }
+    if (message.content.type === "text") {
+        await dispatchText(runtime, cfg, space, message, account, log);
+    }
+    else if (message.content.type === "reaction") {
+        await dispatchTapback(runtime, cfg, space, message, account, log);
+    }
+    else if (message.content.type === "voice" || message.content.type === "attachment") {
+        await dispatchMedia(runtime, cfg, space, message, account, log);
+    }
+    else if (message.content.type === "reply") {
+        await dispatchReply(runtime, cfg, space, message, account, log);
+    }
+    else if (message.content.type === "poll" || message.content.type === "poll_option") {
+        await dispatchPollEvent(runtime, cfg, space, message, account, log);
+    }
+    else if (message.content.type === "edit" || message.content.type === "unsend") {
+        // Agent-facing edit/unsend handling is opt-in (enableEditUnsend);
+        // until then, these are system events: log only.
+        log?.(`[imessage-photon] system event type=${message.content.type} from ${space.id}`);
+    }
+    else {
+        // System events (read, typing, contact, group ops, rename, ...) and any
+        // unknown types are logged, never silently dropped.
+        log?.(`[imessage-photon] system event type=${message.content.type} from ${space.id}`);
+    }
+}
+/** Shared turn dispatch: build session route + context, then run the agent. */
+async function runAgentTurn(runtime, cfg, space, message, account, log, opts) {
+    const phone = senderPhone(space, message) ?? space.id;
+    const senderName = message.sender?.name;
+    // Read receipt: mark the conversation read (iMessage marks the whole chat).
+    if (account.enableReadReceipts) {
+        message.read().catch((err) => log?.(`[imessage-photon] read receipt failed: ${String(err)}`));
+    }
+    // Typing indicator while the agent processes.
+    const stopTyping = async () => {
+        if (account.enableTyping) {
+            space.stopTyping().catch((err) => log?.(`[imessage-photon] stopTyping failed: ${String(err)}`));
+        }
+    };
+    if (account.enableTyping) {
+        space.startTyping().catch((err) => log?.(`[imessage-photon] startTyping failed: ${String(err)}`));
+    }
+    // Seen-ack: native ack-reaction handle; removed after the reply is delivered.
+    const ackReaction = opts.ackEnabled === false
+        ? ""
+        : account.ackReaction ||
+            cfg.messages?.ackReaction ||
+            "";
+    let ackReactionMsg;
+    let ackHandle = null;
+    if (ackReaction) {
+        ackHandle = runtime.reactions.createAckReactionHandle({
+            ackReactionValue: ackReaction,
+            send: async () => {
+                ackReactionMsg = await message.react(ackReaction);
+                if (!ackReactionMsg)
+                    throw new Error("platform did not accept ack reaction");
+            },
+            remove: async () => {
+                await ackReactionMsg?.unsend();
+            },
+            onSendError: (err) => log?.(`[imessage-photon] ack send failed: ${String(err)}`),
+        });
+    }
+    const replyPipeline = createChannelMessageReplyPipeline({
+        cfg,
+        agentId: AGENT_ID,
+        channel: CHANNEL,
+    });
+    await runtime.inbound.run({
+        channel: CHANNEL,
+        raw: message,
+        adapter: {
+            ingest: (raw) => ({
+                id: opts.messageId,
+                timestamp: opts.timestamp,
+                rawText: opts.rawText,
+                textForAgent: opts.textForAgent,
+                raw,
+            }),
+            resolveTurn: async (input) => {
+                const routeSessionKey = runtime.routing.buildAgentSessionKey({
+                    agentId: AGENT_ID,
+                    channel: CHANNEL,
+                    peer: { kind: "direct", id: phone },
+                });
+                const storePath = runtime.session.resolveStorePath(cfg.session?.store, {
+                    agentId: AGENT_ID,
+                });
+                const ctxPayload = await runtime.inbound.buildContext({
+                    channel: CHANNEL,
+                    from: phone,
+                    sender: { id: phone, name: senderName },
+                    conversation: { kind: "direct", id: space.id },
+                    route: { agentId: AGENT_ID, routeSessionKey },
+                    reply: { to: phone, sourceReplyDeliveryMode: "reply" },
+                    message: { rawBody: opts.rawText, bodyForAgent: opts.textForAgent },
+                    media: opts.media,
+                    timestamp: opts.timestamp,
+                    messageId: opts.messageId,
+                });
+                return {
+                    channel: CHANNEL,
+                    routeSessionKey,
+                    storePath,
+                    ctxPayload,
+                    recordInboundSession: runtime.session.recordInboundSession,
+                    runDispatch: () => runtime.reply.dispatchReplyWithBufferedBlockDispatcher({
+                        ctx: ctxPayload,
+                        cfg,
+                        dispatcherOptions: {
+                            ...replyPipeline,
+                            deliver: async (payload) => {
+                                if (payload.text) {
+                                    await sendText(space, payload.text);
+                                }
+                                await stopTyping();
+                                // Reply delivered: remove the seen-ack reaction.
+                                if (ackHandle) {
+                                    runtime.reactions.removeAckReactionHandleAfterReply({
+                                        removeAfterReply: true,
+                                        ackReaction: ackHandle,
+                                        onError: (err) => log?.(`[imessage-photon] ack remove failed: ${String(err)}`),
+                                    });
+                                }
+                            },
+                        },
+                    }),
+                };
+            },
+        },
+    });
+}
+/** Inbound text message -> agent turn. */
+async function dispatchText(runtime, cfg, space, message, account, log) {
+    if (message.content.type !== "text")
+        return;
+    const text = message.content.text;
+    log?.(`[imessage-photon] ${space.id} -> agent: ${text.slice(0, 120)}`);
+    await runAgentTurn(runtime, cfg, space, message, account, log, {
+        rawText: text,
+        messageId: message.id,
+        timestamp: message.timestamp?.getTime(),
+    });
+}
+/** Inbound tapback (reaction) -> forwarded to the agent as a system event. */
+async function dispatchTapback(runtime, cfg, space, message, account, log) {
+    if (account.tapbackNotifications === "off") {
+        log?.(`[imessage-photon] tapback ignored (notifications=off): ${space.id}`);
+        return;
+    }
+    const c = message.content;
+    const emoji = c.emoji ?? c.kind ?? "?";
+    const targetText = c.target?.content?.text ?? c.targetGuid ?? "上一条消息";
+    const hint = `[Tapback] 用户对你发的消息「${targetText}」点了 ${emoji}。请回复一句简短的回应（可选）。`;
+    log?.(`[imessage-photon] tapback ${emoji} from ${space.id}`);
+    await runAgentTurn(runtime, cfg, space, message, account, log, {
+        rawText: hint,
+        textForAgent: hint,
+        messageId: message.id,
+        timestamp: message.timestamp?.getTime(),
+        ackEnabled: false,
+    });
+}
+/** Inbound media (voice / attachment) -> saved to the media store, then the agent is told where it landed. */
+async function dispatchMedia(runtime, cfg, space, message, account, log) {
+    const c = message.content;
+    const kind = c.type === "voice" ? "语音" : "媒体";
+    const mime = c.mimeType ?? "application/octet-stream";
+    const name = c.name ?? (c.type === "voice" ? "voice.m4a" : "attachment.bin");
+    try {
+        if (typeof c.read !== "function") {
+            log?.(`[imessage-photon] inbound ${kind} has no read(): ${space.id}`);
+            return;
+        }
+        const buf = await c.read();
+        const saved = await runtime.media.saveMediaBuffer(buf, mime, "inbound", undefined, name);
+        const mediaKind = c.type === "voice" ? "audio" : "image";
+        const hint = `[iMessage] 用户发来一条${kind}消息（已保存到 media store）。请查看内容并回应。`;
+        log?.(`[imessage-photon] inbound ${kind} saved to ${saved.path} (mediaKind=${mediaKind})`);
+        await runAgentTurn(runtime, cfg, space, message, account, log, {
+            rawText: hint,
+            textForAgent: hint,
+            messageId: message.id,
+            timestamp: message.timestamp?.getTime(),
+            ackEnabled: false,
+            media: [
+                {
+                    path: saved.path,
+                    contentType: mime,
+                    kind: mediaKind,
+                    messageId: message.id,
+                },
+            ],
+        });
+    }
+    catch (err) {
+        log?.(`[imessage-photon] inbound ${kind} handling failed: ${String(err)}`);
+    }
+}
+/** Inbound reply (quoted message) -> forward the inner text to the agent. */
+async function dispatchReply(runtime, cfg, space, message, account, log) {
+    const c = message.content;
+    const inner = c.content;
+    const innerType = inner?.type ?? "unknown";
+    if (innerType === "attachment" || innerType === "voice") {
+        // The quoted media isn't directly readable here; tell the agent about it.
+        const hint = `[iMessage] 用户引用了一条${innerType === "voice" ? "语音" : "媒体"}消息回复。请回应一句简短确认。`;
+        await runAgentTurn(runtime, cfg, space, message, account, log, {
+            rawText: hint,
+            textForAgent: hint,
+            messageId: message.id,
+            timestamp: message.timestamp?.getTime(),
+            ackEnabled: false,
+        });
+        return;
+    }
+    const text = inner?.type === "markdown" ? inner.markdown : inner?.text;
+    const quoted = c.target?.content && c.target.content.type !== "reaction"
+        ? c.target.content.text ??
+            c.target.content.markdown ??
+            ""
+        : "";
+    if (!text) {
+        log?.(`[imessage-photon] reply with empty inner text (type=${innerType})`);
+        return;
+    }
+    const prompt = quoted
+        ? `[iMessage 引用回复] 用户引用了你的消息「${quoted.slice(0, 200)}」并回复：${text}`
+        : `[iMessage 引用回复] ${text}`;
+    log?.(`[imessage-photon] reply -> agent: ${prompt.slice(0, 120)}`);
+    await runAgentTurn(runtime, cfg, space, message, account, log, {
+        rawText: prompt,
+        textForAgent: prompt,
+        messageId: message.id,
+        timestamp: message.timestamp?.getTime(),
+    });
+}
+/** Inbound poll event (user voting / poll appearance) -> notify the agent. */
+async function dispatchPollEvent(runtime, cfg, space, message, account, log) {
+    const c = message.content;
+    let hint;
+    if (c.type === "poll_option" && c.option?.title) {
+        const pollTitle = c.poll?.title ?? c.title ?? "某投票";
+        hint = `[iMessage 投票] 用户在投票「${pollTitle}」中选择了「${c.option.title}」。需要时可以简短确认或继续对话。`;
+    }
+    else {
+        hint = `[iMessage 投票] ${c.title ?? "用户发起/更新了一个投票"}${c.options?.length ? `（选项：${c.options.map((o) => o.title).join(" / ")}）` : ""}`;
+    }
+    await runAgentTurn(runtime, cfg, space, message, account, log, {
+        rawText: hint,
+        textForAgent: hint,
+        messageId: message.id,
+        timestamp: message.timestamp?.getTime(),
+        ackEnabled: false,
+    });
+}

package/dist/src/spectrum.js

@@ -0,0 +1,92 @@
+import { Spectrum } from "spectrum-ts";
+import { imessage } from "@spectrum-ts/imessage";
+let app = null;
+// Known spaces keyed by normalized phone (E.164 with +). Populated from the
+// inbound message stream so outbound actions (message tool) can resolve a
+// target phone to a live Space.
+const spacesByPhone = new Map();
+// Recent messages keyed by id, so actions like react/edit/unsend/reply can
+// target a specific message.
+const messagesById = new Map();
+const MAX_CACHED_MESSAGES = 500;
+/** Record a space observed on the inbound stream. */
+export function rememberSpace(space) {
+    const phone = normalizePhone(phoneFromSpaceId(space.id));
+    if (phone)
+        spacesByPhone.set(phone, space);
+}
+/** Record a message observed on the inbound stream (for target resolution). */
+export function rememberMessage(message) {
+    if (!message.id)
+        return;
+    messagesById.set(message.id, message);
+    if (messagesById.size > MAX_CACHED_MESSAGES) {
+        const oldest = messagesById.keys().next().value;
+        if (oldest !== undefined)
+            messagesById.delete(oldest);
+    }
+}
+/** Resolve a cached Message by id (for react/edit/unsend/reply targets). */
+export function resolveMessage(id) {
+    if (!id)
+        return undefined;
+    return messagesById.get(id);
+}
+/** Resolve a Space for an outbound target (phone number). */
+export function resolveSpace(target) {
+    const phone = normalizePhone(target);
+    if (!phone)
+        return undefined;
+    return spacesByPhone.get(phone);
+}
+/** Number of known spaces (used in diagnostics). */
+export function knownSpaceCount() {
+    return spacesByPhone.size;
+}
+/** Connect to Photon Spectrum Cloud. Reuses an existing connection. */
+export async function connectSpectrum(projectId, projectSecret) {
+    if (app)
+        return app;
+    app = await Spectrum({
+        projectId,
+        projectSecret,
+        providers: [imessage.config()],
+    });
+    return app;
+}
+/** Close the current connection and clear it so the next connect re-creates it. */
+export async function resetSpectrum() {
+    const current = app;
+    app = null;
+    if (current) {
+        try {
+            await current.stop();
+        }
+        catch {
+            // best-effort teardown
+        }
+    }
+}
+/** Send a plain-text reply to a space (iMessage DM). */
+export async function sendText(space, text) {
+    await space.send(text);
+}
+/** React to a message (iMessage tapback). New reactions replace the old one. */
+export async function reactTo(message, emoji) {
+    const ok = await message.react(emoji);
+    return Boolean(ok);
+}
+/** Extract the E.164 phone number from an iMessage space id like "any;-;+8613800138000". */
+export function phoneFromSpaceId(spaceId) {
+    const m = spaceId.match(/\+?\d{6,15}$/);
+    return m ? m[0] : undefined;
+}
+/** Normalize a phone candidate to E.164 with leading "+". */
+export function normalizePhone(raw) {
+    if (!raw)
+        return undefined;
+    const digits = raw.replace(/[^\d]/g, "");
+    if (!digits)
+        return undefined;
+    return `+${digits}`;
+}