target-supabase-sdk 0.2.17 → 0.2.18

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.17",
+    "version": "0.2.18",
     "description": "Supabase client initializer and data access APIs",
     "license": "MIT",
     "author": "KyLoc20",
@@ -69,8 +69,14 @@
         "@supabase/postgrest-js": "^1.19.0",
         "@supabase/supabase-js": "^2.50.0",
         "lodash-es": "^4.17.21",
+        "undici": "^7.10.0",
         "zod": "^3.23.0"
     },
+    "peerDependenciesMeta": {
+        "undici": {
+            "optional": true
+        }
+    },
     "devDependencies": {
         "@biomejs/biome": "^2.5.3",
         "@rollup/plugin-node-resolve": "^16.0.1",
@@ -84,6 +90,7 @@
         "tslib": "^2.8.1",
         "tsx": "^4.19.4",
         "typescript": "~5.7.2",
+        "undici": "^7.10.0",
         "zod": "^3.24.0"
     },
     "publishConfig": {

package/src/node/telegram/api-client.ts

@@ -0,0 +1,146 @@
+import { type Dispatcher, ProxyAgent } from "undici";
+import {
+    createLogger,
+    type FetchInitFactory,
+    fetchBinaryWithRetry,
+    fetchWithRetry,
+    isRetryableHttpStatus,
+} from "../../browser";
+import type { ResolvedTelegramStorageOptions, TelegramApiResponse } from "./types";
+
+const logger = createLogger({ module: "telegram" });
+
+let cachedDispatcher: Dispatcher | undefined;
+let cachedProxyUrl: string | undefined;
+
+/** Per-request undici dispatcher when proxyUrl is set (Supabase stays direct). */
+function telegramFetchDispatcher(proxyUrl: string | undefined): Dispatcher | undefined {
+    if (proxyUrl == null) {
+        return undefined;
+    }
+    if (cachedDispatcher != null && cachedProxyUrl === proxyUrl) {
+        return cachedDispatcher;
+    }
+    cachedDispatcher = new ProxyAgent(proxyUrl);
+    cachedProxyUrl = proxyUrl;
+    return cachedDispatcher;
+}
+
+function telegramNetworkHint(proxyUrl: string | undefined): string {
+    return proxyUrl
+        ? ` (proxy=${proxyUrl}, ensure Clash/V2Ray is running)`
+        : " (set proxyUrl / TELEGRAM_PROXY if api.telegram.org is blocked)";
+}
+
+export interface CallTelegramOptions {
+    timeoutMs?: number;
+    retryAttempts?: number;
+    retryBaseMs?: number;
+}
+
+function botApiUrl(options: ResolvedTelegramStorageOptions, method: string): string {
+    return `${options.apiBaseUrl}/bot${options.botToken}/${method}`;
+}
+
+export function telegramFileDownloadUrl(options: ResolvedTelegramStorageOptions, filePath: string): string {
+    const normalized = filePath.replace(/^\/+/, "");
+    return `${options.apiBaseUrl}/file/bot${options.botToken}/${normalized}`;
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function telegramBackoff(attempt: number, retryBaseMs: number): Promise<void> {
+    return sleep(retryBaseMs * 2 ** (attempt - 1));
+}
+
+/** Bot API JSON call — transport retry via SDK fetch; outer loop retries Telegram `{ ok: false }`. */
+export async function callTelegramApi<T>(
+    options: ResolvedTelegramStorageOptions,
+    method: string,
+    initOrFactory: RequestInit | FetchInitFactory,
+    callOptions: CallTelegramOptions = {},
+): Promise<T> {
+    const timeoutMs = callOptions.timeoutMs ?? options.fetchTimeoutMs;
+    const maxAttempts = callOptions.retryAttempts ?? 1;
+    const retryBaseMs = callOptions.retryBaseMs ?? options.uploadRetryBaseMs;
+    const url = botApiUrl(options, method);
+    const label = `Telegram ${method}`;
+    const dispatcher = telegramFetchDispatcher(options.proxyUrl);
+    const hint = telegramNetworkHint(options.proxyUrl);
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const response = await fetchWithRetry(url, initOrFactory, {
+            label,
+            timeoutMs,
+            maxAttempts: attempt === 1 ? maxAttempts : 1,
+            retryBaseMs,
+            dispatcher,
+            hint,
+            logger,
+        });
+
+        let payload: TelegramApiResponse<T>;
+        try {
+            payload = (await response.json()) as TelegramApiResponse<T>;
+        } catch {
+            lastError = new Error(`${label}: invalid JSON response (HTTP ${response.status})`);
+            if (attempt < maxAttempts && isRetryableHttpStatus(response.status)) {
+                await telegramBackoff(attempt, retryBaseMs);
+                continue;
+            }
+            throw lastError;
+        }
+
+        if (!payload.ok) {
+            const description = payload.description ?? `HTTP ${response.status}`;
+            lastError = new Error(`${label}: ${description}`);
+            if (attempt < maxAttempts && isRetryableHttpStatus(response.status)) {
+                logger.warn("retrying after API error", {
+                    topic: "telegram",
+                    data: { method, attempt, description },
+                });
+                await telegramBackoff(attempt, retryBaseMs);
+                continue;
+            }
+            throw lastError;
+        }
+
+        if (payload.result == null) {
+            throw new Error(`${label}: empty result in response`);
+        }
+
+        if (attempt > 1) {
+            logger.info("request succeeded after retry", { topic: "telegram", data: { method, attempt } });
+        }
+
+        return payload.result;
+    }
+
+    throw lastError ?? new Error(`${label}: request failed`);
+}
+
+export async function telegramDownloadBinary(
+    options: ResolvedTelegramStorageOptions,
+    url: string,
+    label: string,
+    callOptions: CallTelegramOptions = {},
+): Promise<ArrayBuffer> {
+    const dispatcher = telegramFetchDispatcher(options.proxyUrl);
+    return fetchBinaryWithRetry(
+        url,
+        { method: "GET" },
+        {
+            label: `Telegram ${label}`,
+            timeoutMs: callOptions.timeoutMs ?? options.fetchTimeoutMs,
+            maxAttempts: callOptions.retryAttempts ?? 1,
+            retryBaseMs: callOptions.retryBaseMs ?? options.uploadRetryBaseMs,
+            dispatcher,
+            hint: telegramNetworkHint(options.proxyUrl),
+            logger,
+        },
+    );
+}

package/src/node/telegram/chunk-locator.ts

@@ -0,0 +1,23 @@
+/**
+ * Telegram chunk URL encoding: `${messageId}|${fileId}`.
+ * Legacy parcels store bare `file_id` (no messageId → cannot deleteMessage).
+ */
+
+const SEPARATOR = "|";
+
+export function encodeTelegramChunkUrl(messageId: number, fileId: string): string {
+    return `${messageId}${SEPARATOR}${fileId}`;
+}
+
+export function parseTelegramChunkUrl(locator: string): { messageId: number | null; fileId: string } {
+    const idx = locator.indexOf(SEPARATOR);
+    if (idx <= 0) {
+        return { messageId: null, fileId: locator };
+    }
+    const mid = Number(locator.slice(0, idx));
+    const fileId = locator.slice(idx + 1);
+    if (!Number.isInteger(mid) || mid <= 0 || fileId === "") {
+        return { messageId: null, fileId: locator };
+    }
+    return { messageId: mid, fileId };
+}

package/src/node/telegram/chunk.ts

@@ -0,0 +1,33 @@
+import { callTelegramApi, telegramDownloadBinary, telegramFileDownloadUrl } from "./api-client";
+import type { ResolvedTelegramStorageOptions, TelegramFile } from "./types";
+
+/** Download chunk bytes by Telegram `file_id` stored in Chunk.url. */
+export async function downloadTelegramChunk(
+    options: ResolvedTelegramStorageOptions,
+    fileId: string,
+): Promise<ArrayBuffer> {
+    const file = await callTelegramApi<TelegramFile>(
+        options,
+        `getFile?file_id=${encodeURIComponent(fileId)}`,
+        { method: "GET" },
+        {
+            retryAttempts: options.uploadRetryAttempts,
+            retryBaseMs: options.uploadRetryBaseMs,
+        },
+    );
+
+    if (file.file_path == null || file.file_path === "") {
+        throw new Error(`Telegram getFile: missing file_path for file_id ${fileId}`);
+    }
+
+    return telegramDownloadBinary(
+        options,
+        telegramFileDownloadUrl(options, file.file_path),
+        `download:${fileId.slice(0, 12)}…`,
+        {
+            timeoutMs: options.uploadTimeoutMs,
+            retryAttempts: options.uploadRetryAttempts,
+            retryBaseMs: options.uploadRetryBaseMs,
+        },
+    );
+}

package/src/node/telegram/index.ts

@@ -0,0 +1,20 @@
+export type { CallTelegramOptions } from "./api-client";
+export { callTelegramApi, telegramDownloadBinary, telegramFileDownloadUrl } from "./api-client";
+export { downloadTelegramChunk } from "./chunk";
+export { encodeTelegramChunkUrl, parseTelegramChunkUrl } from "./chunk-locator";
+export {
+    createTelegramStorageProvider,
+    PROVIDER_TELEGRAM,
+    type TelegramChunkDeleteResult,
+    type TelegramStorageProvider,
+} from "./storage-provider";
+export type {
+    ResolvedTelegramStorageOptions,
+    TelegramApiResponse,
+    TelegramDocument,
+    TelegramFile,
+    TelegramMessage,
+    TelegramStorageProviderOptions,
+    TelegramUploadResult,
+} from "./types";
+export { resolveTelegramStorageOptions } from "./types";

package/src/node/telegram/storage-provider.ts

@@ -0,0 +1,182 @@
+import type { CreateUploadAdapterOptions, Parcel, StorageProviderModule, UploadTracker } from "../../browser";
+import { isOpaqueChunkUrl } from "../../browser";
+import { callTelegramApi } from "./api-client";
+import { downloadTelegramChunk } from "./chunk";
+import { encodeTelegramChunkUrl, parseTelegramChunkUrl } from "./chunk-locator";
+import {
+    type ResolvedTelegramStorageOptions,
+    resolveTelegramStorageOptions,
+    type TelegramMessage,
+    type TelegramStorageProviderOptions,
+    type TelegramUploadResult,
+} from "./types";
+
+export const PROVIDER_TELEGRAM = "telegram";
+
+export interface TelegramChunkDeleteResult {
+    deleted: number;
+    failed: number;
+    skipped: number;
+}
+
+export interface TelegramStorageProvider extends StorageProviderModule {
+    readonly provider: typeof PROVIDER_TELEGRAM;
+    /** Low-level upload for probes/CLIs. */
+    uploadChunk(data: ArrayBuffer, filename: string): Promise<TelegramUploadResult>;
+    /** Best-effort deleteMessage for rollback / probe cleanup. */
+    deleteMessage(messageId: number): Promise<void>;
+    /**
+     * Best-effort delete Telegram messages for parcel chunks.
+     * Chunks without an encoded messageId (legacy bare file_id) are skipped.
+     */
+    deleteChunkBlobs(parcel: Parcel): Promise<TelegramChunkDeleteResult>;
+}
+
+async function uploadChunkToTelegram(
+    options: ResolvedTelegramStorageOptions,
+    data: ArrayBuffer,
+    filename: string,
+): Promise<TelegramUploadResult> {
+    const sizeMb = (data.byteLength / (1024 * 1024)).toFixed(2);
+
+    const message = await callTelegramApi<TelegramMessage>(
+        options,
+        "sendDocument",
+        () => {
+            const form = new FormData();
+            form.append("chat_id", options.chatId);
+            form.append("document", new Blob([data]), filename);
+            return { method: "POST", body: form };
+        },
+        {
+            timeoutMs: options.uploadTimeoutMs,
+            retryAttempts: options.uploadRetryAttempts,
+            retryBaseMs: options.uploadRetryBaseMs,
+        },
+    );
+
+    const fileId = message.document?.file_id;
+    if (fileId == null || fileId === "") {
+        throw new Error(`Telegram sendDocument: missing file_id (chunk ${filename}, ${sizeMb} MB)`);
+    }
+
+    return { fileId, messageId: message.message_id };
+}
+
+async function deleteTelegramMessage(options: ResolvedTelegramStorageOptions, messageId: number): Promise<void> {
+    await callTelegramApi<boolean>(
+        options,
+        "deleteMessage",
+        () => {
+            const form = new FormData();
+            form.append("chat_id", options.chatId);
+            form.append("message_id", String(messageId));
+            return { method: "POST", body: form };
+        },
+        {
+            retryAttempts: 3,
+            retryBaseMs: 1_000,
+        },
+    );
+}
+
+async function rollbackTelegramUploads(options: ResolvedTelegramStorageOptions, handles: unknown[]): Promise<void> {
+    for (const item of handles) {
+        const upload = item as TelegramUploadResult;
+        if (upload?.messageId == null) {
+            continue;
+        }
+        try {
+            await deleteTelegramMessage(options, upload.messageId);
+        } catch {
+            // Best-effort cleanup
+        }
+    }
+}
+
+function assertTelegramParcel(parcel: Parcel): void {
+    const chunks = parcel.details.chunkList;
+    if (chunks.length === 0) {
+        throw new Error("Parcel has no chunks");
+    }
+
+    const nonTelegram = chunks.filter((chunk) => chunk.provider != null && chunk.provider !== PROVIDER_TELEGRAM);
+    if (nonTelegram.length > 0) {
+        const providers = [...new Set(nonTelegram.map((chunk) => chunk.provider))];
+        throw new Error(
+            `Parcel is not telegram-only (found providers: ${providers.join(", ")}). ` +
+                "Multi-provider restore is not yet supported for this parcel.",
+        );
+    }
+}
+
+/**
+ * Build a Telegram {@link StorageProviderModule}. Caller registers it — no side effects.
+ *
+ * @example
+ * ```ts
+ * import { createStorageProviderRegistry, createTelegramStorageProvider } from "target-supabase-sdk/node";
+ * const registry = createStorageProviderRegistry();
+ * registry.register(createTelegramStorageProvider({ botToken, chatId, proxyUrl }));
+ * ```
+ */
+export function createTelegramStorageProvider(input: TelegramStorageProviderOptions): TelegramStorageProvider {
+    const options = resolveTelegramStorageOptions(input);
+
+    return {
+        provider: PROVIDER_TELEGRAM,
+        uploadChunk: (data, filename) => uploadChunkToTelegram(options, data, filename),
+        deleteMessage: (messageId) => deleteTelegramMessage(options, messageId),
+        async deleteChunkBlobs(parcel) {
+            let deleted = 0;
+            let failed = 0;
+            let skipped = 0;
+            for (const chunk of parcel.details.chunkList) {
+                if (chunk.provider != null && chunk.provider !== PROVIDER_TELEGRAM) {
+                    skipped += 1;
+                    continue;
+                }
+                const { messageId } = parseTelegramChunkUrl(chunk.url);
+                if (messageId == null) {
+                    skipped += 1;
+                    continue;
+                }
+                try {
+                    await deleteTelegramMessage(options, messageId);
+                    deleted += 1;
+                } catch {
+                    failed += 1;
+                }
+            }
+            return { deleted, failed, skipped };
+        },
+        createUploadAdapter(adapterOptions?: CreateUploadAdapterOptions) {
+            const tracker = adapterOptions?.tracker as UploadTracker<TelegramUploadResult> | undefined;
+            return {
+                provider: PROVIDER_TELEGRAM,
+                async upload(data, pathOrKey) {
+                    const result = await uploadChunkToTelegram(options, data, pathOrKey);
+                    tracker?.push(result);
+                    // Persist messageId so later deleteParcel can call deleteMessage.
+                    return { url: encodeTelegramChunkUrl(result.messageId, result.fileId) };
+                },
+            };
+        },
+        resolveChunk: (locator) => {
+            const { fileId } = parseTelegramChunkUrl(locator);
+            return downloadTelegramChunk(options, fileId);
+        },
+        matchesOpaqueUrl: isOpaqueChunkUrl,
+        async probe() {
+            try {
+                const me = await callTelegramApi<{ username?: string }>(options, "getMe", { method: "GET" });
+                return { ok: true as const, detail: { username: me.username ?? "unknown" } };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { ok: false as const, error: message };
+            }
+        },
+        rollbackUpload: (handles) => rollbackTelegramUploads(options, handles),
+        assertParcelRestorable: assertTelegramParcel,
+    };
+}

package/src/node/telegram/types.ts

@@ -0,0 +1,82 @@
+export interface TelegramApiResponse<T> {
+    ok: boolean;
+    description?: string;
+    result?: T;
+}
+
+export interface TelegramDocument {
+    file_id: string;
+    file_unique_id: string;
+    file_size?: number;
+}
+
+export interface TelegramMessage {
+    message_id: number;
+    document?: TelegramDocument;
+}
+
+export interface TelegramFile {
+    file_id: string;
+    file_unique_id: string;
+    file_size?: number;
+    file_path?: string;
+}
+
+export interface TelegramUploadResult {
+    fileId: string;
+    messageId: number;
+}
+
+/** Injected config for Telegram Bot API storage — do not read process.env inside SDK. */
+export interface TelegramStorageProviderOptions {
+    botToken: string;
+    chatId: string;
+    /** Default `https://api.telegram.org`. */
+    apiBaseUrl?: string;
+    /** HTTP(S) proxy for Telegram only (e.g. Clash). Supabase stays direct. */
+    proxyUrl?: string;
+    /** Default 30s — getMe / getFile. */
+    fetchTimeoutMs?: number;
+    /** Default 120s — sendDocument / file download. */
+    uploadTimeoutMs?: number;
+    /** Default 3. */
+    uploadRetryAttempts?: number;
+    /** Default 2000 — backoff base for attempt N: base * 2^(N-1). */
+    uploadRetryBaseMs?: number;
+}
+
+export interface ResolvedTelegramStorageOptions {
+    botToken: string;
+    chatId: string;
+    apiBaseUrl: string;
+    proxyUrl?: string;
+    fetchTimeoutMs: number;
+    uploadTimeoutMs: number;
+    uploadRetryAttempts: number;
+    uploadRetryBaseMs: number;
+}
+
+export function resolveTelegramStorageOptions(options: TelegramStorageProviderOptions): ResolvedTelegramStorageOptions {
+    const botToken = options.botToken.trim();
+    const chatId = options.chatId.trim();
+    if (botToken === "") {
+        throw new Error("TelegramStorageProviderOptions.botToken is required");
+    }
+    if (chatId === "") {
+        throw new Error("TelegramStorageProviderOptions.chatId is required");
+    }
+
+    const apiBaseUrl = (options.apiBaseUrl?.trim() || "https://api.telegram.org").replace(/\/$/, "");
+    const proxyUrl = options.proxyUrl?.trim() || undefined;
+
+    return {
+        botToken,
+        chatId,
+        apiBaseUrl,
+        proxyUrl: proxyUrl !== "" ? proxyUrl : undefined,
+        fetchTimeoutMs: options.fetchTimeoutMs ?? 30_000,
+        uploadTimeoutMs: options.uploadTimeoutMs ?? 120_000,
+        uploadRetryAttempts: options.uploadRetryAttempts ?? 3,
+        uploadRetryBaseMs: options.uploadRetryBaseMs ?? 2_000,
+    };
+}

package/src/node.ts

@@ -134,6 +134,29 @@ export type {
     SingleProcessServiceOptions,
 } from "./node/service-host";
 export { createL3ChildLauncher, createServiceHost, runSingleProcessService } from "./node/service-host";
+export type {
+    CallTelegramOptions,
+    ResolvedTelegramStorageOptions,
+    TelegramApiResponse,
+    TelegramChunkDeleteResult,
+    TelegramDocument,
+    TelegramFile,
+    TelegramMessage,
+    TelegramStorageProvider,
+    TelegramStorageProviderOptions,
+    TelegramUploadResult,
+} from "./node/telegram";
+export {
+    callTelegramApi,
+    createTelegramStorageProvider,
+    downloadTelegramChunk,
+    encodeTelegramChunkUrl,
+    PROVIDER_TELEGRAM,
+    parseTelegramChunkUrl,
+    resolveTelegramStorageOptions,
+    telegramDownloadBinary,
+    telegramFileDownloadUrl,
+} from "./node/telegram";
 export { RepoManager } from "./repo/repo-manager";
 export { runCollectLogTick } from "./shared/log/spool/collector";
 export { LOG_SPOOL_SERVICE_ID_ENV } from "./shared/log/spool/config";