easy-ping 0.6.1 → 0.8.0

package/dist/providers/expo-push.cjs

@@ -0,0 +1,114 @@
+'use strict';
+
+// src/providers/expo-push/index.ts
+var isExpoPushToken = (token) => /^Expo(nent)?PushToken\[[A-Za-z0-9_-]{8,}\]$/.test(token);
+var EXPO_SEND_BATCH = 100;
+var EXPO_RECEIPT_BATCH = 1e3;
+var GONE = /* @__PURE__ */ new Set(["DeviceNotRegistered"]);
+var RETRYABLE = /* @__PURE__ */ new Set(["MessageRateExceeded", "ProviderError", "ExpoError"]);
+var classify = (code, message) => ({
+  error: code ? `${code}: ${message ?? ""}`.trim() : message ?? "expo push failed",
+  gone: code !== void 0 && GONE.has(code),
+  retryable: code !== void 0 && RETRYABLE.has(code)
+});
+function expoPush(options = {}) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = (options.apiBase ?? "https://exp.host").replace(/\/$/, "");
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const redact = (text) => options.accessToken ? text.split(options.accessToken).join("<token>") : text;
+  async function post(path, body, signal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const headers = {
+      accept: "application/json",
+      "content-type": "application/json"
+    };
+    if (options.accessToken) headers.authorization = `Bearer ${options.accessToken}`;
+    const response = await doFetch(`${base}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+    });
+    if (!response.ok) {
+      const text = redact((await response.text().catch(() => "")).slice(0, 200));
+      const error = new Error(`expo push ${path} failed: HTTP ${response.status} ${text}`.trim());
+      error.status = response.status;
+      throw error;
+    }
+    return await response.json();
+  }
+  const transportFailure = (error) => {
+    const status = error?.status;
+    const message = redact(error instanceof Error ? error.message : String(error));
+    const retryable = status === void 0 || status === 429 || status >= 500;
+    return { ok: false, error: message, gone: false, retryable };
+  };
+  return {
+    name: "expo-push",
+    isValidToken: isExpoPushToken,
+    async send(messages, signal) {
+      const results = [];
+      for (let start = 0; start < messages.length; start += EXPO_SEND_BATCH) {
+        const batch = messages.slice(start, start + EXPO_SEND_BATCH);
+        let tickets;
+        try {
+          const response = await post(
+            "/--/api/v2/push/send",
+            batch.map((message) => ({
+              to: message.token,
+              title: message.title,
+              body: message.body,
+              ...message.data ? { data: message.data } : {},
+              ...message.badge === void 0 ? {} : { badge: message.badge },
+              ...message.sound === void 0 ? { sound: "default" } : { sound: message.sound },
+              ...message.channelId ? { channelId: message.channelId } : {}
+            })),
+            signal
+          );
+          tickets = response.data;
+        } catch (error) {
+          const failure = transportFailure(error);
+          for (const _ of batch) results.push(failure);
+          continue;
+        }
+        batch.forEach((_, index) => {
+          const ticket = tickets[index];
+          if (!ticket) {
+            results.push({ ok: false, error: "no ticket returned", gone: false, retryable: true });
+          } else if (ticket.status === "ok") {
+            results.push({ ok: true, ticketId: ticket.id ?? null });
+          } else {
+            results.push({ ok: false, ...classify(ticket.details?.error, ticket.message) });
+          }
+        });
+      }
+      return results;
+    },
+    async receipts(ticketIds, signal) {
+      const out = [];
+      for (let start = 0; start < ticketIds.length; start += EXPO_RECEIPT_BATCH) {
+        const ids = ticketIds.slice(start, start + EXPO_RECEIPT_BATCH);
+        const response = await post(
+          "/--/api/v2/push/getReceipts",
+          { ids },
+          signal
+        );
+        for (const [ticketId, receipt] of Object.entries(response.data ?? {})) {
+          if (receipt.status === "ok") out.push({ ticketId, ok: true });
+          else {
+            const { error, gone } = classify(receipt.details?.error, receipt.message);
+            out.push({ ticketId, ok: false, error, gone });
+          }
+        }
+      }
+      return out;
+    }
+  };
+}
+
+exports.EXPO_RECEIPT_BATCH = EXPO_RECEIPT_BATCH;
+exports.EXPO_SEND_BATCH = EXPO_SEND_BATCH;
+exports.expoPush = expoPush;
+exports.isExpoPushToken = isExpoPushToken;
+//# sourceMappingURL=expo-push.cjs.map
+//# sourceMappingURL=expo-push.cjs.map

package/dist/providers/expo-push.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/providers/expo-push/index.ts"],"names":[],"mappings":"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","file":"expo-push.cjs","sourcesContent":["export type MobilePushMessage = {\n  /** The device's push token as the app registered it. */\n  token: string;\n  title: string;\n  body: string;\n  data?: Record<string, unknown> | undefined;\n  badge?: number | undefined;\n  /** \"default\" plays the platform sound; null is silent. */\n  sound?: \"default\" | null | undefined;\n  /** Android notification channel id. */\n  channelId?: string | undefined;\n};\n\nexport type MobilePushTicket =\n  | { ok: true; ticketId: string | null }\n  | {\n      ok: false;\n      error: string;\n      /** The token will never work again (app uninstalled, token rotated). Prune it. */\n      gone: boolean;\n      retryable: boolean;\n    };\n\nexport type MobilePushReceipt =\n  | { ticketId: string; ok: true }\n  | { ticketId: string; ok: false; error: string; gone: boolean };\n\nexport type MobilePushProvider = {\n  name: string;\n  /** True for a token this provider can deliver to. Rejected at registration otherwise. */\n  isValidToken(token: string): boolean;\n  /** One result per message, in order. Never throws for a per-token failure. */\n  send(messages: readonly MobilePushMessage[], signal?: AbortSignal): Promise<MobilePushTicket[]>;\n  /**\n   * Some services (Expo) accept a message, then learn from APNs/FCM later\n   * that the device is gone. Receipts carry that late verdict.\n   */\n  receipts?(ticketIds: readonly string[], signal?: AbortSignal): Promise<MobilePushReceipt[]>;\n};\n\nexport type ExpoPushOptions = {\n  /** Expo \"enhanced security\" access token. Optional; when set, requests without it are refused by Expo. */\n  accessToken?: string | undefined;\n  fetch?: typeof globalThis.fetch | undefined;\n  /** Default https://exp.host. A local fake for tests. */\n  apiBase?: string | undefined;\n  timeoutMs?: number | undefined;\n};\n\ntype ExpoTicket =\n  | { status: \"ok\"; id: string }\n  | { status: \"error\"; message?: string; details?: { error?: string } };\n\ntype ExpoReceipt =\n  | { status: \"ok\" }\n  | { status: \"error\"; message?: string; details?: { error?: string } };\n\n/** Expo tokens look like ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx] or ExpoPushToken[...]. */\nexport const isExpoPushToken = (token: string): boolean =>\n  /^Expo(nent)?PushToken\\[[A-Za-z0-9_-]{8,}\\]$/.test(token);\n\n/** Expo's send endpoint takes at most this many messages per request. */\nexport const EXPO_SEND_BATCH = 100;\n/** And its receipts endpoint at most this many ids. */\nexport const EXPO_RECEIPT_BATCH = 1000;\n\n// Expo's error codes, per https://docs.expo.dev/push-notifications/sending-notifications/#individual-errors\nconst GONE = new Set([\"DeviceNotRegistered\"]);\nconst RETRYABLE = new Set([\"MessageRateExceeded\", \"ProviderError\", \"ExpoError\"]);\n\nconst classify = (\n  code: string | undefined,\n  message: string | undefined,\n): { error: string; gone: boolean; retryable: boolean } => ({\n  error: code ? `${code}: ${message ?? \"\"}`.trim() : (message ?? \"expo push failed\"),\n  gone: code !== undefined && GONE.has(code),\n  retryable: code !== undefined && RETRYABLE.has(code),\n});\n\n/** Expo Push over fetch, so it runs on edge runtimes. Batches, classifies, never throws per token. */\nexport function expoPush(options: ExpoPushOptions = {}): MobilePushProvider {\n  const doFetch = options.fetch ?? globalThis.fetch;\n  const base = (options.apiBase ?? \"https://exp.host\").replace(/\\/$/, \"\");\n  const timeoutMs = options.timeoutMs ?? 10_000;\n  const redact = (text: string) =>\n    options.accessToken ? text.split(options.accessToken).join(\"<token>\") : text;\n\n  async function post<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {\n    const timeout = AbortSignal.timeout(timeoutMs);\n    const headers: Record<string, string> = {\n      accept: \"application/json\",\n      \"content-type\": \"application/json\",\n    };\n    if (options.accessToken) headers.authorization = `Bearer ${options.accessToken}`;\n    const response = await doFetch(`${base}${path}`, {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify(body),\n      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,\n    });\n    if (!response.ok) {\n      const text = redact((await response.text().catch(() => \"\")).slice(0, 200));\n      const error = new Error(`expo push ${path} failed: HTTP ${response.status} ${text}`.trim());\n      (error as { status?: number }).status = response.status;\n      throw error;\n    }\n    return (await response.json()) as T;\n  }\n\n  const transportFailure = (error: unknown): MobilePushTicket => {\n    const status = (error as { status?: number })?.status;\n    const message = redact(error instanceof Error ? error.message : String(error));\n    // 4xx from the service itself (bad access token, malformed request) cannot be fixed by retrying.\n    const retryable = status === undefined || status === 429 || status >= 500;\n    return { ok: false, error: message, gone: false, retryable };\n  };\n\n  return {\n    name: \"expo-push\",\n    isValidToken: isExpoPushToken,\n\n    async send(messages, signal) {\n      const results: MobilePushTicket[] = [];\n      for (let start = 0; start < messages.length; start += EXPO_SEND_BATCH) {\n        const batch = messages.slice(start, start + EXPO_SEND_BATCH);\n        let tickets: ExpoTicket[];\n        try {\n          const response = await post<{ data: ExpoTicket[] }>(\n            \"/--/api/v2/push/send\",\n            batch.map((message) => ({\n              to: message.token,\n              title: message.title,\n              body: message.body,\n              ...(message.data ? { data: message.data } : {}),\n              ...(message.badge === undefined ? {} : { badge: message.badge }),\n              ...(message.sound === undefined ? { sound: \"default\" } : { sound: message.sound }),\n              ...(message.channelId ? { channelId: message.channelId } : {}),\n            })),\n            signal,\n          );\n          tickets = response.data;\n        } catch (error) {\n          const failure = transportFailure(error);\n          for (const _ of batch) results.push(failure);\n          continue;\n        }\n        batch.forEach((_, index) => {\n          const ticket = tickets[index];\n          if (!ticket) {\n            results.push({ ok: false, error: \"no ticket returned\", gone: false, retryable: true });\n          } else if (ticket.status === \"ok\") {\n            results.push({ ok: true, ticketId: ticket.id ?? null });\n          } else {\n            results.push({ ok: false, ...classify(ticket.details?.error, ticket.message) });\n          }\n        });\n      }\n      return results;\n    },\n\n    async receipts(ticketIds, signal) {\n      const out: MobilePushReceipt[] = [];\n      for (let start = 0; start < ticketIds.length; start += EXPO_RECEIPT_BATCH) {\n        const ids = ticketIds.slice(start, start + EXPO_RECEIPT_BATCH);\n        const response = await post<{ data: Record<string, ExpoReceipt> }>(\n          \"/--/api/v2/push/getReceipts\",\n          { ids },\n          signal,\n        );\n        for (const [ticketId, receipt] of Object.entries(response.data ?? {})) {\n          if (receipt.status === \"ok\") out.push({ ticketId, ok: true });\n          else {\n            const { error, gone } = classify(receipt.details?.error, receipt.message);\n            out.push({ ticketId, ok: false, error, gone });\n          }\n        }\n      }\n      return out;\n    },\n  };\n}\n"]}

package/dist/providers/expo-push.d.cts

@@ -0,0 +1,61 @@
+type MobilePushMessage = {
+    /** The device's push token as the app registered it. */
+    token: string;
+    title: string;
+    body: string;
+    data?: Record<string, unknown> | undefined;
+    badge?: number | undefined;
+    /** "default" plays the platform sound; null is silent. */
+    sound?: "default" | null | undefined;
+    /** Android notification channel id. */
+    channelId?: string | undefined;
+};
+type MobilePushTicket = {
+    ok: true;
+    ticketId: string | null;
+} | {
+    ok: false;
+    error: string;
+    /** The token will never work again (app uninstalled, token rotated). Prune it. */
+    gone: boolean;
+    retryable: boolean;
+};
+type MobilePushReceipt = {
+    ticketId: string;
+    ok: true;
+} | {
+    ticketId: string;
+    ok: false;
+    error: string;
+    gone: boolean;
+};
+type MobilePushProvider = {
+    name: string;
+    /** True for a token this provider can deliver to. Rejected at registration otherwise. */
+    isValidToken(token: string): boolean;
+    /** One result per message, in order. Never throws for a per-token failure. */
+    send(messages: readonly MobilePushMessage[], signal?: AbortSignal): Promise<MobilePushTicket[]>;
+    /**
+     * Some services (Expo) accept a message, then learn from APNs/FCM later
+     * that the device is gone. Receipts carry that late verdict.
+     */
+    receipts?(ticketIds: readonly string[], signal?: AbortSignal): Promise<MobilePushReceipt[]>;
+};
+type ExpoPushOptions = {
+    /** Expo "enhanced security" access token. Optional; when set, requests without it are refused by Expo. */
+    accessToken?: string | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+    /** Default https://exp.host. A local fake for tests. */
+    apiBase?: string | undefined;
+    timeoutMs?: number | undefined;
+};
+/** Expo tokens look like ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx] or ExpoPushToken[...]. */
+declare const isExpoPushToken: (token: string) => boolean;
+/** Expo's send endpoint takes at most this many messages per request. */
+declare const EXPO_SEND_BATCH = 100;
+/** And its receipts endpoint at most this many ids. */
+declare const EXPO_RECEIPT_BATCH = 1000;
+/** Expo Push over fetch, so it runs on edge runtimes. Batches, classifies, never throws per token. */
+declare function expoPush(options?: ExpoPushOptions): MobilePushProvider;
+
+export { EXPO_RECEIPT_BATCH, EXPO_SEND_BATCH, type ExpoPushOptions, type MobilePushMessage, type MobilePushProvider, type MobilePushReceipt, type MobilePushTicket, expoPush, isExpoPushToken };

package/dist/providers/expo-push.d.ts

@@ -0,0 +1,61 @@
+type MobilePushMessage = {
+    /** The device's push token as the app registered it. */
+    token: string;
+    title: string;
+    body: string;
+    data?: Record<string, unknown> | undefined;
+    badge?: number | undefined;
+    /** "default" plays the platform sound; null is silent. */
+    sound?: "default" | null | undefined;
+    /** Android notification channel id. */
+    channelId?: string | undefined;
+};
+type MobilePushTicket = {
+    ok: true;
+    ticketId: string | null;
+} | {
+    ok: false;
+    error: string;
+    /** The token will never work again (app uninstalled, token rotated). Prune it. */
+    gone: boolean;
+    retryable: boolean;
+};
+type MobilePushReceipt = {
+    ticketId: string;
+    ok: true;
+} | {
+    ticketId: string;
+    ok: false;
+    error: string;
+    gone: boolean;
+};
+type MobilePushProvider = {
+    name: string;
+    /** True for a token this provider can deliver to. Rejected at registration otherwise. */
+    isValidToken(token: string): boolean;
+    /** One result per message, in order. Never throws for a per-token failure. */
+    send(messages: readonly MobilePushMessage[], signal?: AbortSignal): Promise<MobilePushTicket[]>;
+    /**
+     * Some services (Expo) accept a message, then learn from APNs/FCM later
+     * that the device is gone. Receipts carry that late verdict.
+     */
+    receipts?(ticketIds: readonly string[], signal?: AbortSignal): Promise<MobilePushReceipt[]>;
+};
+type ExpoPushOptions = {
+    /** Expo "enhanced security" access token. Optional; when set, requests without it are refused by Expo. */
+    accessToken?: string | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+    /** Default https://exp.host. A local fake for tests. */
+    apiBase?: string | undefined;
+    timeoutMs?: number | undefined;
+};
+/** Expo tokens look like ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx] or ExpoPushToken[...]. */
+declare const isExpoPushToken: (token: string) => boolean;
+/** Expo's send endpoint takes at most this many messages per request. */
+declare const EXPO_SEND_BATCH = 100;
+/** And its receipts endpoint at most this many ids. */
+declare const EXPO_RECEIPT_BATCH = 1000;
+/** Expo Push over fetch, so it runs on edge runtimes. Batches, classifies, never throws per token. */
+declare function expoPush(options?: ExpoPushOptions): MobilePushProvider;
+
+export { EXPO_RECEIPT_BATCH, EXPO_SEND_BATCH, type ExpoPushOptions, type MobilePushMessage, type MobilePushProvider, type MobilePushReceipt, type MobilePushTicket, expoPush, isExpoPushToken };

package/dist/providers/expo-push.js

@@ -0,0 +1,109 @@
+// src/providers/expo-push/index.ts
+var isExpoPushToken = (token) => /^Expo(nent)?PushToken\[[A-Za-z0-9_-]{8,}\]$/.test(token);
+var EXPO_SEND_BATCH = 100;
+var EXPO_RECEIPT_BATCH = 1e3;
+var GONE = /* @__PURE__ */ new Set(["DeviceNotRegistered"]);
+var RETRYABLE = /* @__PURE__ */ new Set(["MessageRateExceeded", "ProviderError", "ExpoError"]);
+var classify = (code, message) => ({
+  error: code ? `${code}: ${message ?? ""}`.trim() : message ?? "expo push failed",
+  gone: code !== void 0 && GONE.has(code),
+  retryable: code !== void 0 && RETRYABLE.has(code)
+});
+function expoPush(options = {}) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = (options.apiBase ?? "https://exp.host").replace(/\/$/, "");
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const redact = (text) => options.accessToken ? text.split(options.accessToken).join("<token>") : text;
+  async function post(path, body, signal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const headers = {
+      accept: "application/json",
+      "content-type": "application/json"
+    };
+    if (options.accessToken) headers.authorization = `Bearer ${options.accessToken}`;
+    const response = await doFetch(`${base}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+    });
+    if (!response.ok) {
+      const text = redact((await response.text().catch(() => "")).slice(0, 200));
+      const error = new Error(`expo push ${path} failed: HTTP ${response.status} ${text}`.trim());
+      error.status = response.status;
+      throw error;
+    }
+    return await response.json();
+  }
+  const transportFailure = (error) => {
+    const status = error?.status;
+    const message = redact(error instanceof Error ? error.message : String(error));
+    const retryable = status === void 0 || status === 429 || status >= 500;
+    return { ok: false, error: message, gone: false, retryable };
+  };
+  return {
+    name: "expo-push",
+    isValidToken: isExpoPushToken,
+    async send(messages, signal) {
+      const results = [];
+      for (let start = 0; start < messages.length; start += EXPO_SEND_BATCH) {
+        const batch = messages.slice(start, start + EXPO_SEND_BATCH);
+        let tickets;
+        try {
+          const response = await post(
+            "/--/api/v2/push/send",
+            batch.map((message) => ({
+              to: message.token,
+              title: message.title,
+              body: message.body,
+              ...message.data ? { data: message.data } : {},
+              ...message.badge === void 0 ? {} : { badge: message.badge },
+              ...message.sound === void 0 ? { sound: "default" } : { sound: message.sound },
+              ...message.channelId ? { channelId: message.channelId } : {}
+            })),
+            signal
+          );
+          tickets = response.data;
+        } catch (error) {
+          const failure = transportFailure(error);
+          for (const _ of batch) results.push(failure);
+          continue;
+        }
+        batch.forEach((_, index) => {
+          const ticket = tickets[index];
+          if (!ticket) {
+            results.push({ ok: false, error: "no ticket returned", gone: false, retryable: true });
+          } else if (ticket.status === "ok") {
+            results.push({ ok: true, ticketId: ticket.id ?? null });
+          } else {
+            results.push({ ok: false, ...classify(ticket.details?.error, ticket.message) });
+          }
+        });
+      }
+      return results;
+    },
+    async receipts(ticketIds, signal) {
+      const out = [];
+      for (let start = 0; start < ticketIds.length; start += EXPO_RECEIPT_BATCH) {
+        const ids = ticketIds.slice(start, start + EXPO_RECEIPT_BATCH);
+        const response = await post(
+          "/--/api/v2/push/getReceipts",
+          { ids },
+          signal
+        );
+        for (const [ticketId, receipt] of Object.entries(response.data ?? {})) {
+          if (receipt.status === "ok") out.push({ ticketId, ok: true });
+          else {
+            const { error, gone } = classify(receipt.details?.error, receipt.message);
+            out.push({ ticketId, ok: false, error, gone });
+          }
+        }
+      }
+      return out;
+    }
+  };
+}
+
+export { EXPO_RECEIPT_BATCH, EXPO_SEND_BATCH, expoPush, isExpoPushToken };
+//# sourceMappingURL=expo-push.js.map
+//# sourceMappingURL=expo-push.js.map

package/dist/providers/expo-push.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/providers/expo-push/index.ts"],"names":[],"mappings":"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","file":"expo-push.js","sourcesContent":["export type MobilePushMessage = {\n  /** The device's push token as the app registered it. */\n  token: string;\n  title: string;\n  body: string;\n  data?: Record<string, unknown> | undefined;\n  badge?: number | undefined;\n  /** \"default\" plays the platform sound; null is silent. */\n  sound?: \"default\" | null | undefined;\n  /** Android notification channel id. */\n  channelId?: string | undefined;\n};\n\nexport type MobilePushTicket =\n  | { ok: true; ticketId: string | null }\n  | {\n      ok: false;\n      error: string;\n      /** The token will never work again (app uninstalled, token rotated). Prune it. */\n      gone: boolean;\n      retryable: boolean;\n    };\n\nexport type MobilePushReceipt =\n  | { ticketId: string; ok: true }\n  | { ticketId: string; ok: false; error: string; gone: boolean };\n\nexport type MobilePushProvider = {\n  name: string;\n  /** True for a token this provider can deliver to. Rejected at registration otherwise. */\n  isValidToken(token: string): boolean;\n  /** One result per message, in order. Never throws for a per-token failure. */\n  send(messages: readonly MobilePushMessage[], signal?: AbortSignal): Promise<MobilePushTicket[]>;\n  /**\n   * Some services (Expo) accept a message, then learn from APNs/FCM later\n   * that the device is gone. Receipts carry that late verdict.\n   */\n  receipts?(ticketIds: readonly string[], signal?: AbortSignal): Promise<MobilePushReceipt[]>;\n};\n\nexport type ExpoPushOptions = {\n  /** Expo \"enhanced security\" access token. Optional; when set, requests without it are refused by Expo. */\n  accessToken?: string | undefined;\n  fetch?: typeof globalThis.fetch | undefined;\n  /** Default https://exp.host. A local fake for tests. */\n  apiBase?: string | undefined;\n  timeoutMs?: number | undefined;\n};\n\ntype ExpoTicket =\n  | { status: \"ok\"; id: string }\n  | { status: \"error\"; message?: string; details?: { error?: string } };\n\ntype ExpoReceipt =\n  | { status: \"ok\" }\n  | { status: \"error\"; message?: string; details?: { error?: string } };\n\n/** Expo tokens look like ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx] or ExpoPushToken[...]. */\nexport const isExpoPushToken = (token: string): boolean =>\n  /^Expo(nent)?PushToken\\[[A-Za-z0-9_-]{8,}\\]$/.test(token);\n\n/** Expo's send endpoint takes at most this many messages per request. */\nexport const EXPO_SEND_BATCH = 100;\n/** And its receipts endpoint at most this many ids. */\nexport const EXPO_RECEIPT_BATCH = 1000;\n\n// Expo's error codes, per https://docs.expo.dev/push-notifications/sending-notifications/#individual-errors\nconst GONE = new Set([\"DeviceNotRegistered\"]);\nconst RETRYABLE = new Set([\"MessageRateExceeded\", \"ProviderError\", \"ExpoError\"]);\n\nconst classify = (\n  code: string | undefined,\n  message: string | undefined,\n): { error: string; gone: boolean; retryable: boolean } => ({\n  error: code ? `${code}: ${message ?? \"\"}`.trim() : (message ?? \"expo push failed\"),\n  gone: code !== undefined && GONE.has(code),\n  retryable: code !== undefined && RETRYABLE.has(code),\n});\n\n/** Expo Push over fetch, so it runs on edge runtimes. Batches, classifies, never throws per token. */\nexport function expoPush(options: ExpoPushOptions = {}): MobilePushProvider {\n  const doFetch = options.fetch ?? globalThis.fetch;\n  const base = (options.apiBase ?? \"https://exp.host\").replace(/\\/$/, \"\");\n  const timeoutMs = options.timeoutMs ?? 10_000;\n  const redact = (text: string) =>\n    options.accessToken ? text.split(options.accessToken).join(\"<token>\") : text;\n\n  async function post<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {\n    const timeout = AbortSignal.timeout(timeoutMs);\n    const headers: Record<string, string> = {\n      accept: \"application/json\",\n      \"content-type\": \"application/json\",\n    };\n    if (options.accessToken) headers.authorization = `Bearer ${options.accessToken}`;\n    const response = await doFetch(`${base}${path}`, {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify(body),\n      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,\n    });\n    if (!response.ok) {\n      const text = redact((await response.text().catch(() => \"\")).slice(0, 200));\n      const error = new Error(`expo push ${path} failed: HTTP ${response.status} ${text}`.trim());\n      (error as { status?: number }).status = response.status;\n      throw error;\n    }\n    return (await response.json()) as T;\n  }\n\n  const transportFailure = (error: unknown): MobilePushTicket => {\n    const status = (error as { status?: number })?.status;\n    const message = redact(error instanceof Error ? error.message : String(error));\n    // 4xx from the service itself (bad access token, malformed request) cannot be fixed by retrying.\n    const retryable = status === undefined || status === 429 || status >= 500;\n    return { ok: false, error: message, gone: false, retryable };\n  };\n\n  return {\n    name: \"expo-push\",\n    isValidToken: isExpoPushToken,\n\n    async send(messages, signal) {\n      const results: MobilePushTicket[] = [];\n      for (let start = 0; start < messages.length; start += EXPO_SEND_BATCH) {\n        const batch = messages.slice(start, start + EXPO_SEND_BATCH);\n        let tickets: ExpoTicket[];\n        try {\n          const response = await post<{ data: ExpoTicket[] }>(\n            \"/--/api/v2/push/send\",\n            batch.map((message) => ({\n              to: message.token,\n              title: message.title,\n              body: message.body,\n              ...(message.data ? { data: message.data } : {}),\n              ...(message.badge === undefined ? {} : { badge: message.badge }),\n              ...(message.sound === undefined ? { sound: \"default\" } : { sound: message.sound }),\n              ...(message.channelId ? { channelId: message.channelId } : {}),\n            })),\n            signal,\n          );\n          tickets = response.data;\n        } catch (error) {\n          const failure = transportFailure(error);\n          for (const _ of batch) results.push(failure);\n          continue;\n        }\n        batch.forEach((_, index) => {\n          const ticket = tickets[index];\n          if (!ticket) {\n            results.push({ ok: false, error: \"no ticket returned\", gone: false, retryable: true });\n          } else if (ticket.status === \"ok\") {\n            results.push({ ok: true, ticketId: ticket.id ?? null });\n          } else {\n            results.push({ ok: false, ...classify(ticket.details?.error, ticket.message) });\n          }\n        });\n      }\n      return results;\n    },\n\n    async receipts(ticketIds, signal) {\n      const out: MobilePushReceipt[] = [];\n      for (let start = 0; start < ticketIds.length; start += EXPO_RECEIPT_BATCH) {\n        const ids = ticketIds.slice(start, start + EXPO_RECEIPT_BATCH);\n        const response = await post<{ data: Record<string, ExpoReceipt> }>(\n          \"/--/api/v2/push/getReceipts\",\n          { ids },\n          signal,\n        );\n        for (const [ticketId, receipt] of Object.entries(response.data ?? {})) {\n          if (receipt.status === \"ok\") out.push({ ticketId, ok: true });\n          else {\n            const { error, gone } = classify(receipt.details?.error, receipt.message);\n            out.push({ ticketId, ok: false, error, gone });\n          }\n        }\n      }\n      return out;\n    },\n  };\n}\n"]}

package/dist/providers/telegram.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+// src/providers/telegram/index.ts
+var telegramStartLink = (botUsername, code) => `https://t.me/${botUsername.replace(/^@/, "")}?start=${encodeURIComponent(code)}`;
+function telegramBot(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = `${(options.apiBase ?? "https://api.telegram.org").replace(/\/$/, "")}/bot${options.token}`;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const redact = (text) => text.split(options.token).join("<token>");
+  async function call(method, body, signal, budgetMs = timeoutMs) {
+    const timeout = AbortSignal.timeout(budgetMs);
+    const merged = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    const response = await doFetch(`${base}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: merged
+    });
+    const data = await response.json().catch(() => ({ ok: false }));
+    return { status: response.status, data };
+  }
+  async function must(method, body) {
+    const { data } = await call(method, body);
+    if (!data.ok)
+      throw new Error(redact(`telegram ${method} failed: ${data.description ?? "unknown"}`));
+    return data.result;
+  }
+  return {
+    name: "telegram",
+    async send(message) {
+      const body = {
+        chat_id: message.chatId,
+        text: message.text,
+        parse_mode: "HTML",
+        link_preview_options: { is_disabled: true }
+      };
+      if (message.buttons?.length) {
+        body.reply_markup = {
+          inline_keyboard: [
+            message.buttons.map((button) => ({ text: button.text, url: button.url }))
+          ]
+        };
+      }
+      let status;
+      let data;
+      try {
+        ({ status, data } = await call(
+          "sendMessage",
+          body,
+          message.signal
+        ));
+      } catch (error) {
+        const text = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: redact(text), retryable: true, gone: false };
+      }
+      if (data.ok) return { ok: true, messageId: data.result.message_id };
+      const description = redact(data.description ?? `HTTP ${status}`);
+      const code = data.error_code ?? status;
+      if (code === 429) {
+        return {
+          ok: false,
+          error: description,
+          retryable: true,
+          gone: false,
+          retryAfterSeconds: data.parameters?.retry_after
+        };
+      }
+      const gone = code === 403 || code === 400 && /chat not found|user is deactivated|bot was kicked/i.test(description);
+      return { ok: false, error: description, retryable: code >= 500, gone };
+    },
+    async getUpdates({ offset, timeoutSeconds = 25, signal }) {
+      const { data } = await call(
+        "getUpdates",
+        {
+          ...offset === void 0 ? {} : { offset },
+          timeout: timeoutSeconds,
+          allowed_updates: ["message", "my_chat_member"]
+        },
+        signal,
+        (timeoutSeconds + 10) * 1e3
+      );
+      if (!data.ok)
+        throw new Error(redact(`telegram getUpdates failed: ${data.description ?? "unknown"}`));
+      return data.result;
+    },
+    setWebhook: async (url, secretToken) => {
+      await must("setWebhook", {
+        url,
+        secret_token: secretToken,
+        allowed_updates: ["message", "my_chat_member"]
+      });
+    },
+    deleteWebhook: async () => {
+      await must("deleteWebhook", {});
+    },
+    getMe: () => must("getMe", {})
+  };
+}
+
+exports.telegramBot = telegramBot;
+exports.telegramStartLink = telegramStartLink;
+//# sourceMappingURL=telegram.cjs.map
+//# sourceMappingURL=telegram.cjs.map

package/dist/providers/telegram.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/providers/telegram/index.ts"],"names":[],"mappings":";;;AAiEO,IAAM,iBAAA,GAAoB,CAAC,WAAA,EAAqB,IAAA,KACrD,CAAA,aAAA,EAAgB,WAAA,CAAY,OAAA,CAAQ,IAAA,EAAM,EAAE,CAAC,CAAA,OAAA,EAAU,kBAAA,CAAmB,IAAI,CAAC,CAAA;AAG1E,SAAS,YAAY,OAAA,EAA+C;AACzE,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,KAAA,IAAS,UAAA,CAAW,KAAA;AAC5C,EAAA,MAAM,IAAA,GAAO,CAAA,EAAA,CAAI,OAAA,CAAQ,OAAA,IAAW,0BAAA,EAA4B,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAC,CAAA,IAAA,EAAO,OAAA,CAAQ,KAAK,CAAA,CAAA;AACtG,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,GAAA;AACvC,EAAA,MAAM,MAAA,GAAS,CAAC,IAAA,KAAiB,IAAA,CAAK,MAAM,OAAA,CAAQ,KAAK,CAAA,CAAE,IAAA,CAAK,SAAS,CAAA;AAEzE,EAAA,eAAe,IAAA,CACb,MAAA,EACA,IAAA,EACA,MAAA,EACA,WAAW,SAAA,EACwC;AACnD,IAAA,MAAM,OAAA,GAAU,WAAA,CAAY,OAAA,CAAQ,QAAQ,CAAA;AAC5C,IAAA,MAAM,MAAA,GAAS,SAAS,WAAA,CAAY,GAAA,CAAI,CAAC,MAAA,EAAQ,OAAO,CAAC,CAAA,GAAI,OAAA;AAC7D,IAAA,MAAM,WAAW,MAAM,OAAA,CAAQ,GAAG,IAAI,CAAA,CAAA,EAAI,MAAM,CAAA,CAAA,EAAI;AAAA,MAClD,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS,EAAE,cAAA,EAAgB,kBAAA,EAAmB;AAAA,MAC9C,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,IAAI,CAAA;AAAA,MACzB,MAAA,EAAQ;AAAA,KACT,CAAA;AACD,IAAA,MAAM,IAAA,GAAQ,MAAM,QAAA,CAAS,IAAA,EAAK,CAAE,MAAM,OAAO,EAAE,EAAA,EAAI,KAAA,EAAM,CAAE,CAAA;AAC/D,IAAA,OAAO,EAAE,MAAA,EAAQ,QAAA,CAAS,MAAA,EAAQ,IAAA,EAAK;AAAA,EACzC;AAEA,EAAA,eAAe,IAAA,CAAQ,QAAgB,IAAA,EAA2C;AAChF,IAAA,MAAM,EAAE,IAAA,EAAK,GAAI,MAAM,IAAA,CAAQ,QAAQ,IAAI,CAAA;AAC3C,IAAA,IAAI,CAAC,IAAA,CAAK,EAAA;AACR,MAAA,MAAM,IAAI,KAAA,CAAM,MAAA,CAAO,CAAA,SAAA,EAAY,MAAM,YAAY,IAAA,CAAK,WAAA,IAAe,SAAS,CAAA,CAAE,CAAC,CAAA;AACvF,IAAA,OAAO,IAAA,CAAK,MAAA;AAAA,EACd;AAEA,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,UAAA;AAAA,IAEN,MAAM,KAAK,OAAA,EAAS;AAClB,MAAA,MAAM,IAAA,GAAgC;AAAA,QACpC,SAAS,OAAA,CAAQ,MAAA;AAAA,QACjB,MAAM,OAAA,CAAQ,IAAA;AAAA,QACd,UAAA,EAAY,MAAA;AAAA,QACZ,oBAAA,EAAsB,EAAE,WAAA,EAAa,IAAA;AAAK,OAC5C;AACA,MAAA,IAAI,OAAA,CAAQ,SAAS,MAAA,EAAQ;AAC3B,QAAA,IAAA,CAAK,YAAA,GAAe;AAAA,UAClB,eAAA,EAAiB;AAAA,YACf,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,CAAC,MAAA,MAAY,EAAE,IAAA,EAAM,MAAA,CAAO,IAAA,EAAM,GAAA,EAAK,MAAA,CAAO,GAAA,EAAI,CAAE;AAAA;AAC1E,SACF;AAAA,MACF;AAEA,MAAA,IAAI,MAAA;AACJ,MAAA,IAAI,IAAA;AACJ,MAAA,IAAI;AACF,QAAA,CAAC,EAAE,MAAA,EAAQ,IAAA,EAAK,GAAI,MAAM,IAAA;AAAA,UACxB,aAAA;AAAA,UACA,IAAA;AAAA,UACA,OAAA,CAAQ;AAAA,SACV;AAAA,MACF,SAAS,KAAA,EAAO;AACd,QAAA,MAAM,OAAO,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,OAAO,KAAK,CAAA;AAClE,QAAA,OAAO,EAAE,EAAA,EAAI,KAAA,EAAO,KAAA,EAAO,MAAA,CAAO,IAAI,CAAA,EAAG,SAAA,EAAW,IAAA,EAAM,IAAA,EAAM,KAAA,EAAM;AAAA,MACxE;AAEA,MAAA,IAAI,IAAA,CAAK,IAAI,OAAO,EAAE,IAAI,IAAA,EAAM,SAAA,EAAW,IAAA,CAAK,MAAA,CAAO,UAAA,EAAW;AAElE,MAAA,MAAM,cAAc,MAAA,CAAO,IAAA,CAAK,WAAA,IAAe,CAAA,KAAA,EAAQ,MAAM,CAAA,CAAE,CAAA;AAC/D,MAAA,MAAM,IAAA,GAAO,KAAK,UAAA,IAAc,MAAA;AAChC,MAAA,IAAI,SAAS,GAAA,EAAK;AAChB,QAAA,OAAO;AAAA,UACL,EAAA,EAAI,KAAA;AAAA,UACJ,KAAA,EAAO,WAAA;AAAA,UACP,SAAA,EAAW,IAAA;AAAA,UACX,IAAA,EAAM,KAAA;AAAA,UACN,iBAAA,EAAmB,KAAK,UAAA,EAAY;AAAA,SACtC;AAAA,MACF;AAEA,MAAA,MAAM,OACJ,IAAA,KAAS,GAAA,IACR,SAAS,GAAA,IAAO,oDAAA,CAAqD,KAAK,WAAW,CAAA;AACxF,MAAA,OAAO,EAAE,IAAI,KAAA,EAAO,KAAA,EAAO,aAAa,SAAA,EAAW,IAAA,IAAQ,KAAK,IAAA,EAAK;AAAA,IACvE,CAAA;AAAA,IAEA,MAAM,UAAA,CAAW,EAAE,QAAQ,cAAA,GAAiB,EAAA,EAAI,QAAO,EAAG;AAExD,MAAA,MAAM,EAAE,IAAA,EAAK,GAAI,MAAM,IAAA;AAAA,QACrB,YAAA;AAAA,QACA;AAAA,UACE,GAAI,MAAA,KAAW,MAAA,GAAY,EAAC,GAAI,EAAE,MAAA,EAAO;AAAA,UACzC,OAAA,EAAS,cAAA;AAAA,UACT,eAAA,EAAiB,CAAC,SAAA,EAAW,gBAAgB;AAAA,SAC/C;AAAA,QACA,MAAA;AAAA,QAAA,CACC,iBAAiB,EAAA,IAAM;AAAA,OAC1B;AACA,MAAA,IAAI,CAAC,IAAA,CAAK,EAAA;AACR,QAAA,MAAM,IAAI,MAAM,MAAA,CAAO,CAAA,4BAAA,EAA+B,KAAK,WAAA,IAAe,SAAS,EAAE,CAAC,CAAA;AACxF,MAAA,OAAO,IAAA,CAAK,MAAA;AAAA,IACd,CAAA;AAAA,IAEA,UAAA,EAAY,OAAO,GAAA,EAAK,WAAA,KAAgB;AACtC,MAAA,MAAM,KAAK,YAAA,EAAc;AAAA,QACvB,GAAA;AAAA,QACA,YAAA,EAAc,WAAA;AAAA,QACd,eAAA,EAAiB,CAAC,SAAA,EAAW,gBAAgB;AAAA,OAC9C,CAAA;AAAA,IACH,CAAA;AAAA,IACA,eAAe,YAAY;AACzB,MAAA,MAAM,IAAA,CAAK,eAAA,EAAiB,EAAE,CAAA;AAAA,IAChC,CAAA;AAAA,IACA,KAAA,EAAO,MAAM,IAAA,CAAK,OAAA,EAAS,EAAE;AAAA,GAC/B;AACF","file":"telegram.cjs","sourcesContent":["export type TelegramButton = { text: string; url: string };\n\nexport type TelegramMessage = {\n  chatId: string;\n  /** Telegram HTML: <b>, <i>, <a href>, <code>, <pre>. Escape user text with escapeHtml(). */\n  text: string;\n  buttons?: readonly TelegramButton[] | undefined;\n  signal?: AbortSignal | undefined;\n};\n\nexport type TelegramSendResult =\n  | { ok: true; messageId: number }\n  | {\n      ok: false;\n      error: string;\n      /** Worth another attempt: rate limit, 5xx, network. */\n      retryable: boolean;\n      /** The chat can never receive again (user blocked the bot, chat deleted). Prune it. */\n      gone: boolean;\n      retryAfterSeconds?: number | undefined;\n    };\n\n/** The slice of a Bot API update the plugin reads. Everything else passes through untouched. */\nexport type TelegramUpdate = {\n  update_id: number;\n  message?: {\n    text?: string;\n    chat: { id: number | string; type: string; username?: string; title?: string };\n    from?: { id: number; username?: string; first_name?: string };\n  };\n  my_chat_member?: {\n    chat: { id: number | string; type: string; username?: string; title?: string };\n    new_chat_member: { status: string };\n  };\n};\n\nexport type TelegramProvider = {\n  name: string;\n  send(message: TelegramMessage): Promise<TelegramSendResult>;\n  /** Long-polls for updates. For development or hosts without a public URL. */\n  getUpdates(options: {\n    offset?: number | undefined;\n    timeoutSeconds?: number | undefined;\n    signal?: AbortSignal | undefined;\n  }): Promise<TelegramUpdate[]>;\n  /** Points Telegram at your webhook route. Run once per deployment URL. */\n  setWebhook(url: string, secretToken: string): Promise<void>;\n  deleteWebhook(): Promise<void>;\n  getMe(): Promise<{ id: number; username: string }>;\n};\n\nexport type TelegramBotOptions = {\n  /** From @BotFather. Never appears in errors or logs. */\n  token: string;\n  fetch?: typeof globalThis.fetch | undefined;\n  /** Default https://api.telegram.org. A local fake for tests. */\n  apiBase?: string | undefined;\n  timeoutMs?: number | undefined;\n};\n\ntype ApiResponse<T> =\n  | { ok: true; result: T }\n  | { ok: false; description?: string; error_code?: number; parameters?: { retry_after?: number } };\n\n/** Deep link that opens the bot with a start parameter. Codes are [A-Za-z0-9_-], at most 64 chars. */\nexport const telegramStartLink = (botUsername: string, code: string) =>\n  `https://t.me/${botUsername.replace(/^@/, \"\")}?start=${encodeURIComponent(code)}`;\n\n/** Bot API over fetch, so it runs on edge runtimes. Failures are classified, never thrown, on send. */\nexport function telegramBot(options: TelegramBotOptions): TelegramProvider {\n  const doFetch = options.fetch ?? globalThis.fetch;\n  const base = `${(options.apiBase ?? \"https://api.telegram.org\").replace(/\\/$/, \"\")}/bot${options.token}`;\n  const timeoutMs = options.timeoutMs ?? 10_000;\n  const redact = (text: string) => text.split(options.token).join(\"<token>\");\n\n  async function call<T>(\n    method: string,\n    body: Record<string, unknown>,\n    signal?: AbortSignal,\n    budgetMs = timeoutMs,\n  ): Promise<{ status: number; data: ApiResponse<T> }> {\n    const timeout = AbortSignal.timeout(budgetMs);\n    const merged = signal ? AbortSignal.any([signal, timeout]) : timeout;\n    const response = await doFetch(`${base}/${method}`, {\n      method: \"POST\",\n      headers: { \"content-type\": \"application/json\" },\n      body: JSON.stringify(body),\n      signal: merged,\n    });\n    const data = (await response.json().catch(() => ({ ok: false }))) as ApiResponse<T>;\n    return { status: response.status, data };\n  }\n\n  async function must<T>(method: string, body: Record<string, unknown>): Promise<T> {\n    const { data } = await call<T>(method, body);\n    if (!data.ok)\n      throw new Error(redact(`telegram ${method} failed: ${data.description ?? \"unknown\"}`));\n    return data.result;\n  }\n\n  return {\n    name: \"telegram\",\n\n    async send(message) {\n      const body: Record<string, unknown> = {\n        chat_id: message.chatId,\n        text: message.text,\n        parse_mode: \"HTML\",\n        link_preview_options: { is_disabled: true },\n      };\n      if (message.buttons?.length) {\n        body.reply_markup = {\n          inline_keyboard: [\n            message.buttons.map((button) => ({ text: button.text, url: button.url })),\n          ],\n        };\n      }\n\n      let status: number;\n      let data: ApiResponse<{ message_id: number }>;\n      try {\n        ({ status, data } = await call<{ message_id: number }>(\n          \"sendMessage\",\n          body,\n          message.signal,\n        ));\n      } catch (error) {\n        const text = error instanceof Error ? error.message : String(error);\n        return { ok: false, error: redact(text), retryable: true, gone: false };\n      }\n\n      if (data.ok) return { ok: true, messageId: data.result.message_id };\n\n      const description = redact(data.description ?? `HTTP ${status}`);\n      const code = data.error_code ?? status;\n      if (code === 429) {\n        return {\n          ok: false,\n          error: description,\n          retryable: true,\n          gone: false,\n          retryAfterSeconds: data.parameters?.retry_after,\n        };\n      }\n      // 403: the user blocked the bot or was deactivated. 400 \"chat not found\": deleted or never existed.\n      const gone =\n        code === 403 ||\n        (code === 400 && /chat not found|user is deactivated|bot was kicked/i.test(description));\n      return { ok: false, error: description, retryable: code >= 500, gone };\n    },\n\n    async getUpdates({ offset, timeoutSeconds = 25, signal }) {\n      // Telegram holds the request open for `timeout` seconds; the budget must outlive it.\n      const { data } = await call<TelegramUpdate[]>(\n        \"getUpdates\",\n        {\n          ...(offset === undefined ? {} : { offset }),\n          timeout: timeoutSeconds,\n          allowed_updates: [\"message\", \"my_chat_member\"],\n        },\n        signal,\n        (timeoutSeconds + 10) * 1000,\n      );\n      if (!data.ok)\n        throw new Error(redact(`telegram getUpdates failed: ${data.description ?? \"unknown\"}`));\n      return data.result;\n    },\n\n    setWebhook: async (url, secretToken) => {\n      await must(\"setWebhook\", {\n        url,\n        secret_token: secretToken,\n        allowed_updates: [\"message\", \"my_chat_member\"],\n      });\n    },\n    deleteWebhook: async () => {\n      await must(\"deleteWebhook\", {});\n    },\n    getMe: () => must(\"getMe\", {}),\n  };\n}\n"]}

package/dist/providers/telegram.d.cts

@@ -0,0 +1,83 @@
+type TelegramButton = {
+    text: string;
+    url: string;
+};
+type TelegramMessage = {
+    chatId: string;
+    /** Telegram HTML: <b>, <i>, <a href>, <code>, <pre>. Escape user text with escapeHtml(). */
+    text: string;
+    buttons?: readonly TelegramButton[] | undefined;
+    signal?: AbortSignal | undefined;
+};
+type TelegramSendResult = {
+    ok: true;
+    messageId: number;
+} | {
+    ok: false;
+    error: string;
+    /** Worth another attempt: rate limit, 5xx, network. */
+    retryable: boolean;
+    /** The chat can never receive again (user blocked the bot, chat deleted). Prune it. */
+    gone: boolean;
+    retryAfterSeconds?: number | undefined;
+};
+/** The slice of a Bot API update the plugin reads. Everything else passes through untouched. */
+type TelegramUpdate = {
+    update_id: number;
+    message?: {
+        text?: string;
+        chat: {
+            id: number | string;
+            type: string;
+            username?: string;
+            title?: string;
+        };
+        from?: {
+            id: number;
+            username?: string;
+            first_name?: string;
+        };
+    };
+    my_chat_member?: {
+        chat: {
+            id: number | string;
+            type: string;
+            username?: string;
+            title?: string;
+        };
+        new_chat_member: {
+            status: string;
+        };
+    };
+};
+type TelegramProvider = {
+    name: string;
+    send(message: TelegramMessage): Promise<TelegramSendResult>;
+    /** Long-polls for updates. For development or hosts without a public URL. */
+    getUpdates(options: {
+        offset?: number | undefined;
+        timeoutSeconds?: number | undefined;
+        signal?: AbortSignal | undefined;
+    }): Promise<TelegramUpdate[]>;
+    /** Points Telegram at your webhook route. Run once per deployment URL. */
+    setWebhook(url: string, secretToken: string): Promise<void>;
+    deleteWebhook(): Promise<void>;
+    getMe(): Promise<{
+        id: number;
+        username: string;
+    }>;
+};
+type TelegramBotOptions = {
+    /** From @BotFather. Never appears in errors or logs. */
+    token: string;
+    fetch?: typeof globalThis.fetch | undefined;
+    /** Default https://api.telegram.org. A local fake for tests. */
+    apiBase?: string | undefined;
+    timeoutMs?: number | undefined;
+};
+/** Deep link that opens the bot with a start parameter. Codes are [A-Za-z0-9_-], at most 64 chars. */
+declare const telegramStartLink: (botUsername: string, code: string) => string;
+/** Bot API over fetch, so it runs on edge runtimes. Failures are classified, never thrown, on send. */
+declare function telegramBot(options: TelegramBotOptions): TelegramProvider;
+
+export { type TelegramBotOptions, type TelegramButton, type TelegramMessage, type TelegramProvider, type TelegramSendResult, type TelegramUpdate, telegramBot, telegramStartLink };