target-supabase-sdk 0.2.16 → 0.2.18

package/dist/shared/media/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Media Link — browser-safe barrel only.
+ *
+ * Node-only code lives in `./node/` and is exported from `src/node.ts`,
+ * never from this file (see README.md).
+ */
+export type { BuildMediaLinkDraftInput } from "./media.build";
+export { buildMediaLinkDraft } from "./media.build";
+export type { MediaOriginal, MediaValue } from "./media.interface";
+export { isMediaValue, MEDIA_CONTENT_HASH_ALGORITHM, MEDIA_CONTENT_HASH_PREFIX_LENGTH, MEDIA_VALUES, } from "./media.interface";
+export { guessMediaMime } from "./media.mime";
+export { buildMediaNameFromLocator } from "./media.name";
+export { mediaLinkDedupFilters } from "./media.query";
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/media/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/media/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EACH,YAAY,EACZ,4BAA4B,EAC5B,gCAAgC,EAChC,YAAY,GACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/shared/media/media.build.d.ts

@@ -0,0 +1,20 @@
+import type { TargetDraft } from "../../core.interface";
+import type { Link } from "../../link/link.interface";
+import { type MediaValue } from "./media.interface";
+export interface BuildMediaLinkDraftInput {
+    value: MediaValue;
+    name: string;
+    storageProvider: string;
+    locator: string;
+    contentHash: string;
+    size: number;
+    mimeType: string;
+    description?: string;
+    tagList?: string[];
+}
+/**
+ * Assemble a media {@link Link} draft (`category=link`, `loaderKey === value`).
+ * Does not validate filesystem or write to Supabase.
+ */
+export declare function buildMediaLinkDraft(input: BuildMediaLinkDraftInput): TargetDraft<Link>;
+//# sourceMappingURL=media.build.d.ts.map

package/dist/shared/media/media.build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.build.d.ts","sourceRoot":"","sources":["../../../src/shared/media/media.build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEtF,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,WAAW,CAAC,IAAI,CAAC,CA+CtF"}

package/dist/shared/media/media.interface.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Media Link protocol — Link rows with value/loaderKey in {@link MEDIA_VALUES}.
+ * No separate Target category; category remains `link`.
+ */
+/** Fixed digest algorithm for single-file media `contentHash`. */
+export declare const MEDIA_CONTENT_HASH_ALGORITHM: "sha256";
+/** Hex prefix length for {@link buildMediaNameFromLocator}. */
+export declare const MEDIA_CONTENT_HASH_PREFIX_LENGTH = 6;
+export declare const MEDIA_VALUES: readonly ["video", "audio", "image", "image-list"];
+/** Discriminator stored in both `Link.value` and `details.loaderKey`. */
+export type MediaValue = (typeof MEDIA_VALUES)[number];
+/**
+ * `Link.details.original` for media Links.
+ *
+ * - `locator` — absolute filesystem path, or (future) network URL keyed by `storageProvider`.
+ * - `image-list`: `locator` is an absolute directory path; only the **immediate** children
+ *   (one level, non-recursive) are counted. `contentHash` and `mimeType` are `""`;
+ *   `size` is the number of files in that directory (not bytes).
+ * - other values: `size` is byte length; `contentHash` is SHA-256 hex; `mimeType` from the file.
+ */
+export interface MediaOriginal {
+    storageProvider: string;
+    locator: string;
+    /**
+     * SHA-256 hex of file bytes, or `""` when `value === "image-list"`.
+     * Algorithm is always {@link MEDIA_CONTENT_HASH_ALGORITHM}.
+     */
+    contentHash: string;
+    /**
+     * Single-file media: byte length.
+     * `image-list`: number of files in the directory (one level).
+     */
+    size: number;
+    /** e.g. `video/mp4`, or `""` when `value === "image-list"`. */
+    mimeType: string;
+}
+export declare function isMediaValue(value: string): value is MediaValue;
+//# sourceMappingURL=media.interface.d.ts.map

package/dist/shared/media/media.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/media/media.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kEAAkE;AAClE,eAAO,MAAM,4BAA4B,EAAG,QAAiB,CAAC;AAE9D,+DAA+D;AAC/D,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,eAAO,MAAM,YAAY,oDAAqD,CAAC;AAE/E,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D"}

package/dist/shared/media/media.mime.d.ts

@@ -0,0 +1,4 @@
+import type { MediaValue } from "./media.interface";
+/** Guess MIME from path extension; `null` when unknown. */
+export declare function guessMediaMime(locator: string, value: Exclude<MediaValue, "image-list">): string | null;
+//# sourceMappingURL=media.mime.d.ts.map

package/dist/shared/media/media.mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.mime.d.ts","sourceRoot":"","sources":["../../../src/shared/media/media.mime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAkDpD,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG,MAAM,GAAG,IAAI,CAYvG"}

package/dist/shared/media/media.name.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `{basename}.{hash6}.{ext}` from an absolute (or path-like) locator and full content hash.
+ * Does not touch the filesystem.
+ */
+export declare function buildMediaNameFromLocator(locator: string, contentHash: string): string;
+//# sourceMappingURL=media.name.d.ts.map

package/dist/shared/media/media.name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.name.d.ts","sourceRoot":"","sources":["../../../src/shared/media/media.name.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CA0BtF"}

package/dist/shared/media/media.query.d.ts

