target-supabase-sdk 0.2.20 → 0.2.22

package/src/shared/http/fetch-retry.ts

@@ -28,6 +28,8 @@ export interface FetchRetryOptions {
     /** When set, retry/success lines are logged via SDK logger. */
     logger?: LoggerWithScope;
     hint?: string;
+    /** Override global `fetch` (e.g. proxied outbound fetch). Ignores `dispatcher`. */
+    fetch?: (url: string, init?: RequestInit) => Promise<Response>;
 }
 
 function backoffMs(retryBaseMs: number, attempt: number, response?: Response, maxBackoffMs?: number): number {
@@ -47,11 +49,20 @@ function backoffMs(retryBaseMs: number, attempt: number, response?: Response, ma
     return delayMs;
 }
 
-async function fetchOnce(url: string, init: RequestInit, timeoutMs: number, dispatcher?: unknown): Promise<Response> {
+async function fetchOnce(
+    url: string,
+    init: RequestInit,
+    timeoutMs: number,
+    dispatcher?: unknown,
+    fetchImpl?: (url: string, init?: RequestInit) => Promise<Response>,
+): Promise<Response> {
     const options: RequestInit & { dispatcher?: unknown } = {
         ...init,
         signal: AbortSignal.timeout(timeoutMs),
     };
+    if (fetchImpl != null) {
+        return fetchImpl(url, options);
+    }
     if (dispatcher != null) {
         options.dispatcher = dispatcher;
     }
@@ -76,7 +87,7 @@ export async function fetchWithRetry(
 
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {
-            const response = await fetchOnce(url, buildInit(), options.timeoutMs, options.dispatcher);
+            const response = await fetchOnce(url, buildInit(), options.timeoutMs, options.dispatcher, options.fetch);
 
             if (!response.ok && isRetryableStatus(response.status) && attempt < maxAttempts) {
                 const delayMs = backoffMs(retryBaseMs, attempt, response, options.maxBackoffMs);

package/src/shared/media/README.md

@@ -93,10 +93,10 @@ Internal SDK code:
 
 ## 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).
+1. **Dedup** — `category` + `value` + `name` via `findMediaLink`. Local locator: if present → `{ id, created: false }`. HTTP locator: patch `original` when storage/locator differ.
+2. **Availability** — local path: `storageProvider` must equal `localStorageProvider`; `locator` absolute and reachable. HTTP `locator`: require `localLocator` and probe that file on `localStorageProvider`.
+3. **Probe** — stream SHA-256 / `stat` / MIME (or directory file count for `image-list`) from the local file.
+4. **Insert** — `buildMediaLinkDraft` → `postTarget` (race → re-find / HTTP patch). Persisted `locator` may be the HTTP URL.
 
 ## Env (Node hosts)
 

package/src/shared/media/node/media.service.ts

@@ -1,6 +1,7 @@
-import { getPossibleTarget, isCreateTargetAlreadyExistsError, postTarget } from "../../../core.api";
-import type { Link } from "../../../link/link.interface";
+import { getPossibleTarget, isCreateTargetAlreadyExistsError, postTarget, updateTarget } from "../../../core.api";
+import { CategoryLink, type Link, type LinkDetails } from "../../../link/link.interface";
 import { createLogger } from "../../log/core/create-logger";
+import { isHttpUrl } from "../../utils/fetch-url";
 import { buildMediaLinkDraft } from "../media.build";
 import { isMediaValue, type MediaValue } from "../media.interface";
 import { mediaLinkDedupFilters } from "../media.query";
@@ -35,6 +36,11 @@ export interface RegisterMediaLinkInput {
     locator: string;
     /** This host id for availability (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). */
     localStorageProvider: string;
+    /**
+     * Local file to probe when `locator` is http(s) (OSS ingest).
+     * Availability uses this path + `localStorageProvider`.
+     */
+    localLocator?: string;
     description?: string;
     tagList?: string[];
 }
@@ -44,9 +50,53 @@ export interface RegisterMediaLinkResult {
     created: boolean;
 }
 
+function mediaOriginalFromRow(row: { details?: unknown }): { storageProvider?: string; locator?: string } {
+    const details = row.details as LinkDetails | undefined;
+    const original = details?.original as { storageProvider?: string; locator?: string } | undefined;
+    return original ?? {};
+}
+
+async function patchMediaOriginal(
+    existing: Link,
+    storageProvider: string,
+    locator: string,
+): Promise<RegisterMediaLinkResult> {
+    const original = mediaOriginalFromRow(existing);
+    if (original.storageProvider === storageProvider && original.locator === locator) {
+        return { id: existing.id, created: false };
+    }
+    await updateTarget({
+        id: existing.id,
+        optimisticLockFilterList: [
+            { field: "category", operator: "eq", value: CategoryLink.LINK },
+            { field: "value", operator: "eq", value: existing.value },
+        ],
+        updateFn: (row) => {
+            const details = row.details as LinkDetails;
+            const prev = (details.original ?? {}) as Record<string, unknown>;
+            return {
+                details: {
+                    ...details,
+                    original: {
+                        ...prev,
+                        storageProvider,
+                        locator,
+                    },
+                },
+            };
+        },
+    });
+    logger.info("media original patched", {
+        topic: "register",
+        data: { id: existing.id, locator },
+    });
+    return { id: existing.id, created: false };
+}
+
 /**
  * Register a media Link: dedup → availability → probe → `postTarget`.
- * Idempotent when `category`+`value`+`name` already exist.
+ * Idempotent when `category`+`value`+`name` already exist (local path).
+ * HTTP `locator` + `localLocator`: probe local file, persist remote URL; patch if name exists.
  *
  * **Node-only** — under `shared/media/node/`; do not import from the browser entry.
  */
@@ -59,19 +109,33 @@ export async function registerMediaLink(input: RegisterMediaLinkInput): Promise<
         throw new Error("registerMediaLink: name is empty");
     }
 
+    const storageProvider = input.storageProvider.trim();
+    const locator = input.locator.trim();
+    const localLocator = input.localLocator?.trim() ?? "";
+    const httpLocator = isHttpUrl(locator);
+
     const existing = await findMediaLink({ value: input.value, name });
-    if (existing != null) {
+    if (existing != null && !httpLocator) {
         logger.info("media already registered", {
             topic: "dedup",
             data: { id: existing.id, value: input.value, name },
         });
         return { id: existing.id, created: false };
     }
+    if (existing != null && httpLocator) {
+        return patchMediaOriginal(existing, storageProvider, locator);
+    }
+
+    const probeStorageProvider = httpLocator ? input.localStorageProvider.trim() : storageProvider;
+    const probeLocator = httpLocator ? localLocator : locator;
+    if (httpLocator && probeLocator === "") {
+        throw new Error("registerMediaLink: localLocator is required when locator is http(s)");
+    }
 
     const availability = await checkMediaAvailability({
         value: input.value,
-        storageProvider: input.storageProvider,
-        locator: input.locator,
+        storageProvider: probeStorageProvider,
+        locator: probeLocator,
         localStorageProvider: input.localStorageProvider,
     });
     if (!availability.ok || availability.absolutePath == null) {
@@ -80,16 +144,16 @@ export async function registerMediaLink(input: RegisterMediaLinkInput): Promise<
 
     const probed = await probeMediaOriginal({
         value: input.value,
-        storageProvider: input.storageProvider,
-        locator: input.locator,
+        storageProvider: probeStorageProvider,
+        locator: probeLocator,
         absolutePath: availability.absolutePath,
     });
 
     const draft = buildMediaLinkDraft({
         value: input.value,
         name,
-        storageProvider: probed.storageProvider,
-        locator: probed.locator,
+        storageProvider: httpLocator ? storageProvider : probed.storageProvider,
+        locator: httpLocator ? locator : probed.locator,
         contentHash: probed.contentHash,
         size: probed.size,
         mimeType: probed.mimeType,
@@ -117,6 +181,9 @@ export async function registerMediaLink(input: RegisterMediaLinkInput): Promise<
         if (isCreateTargetAlreadyExistsError(error)) {
             const raced = await findMediaLink({ value: input.value, name });
             if (raced != null) {
+                if (httpLocator) {
+                    return patchMediaOriginal(raced, storageProvider, locator);
+                }
                 logger.info("media register race — using existing", {
                     topic: "dedup",
                     data: { id: raced.id, value: input.value, name },

package/src/shared/review/README.md

@@ -2,7 +2,7 @@
 
 Review is a **convention on `Link`**, not a new Target category (`category` stays `link`).
 
-A **Review** records **one user interaction** with a **subject Target** (for example: open, play, complete, rate, dismiss). **Each interaction creates a new Review row.** The subject is linked by storing the Target id on `Link.name` (`refId` at create time). **Many review Links may share the same `refId`** — the SDK does not define dedup or idempotent create for reviews.
+A **Review** records **one user interaction** (for example: open, play, complete, rate, dismiss). **Each interaction creates a new Review row.** **Many review Links may share the same `Link.name`** — the SDK does not define dedup or idempotent create for reviews.
 
 All review code lives under **`src/shared/review/`**. There is no Node-only ingest layer (unlike feed/media register flows) — create drafts on any host and persist with `postTarget` / `createTarget`.
 
@@ -19,12 +19,12 @@ src/shared/review/
 
 | Consumer import | What you get |
 |-----------------|--------------|
-| `from "target-supabase-sdk"` | Draft builder, constants, list filters |
+| `from "target-supabase-sdk"` | Draft builder, list filters |
 
 ```typescript
 import {
   buildReviewLinkDraft,
-  reviewLinksForTargetFilters,
+  reviewLinksForNameFilters,
 } from "target-supabase-sdk";
 ```
 
@@ -34,12 +34,12 @@ import {
 
 | Concept | Where it lives |
 |---------|----------------|
-| Subject Target | `Link.name` — the associated Target id (`refId` when building the draft) |
+| Grouping key | `Link.name` — caller-defined (often a subject Target id, not required) |
 | Interaction body | `Link.details.original` — caller-defined JSON-serializable payload |
 | Review kind | Fixed `Link.value` / `details.loaderKey` = `"review"` |
 | Labels | Optional `tagList` (e.g. interaction type, client, experiment) |
 
-Each persisted Review is its **own** Target row (its own `id`). Repeating the same `refId` on `name` is expected when listing interaction history for one subject.
+Each persisted Review is its **own** Target row (its own `id`). Repeating the same `name` is expected when listing interaction history under one grouping key.
 
 `details.original` is intentionally **untyped** (`unknown`) in the SDK so products can store scores, dwell time, UI state, model output, etc., without a shared schema in this package.
 
@@ -51,8 +51,7 @@ Built via `buildReviewLinkDraft` → `buildLinkTargetDraft`.
 
 | Create field | Required | Link field |
 |--------------|----------|------------|
-| `value` | yes | `value` — must be `"review"` |
-| `refId` | yes | `name` — subject Target id |
+| `name` | yes | `name` |
 | `original` | yes | `details.original` |
 | `tagList` | no | `tagList` (default `[]`) |
 | `description` | no | `details.description` (default `""`) |
@@ -61,8 +60,9 @@ Fixed at build time (not on create input):
 
 | Link field | Value |
 |------------|--------|
+| `value` | `"review"` |
 | `category` | `link` |
-| `details.loaderKey` | `"review"` (same as `value`) |
+| `details.loaderKey` | `"review"` |
 | `details.manifestVersion` | `0` |
 | `details.preview` | `""` |
 
@@ -75,8 +75,7 @@ import { buildReviewLinkDraft } from "target-supabase-sdk";
 import { postTarget } from "target-supabase-sdk"; // or your create API
 
 const draft = buildReviewLinkDraft({
-  value: "review",
-  refId: subjectTargetId,
+  name: subjectTargetId,
   original: {
     action: "complete",
     progress: 1,
@@ -88,23 +87,23 @@ const draft = buildReviewLinkDraft({
 await postTarget(draft);
 ```
 
-Every interaction: build a new draft (same `refId` is fine) and insert again.
+Every interaction: build a new draft (same `name` is fine) and insert again.
 
 ---
 
 ## Query
 
-List review Links for one subject Target:
+List review Links sharing a `Link.name`:
 
 ```typescript
-import { reviewLinksForTargetFilters, scanTargetList } from "target-supabase-sdk";
+import { reviewLinksForNameFilters, scanTargetList } from "target-supabase-sdk";
 
 const reviews = await scanTargetList({
-  filters: reviewLinksForTargetFilters(subjectTargetId),
+  filters: reviewLinksForNameFilters(subjectTargetId),
 });
 ```
 
-Filters: `category=link`, `value=review`, `name=refId`. Use pagination / `scanTargetList` when history is long.
+Filters: `category=link`, `value=review`, `name=<trimmed name>`. Use pagination / `scanTargetList` when history is long.
 
 There is **no** SDK helper for dedup or “find existing review” — callers always create new rows unless they add their own policy.
 
@@ -114,7 +113,7 @@ There is **no** SDK helper for dedup or “find existing review” — callers a
 
 ```typescript
 if (link.category === "link" && link.value === "review") {
-  const subjectTargetId = link.name;
+  const groupingKey = link.name;
   const payload = link.details.original;
 }
 ```

package/src/shared/review/index.ts

@@ -4,4 +4,4 @@
 
 export type { BuildReviewLinkDraftInput } from "./review.build";
 export { buildReviewLinkDraft } from "./review.build";
-export { reviewLinksForTargetFilters } from "./review.query";
+export { reviewLinksForNameFilters } from "./review.query";

package/src/shared/review/review.build.ts

@@ -1,13 +1,11 @@
 import type { TargetDraft } from "../../core.interface";
 import { buildLinkTargetDraft } from "../../link/link.build";
 import type { Link } from "../../link/link.interface";
-import { isReviewValue, REVIEW_VALUE, type ReviewValue } from "./review.interface";
+import { REVIEW_VALUE } from "./review.interface";
 
 export interface BuildReviewLinkDraftInput {
-    /** Must be {@link REVIEW_VALUE}. */
-    value: ReviewValue;
-    /** Associated Target id — written to `Link.name`. */
-    refId: string;
+    /** Written to `Link.name` (caller-defined; often a subject Target id). */
+    name: string;
     /** Interaction payload — written to `Link.details.original`. */
     original: unknown;
     tagList?: string[];
@@ -16,19 +14,16 @@ export interface BuildReviewLinkDraftInput {
 
 /**
  * Assemble a review {@link Link} draft (`category=link`, `loaderKey === value === "review"`).
- * Does not validate `refId` existence or write to Supabase.
+ * Does not validate `name` or write to Supabase.
  */
 export function buildReviewLinkDraft(input: BuildReviewLinkDraftInput): TargetDraft<Link> {
-    if (!isReviewValue(input.value)) {
-        throw new Error(`buildReviewLinkDraft: unsupported review value: ${String(input.value)}`);
-    }
-    const refId = input.refId.trim();
-    if (refId === "") {
-        throw new Error("buildReviewLinkDraft: refId is empty");
+    const name = input.name.trim();
+    if (name === "") {
+        throw new Error("buildReviewLinkDraft: name is empty");
     }
 
     return buildLinkTargetDraft({
-        name: refId,
+        name,
         value: REVIEW_VALUE,
         description: input.description ?? "",
         preview: "",

package/src/shared/review/review.interface.ts

@@ -2,8 +2,8 @@
  * Review Link protocol — Link rows with `value` / `loaderKey` === {@link REVIEW_VALUE}.
  * No separate Target category; category remains `link`.
  *
- * A Review records one user interaction with a subject Target (`Link.name` = that Target's id).
- * Many review Links may share the same subject id.
+ * A Review records one user interaction; `Link.name` is caller-defined (often a subject Target id).
+ * Many review Links may share the same `name`.
  */
 
 export const REVIEW_VALUE = "review" as const;

package/src/shared/review/review.query.ts

@@ -3,14 +3,14 @@ import { CategoryLink } from "../../link/link.interface";
 import { REVIEW_VALUE } from "./review.interface";
 
 /**
- * Filters for all review Links whose subject Target is `refId` (`Link.name === refId`).
+ * Filters for review Links with `Link.name === name`.
  * Many rows may match — the SDK does not define dedup for reviews.
  */
-export function reviewLinksForTargetFilters(refId: string): QueryFilter[] {
-    const name = refId.trim();
+export function reviewLinksForNameFilters(name: string): QueryFilter[] {
+    const trimmed = name.trim();
     return [
         { field: "category", operator: "eq", value: CategoryLink.LINK },
         { field: "value", operator: "eq", value: REVIEW_VALUE },
-        { field: "name", operator: "eq", value: name },
+        { field: "name", operator: "eq", value: trimmed },
     ];
 }