target-supabase-sdk 0.2.17 → 0.2.19

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,7 +134,44 @@ 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 type {
+    CheckFeedLocalAvailabilityInput,
+    FeedAvailabilityResult,
+    FeedIngestSource,
+    RegisterFeedInput,
+    RegisterFeedResult,
+} from "./shared/feed/node";
+export {
+    checkFeedLocalAvailability,
+    checkFeedOssAvailability,
+    FEED_INGEST_SOURCES,
+    isFeedIngestSource,
+    registerFeed,
+} from "./shared/feed/node";
 export { runCollectLogTick } from "./shared/log/spool/collector";
 export { LOG_SPOOL_SERVICE_ID_ENV } from "./shared/log/spool/config";
 export type { LogSpoolCoordinator, LogSpoolCoordinatorOptions } from "./shared/log/spool/coordinator";

package/src/shared/feed/README.md

@@ -0,0 +1,163 @@
+# Feed Links (`shared/feed`)
+
+Feed is a **convention on `Link`**, not a new Target category (`category` stays `link`).
+
+```text
+src/shared/feed/
+  index.ts              ← browser-safe barrel ONLY (never export ./node)
+  feed.interface.ts
+  feed.build.ts
+  feed.name.ts
+  feed.query.ts
+  README.md
+  node/                 ← Node-only (ingest / availability)
+    index.ts            ← barrel for src/node.ts only
+    feed.access.ts
+    feed.service.ts
+```
+
+## Package entry split
+
+| Consumer import | What you get | Source |
+|-----------------|--------------|--------|
+| `from "target-supabase-sdk"` | Draft, name, tag merge, dedup filters | `shared/feed/index.ts` → `browser.ts` |
+| `from "target-supabase-sdk/node"` | + `registerFeed`, availability checks | `shared/feed/node/` → `node.ts` |
+
+**Do not** re-export `./node` from `index.ts` / `browser.ts`.
+
+```typescript
+// Default / browser — create draft, dedup, recognize feed Links
+import {
+  buildFeedLinkDraft,
+  buildFeedLinkName,
+  feedLinkDedupFilters,
+  FEED_VALUES,
+  isFeedValue,
+} from "target-supabase-sdk";
+
+// Node — ingest after .public draft exists
+import { registerFeed, FEED_INGEST_SOURCES } from "target-supabase-sdk/node";
+```
+
+---
+
+## Lifecycle
+
+1. **Create (browser or any host)** — `buildFeedLinkDraft` with `source: ".public"`, public `locator` (often a platform URL), `original.storageProvider: ""`. Persist via `postTarget` / `createTarget`.
+2. **Ingest (Node)** — `registerFeed` on an existing row `id`: validate the new locator, then promote `tagList` from `.public` to `.local` or `.oss` and update `original.storageProvider` + `locator`. Preserves `twinList` and other non-source tags.
+
+---
+
+## Link field rules
+
+| Field | Rule |
+|-------|------|
+| `value` | `feed.image` \| `feed.audio` \| `feed.video` \| `feed.image-list` |
+| `details.loaderKey` | Always equals `value` |
+| `name` | `{platformName}.{feedKey}` via `buildFeedLinkName` |
+| Dedup | `category=link` + `value` + `name` (`feedLinkDedupFilters`) |
+| `tagList` | Exactly one feed **system** source tag (`.public` \| `.local` \| `.oss`) |
+| `description` / `preview` | Optional; default `""` |
+
+### Naming
+
+- `sanitizeFeedPlatformName` replaces `.` in `platformName` with spaces before ``${platform}.${feedKey}``.
+
+---
+
+## `details.original`
+
+| Key | `.public` draft | After ingest |
+|-----|-----------------|--------------|
+| `storageProvider` | `""` | Backend id (required for `.local` / `.oss`) |
+| `locator` | Public / platform locator | Validated path (`.local`) or URL (`.oss`) |
+| `twinList` | Optional sibling locators | Unchanged by `registerFeed` |
+
+---
+
+## System vs user tags
+
+Leading `.` marks **system** tags (not user tags).
+
+| Tag | Meaning |
+|-----|---------|
+| `.public` | Public-network link; ingest when stable copy exists |
+| `.local` | In Target on this device (`LOCAL_STORAGE_PROVIDER` + absolute file/dir path) |
+| `.oss` | In Target on shared storage (HTTP(S) locator must respond) |
+
+`buildFeedTagList` strips `.public` / `.local` / `.oss` from user input and appends the chosen `source` once.
+
+---
+
+## Register flow (`registerFeed`)
+
+**Input**
+
+| Field | Rule |
+|-------|------|
+| `id` | Existing feed Link row |
+| `source` | `.local` or `.oss` only |
+| `storageProvider` | Non-empty (validated by `resolveFeedOriginalStorageProvider`) |
+| `locator` | New canonical locator after ingest |
+| `localStorageProvider` | **Required** when `source` is `.local` (typically `process.env.LOCAL_STORAGE_PROVIDER`). Ignored for `.oss`. |
+
+**Steps**
+
+1. Load target by `id`; must be `category=link` with `isFeedValue(value)` and `loaderKey === value`.
+2. **Idempotent** — if `tagList` already has the target `source` and `original` matches `storageProvider` + `locator` → `{ id, updated: false }`.
+3. Require `tagList` to include `.public` (not already ingested with different state).
+4. **Availability**
+   - `.local` — `checkFeedLocalAvailability`: `storageProvider === localStorageProvider`, absolute path, file (or directory for `feed.image-list`) exists and is non-empty where applicable.
+   - `.oss` — `checkFeedOssAvailability`: `http(s)` URL; `HEAD`, then `GET` with `Range: bytes=0-0` if `HEAD` is not supported.
+5. **Update** — `updateTarget` with optimistic lock `details->original->>storageProvider` eq `""` (still `.public` tier). Sets `tagList` via `buildFeedTagList`, updates `original.storageProvider` and `locator`, keeps `twinList`.
+
+**Errors (representative)**
+
+| Condition | Result |
+|-----------|--------|
+| Not a feed Link | throw |
+| Already `.local`/`.oss` with different locator | throw |
+| Missing `.public` tag | throw |
+| Locator check fails | throw |
+| Concurrent ingest (storageProvider already set) | optimistic lock failure |
+
+```typescript
+import { registerFeed } from "target-supabase-sdk/node";
+
+const { id, updated } = await registerFeed({
+  id: feedLinkId,
+  source: ".local",
+  storageProvider: process.env.LOCAL_STORAGE_PROVIDER!,
+  locator: "D:\\\\data\\\\feeds\\\\bilibili.12345.mp4",
+  localStorageProvider: process.env.LOCAL_STORAGE_PROVIDER!,
+});
+```
+
+---
+
+## Env (Node hosts)
+
+| Variable | Role |
+|----------|------|
+| `LOCAL_STORAGE_PROVIDER` | This machine’s storage id; pass as both `storageProvider` and `localStorageProvider` for `.local` ingest on this host |
+
+Same variable as media register — see `src/shared/media/README.md`.
+
+---
+
+## Design notes / limitations
+
+| Topic | Current behavior | Possible follow-up |
+|-------|------------------|-------------------|
+| OSS auth | Only anonymous `HEAD`/`GET` | Signed URLs or provider-specific probes |
+| `.local` on another host | Fails availability (by design, like media) | Remote agent ingest |
+| `twinList` on ingest | Not re-validated | Optional probe per twin |
+| Re-ingest / migrate `.local` → `.oss` | Not supported | New API with lock on prior source tag |
+
+---
+
+## Related
+
+- `.cursor/skills/feed-link/SKILL.md`
+- Media register pattern: `src/shared/media/README.md`
+- Optimistic lock: `.cursor/skills/optimistic-lock-update/SKILL.md`

