target-supabase-sdk 0.2.17 → 0.2.19

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

@@ -0,0 +1,33 @@
+import type { TargetDraft } from "../../core.interface";
+import type { Link } from "../../link/link.interface";
+import { type FeedSource, type FeedValue } from "./feed.interface";
+export interface BuildFeedLinkDraftInput {
+    value: FeedValue;
+    /** Dots are normalized to spaces in {@link buildFeedLinkName} before joining with `feedKey`. */
+    platformName: string;
+    feedKey: string;
+    source: FeedSource;
+    locator: string;
+    /**
+     * Written to `original.storageProvider`. Must be empty when `source` is `.public`;
+     * required when `source` is `.local` or `.oss`.
+     */
+    storageProvider?: string;
+    description?: string;
+    preview?: string;
+    /** Locators for related resources of the same feed; stored on `original.twinList`. */
+    twinList?: string[];
+    tagList?: string[];
+}
+/** Trim entries and drop empties; `undefined` when input omitted. */
+export declare function normalizeFeedTwinList(twinList?: string[]): string[] | undefined;
+/** `original.storageProvider` from optional input and required `source` tier. */
+export declare function resolveFeedOriginalStorageProvider(source: FeedSource, storageProvider?: string): string;
+/** Merge user tags with required `source`; strip any other feed source tags from user input. */
+export declare function buildFeedTagList(source: FeedSource, tagList?: string[]): string[];
+/**
+ * Assemble a feed {@link Link} draft (`category=link`, `loaderKey === value`).
+ * Does not validate locator reachability or write to Supabase.
+ */
+export declare function buildFeedLinkDraft(input: BuildFeedLinkDraftInput): TargetDraft<Link>;
+//# sourceMappingURL=feed.build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.build.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAGH,KAAK,UAAU,EACf,KAAK,SAAS,EAGjB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,SAAS,CAAC;IACjB,gGAAgG;IAChG,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAK/E;AAED,iFAAiF;AACjF,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAcvG;AAED,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAKjF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,WAAW,CAAC,IAAI,CAAC,CA+BpF"}

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

@@ -0,0 +1,35 @@
+/**
+ * Feed Link protocol — Link rows with value/loaderKey in {@link FEED_VALUES}.
+ * No separate Target category; category remains `link`.
+ */
+export declare const FEED_VALUES: readonly ["feed.image", "feed.audio", "feed.video", "feed.image-list"];
+/** Discriminator stored in both `Link.value` and `details.loaderKey`. */
+export type FeedValue = (typeof FEED_VALUES)[number];
+/**
+ * Feed lifecycle tier — exactly one must appear in `tagList` (via `buildFeedTagList`).
+ *
+ * Leading `.` marks **system** tags (distinct from user-defined `tagList` entries).
+ */
+export declare const FEED_SOURCE_TAGS: readonly [".public", ".local", ".oss"];
+export type FeedSource = (typeof FEED_SOURCE_TAGS)[number];
+/** `registerFeed` only transitions `.public` → `.local` or `.oss`. */
+export declare const FEED_INGEST_SOURCES: readonly [".local", ".oss"];
+export type FeedIngestSource = (typeof FEED_INGEST_SOURCES)[number];
+export declare function isFeedIngestSource(value: string): value is FeedIngestSource;
+/** `Link.details.original` for feed Links. */
+export interface FeedOriginal {
+    /**
+     * Backend / host id when {@link FeedSource} is `.local` or `.oss` (e.g. `LOCAL_STORAGE_PROVIDER`).
+     * Empty string when source is `.public`.
+     */
+    storageProvider: string;
+    locator: string;
+    /**
+     * Locators for sibling resources of the same feed (e.g. other media types).
+     * Omitted when not supplied on create.
+     */
+    twinList?: string[];
+}
+export declare function isFeedValue(value: string): value is FeedValue;
+export declare function isFeedSource(value: string): value is FeedSource;
+//# sourceMappingURL=feed.interface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,WAAW,wEAAyE,CAAC;AAElG,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wCAAyC,CAAC;AAEvE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,6BAA8B,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D"}

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

@@ -0,0 +1,8 @@
+/** Normalize `platformName` so `Link.name` stays `{platform}.{feedKey}` with a single separator dot. */
+export declare function sanitizeFeedPlatformName(platformName: string): string;
+/**
+ * Default dedup `Link.name` for feed Links: `{platformName}.{feedKey}`.
+ * Dots in `platformName` are replaced with spaces before joining (see {@link sanitizeFeedPlatformName}).
+ */
+export declare function buildFeedLinkName(platformName: string, feedKey: string): string;
+//# sourceMappingURL=feed.name.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.name.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.name.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAU/E"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.query.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CAO7F"}

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

