@pylonsync/create-pylon 0.19.1 → 0.20.0

package/templates/imessage/lib/transport.ts

@@ -0,0 +1,135 @@
+// The one interface both iMessage transports implement. Server code talks to a
+// `MessageTransport`; which adapter it gets depends on IMESSAGE_TRANSPORT.
+//
+//   sendblue  Sendblue's hosted iMessage API. Inbound: signed webhook to
+//             /api/webhooks/sendblueWebhook. Outbound: their REST API.
+//   relay     A Bun script on an always-on Mac (relay/). Inbound: the relay
+//             reads ~/Library/Messages/chat.db and posts new rows to
+//             /api/fn/relaySync. Outbound: replies wait in the Message table
+//             until the relay's next sync picks them up and sends them with
+//             Messages.app.
+
+import { normalizeHandle } from "./handles";
+
+export type TransportName = "sendblue" | "relay";
+
+/** A message a transport received, in the app's shape. */
+export interface InboundMessage {
+  /** The transport's own message id. Webhooks retry, so this is the dedupe key. */
+  externalId: string;
+  /** Normalized sender handle (E.164 phone or lowercase email). */
+  handle: string;
+  text: string;
+  /** ISO-8601 time the sender sent it. */
+  sentAt: string;
+  /** "iMessage" | "SMS" | … as reported by the transport. */
+  service: string;
+}
+
+/** A message the app wants delivered. */
+export interface OutboundMessage {
+  /** Id of the outbound Message row this send belongs to. */
+  messageId: string;
+  to: string;
+  text: string;
+}
+
+export type SendResult =
+  /** The transport accepted the message. */
+  | { status: "sent"; externalId: string | null }
+  /** The message waits for a pull-based transport (the Mac relay) to collect it. */
+  | { status: "queued" }
+  /** IMESSAGE_DRY_RUN is on: nothing left the server. */
+  | { status: "dry_run" }
+  | { status: "failed"; error: string };
+
+export interface MessageTransport {
+  readonly name: TransportName;
+  /** Turn one raw inbound payload into an InboundMessage, or say why it is skipped. */
+  normalizeInbound(payload: unknown): { message: InboundMessage } | { skip: string };
+  send(message: OutboundMessage): Promise<SendResult>;
+}
+
+type Env = Record<string, string | undefined>;
+
+function present(env: Env, key: string): boolean {
+  const v = env[key];
+  return typeof v === "string" && v.trim() !== "";
+}
+
+/** The transport named by IMESSAGE_TRANSPORT, or null when unset or unknown. */
+export function selectedTransport(env: Env): TransportName | null {
+  const v = (env.IMESSAGE_TRANSPORT ?? "").trim().toLowerCase();
+  return v === "sendblue" || v === "relay" ? v : null;
+}
+
+function flag(env: Env, key: string): boolean {
+  const v = (env[key] ?? "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/** `pylon dev` sets PYLON_DEV_MODE=1. */
+export function isDevMode(env: Env): boolean {
+  return flag(env, "PYLON_DEV_MODE");
+}
+
+/**
+ * Whether outbound messages are recorded without being sent. True when
+ * IMESSAGE_DRY_RUN is set, and always in `pylon dev` unless
+ * IMESSAGE_ALLOW_DEV_SENDS=1: a development server is reachable from the local
+ * network and hands out sign-in codes in its responses, so it must not be able
+ * to text real people by default.
+ */
+export function isDryRun(env: Env): boolean {
+  if (flag(env, "IMESSAGE_DRY_RUN")) return true;
+  return isDevMode(env) && !flag(env, "IMESSAGE_ALLOW_DEV_SENDS");
+}
+
+export interface SetupItem {
+  key: string;
+  label: string;
+  ok: boolean;
+  /** One sentence on what to do when `ok` is false. */
+  hint: string;
+}
+
+/** What each transport needs, as a checklist. Reports presence only, never values. */
+export function transportChecklist(env: Env, name: TransportName): SetupItem[] {
+  if (name === "sendblue") {
+    const from = normalizeHandle(env.SENDBLUE_FROM_NUMBER ?? "");
+    return [
+      {
+        key: "SENDBLUE_API_KEY",
+        label: "Sendblue API key id",
+        ok: present(env, "SENDBLUE_API_KEY"),
+        hint: "Copy the API key id from the Sendblue dashboard.",
+      },
+      {
+        key: "SENDBLUE_API_SECRET",
+        label: "Sendblue API secret",
+        ok: present(env, "SENDBLUE_API_SECRET"),
+        hint: "Copy the API secret from the Sendblue dashboard.",
+      },
+      {
+        key: "SENDBLUE_FROM_NUMBER",
+        label: "Sendblue number",
+        ok: from?.kind === "phone",
+        hint: "Your Sendblue line in E.164 form, for example +15125550100.",
+      },
+      {
+        key: "SENDBLUE_WEBHOOK_SECRET",
+        label: "Webhook secret",
+        ok: (env.SENDBLUE_WEBHOOK_SECRET ?? "").trim().length >= 24,
+        hint: "At least 24 random characters. Set the same value as the webhook secret in Sendblue.",
+      },
+    ];
+  }
+  return [
+    {
+      key: "RELAY_TOKEN",
+      label: "Relay token",
+      ok: (env.RELAY_TOKEN ?? "").trim().length >= 24,
+      hint: "At least 24 random characters. The relay on your Mac sends the same value.",
+    },
+  ];
+}

package/templates/imessage/lib/utils.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+// `cn` — the shadcn class merger. clsx resolves conditional/array class
+// inputs; tailwind-merge then dedupes conflicting Tailwind utilities so
+// the last one wins (e.g. `cn("px-2", "px-4")` → "px-4"). Every shadcn
+// component routes its className through this.
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/imessage/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "__APP_NAME_KEBAB__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pylon dev",
+    "deploy": "pylon deploy",
+    "check": "tsc --noEmit",
+    "test": "pylon test",
+    "relay": "bun relay/main.ts"
+  },
+  "dependencies": {
+    "@pylonsync/react": "^__PYLON_VERSION__",
+    "@pylonsync/sdk": "^__PYLON_VERSION__",
+    "@pylonsync/functions": "^__PYLON_VERSION__",
+    "@pylonsync/client": "^__PYLON_VERSION__",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.3.0",
+    "@tailwindcss/cli": "^4.3.0",
+    "tw-animate-css": "^1.2.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.5.0",
+    "lucide-react": "^0.460.0",
+    "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-slot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/imessage/relay/.env.example

@@ -0,0 +1,14 @@
+# Copy to relay/.env on the Mac that runs the relay. Bun loads it automatically
+# when you start the relay from this directory.
+
+# Your app's public origin (https). The relay calls <PYLON_URL>/api/fn/relaySync.
+PYLON_URL=https://your-app.example.com
+
+# Same value as RELAY_TOKEN on the server. Generate with: openssl rand -hex 32
+RELAY_TOKEN=
+
+# Optional
+# CHAT_DB=/Users/you/Library/Messages/chat.db
+# RELAY_STATE=/Users/you/.pylon-imessage-relay/state.json
+# POLL_MS=3000   (minimum 2500)
+# RELAY_DRY_RUN=1

package/templates/imessage/relay/applescript.ts

@@ -0,0 +1,70 @@
+// Send an iMessage through Messages.app with osascript.
+//
+// The message text and the recipient are passed as ARGUMENTS to a fixed
+// AppleScript (`on run argv`), never spliced into script source, so quotes,
+// backslashes, newlines, or AppleScript keywords in a message cannot change
+// what the script does. osascript is spawned directly, without a shell.
+
+import { isNormalizedHandle } from "../lib/handles";
+
+export const SEND_SCRIPT = `on run argv
+  set theHandle to item 2 of argv
+  set theText to item 3 of argv
+  tell application "Messages"
+    set theService to 1st account whose service type = iMessage
+    set theBuddy to participant theHandle of theService
+    send theText to theBuddy
+  end tell
+end run`;
+
+/**
+ * Fixed first argument. osascript stops option parsing at the first
+ * non-option argument, so this keeps a message that starts with "-" from
+ * being read as an osascript flag.
+ */
+export const ARGV_SENTINEL = "pylon-imessage";
+
+export const MAX_SEND_CHARS = 20_000;
+
+export function buildOsascriptArgv(handle: string, text: string): string[] {
+  if (!isNormalizedHandle(handle)) throw new Error("Refusing to send: recipient is not a phone number or email");
+  if (typeof text !== "string" || text.length === 0) throw new Error("Refusing to send an empty message");
+  if (text.length > MAX_SEND_CHARS) throw new Error("Refusing to send: message too long");
+  if (text.includes("\u0000")) throw new Error("Refusing to send: message contains a NUL byte");
+  return ["osascript", "-e", SEND_SCRIPT, ARGV_SENTINEL, handle, text];
+}
+
+export interface SpawnResult {
+  exitCode: number;
+  stderr: string;
+}
+
+export type Spawner = (argv: string[]) => Promise<SpawnResult>;
+
+/** Default spawner: Bun.spawn with an argv array (no shell). */
+export const bunSpawner: Spawner = async (argv) => {
+  const proc = Bun.spawn(argv, { stdout: "ignore", stderr: "pipe", stdin: "ignore" });
+  const timer = setTimeout(() => proc.kill(), 30_000);
+  const [exitCode, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+  clearTimeout(timer);
+  return { exitCode, stderr };
+};
+
+export async function sendIMessage(
+  handle: string,
+  text: string,
+  options: { dryRun: boolean; spawn?: Spawner },
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  let argv: string[];
+  try {
+    argv = buildOsascriptArgv(handle, text);
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+  if (options.dryRun) return { ok: true };
+  const result = await (options.spawn ?? bunSpawner)(argv);
+  if (result.exitCode !== 0) {
+    return { ok: false, error: `osascript exited ${result.exitCode}: ${result.stderr.trim().slice(0, 300)}` };
+  }
+  return { ok: true };
+}

package/templates/imessage/relay/chatdb.ts

@@ -0,0 +1,165 @@
+// Read new messages from macOS Messages' database (~/Library/Messages/chat.db).
+//
+// The database is opened READ-ONLY. Messages.app owns it; this script never
+// writes to it. New rows are found by ROWID watermark: every message row gets
+// a larger ROWID than the ones before it.
+
+import { Database } from "bun:sqlite";
+
+/** Seconds between 1970-01-01 and 2001-01-01 (Apple's reference date). */
+const APPLE_EPOCH_OFFSET_S = 978_307_200;
+
+export interface ChatDbMessage {
+  rowId: number;
+  guid: string;
+  handle: string;
+  text: string;
+  sentAt: string;
+  service: string;
+  /** Set when the row belongs to a group chat; the relay skips those. */
+  isGroup: boolean;
+}
+
+export function openChatDb(path: string): Database {
+  return new Database(path, { readonly: true });
+}
+
+/** message.date: nanoseconds since 2001 on macOS 10.13+, seconds before that. */
+export function appleDateToIso(value: number | bigint | null): string {
+  if (value === null || value === undefined) return new Date().toISOString();
+  const n = Number(value);
+  if (!Number.isFinite(n) || n === 0) return new Date().toISOString();
+  const seconds = n > 1e12 ? n / 1e9 : n;
+  return new Date((seconds + APPLE_EPOCH_OFFSET_S) * 1000).toISOString();
+}
+
+/**
+ * Pull the plain text out of `message.attributedBody`, an NSAttributedString
+ * archived with NSArchiver (typedstream). Since macOS 13 many rows have a
+ * null `text` column and carry the text only here.
+ *
+ * Layout around the string: the class name "NSString", five bytes of
+ * typedstream framing ending in 0x2B ('+'), then a length and the UTF-8
+ * bytes. The length is one byte, or 0x81 followed by a little-endian uint16,
+ * or 0x82 followed by a little-endian uint32.
+ */
+export function decodeAttributedBody(blob: Uint8Array | null | undefined): string | null {
+  if (!blob || blob.length === 0) return null;
+  const bytes = blob instanceof Uint8Array ? blob : new Uint8Array(blob);
+  const marker = new TextEncoder().encode("NSString");
+  const start = indexOf(bytes, marker);
+  if (start === -1) return null;
+  let i = start + marker.length;
+  // Find the '+' that introduces the string payload within the framing bytes.
+  const plus = bytes.indexOf(0x2b, i);
+  if (plus === -1 || plus - i > 8) return null;
+  i = plus + 1;
+  if (i >= bytes.length) return null;
+  let length = bytes[i];
+  i += 1;
+  if (length === 0x81) {
+    if (i + 2 > bytes.length) return null;
+    length = bytes[i] | (bytes[i + 1] << 8);
+    i += 2;
+  } else if (length === 0x82) {
+    if (i + 4 > bytes.length) return null;
+    length = (bytes[i] | (bytes[i + 1] << 8) | (bytes[i + 2] << 16) | (bytes[i + 3] << 24)) >>> 0;
+    i += 4;
+  }
+  if (length === 0 || i + length > bytes.length) return null;
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(i, i + length));
+  return text.replace(//g, "").trim() || null;
+}
+
+function indexOf(haystack: Uint8Array, needle: Uint8Array): number {
+  outer: for (let i = 0; i <= haystack.length - needle.length; i++) {
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}
+
+/** The newest ROWID, used as the starting watermark so old history is never replayed. */
+export function latestRowId(db: Database): number {
+  const row = db.query("SELECT COALESCE(MAX(ROWID), 0) AS max FROM message").get() as { max: number };
+  return Number(row.max) || 0;
+}
+
+interface RawRow {
+  rowId: number;
+  guid: string;
+  text: string | null;
+  attributedBody: Uint8Array | null;
+  date: number | bigint | null;
+  service: string | null;
+  handle: string | null;
+  chatStyle: number | null;
+  participants: number | null;
+}
+
+/**
+ * Inbound messages after `afterRowId`, oldest first. Skips the owner's own
+ * sent messages, tapbacks and other reactions (associated_message_type != 0),
+ * and rows with no sender handle. Group-chat rows are returned with
+ * `isGroup: true` so the caller can advance past them.
+ */
+export function readNewMessages(db: Database, afterRowId: number, limit = 100): ChatDbMessage[] {
+  const rows = db
+    .query(
+      `SELECT m.ROWID AS rowId, m.guid AS guid, m.text AS text, m.attributedBody AS attributedBody,
+              m.date AS date, m.service AS service, h.id AS handle,
+              c.style AS chatStyle,
+              (SELECT COUNT(*) FROM chat_handle_join chj WHERE chj.chat_id = c.ROWID) AS participants
+         FROM message m
+         LEFT JOIN handle h ON h.ROWID = m.handle_id
+         LEFT JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+         LEFT JOIN chat c ON c.ROWID = cmj.chat_id
+        WHERE m.ROWID > ?1
+          AND m.is_from_me = 0
+          AND COALESCE(m.associated_message_type, 0) = 0
+        GROUP BY m.ROWID
+        ORDER BY m.ROWID ASC
+        LIMIT ?2`,
+    )
+    .all(afterRowId, limit) as RawRow[];
+
+  const out: ChatDbMessage[] = [];
+  for (const r of rows) {
+    const text = r.text && r.text.trim() !== "" ? r.text : decodeAttributedBody(r.attributedBody);
+    out.push({
+      rowId: Number(r.rowId),
+      guid: String(r.guid),
+      handle: r.handle ?? "",
+      text: (text ?? "").replace(//g, "").trim(),
+      sentAt: appleDateToIso(r.date),
+      service: r.service ?? "iMessage",
+      // chat.style 43 is a group chat, 45 a one-to-one chat.
+      isGroup: r.chatStyle === 43 || Number(r.participants ?? 0) > 1,
+    });
+  }
+  return out;
+}
+
+/**
+ * The new watermark after a sync. Walks the batch in ROWID order and stops at
+ * the first message that was sent to the server but not accepted, so that
+ * message is read again next time. Rows the relay skipped (group chats,
+ * reactions without text) are passed over.
+ */
+export function advanceWatermark(
+  current: number,
+  rows: { rowId: number; guid: string }[],
+  sent: { guid: string }[],
+  accepted: string[],
+): number {
+  const sentGuids = new Set(sent.map((m) => m.guid));
+  const acceptedGuids = new Set(accepted);
+  let watermark = current;
+  for (const r of rows) {
+    if (sentGuids.has(r.guid) && !acceptedGuids.has(r.guid)) break;
+    if (r.rowId > watermark) watermark = r.rowId;
+  }
+  return watermark;
+}

package/templates/imessage/relay/client.ts

@@ -0,0 +1,41 @@
+// HTTP client for the server's relaySync endpoint.
+
+import type { RelaySyncRequest, RelaySyncResponse } from "../lib/relay-protocol";
+
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+export class RelayHttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export async function relaySync(
+  serverUrl: string,
+  token: string,
+  body: RelaySyncRequest,
+  fetchImpl: FetchLike = fetch,
+): Promise<RelaySyncResponse> {
+  const url = new URL("/api/fn/relaySync", serverUrl);
+  const res = await fetchImpl(url.toString(), {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+  const json = (await res.json().catch(() => null)) as
+    | (RelaySyncResponse & { error?: { code?: string; message?: string } })
+    | null;
+  if (!res.ok || !json || json.error) {
+    const code = json?.error?.code ?? `HTTP_${res.status}`;
+    throw new RelayHttpError(res.status, code, json?.error?.message ?? `relaySync failed with HTTP ${res.status}`);
+  }
+  return {
+    accepted: Array.isArray(json.accepted) ? json.accepted.map(String) : [],
+    outbound: Array.isArray(json.outbound) ? json.outbound : [],
+  };
+}

package/templates/imessage/relay/main.ts

@@ -0,0 +1,137 @@
+// iMessage relay for a Mac that stays on. Run with `bun relay/main.ts` (or
+// `bun run relay` from the project root). See the README's "Mac relay" section
+// for the Full Disk Access and Automation permissions it needs.
+//
+// Every POLL_MS it:
+//   1. reads chat.db rows newer than its watermark (read-only),
+//   2. sends them to the server along with acks for replies it sent,
+//   3. advances the watermark past the rows the server accepted,
+//   4. sends the replies the server handed back, through Messages.app.
+//
+// Configuration (environment, or relay/.env which Bun loads automatically):
+//   PYLON_URL       your app's origin, e.g. https://assistant.example.com
+//   RELAY_TOKEN     same value as RELAY_TOKEN on the server
+//   CHAT_DB         default ~/Library/Messages/chat.db
+//   RELAY_STATE     default ~/.pylon-imessage-relay/state.json
+//   POLL_MS         default 3000, minimum 2500 (the server allows 30 syncs a minute)
+//   RELAY_DRY_RUN   1 to log replies instead of sending them
+
+import { hostname, homedir } from "node:os";
+import { join } from "node:path";
+import { normalizeHandle } from "../lib/handles";
+import { MAX_INBOUND_PER_SYNC, type RelayAck, type RelayInboundItem } from "../lib/relay-protocol";
+import { sendIMessage } from "./applescript";
+import { advanceWatermark, latestRowId, openChatDb, readNewMessages } from "./chatdb";
+import { RelayHttpError, relaySync } from "./client";
+import { loadState, saveState, type RelayState } from "./state";
+
+const VERSION = "1.0.0";
+
+function config() {
+  const serverUrl = (process.env.PYLON_URL ?? "").trim();
+  const token = (process.env.RELAY_TOKEN ?? "").trim();
+  if (!/^https?:\/\//.test(serverUrl)) throw new Error("Set PYLON_URL to your app's origin, e.g. https://assistant.example.com");
+  if (serverUrl.startsWith("http://") && !/^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(serverUrl)) {
+    throw new Error("PYLON_URL must use https:// (http:// is allowed only for localhost)");
+  }
+  if (token.length < 24) throw new Error("Set RELAY_TOKEN (at least 24 characters, same value as the server)");
+  return {
+    serverUrl,
+    token,
+    chatDb: process.env.CHAT_DB || join(homedir(), "Library", "Messages", "chat.db"),
+    statePath: process.env.RELAY_STATE || join(homedir(), ".pylon-imessage-relay", "state.json"),
+    pollMs: Math.max(2500, Number(process.env.POLL_MS) || 3000),
+    dryRun: ["1", "true", "yes"].includes((process.env.RELAY_DRY_RUN ?? "").toLowerCase()),
+  };
+}
+
+const log = (msg: string) => console.log(`[relay ${new Date().toISOString()}] ${msg}`);
+
+async function main() {
+  const cfg = config();
+  let db;
+  try {
+    db = openChatDb(cfg.chatDb);
+  } catch (err) {
+    throw new Error(
+      `Cannot open ${cfg.chatDb}. Grant Full Disk Access to the app running this script (see README). ${err instanceof Error ? err.message : err}`,
+    );
+  }
+
+  let state: RelayState = loadState(cfg.statePath) ?? { lastRowId: latestRowId(db), sentUnacked: [] };
+  saveState(cfg.statePath, state);
+  log(`started v${VERSION}; watermark ROWID ${state.lastRowId}${cfg.dryRun ? "; dry run, replies are not sent" : ""}`);
+
+  // Acks for replies sent in a previous loop (or before a restart).
+  let acks: RelayAck[] = state.sentUnacked.map((id) => ({ id, ok: true, dryRun: cfg.dryRun }));
+  let stopping = false;
+  process.on("SIGINT", () => (stopping = true));
+  process.on("SIGTERM", () => (stopping = true));
+
+  while (!stopping) {
+    try {
+      const rows = readNewMessages(db, state.lastRowId, MAX_INBOUND_PER_SYNC);
+      const inbound: RelayInboundItem[] = [];
+      for (const r of rows) {
+        const handle = normalizeHandle(r.handle)?.handle;
+        if (r.isGroup || !handle || r.text === "") continue;
+        inbound.push({ guid: r.guid, handle, text: r.text, sentAt: r.sentAt, service: r.service });
+      }
+
+      const res = await relaySync(cfg.serverUrl, cfg.token, {
+        relayVersion: VERSION,
+        host: hostname().slice(0, 64),
+        inbound,
+        acks,
+      });
+
+      // The server stored the acks; forget them.
+      const ackedIds = new Set(acks.map((a) => a.id));
+      state = { ...state, sentUnacked: state.sentUnacked.filter((id) => !ackedIds.has(id)) };
+      acks = [];
+
+      state = { ...state, lastRowId: advanceWatermark(state.lastRowId, rows, inbound, res.accepted) };
+      saveState(cfg.statePath, state);
+      if (inbound.length > 0) log(`delivered ${inbound.length} inbound message(s)`);
+
+      for (const item of res.outbound) {
+        if (state.sentUnacked.includes(item.id)) {
+          acks.push({ id: item.id, ok: true, dryRun: cfg.dryRun });
+          continue;
+        }
+        const handle = normalizeHandle(item.handle)?.handle;
+        const result = handle
+          ? await sendIMessage(handle, item.text, { dryRun: cfg.dryRun })
+          : ({ ok: false, error: "invalid recipient" } as const);
+        if (result.ok) {
+          // Persist before acking so a crash here never sends twice.
+          state = { ...state, sentUnacked: [...state.sentUnacked, item.id] };
+          saveState(cfg.statePath, state);
+          acks.push({ id: item.id, ok: true, dryRun: cfg.dryRun });
+        } else {
+          acks.push({ id: item.id, ok: false, error: result.error });
+          log(`send failed: ${result.error}`);
+        }
+      }
+      if (res.outbound.length > 0) log(`${cfg.dryRun ? "dry run: skipped" : "sent"} ${res.outbound.length} repl${res.outbound.length === 1 ? "y" : "ies"}`);
+    } catch (err) {
+      if (err instanceof RelayHttpError && (err.code === "UNAUTHORIZED" || err.code === "NOT_CONFIGURED")) {
+        log(`server rejected the relay (${err.code}). Check RELAY_TOKEN on both sides.`);
+      } else if (err instanceof RelayHttpError && err.code === "TRANSPORT_DISABLED") {
+        log("server is not using the relay transport. Set IMESSAGE_TRANSPORT=relay on the server.");
+      } else {
+        log(`sync failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    await Bun.sleep(cfg.pollMs);
+  }
+  db.close();
+  log("stopped");
+}
+
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error(`[relay] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  });
+}

package/templates/imessage/relay/state.ts

@@ -0,0 +1,35 @@
+// The relay's small on-disk state: the chat.db ROWID watermark and the ids of
+// replies it already sent but has not had acknowledged yet. Written with a
+// temp file + rename, so a crash mid-write leaves the previous state intact.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface RelayState {
+  /** Highest chat.db ROWID the server has accepted. */
+  lastRowId: number;
+  /** Replies sent through Messages.app whose ack the server has not received. */
+  sentUnacked: string[];
+}
+
+export function loadState(path: string): RelayState | null {
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<RelayState>;
+    const lastRowId = Number(raw.lastRowId);
+    if (!Number.isFinite(lastRowId) || lastRowId < 0) return null;
+    return {
+      lastRowId,
+      sentUnacked: Array.isArray(raw.sentUnacked) ? raw.sentUnacked.filter((s) => typeof s === "string") : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveState(path: string, state: RelayState): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+  renameSync(tmp, path);
+}