package/src/shared/feed/feed.build.ts

@@ -0,0 +1,101 @@
+import type { TargetDraft } from "../../core.interface";
+import { buildLinkTargetDraft } from "../../link/link.build";
+import type { Link } from "../../link/link.interface";
+import {
+    FEED_SOURCE_TAGS,
+    type FeedOriginal,
+    type FeedSource,
+    type FeedValue,
+    isFeedSource,
+    isFeedValue,
+} from "./feed.interface";
+import { buildFeedLinkName } from "./feed.name";
+
+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 function normalizeFeedTwinList(twinList?: string[]): string[] | undefined {
+    if (twinList === undefined) {
+        return undefined;
+    }
+    return twinList.map((entry) => entry.trim()).filter((entry) => entry !== "");
+}
+
+/** `original.storageProvider` from optional input and required `source` tier. */
+export function resolveFeedOriginalStorageProvider(source: FeedSource, storageProvider?: string): string {
+    const trimmed = storageProvider?.trim() ?? "";
+    if (source === ".public") {
+        if (trimmed !== "") {
+            throw new Error("resolveFeedOriginalStorageProvider: storageProvider must be empty when source is .public");
+        }
+        return "";
+    }
+    if (trimmed === "") {
+        throw new Error(
+            "resolveFeedOriginalStorageProvider: storageProvider is required when source is .local or .oss",
+        );
+    }
+    return trimmed;
+}
+
+/** Merge user tags with required `source`; strip any other feed source tags from user input. */
+export function buildFeedTagList(source: FeedSource, tagList?: string[]): string[] {
+    const sourceSet = new Set<string>(FEED_SOURCE_TAGS);
+    const user = tagList ?? [];
+    const filtered = user.filter((tag) => !sourceSet.has(tag));
+    return [...filtered, source];
+}
+
+/**
+ * Assemble a feed {@link Link} draft (`category=link`, `loaderKey === value`).
+ * Does not validate locator reachability or write to Supabase.
+ */
+export function buildFeedLinkDraft(input: BuildFeedLinkDraftInput): TargetDraft<Link> {
+    if (!isFeedValue(input.value)) {
+        throw new Error(`buildFeedLinkDraft: unsupported feed value: ${String(input.value)}`);
+    }
+    if (!isFeedSource(input.source)) {
+        throw new Error(`buildFeedLinkDraft: unsupported feed source: ${String(input.source)}`);
+    }
+
+    const name = buildFeedLinkName(input.platformName, input.feedKey);
+    const locator = input.locator.trim();
+    if (locator === "") {
+        throw new Error("buildFeedLinkDraft: locator is empty");
+    }
+
+    const twinList = normalizeFeedTwinList(input.twinList);
+    const storageProvider = resolveFeedOriginalStorageProvider(input.source, input.storageProvider);
+    const original: FeedOriginal = {
+        storageProvider,
+        locator,
+        ...(twinList !== undefined ? { twinList } : {}),
+    };
+
+    return buildLinkTargetDraft({
+        name,
+        value: input.value,
+        description: input.description ?? "",
+        preview: input.preview ?? "",
+        loaderKey: input.value,
+        tagList: buildFeedTagList(input.source, input.tagList),
+        original,
+    });
+}

