target-supabase-sdk 0.2.16 → 0.2.17

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.17",
     "description": "Supabase client initializer and data access APIs",
     "license": "MIT",
     "author": "KyLoc20",

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.ts

@@ -165,6 +165,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";