target-supabase-sdk 0.2.18 → 0.2.20

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})` };
+    }
+}

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

@@ -0,0 +1,183 @@
+import { getTarget, updateTarget } from "../../../core.api";
+import type { Target } from "../../../core.interface";
+import { CategoryLink, type Link, type LinkDetails } from "../../../link/link.interface";
+import { createLogger } from "../../log/core/create-logger";
+import { buildFeedTagList, resolveFeedOriginalStorageProvider } from "../feed.build";
+import {
+    type FeedIngestSource,
+    type FeedOriginal,
+    type FeedValue,
+    isFeedIngestSource,
+    isFeedValue,
+} from "../feed.interface";
+import { checkFeedLocalAvailability, checkFeedOssAvailability } from "./feed.access";
+
+const logger = createLogger({ module: "feed" });
+
+export interface RegisterFeedInput {
+    /** Existing feed Link row id (must still be `.public` unless already ingested with same payload). */
+    id: string;
+    source: FeedIngestSource;
+    storageProvider: string;
+    locator: string;
+    /** Required when `source` is `.local` (e.g. `process.env.LOCAL_STORAGE_PROVIDER`). Ignored for `.oss`. */
+    localStorageProvider?: string;
+}
+
+export interface RegisterFeedResult {
+    id: string;
+    /** `false` when row was already ingested with the same source, storageProvider, and locator. */
+    updated: boolean;
+}
+
+function parseFeedOriginal(original: unknown): FeedOriginal | null {
+    if (original == null || typeof original !== "object") {
+        return null;
+    }
+    const record = original as Record<string, unknown>;
+    const storageProvider = typeof record.storageProvider === "string" ? record.storageProvider : null;
+    const locator = typeof record.locator === "string" ? record.locator : null;
+    if (storageProvider == null || locator == null) {
+        return null;
+    }
+    const twinList = Array.isArray(record.twinList)
+        ? record.twinList.filter((entry): entry is string => typeof entry === "string")
+        : undefined;
+    return {
+        storageProvider,
+        locator,
+        ...(twinList !== undefined ? { twinList } : {}),
+    };
+}
+
+function assertFeedLink(target: Target): Link {
+    if (target.category !== CategoryLink.LINK) {
+        throw new Error(`registerFeed: target is not a link (category=${target.category})`);
+    }
+    if (!isFeedValue(target.value)) {
+        throw new Error(`registerFeed: target value is not a feed loader: ${target.value}`);
+    }
+    const details = target.details as LinkDetails | undefined;
+    if (details == null || details.loaderKey !== target.value) {
+        throw new Error("registerFeed: invalid feed link details (loaderKey must equal value)");
+    }
+    return target as Link;
+}
+
+function hasIngestSourceTag(tagList: string[]): boolean {
+    return tagList.some((tag) => tag === ".local" || tag === ".oss");
+}
+
+function isSameIngestState(link: Link, source: FeedIngestSource, storageProvider: string, locator: string): boolean {
+    if (!link.tagList.includes(source)) {
+        return false;
+    }
+    const original = parseFeedOriginal(link.details.original);
+    if (original == null) {
+        return false;
+    }
+    return original.storageProvider === storageProvider && original.locator === locator;
+}
+
+/**
+ * Ingest a `.public` feed Link: validate locator, then promote `tagList` source to `.local` or `.oss`
+ * and update `details.original.storageProvider` + `locator`.
+ *
+ * **Node-only** — under `shared/feed/node/`; do not import from the browser entry.
+ */
+export async function registerFeed(input: RegisterFeedInput): Promise<RegisterFeedResult> {
+    const id = input.id.trim();
+    if (id === "") {
+        throw new Error("registerFeed: id is empty");
+    }
+    if (!isFeedIngestSource(input.source)) {
+        throw new Error(`registerFeed: source must be .local or .oss, got ${String(input.source)}`);
+    }
+
+    const resolvedStorageProvider = resolveFeedOriginalStorageProvider(input.source, input.storageProvider);
+    const locator = input.locator.trim();
+    if (locator === "") {
+        throw new Error("registerFeed: locator is empty");
+    }
+
+    const { data: target } = await getTarget({ id });
+    if (target == null) {
+        throw new Error(`registerFeed: target not found: ${id}`);
+    }
+
+    const link = assertFeedLink(target);
+    const feedValue = link.value as FeedValue;
+
+    if (!link.tagList.includes(".public")) {
+        if (isSameIngestState(link, input.source, resolvedStorageProvider, locator)) {
+            logger.info("feed already ingested", {
+                topic: "dedup",
+                data: { id, source: input.source, locator },
+            });
+            return { id, updated: false };
+        }
+        if (hasIngestSourceTag(link.tagList)) {
+            throw new Error("registerFeed: feed already ingested with different source, storageProvider, or locator");
+        }
+        throw new Error("registerFeed: feed is not .public — cannot ingest");
+    }
+
+    if (input.source === ".local") {
+        const localStorageProvider = input.localStorageProvider?.trim() ?? "";
+        if (localStorageProvider === "") {
+            throw new Error("registerFeed: localStorageProvider is required when source is .local");
+        }
+        const availability = await checkFeedLocalAvailability({
+            value: feedValue,
+            storageProvider: resolvedStorageProvider,
+            locator,
+            localStorageProvider,
+        });
+        if (!availability.ok) {
+            throw new Error(`registerFeed: local locator unavailable — ${availability.reason ?? "unknown"}`);
+        }
+    } else {
+        const availability = await checkFeedOssAvailability(locator);
+        if (!availability.ok) {
+            throw new Error(`registerFeed: oss locator unavailable — ${availability.reason ?? "unknown"}`);
+        }
+    }
+
+    await updateTarget<Link, LinkDetails>({
+        id,
+        optimisticLockFilterList: [
+            { field: "category", operator: "eq", value: CategoryLink.LINK },
+            { field: "details->original->>storageProvider", operator: "eq", value: "" },
+        ],
+        updateFn: (row) => {
+            if (!row.tagList.includes(".public")) {
+                throw new Error("registerFeed: optimistic lock failed — .public tag missing");
+            }
+            if (hasIngestSourceTag(row.tagList) && !row.tagList.includes(".public")) {
+                throw new Error("registerFeed: feed already ingested");
+            }
+
+            const details = row.details;
+            const prior = parseFeedOriginal(details.original);
+            const nextOriginal: FeedOriginal = {
+                storageProvider: resolvedStorageProvider,
+                locator,
+                ...(prior?.twinList !== undefined ? { twinList: prior.twinList } : {}),
+            };
+
+            return {
+                tagList: buildFeedTagList(input.source, row.tagList),
+                details: {
+                    ...details,
+                    original: nextOriginal,
+                },
+            };
+        },
+    });
+
+    logger.info("feed ingested", {
+        topic: "register",
+        data: { id, source: input.source, storageProvider: resolvedStorageProvider, locator },
+    });
+    return { id, updated: true };
+}

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

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

package/src/shared/review/README.md

@@ -0,0 +1,128 @@
+# Review Links (`shared/review`)
+
+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.
+
+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`.
+
+```text
+src/shared/review/
+  index.ts
+  review.interface.ts
+  review.build.ts
+  review.query.ts
+  README.md
+```
+
+## Package entry
+
+| Consumer import | What you get |
+|-----------------|--------------|
+| `from "target-supabase-sdk"` | Draft builder, constants, list filters |
+
+```typescript
+import {
+  buildReviewLinkDraft,
+  reviewLinksForTargetFilters,
+} from "target-supabase-sdk";
+```
+
+---
+
+## Meaning
+
+| Concept | Where it lives |
+|---------|----------------|
+| Subject Target | `Link.name` — the associated Target id (`refId` when building the draft) |
+| 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.
+
+`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.
+
+---
+
+## Create input → Link mapping
+
+Built via `buildReviewLinkDraft` → `buildLinkTargetDraft`.
+
+| Create field | Required | Link field |
+|--------------|----------|------------|
+| `value` | yes | `value` — must be `"review"` |
+| `refId` | yes | `name` — subject Target id |
+| `original` | yes | `details.original` |
+| `tagList` | no | `tagList` (default `[]`) |
+| `description` | no | `details.description` (default `""`) |
+
+Fixed at build time (not on create input):
+
+| Link field | Value |
+|------------|--------|
+| `category` | `link` |
+| `details.loaderKey` | `"review"` (same as `value`) |
+| `details.manifestVersion` | `0` |
+| `details.preview` | `""` |
+
+---
+
+## Example
+
+```typescript
+import { buildReviewLinkDraft } from "target-supabase-sdk";
+import { postTarget } from "target-supabase-sdk"; // or your create API
+
+const draft = buildReviewLinkDraft({
+  value: "review",
+  refId: subjectTargetId,
+  original: {
+    action: "complete",
+    progress: 1,
+    at: new Date().toISOString(),
+  },
+  tagList: ["client:web"],
+});
+
+await postTarget(draft);
+```
+
+Every interaction: build a new draft (same `refId` is fine) and insert again.
+
+---
+
+## Query
+
+List review Links for one subject Target:
+
+```typescript
+import { reviewLinksForTargetFilters, scanTargetList } from "target-supabase-sdk";
+
+const reviews = await scanTargetList({
+  filters: reviewLinksForTargetFilters(subjectTargetId),
+});
+```
+
+Filters: `category=link`, `value=review`, `name=refId`. 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.
+
+---
+
+## Recognizing review Links
+
+```typescript
+if (link.category === "link" && link.value === "review") {
+  const subjectTargetId = link.name;
+  const payload = link.details.original;
+}
+```
+
+---
+
+## Related
+
+- `src/link/link.build.ts` — `buildLinkTargetDraft`
+- `src/shared/media/README.md` — same Link-convention pattern for media
+- `src/shared/feed/README.md` — feed Links with richer lifecycle

package/src/shared/review/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Review Link — browser-safe barrel.
+ */
+
+export type { BuildReviewLinkDraftInput } from "./review.build";
+export { buildReviewLinkDraft } from "./review.build";
+export { reviewLinksForTargetFilters } from "./review.query";

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

@@ -0,0 +1,39 @@
+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";
+
+export interface BuildReviewLinkDraftInput {
+    /** Must be {@link REVIEW_VALUE}. */
+    value: ReviewValue;
+    /** Associated Target id — written to `Link.name`. */
+    refId: string;
+    /** Interaction payload — written to `Link.details.original`. */
+    original: unknown;
+    tagList?: string[];
+    description?: string;
+}
+
+/**
+ * Assemble a review {@link Link} draft (`category=link`, `loaderKey === value === "review"`).
+ * Does not validate `refId` existence 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");
+    }
+
+    return buildLinkTargetDraft({
+        name: refId,
+        value: REVIEW_VALUE,
+        description: input.description ?? "",
+        preview: "",
+        loaderKey: REVIEW_VALUE,
+        tagList: input.tagList ?? [],
+        original: input.original,
+    });
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+
+export const REVIEW_VALUE = "review" as const;
+
+/** Discriminator stored in both `Link.value` and `details.loaderKey`. */
+export type ReviewValue = typeof REVIEW_VALUE;
+
+/** Caller-defined payload stored in `Link.details.original`. */
+export type ReviewOriginal = unknown;
+
+export function isReviewValue(value: string): value is ReviewValue {
+    return value === REVIEW_VALUE;
+}

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

@@ -0,0 +1,16 @@
+import type { QueryFilter } from "../../core.interface";
+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`).
+ * Many rows may match — the SDK does not define dedup for reviews.
+ */
+export function reviewLinksForTargetFilters(refId: string): QueryFilter[] {
+    const name = refId.trim();
+    return [
+        { field: "category", operator: "eq", value: CategoryLink.LINK },
+        { field: "value", operator: "eq", value: REVIEW_VALUE },
+        { field: "name", operator: "eq", value: name },
+    ];
+}