package/src/shared/feed/feed.interface.ts

@@ -0,0 +1,50 @@
+/**
+ * Feed Link protocol — Link rows with value/loaderKey in {@link FEED_VALUES}.
+ * No separate Target category; category remains `link`.
+ */
+
+export const FEED_VALUES = ["feed.image", "feed.audio", "feed.video", "feed.image-list"] as const;
+
+/** 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 const FEED_SOURCE_TAGS = [".public", ".local", ".oss"] as const;
+
+export type FeedSource = (typeof FEED_SOURCE_TAGS)[number];
+
+/** `registerFeed` only transitions `.public` → `.local` or `.oss`. */
+export const FEED_INGEST_SOURCES = [".local", ".oss"] as const;
+
+export type FeedIngestSource = (typeof FEED_INGEST_SOURCES)[number];
+
+export function isFeedIngestSource(value: string): value is FeedIngestSource {
+    return (FEED_INGEST_SOURCES as readonly string[]).includes(value);
+}
+
+/** `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 function isFeedValue(value: string): value is FeedValue {
+    return (FEED_VALUES as readonly string[]).includes(value);
+}
+
+export function isFeedSource(value: string): value is FeedSource {
+    return (FEED_SOURCE_TAGS as readonly string[]).includes(value);
+}

package/src/shared/feed/feed.name.ts

@@ -0,0 +1,20 @@
+/** Normalize `platformName` so `Link.name` stays `{platform}.{feedKey}` with a single separator dot. */
+export function sanitizeFeedPlatformName(platformName: string): string {
+    return platformName.trim().replaceAll(".", " ");
+}
+
+/**
+ * Default dedup `Link.name` for feed Links: `{platformName}.{feedKey}`.
+ * Dots in `platformName` are replaced with spaces before joining (see {@link sanitizeFeedPlatformName}).
+ */
+export function buildFeedLinkName(platformName: string, feedKey: string): string {
+    const platform = sanitizeFeedPlatformName(platformName);
+    const key = feedKey.trim();
+    if (platform === "") {
+        throw new Error("buildFeedLinkName: platformName is empty");
+    }
+    if (key === "") {
+        throw new Error("buildFeedLinkName: feedKey is empty");
+    }
+    return `${platform}.${key}`;
+}