@@ -0,0 +1,8 @@
+import type { QueryFilter } from "../../core.interface";
+import type { MediaValue } from "./media.interface";
+/** Dedup key: `category=link` + `value` + `name` (matches register / find). */
+export declare function mediaLinkDedupFilters(input: {
+    value: MediaValue;
+    name: string;
+}): QueryFilter[];
+//# sourceMappingURL=media.query.d.ts.map

package/dist/shared/media/media.query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.query.d.ts","sourceRoot":"","sources":["../../../src/shared/media/media.query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CAO/F"}

package/dist/shared/media/node/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Node-only media surface — for `src/node.ts` / `target-supabase-sdk/node` only.
+ * Never re-export from `../index.ts` or `browser.ts`.
+ */
+export type { CheckMediaAvailabilityInput, MediaAvailabilityResult } from "./media.access";
+export { checkMediaAvailability, probeMediaOriginal } from "./media.access";
+export type { FindMediaLinkInput, RegisterMediaLinkInput, RegisterMediaLinkResult, } from "./media.service";
+export { findMediaLink, registerMediaLink } from "./media.service";
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/media/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/shared/media/node/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EACR,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/shared/media/node/media.access.d.ts

@@ -0,0 +1,40 @@
+import { type MediaOriginal, type MediaValue } from "../media.interface";
+export interface CheckMediaAvailabilityInput {
+    value: MediaValue;
+    storageProvider: string;
+    locator: string;
+    /**
+     * This host's storage id (e.g. from `LOCAL_STORAGE_PROVIDER`).
+     * Local path checks only run when it equals `storageProvider`.
+     */
+    localStorageProvider: string;
+}
+export interface MediaAvailabilityResult {
+    ok: boolean;
+    /** Absolute path when the locator was resolved on this host. */
+    absolutePath?: string;
+    reason?: string;
+}
+/**
+ * Fast local reachability check for a media locator.
+ *
+ * - Requires `storageProvider === localStorageProvider` (cross-host → not ok).
+ * - `locator` must be an absolute path.
+ * - `image-list`: directory exists; only immediate children are considered.
+ * - other values: path exists and is a non-empty file.
+ *
+ * **Node-only** — under `shared/media/node/`; do not import from the browser entry.
+ */
+export declare function checkMediaAvailability(input: CheckMediaAvailabilityInput): Promise<MediaAvailabilityResult>;
+/**
+ * Derive `contentHash` / `size` / `mimeType` for {@link MediaOriginal} after availability succeeds.
+ *
+ * **Node-only** — under `shared/media/node/`; do not import from the browser entry.
+ */
+export declare function probeMediaOriginal(input: {
+    value: MediaValue;
+    storageProvider: string;
+    locator: string;
+    absolutePath: string;
+}): Promise<MediaOriginal>;
+//# sourceMappingURL=media.access.d.ts.map

package/dist/shared/media/node/media.access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.access.d.ts","sourceRoot":"","sources":["../../../../src/shared/media/node/media.access.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgC,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGvG,MAAM,WAAW,2BAA2B;IACxC,KAAK,EAAE,UAAU,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACpC,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AA+BD;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA0CjH;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC5C,KAAK,EAAE,UAAU,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,aAAa,CAAC,CA4BzB"}

package/dist/shared/media/node/media.service.d.ts

@@ -0,0 +1,30 @@
+import type { Link } from "../../../link/link.interface";
+import { type MediaValue } from "../media.interface";
+export interface FindMediaLinkInput {
+    value: MediaValue;
+    name: string;
+}
+/** Dedup lookup: same `category` + `value` + `name`. */
+export declare function findMediaLink(input: FindMediaLinkInput): Promise<Link | null>;
+export interface RegisterMediaLinkInput {
+    value: MediaValue;
+    name: string;
+    storageProvider: string;
+    locator: string;
+    /** This host id for availability (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). */
+    localStorageProvider: string;
+    description?: string;
+    tagList?: string[];
+}
+export interface RegisterMediaLinkResult {
+    id: string;
+    created: boolean;
+}
+/**
+ * Register a media Link: dedup → availability → probe → `postTarget`.
+ * Idempotent when `category`+`value`+`name` already exist.
+ *
+ * **Node-only** — under `shared/media/node/`; do not import from the browser entry.
+ */
+export declare function registerMediaLink(input: RegisterMediaLinkInput): Promise<RegisterMediaLinkResult>;
+//# sourceMappingURL=media.service.d.ts.map

package/dist/shared/media/node/media.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.service.d.ts","sourceRoot":"","sources":["../../../../src/shared/media/node/media.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAGzD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMnE,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,wDAAwD;AACxD,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAYnF;AAED,MAAM,WAAW,sBAAsB;IACnC,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA4EvG"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.16",
+    "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/browser.ts

@@ -223,6 +223,17 @@ export {
     parseLogBatchMeta,
     resolveLogMinLevel,
 } from "./shared/log";
+export type { BuildMediaLinkDraftInput, MediaOriginal, MediaValue } from "./shared/media";
+export {
+    buildMediaLinkDraft,
+    buildMediaNameFromLocator,
+    guessMediaMime,
+    isMediaValue,
+    MEDIA_CONTENT_HASH_ALGORITHM,
+    MEDIA_CONTENT_HASH_PREFIX_LENGTH,
+    MEDIA_VALUES,
+    mediaLinkDedupFilters,
+} from "./shared/media";
 export { isHttpUrl, resolveFetchUrl } from "./shared/utils/fetch-url";
 export { getValueAtPath } from "./shared/utils/get-value-at-path";
 export type {

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";