target-supabase-sdk 0.2.16 → 0.2.18

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";
@@ -165,6 +188,19 @@ export {
     shutdownLogSpool,
 } from "./shared/log/spool/service-lifecycle";
 export type { LogBatchMeta, LogPersistLane } from "./shared/log/upload/interface";
+export type {
+    CheckMediaAvailabilityInput,
+    FindMediaLinkInput,
+    MediaAvailabilityResult,
+    RegisterMediaLinkInput,
+    RegisterMediaLinkResult,
+} from "./shared/media/node";
+export {
+    checkMediaAvailability,
+    findMediaLink,
+    probeMediaOriginal,
+    registerMediaLink,
+} from "./shared/media/node";
 export type {
     ConfigSchema,
     LoadCachedJsConfigOptions,

package/src/shared/media/README.md

@@ -0,0 +1,109 @@
+# Media Links (`shared/media`)
+
+Media is a **convention on `Link`**, not a new Target category (`category` stays `link`).
+
+All media code lives under **`src/shared/media/`**. Node-only modules are kept in the **`node/`** subdirectory so the filesystem path matches the package entry split.
+
+## Package entry split (important)
+
+| Consumer import | What you get | Source |
+|-----------------|--------------|--------|
+| `from "target-supabase-sdk"` | Browser-safe helpers only | `shared/media/index.ts` → `browser.ts` |
+| `from "target-supabase-sdk/node"` | + register / availability / probe | `shared/media/node/` → `node.ts` |
+
+There is **no** public subpath like `target-supabase-sdk/shared/media/node` — consumers always use the package `/node` entry.
+
+**Do not** re-export anything from `node/` in `index.ts` / `browser.ts`. Those files import `node:fs` / `node:crypto` / `node:path`. Pulling them into the default entry breaks Chrome/Webpack bundles (`verify-browser-entry` will fail).
+
+```text
+src/shared/media/
+  index.ts              ← browser-safe barrel ONLY (never export ./node)
+  media.interface.ts
+  media.build.ts
+  media.mime.ts
+  media.name.ts
+  media.query.ts
+  README.md
+  node/                 ← Node-only (fs / register)
+    index.ts            ← barrel for src/node.ts only
+    media.access.ts
+    media.service.ts
+```
+
+### Correct consumer imports
+
+```typescript
+// Default / browser — draft, mime, name, filters
+import {
+  buildMediaLinkDraft,
+  buildMediaNameFromLocator,
+  MEDIA_VALUES,
+  mediaLinkDedupFilters,
+} from "target-supabase-sdk";
+
+// Node workers / CLI — dedup + availability + register
+import {
+  findMediaLink,
+  checkMediaAvailability,
+  registerMediaLink,
+} from "target-supabase-sdk/node";
+```
+
+### Incorrect
+
+```typescript
+// BAD: Node-only APIs are not on the default entry
+import { registerMediaLink } from "target-supabase-sdk";
+```
+
+Internal SDK code:
+
+- Browser-safe leaves: `from "../media.build"` (etc.)
+- Node leaves: `from "./media.access"` inside `node/`, or `from "../shared/media/node"` from `src/node.ts`
+- Never pull `./node` through the parent `index.ts`
+
+---
+
+## Link field rules
+
+| Field | Rule |
+|-------|------|
+| `value` | `video` \| `audio` \| `image` \| `image-list` |
+| `details.loaderKey` | Always equals `value` |
+| `name` | Caller-provided unique key (or `buildMediaNameFromLocator`) |
+| `tagList` / `description` | Caller-defined (e.g. producer / scene tags) |
+| `details.manifestVersion` | `0` (via `buildLinkTargetDraft`) |
+| `details.preview` | `""` |
+
+## `details.original`
+
+| Key | Single file (`video`/`audio`/`image`) | `image-list` |
+|-----|----------------------------------------|--------------|
+| `storageProvider` | Host / backend id (e.g. `windows-storage:HOSTNAME`) | same |
+| `locator` | Absolute file path | Absolute **directory** path |
+| `contentHash` | SHA-256 hex (`MEDIA_CONTENT_HASH_ALGORITHM`) | `""` |
+| `size` | Byte length | File count (immediate children only, non-recursive) |
+| `mimeType` | e.g. `video/mp4` | `""` |
+
+`image-list` rules:
+
+1. `locator` must be an **absolute** directory path.
+2. Only **one level** under that directory is considered (no recursion).
+3. `size` counts **files** in that level (directories among children are ignored).
+
+## Register flow (`registerMediaLink`)
+
+1. **Dedup** — `category` + `value` + `name` via `findMediaLink`. If present → `{ id, created: false }`.
+2. **Availability** — `storageProvider` must equal `localStorageProvider` (typically `LOCAL_STORAGE_PROVIDER` from the service `.env`); `locator` absolute and reachable.
+3. **Probe** — stream SHA-256 / `stat` / MIME (or directory file count for `image-list`).
+4. **Insert** — `buildMediaLinkDraft` → `postTarget` (race → re-find).
+
+## Env (Node hosts)
+
+| Variable | Role |
+|----------|------|
+| `LOCAL_STORAGE_PROVIDER` | This machine’s storage id; pass as `localStorageProvider` into availability / register |
+
+Cross-host `storageProvider` cannot be verified on the current process — availability returns `ok: false`.
+
+See `.cursor/skills/media-link/SKILL.md`.

package/src/shared/media/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 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";

package/src/shared/media/media.build.ts

@@ -0,0 +1,69 @@
+import type { TargetDraft } from "../../core.interface";
+import { buildLinkTargetDraft } from "../../link/link.build";
+import type { Link } from "../../link/link.interface";
+import { isMediaValue, type MediaOriginal, 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 function buildMediaLinkDraft(input: BuildMediaLinkDraftInput): TargetDraft<Link> {
+    if (!isMediaValue(input.value)) {
+        throw new Error(`buildMediaLinkDraft: unsupported media value: ${String(input.value)}`);
+    }
+    const name = input.name.trim();
+    if (name === "") {
+        throw new Error("buildMediaLinkDraft: name is empty");
+    }
+    const storageProvider = input.storageProvider.trim();
+    if (storageProvider === "") {
+        throw new Error("buildMediaLinkDraft: storageProvider is empty");
+    }
+    const locator = input.locator.trim();
+    if (locator === "") {
+        throw new Error("buildMediaLinkDraft: locator is empty");
+    }
+    if (!Number.isFinite(input.size) || input.size < 0) {
+        throw new Error("buildMediaLinkDraft: size must be a non-negative number");
+    }
+
+    const isList = input.value === "image-list";
+    const contentHash = isList ? "" : input.contentHash.trim().toLowerCase();
+    const mimeType = isList ? "" : input.mimeType.trim();
+    if (!isList && contentHash === "") {
+        throw new Error("buildMediaLinkDraft: contentHash is required for single-file media");
+    }
+    if (!isList && mimeType === "") {
+        throw new Error("buildMediaLinkDraft: mimeType is required for single-file media");
+    }
+
+    const original: MediaOriginal = {
+        storageProvider,
+        locator,
+        contentHash,
+        size: Math.floor(input.size),
+        mimeType,
+    };
+
+    return buildLinkTargetDraft({
+        name,
+        value: input.value,
+        description: input.description ?? "",
+        preview: "",
+        loaderKey: input.value,
+        tagList: input.tagList ?? [],
+        original,
+    });
+}

package/src/shared/media/media.interface.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 const MEDIA_CONTENT_HASH_ALGORITHM = "sha256" as const;
+
+/** Hex prefix length for {@link buildMediaNameFromLocator}. */
+export const MEDIA_CONTENT_HASH_PREFIX_LENGTH = 6;
+
+export const MEDIA_VALUES = ["video", "audio", "image", "image-list"] as const;
+
+/** 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 function isMediaValue(value: string): value is MediaValue {
+    return (MEDIA_VALUES as readonly string[]).includes(value);
+}

package/src/shared/media/media.mime.ts

@@ -0,0 +1,64 @@
+import type { MediaValue } from "./media.interface";
+
+const VIDEO_EXT_MIME: Record<string, string> = {
+    mp4: "video/mp4",
+    m4v: "video/mp4",
+    mov: "video/quicktime",
+    mkv: "video/x-matroska",
+    webm: "video/webm",
+    avi: "video/x-msvideo",
+    mpeg: "video/mpeg",
+    mpg: "video/mpeg",
+    wmv: "video/x-ms-wmv",
+    flv: "video/x-flv",
+    ts: "video/mp2t",
+    m2ts: "video/mp2t",
+};
+
+const AUDIO_EXT_MIME: Record<string, string> = {
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    m4a: "audio/mp4",
+    aac: "audio/aac",
+    flac: "audio/flac",
+    ogg: "audio/ogg",
+    oga: "audio/ogg",
+    opus: "audio/opus",
+    wma: "audio/x-ms-wma",
+};
+
+const IMAGE_EXT_MIME: Record<string, string> = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    webp: "image/webp",
+    gif: "image/gif",
+    bmp: "image/bmp",
+    tif: "image/tiff",
+    tiff: "image/tiff",
+};
+
+function extensionOf(pathOrUrl: string): string {
+    const cleaned = pathOrUrl.split(/[?#]/)[0] ?? pathOrUrl;
+    const base = cleaned.replace(/\\/g, "/").split("/").pop() ?? cleaned;
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1) {
+        return "";
+    }
+    return base.slice(dot + 1).toLowerCase();
+}
+
+/** Guess MIME from path extension; `null` when unknown. */
+export function guessMediaMime(locator: string, value: Exclude<MediaValue, "image-list">): string | null {
+    const ext = extensionOf(locator);
+    if (ext === "") {
+        return null;
+    }
+    if (value === "video") {
+        return VIDEO_EXT_MIME[ext] ?? null;
+    }
+    if (value === "audio") {
+        return AUDIO_EXT_MIME[ext] ?? null;
+    }
+    return IMAGE_EXT_MIME[ext] ?? null;
+}

package/src/shared/media/media.name.ts

@@ -0,0 +1,33 @@
+import { MEDIA_CONTENT_HASH_PREFIX_LENGTH } from "./media.interface";
+
+/**
+ * `{basename}.{hash6}.{ext}` from an absolute (or path-like) locator and full content hash.
+ * Does not touch the filesystem.
+ */
+export function buildMediaNameFromLocator(locator: string, contentHash: string): string {
+    const trimmedLocator = locator.trim();
+    if (trimmedLocator === "") {
+        throw new Error("buildMediaNameFromLocator: locator is empty");
+    }
+    const hash = contentHash.trim().toLowerCase();
+    if (hash.length < MEDIA_CONTENT_HASH_PREFIX_LENGTH) {
+        throw new Error(
+            `buildMediaNameFromLocator: contentHash must be at least ${MEDIA_CONTENT_HASH_PREFIX_LENGTH} hex chars`,
+        );
+    }
+    const hash6 = hash.slice(0, MEDIA_CONTENT_HASH_PREFIX_LENGTH);
+
+    const normalized = trimmedLocator.replace(/\\/g, "/");
+    const base = normalized.split("/").pop() ?? normalized;
+    if (base === "" || base === "." || base === "..") {
+        throw new Error(`buildMediaNameFromLocator: invalid basename from locator: ${locator}`);
+    }
+
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1) {
+        return `${base}.${hash6}`;
+    }
+    const stem = base.slice(0, dot);
+    const ext = base.slice(dot + 1);
+    return `${stem}.${hash6}.${ext}`;
+}

package/src/shared/media/media.query.ts

@@ -0,0 +1,13 @@
+import type { QueryFilter } from "../../core.interface";
+import { CategoryLink } from "../../link/link.interface";
+import type { MediaValue } from "./media.interface";
+
+/** Dedup key: `category=link` + `value` + `name` (matches register / find). */
+export function mediaLinkDedupFilters(input: { value: MediaValue; 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/media/node/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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";