package/src/shared/feed/feed.query.ts

@@ -0,0 +1,13 @@
+import type { QueryFilter } from "../../core.interface";
+import { CategoryLink } from "../../link/link.interface";
+import type { FeedValue } from "./feed.interface";
+
+/** Dedup key: `category=link` + `value` + `name` (matches register / find). */
+export function feedLinkDedupFilters(input: { value: FeedValue; name: string }): QueryFilter[] {
+    const name = input.name.trim();
+    return [
+        { field: "category", operator: "eq", value: CategoryLink.LINK },
+        { field: "value", operator: "eq", value: input.value },
+        { field: "name", operator: "eq", value: name },
+    ];
+}

package/src/shared/feed/index.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";

package/src/shared/feed/node/feed.access.ts

@@ -0,0 +1,134 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+
+import { fetchWithRetry } from "../../http/fetch-retry";
+import { isHttpUrl } from "../../utils/fetch-url";
+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;
+}
+
+function sameStorageHost(storageProvider: string, localStorageProvider: string): boolean {
+    return storageProvider.trim() === localStorageProvider.trim();
+}
+
+function isFeedDirectoryValue(value: FeedValue): boolean {
+    return value === "feed.image-list";
+}
+
+/**
+ * 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 async function checkFeedLocalAvailability(
+    input: CheckFeedLocalAvailabilityInput,
+): Promise<FeedAvailabilityResult> {
+    const storageProvider = input.storageProvider.trim();
+    const localStorageProvider = input.localStorageProvider.trim();
+    const locator = input.locator.trim();
+
+    if (storageProvider === "" || localStorageProvider === "") {
+        return { ok: false, reason: "storageProvider and localStorageProvider are required" };
+    }
+    if (locator === "") {
+        return { ok: false, reason: "locator is empty" };
+    }
+    if (!sameStorageHost(storageProvider, localStorageProvider)) {
+        return {
+            ok: false,
+            reason: `storageProvider not on this host (${storageProvider} !== ${localStorageProvider})`,
+        };
+    }
+    if (!isAbsolute(locator)) {
+        return { ok: false, reason: `locator must be an absolute path: ${locator}` };
+    }
+
+    const absolutePath = resolve(locator);
+
+    try {
+        const info = await stat(absolutePath);
+        if (isFeedDirectoryValue(input.value)) {
+            if (!info.isDirectory()) {
+                return { ok: false, reason: `feed.image-list locator is not a directory: ${absolutePath}` };
+            }
+            return { ok: true, absolutePath };
+        }
+        if (!info.isFile()) {
+            return { ok: false, reason: `locator is not a file: ${absolutePath}` };
+        }
+        if (info.size <= 0) {
+            return { ok: false, reason: `file is empty: ${absolutePath}` };
+        }
+        return { ok: true, absolutePath };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `locator not reachable: ${absolutePath} (${message})` };
+    }
+}
+
+const OSS_CHECK_TIMEOUT_MS = 15_000;
+const OSS_CHECK_MAX_ATTEMPTS = 2;
+
+async function probeHttpLocator(locator: string, method: "HEAD" | "GET"): Promise<Response> {
+    return fetchWithRetry(
+        locator,
+        {
+            method,
+            ...(method === "GET" ? { headers: { Range: "bytes=0-0" } } : {}),
+        },
+        {
+            label: "feed-oss-check",
+            timeoutMs: OSS_CHECK_TIMEOUT_MS,
+            maxAttempts: OSS_CHECK_MAX_ATTEMPTS,
+        },
+    );
+}
+
+/**
+ * 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 async function checkFeedOssAvailability(locator: string): Promise<FeedAvailabilityResult> {
+    const trimmed = locator.trim();
+    if (trimmed === "") {
+        return { ok: false, reason: "locator is empty" };
+    }
+    if (!isHttpUrl(trimmed)) {
+        return { ok: false, reason: `oss locator must be an http(s) URL: ${trimmed}` };
+    }
+
+    try {
+        let response = await probeHttpLocator(trimmed, "HEAD");
+        if (response.status === 405 || response.status === 501) {
+            response = await probeHttpLocator(trimmed, "GET");
+        }
+        if (response.ok || (response.status >= 200 && response.status < 400)) {
+            return { ok: true };
+        }
+        return { ok: false, reason: `oss locator HTTP ${response.status}: ${trimmed}` };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `oss locator request failed: ${trimmed} (${message})` };
+    }
+}