@@ -0,0 +1,13 @@
+/**
+ * Feed Link — browser-safe public barrel only.
+ *
+ * Node-only code lives in `./node/` and is exported from `src/node.ts`,
+ * never from this file.
+ */
+export type { BuildFeedLinkDraftInput } from "./feed.build";
+export { buildFeedLinkDraft } from "./feed.build";
+export type { FeedOriginal, FeedSource, FeedValue } from "./feed.interface";
+export { FEED_VALUES, isFeedValue } from "./feed.interface";
+export { buildFeedLinkName } from "./feed.name";
+export { feedLinkDedupFilters } from "./feed.query";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,34 @@
+import type { FeedValue } from "../feed.interface";
+export interface CheckFeedLocalAvailabilityInput {
+    value: FeedValue;
+    storageProvider: string;
+    locator: string;
+    /** This host id (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). */
+    localStorageProvider: string;
+}
+export interface FeedAvailabilityResult {
+    ok: boolean;
+    /** Absolute path when the locator was resolved on this host. */
+    absolutePath?: string;
+    reason?: string;
+}
+/**
+ * Local reachability for feed ingest (`.local` source).
+ *
+ * - Requires `storageProvider === localStorageProvider`.
+ * - `locator` must be an absolute path.
+ * - `feed.image-list`: directory exists.
+ * - Other feed values: non-empty file.
+ *
+ * **Node-only**
+ */
+export declare function checkFeedLocalAvailability(input: CheckFeedLocalAvailabilityInput): Promise<FeedAvailabilityResult>;
+/**
+ * Remote reachability for feed ingest (`.oss` source) via HTTP(S).
+ *
+ * Tries `HEAD`, then `GET` with `Range: bytes=0-0` when `HEAD` is not allowed.
+ *
+ * **Node-only**
+ */
+export declare function checkFeedOssAvailability(locator: string): Promise<FeedAvailabilityResult>;
+//# sourceMappingURL=feed.access.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.access.d.ts","sourceRoot":"","sources":["../../../../src/shared/feed/node/feed.access.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,+BAA+B;IAC5C,KAAK,EAAE,SAAS,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC5C,KAAK,EAAE,+BAA+B,GACvC,OAAO,CAAC,sBAAsB,CAAC,CA0CjC;AAoBD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAsB/F"}

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

@@ -0,0 +1,23 @@
+import { type FeedIngestSource } from "../feed.interface";
+export interface RegisterFeedInput {
+    /** Existing feed Link row id (must still be `.public` unless already ingested with same payload). */
+    id: string;
+    source: FeedIngestSource;
+    storageProvider: string;
+    locator: string;
+    /** Required when `source` is `.local` (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). Ignored for `.oss`. */
+    localStorageProvider?: string;
+}
+export interface RegisterFeedResult {
+    id: string;
+    /** `false` when row was already ingested with the same source, storageProvider, and locator. */
+    updated: boolean;
+}
+/**
+ * Ingest a `.public` feed Link: validate locator, then promote `tagList` source to `.local` or `.oss`
+ * and update `details.original.storageProvider` + `locator`.
+ *
+ * **Node-only** — under `shared/feed/node/`; do not import from the browser entry.
+ */
+export declare function registerFeed(input: RegisterFeedInput): Promise<RegisterFeedResult>;
+//# sourceMappingURL=feed.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.service.d.ts","sourceRoot":"","sources":["../../../../src/shared/feed/node/feed.service.ts"],"names":[],"mappings":"AAKA,OAAO,EACH,KAAK,gBAAgB,EAKxB,MAAM,mBAAmB,CAAC;AAK3B,MAAM,WAAW,iBAAiB;IAC9B,qGAAqG;IACrG,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,gGAAgG;IAChG,OAAO,EAAE,OAAO,CAAC;CACpB;AAmDD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+FxF"}

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

@@ -0,0 +1,11 @@
+/**
+ * Node-only feed surface — for `src/node.ts` / `target-supabase-sdk/node` only.
+ * Never re-export from `../index.ts` or `browser.ts`.
+ */
+export type { FeedIngestSource } from "../feed.interface";
+export { FEED_INGEST_SOURCES, isFeedIngestSource } from "../feed.interface";
+export type { CheckFeedLocalAvailabilityInput, FeedAvailabilityResult } from "./feed.access";
+export { checkFeedLocalAvailability, checkFeedOssAvailability } from "./feed.access";
+export type { RegisterFeedInput, RegisterFeedResult } from "./feed.service";
+export { registerFeed } from "./feed.service";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/shared/feed/node/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,+BAA+B,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACrF,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.17",
+    "version": "0.2.19",
     "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

@@ -189,7 +189,14 @@ export {
     unregisterService,
     unregisterServiceAtShutdown,
 } from "./service/index";
-
+export type { BuildFeedLinkDraftInput, FeedOriginal, FeedSource, FeedValue } from "./shared/feed";
+export {
+    buildFeedLinkDraft,
+    buildFeedLinkName,
+    FEED_VALUES,
+    feedLinkDedupFilters,
+    isFeedValue,
+} from "./shared/feed";
 export type { FetchInitFactory, FetchRetryOptions } from "./shared/http/fetch-retry";
 export {
     fetchBinaryWithRetry,

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,
+    };
+}