target-supabase-sdk 0.2.19 → 0.2.20

package/dist/node.js

@@ -6,8 +6,8 @@ export { C as CLI_PROD_FLAG, S as SERVICE_ENV_PROFILE_ENV_KEY, w as SERVICE_ENV_
 import { randomBytes, createHash } from 'node:crypto';
 import { readFile, unlink, mkdir, writeFile, rename, access, stat, readdir, constants } from 'node:fs/promises';
 import { dirname, resolve, join, isAbsolute } from 'node:path';
-import { bv as sha256Hex, bB as getErrorMessage, bC as LOG_TOPIC_NODE, aZ as postRegisterNode, aD as patchChangeNodeStatus, N as NodeStatus, aO as patchStopNode, aL as patchNodeHeartBeat, E as EMPTY_REGISTRY_SLOT_RUNTIME_STATE, bl as runRegistrySlotGuardCheck, bb as registrySlotRuntimePatchFromGuardResult, c as CategoryNode, a0 as evaluateBusyNodeLiveness, aN as patchServiceRuntime, as as isLogEntry, I as claimServiceRegistrySlot, m as ServiceRegistryError, a3 as fetchWithRetry, av as isRetryableHttpStatus, a2 as fetchBinaryWithRetry, au as isOpaqueChunkUrl, e as CategoryRepo, ap as isHttpUrl, bD as isFeedIngestSource, bE as resolveFeedOriginalStorageProvider, b as CategoryLink, bF as buildFeedTagList, ao as isFeedValue, am as guessMediaMime, M as MEDIA_CONTENT_HASH_ALGORITHM, at as isMediaValue, ax as mediaLinkDedupFilters, B as buildMediaLinkDraft, R as ResultCode, bG as LOG_TOPIC_TASK, o as TASK_REPO_USAGE, ag as getScanRemoteRepoValues, aH as patchClaimTask, bH as CRITICAL_UNKNOWN_TASK_TRACE_ID, aF as patchChangeTaskStatus, q as TaskStatusAction, bI as toError, b5 as postTaskSchema, bJ as createTaskRow, p as TaskStatus } from './chunks/task-queue-CUa40Vb5.js';
-export { A as ApiMethod, C as CategoryConfig, a as CategoryExtraction, d as CategoryParcel, f as CategoryService, g as CategoryTask, D as DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS, bK as FEED_INGEST_SOURCES, F as FEED_VALUES, L as LINK_MANIFEST_VERSION, h as LIST_MANIFEST_VERSION, i as MEDIA_CONTENT_HASH_PREFIX_LENGTH, j as MEDIA_VALUES, P as POST_TASK_DEFAULT_MAX_ATTEMPTS, k as ParcelManager, l as PostLinkValidator, S as ServiceLifecycleStatus, n as ServiceSlotStatus, T as TARGET_SYSTEM_REGISTRY_KEY, r as apiDetailsSchema, s as appendSystemRegistryEmptySlots, t as assertRegistrySlotAvailable, u as assertRegistrySlotOwner, v as buildEmptyServiceSlots, w as buildFeedLinkDraft, x as buildFeedLinkName, y as buildLinkTargetDraft, z as buildListTargetDraft, G as buildMediaNameFromLocator, H as buildSystemRegistryConfigDetails, J as classifyNetworkError, K as countTasksByType, O as createActiveServiceLifecycle, Q as createClaimedRegistrySlotRuntimeState, U as createStorageProviderRegistry, V as createUploadTracker, W as decodeLogBatch, X as decodeLogBatchList, Y as defaultL3ServiceDetails, Z as deleteParcel, _ as deleteParcelSchema, $ as escapeIlikePattern, a1 as feedLinkDedupFilters, a4 as fieldDefinitionSchema, a5 as flattenLogBatch, a6 as flattenLogBatches, a7 as formatNetworkError, a8 as getApi, a9 as getApiSchema, aa as getConfig, ab as getConfigSchema, ac as getExtraction, ad as getExtractionSchema, ae as getParcel, af as getParcelSchema, ah as getScanRemoteRepoValuesSchema, ai as getService, aj as getServiceSchema, ak as getTargetSystemRegistry, al as getValueAtPath, an as installChunkFetchRegistry, aq as isLocalFilesystemPath, ar as isLogBatchList, aw as linkTargetDraftBuildInputSchema, ay as parcelDetailsSchema, az as parseLogBatchMeta, aA as parseProviderPrefixedUrl, aB as parseServiceSlot, aC as parseServiceSlots, aE as patchChangeNodeStatusSchema, aG as patchChangeTaskStatusSchema, aI as patchClaimTaskSchema, aJ as patchExtractionObjects, aK as patchExtractionObjectsSchema, aM as patchNodeHeartBeatSchema, aP as patchStopNodeSchema, aQ as patchTaskProgress, aR as patchTaskProgressSchema, aS as postApi, aT as postApiSchema, aU as postExtraction, aV as postExtractionSchema, aW as postLinkCreate, aX as postParcel, aY as postParcelSchema, a_ as postRegisterNodeSchema, a$ as postService, b0 as postServiceInstance, b1 as postServiceSchema, b2 as postSystemRegistryConfig, b3 as postSystemRegistryConfigSchema, b4 as postTask, b6 as postTaskWithRetry, b7 as publishParcel, b8 as registerProviderChunkResolver, b9 as registerService, ba as registerServiceAtStartup, bc as releaseSystemRegistrySlots, bd as releaseSystemRegistrySlotsByServiceId, be as requestHasBody, bf as resetSystemRegistryConfig, bg as resetSystemRegistryConfigSchema, bh as resolveActiveRegistryServiceId, bi as resolveFetchUrl, bj as restoreParcel, bk as restoreParcelById, bm as sanitizeFileName, bn as sanitizeParcelFileName, bo as scanExtractionList, bp as scanExtractionListSchema, bq as schemaDefinitionSchema, br as serviceDetailsSchema, bs as serviceLifecycleSchema, bt as serviceNodeSnapshotSchema, bu as serviceRuntimeSchema, bw as summarizeTaskQueue, bx as systemRegistrySeedSlotSchema, by as toPostgrestTextArrayLiteral, bz as unregisterService, bA as unregisterServiceAtShutdown } from './chunks/task-queue-CUa40Vb5.js';
+import { bx as sha256Hex, bD as getErrorMessage, bE as LOG_TOPIC_NODE, a_ as postRegisterNode, aE as patchChangeNodeStatus, N as NodeStatus, aP as patchStopNode, aM as patchNodeHeartBeat, E as EMPTY_REGISTRY_SLOT_RUNTIME_STATE, bn as runRegistrySlotGuardCheck, bc as registrySlotRuntimePatchFromGuardResult, c as CategoryNode, a1 as evaluateBusyNodeLiveness, aO as patchServiceRuntime, at as isLogEntry, J as claimServiceRegistrySlot, m as ServiceRegistryError, a4 as fetchWithRetry, aw as isRetryableHttpStatus, a3 as fetchBinaryWithRetry, av as isOpaqueChunkUrl, e as CategoryRepo, aq as isHttpUrl, bF as isFeedIngestSource, bG as resolveFeedOriginalStorageProvider, b as CategoryLink, bH as buildFeedTagList, ap as isFeedValue, an as guessMediaMime, M as MEDIA_CONTENT_HASH_ALGORITHM, au as isMediaValue, ay as mediaLinkDedupFilters, B as buildMediaLinkDraft, R as ResultCode, bI as LOG_TOPIC_TASK, o as TASK_REPO_USAGE, ah as getScanRemoteRepoValues, aI as patchClaimTask, bJ as CRITICAL_UNKNOWN_TASK_TRACE_ID, aG as patchChangeTaskStatus, q as TaskStatusAction, bK as toError, b6 as postTaskSchema, bL as createTaskRow, p as TaskStatus } from './chunks/task-queue-CqmIVCBi.js';
+export { A as ApiMethod, C as CategoryConfig, a as CategoryExtraction, d as CategoryParcel, f as CategoryService, g as CategoryTask, D as DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS, bM as FEED_INGEST_SOURCES, F as FEED_VALUES, L as LINK_MANIFEST_VERSION, h as LIST_MANIFEST_VERSION, i as MEDIA_CONTENT_HASH_PREFIX_LENGTH, j as MEDIA_VALUES, P as POST_TASK_DEFAULT_MAX_ATTEMPTS, k as ParcelManager, l as PostLinkValidator, S as ServiceLifecycleStatus, n as ServiceSlotStatus, T as TARGET_SYSTEM_REGISTRY_KEY, r as apiDetailsSchema, s as appendSystemRegistryEmptySlots, t as assertRegistrySlotAvailable, u as assertRegistrySlotOwner, v as buildEmptyServiceSlots, w as buildFeedLinkDraft, x as buildFeedLinkName, y as buildLinkTargetDraft, z as buildListTargetDraft, G as buildMediaNameFromLocator, H as buildReviewLinkDraft, I as buildSystemRegistryConfigDetails, K as classifyNetworkError, O as countTasksByType, Q as createActiveServiceLifecycle, U as createClaimedRegistrySlotRuntimeState, V as createStorageProviderRegistry, W as createUploadTracker, X as decodeLogBatch, Y as decodeLogBatchList, Z as defaultL3ServiceDetails, _ as deleteParcel, $ as deleteParcelSchema, a0 as escapeIlikePattern, a2 as feedLinkDedupFilters, a5 as fieldDefinitionSchema, a6 as flattenLogBatch, a7 as flattenLogBatches, a8 as formatNetworkError, a9 as getApi, aa as getApiSchema, ab as getConfig, ac as getConfigSchema, ad as getExtraction, ae as getExtractionSchema, af as getParcel, ag as getParcelSchema, ai as getScanRemoteRepoValuesSchema, aj as getService, ak as getServiceSchema, al as getTargetSystemRegistry, am as getValueAtPath, ao as installChunkFetchRegistry, ar as isLocalFilesystemPath, as as isLogBatchList, ax as linkTargetDraftBuildInputSchema, az as parcelDetailsSchema, aA as parseLogBatchMeta, aB as parseProviderPrefixedUrl, aC as parseServiceSlot, aD as parseServiceSlots, aF as patchChangeNodeStatusSchema, aH as patchChangeTaskStatusSchema, aJ as patchClaimTaskSchema, aK as patchExtractionObjects, aL as patchExtractionObjectsSchema, aN as patchNodeHeartBeatSchema, aQ as patchStopNodeSchema, aR as patchTaskProgress, aS as patchTaskProgressSchema, aT as postApi, aU as postApiSchema, aV as postExtraction, aW as postExtractionSchema, aX as postLinkCreate, aY as postParcel, aZ as postParcelSchema, a$ as postRegisterNodeSchema, b0 as postService, b1 as postServiceInstance, b2 as postServiceSchema, b3 as postSystemRegistryConfig, b4 as postSystemRegistryConfigSchema, b5 as postTask, b7 as postTaskWithRetry, b8 as publishParcel, b9 as registerProviderChunkResolver, ba as registerService, bb as registerServiceAtStartup, bd as releaseSystemRegistrySlots, be as releaseSystemRegistrySlotsByServiceId, bf as requestHasBody, bg as resetSystemRegistryConfig, bh as resetSystemRegistryConfigSchema, bi as resolveActiveRegistryServiceId, bj as resolveFetchUrl, bk as restoreParcel, bl as restoreParcelById, bm as reviewLinksForTargetFilters, bo as sanitizeFileName, bp as sanitizeParcelFileName, bq as scanExtractionList, br as scanExtractionListSchema, bs as schemaDefinitionSchema, bt as serviceDetailsSchema, bu as serviceLifecycleSchema, bv as serviceNodeSnapshotSchema, bw as serviceRuntimeSchema, by as summarizeTaskQueue, bz as systemRegistrySeedSlotSchema, bA as toPostgrestTextArrayLiteral, bB as unregisterService, bC as unregisterServiceAtShutdown } from './chunks/task-queue-CqmIVCBi.js';
 import { spawn } from 'node:child_process';
 import { ProxyAgent } from 'undici';
 import { tmpdir } from 'node:os';

package/dist/shared/review/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/review/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/review/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/shared/review/review.build.d.ts

@@ -0,0 +1,19 @@
+import type { TargetDraft } from "../../core.interface";
+import type { Link } from "../../link/link.interface";
+import { 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 declare function buildReviewLinkDraft(input: BuildReviewLinkDraftInput): TargetDraft<Link>;
+//# sourceMappingURL=review.build.d.ts.map

package/dist/shared/review/review.build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.build.d.ts","sourceRoot":"","sources":["../../../src/shared/review/review.build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,yBAAyB;IACtC,oCAAoC;IACpC,KAAK,EAAE,WAAW,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,WAAW,CAAC,IAAI,CAAC,CAkBxF"}

package/dist/shared/review/review.interface.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare const REVIEW_VALUE: "review";
+/** 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 declare function isReviewValue(value: string): value is ReviewValue;
+//# sourceMappingURL=review.interface.d.ts.map

package/dist/shared/review/review.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/review/review.interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,YAAY,EAAG,QAAiB,CAAC;AAE9C,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,OAAO,YAAY,CAAC;AAE9C,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;AAErC,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEjE"}

package/dist/shared/review/review.query.d.ts

@@ -0,0 +1,7 @@
+import type { QueryFilter } from "../../core.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 declare function reviewLinksForTargetFilters(refId: string): QueryFilter[];
+//# sourceMappingURL=review.query.d.ts.map

package/dist/shared/review/review.query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.query.d.ts","sourceRoot":"","sources":["../../../src/shared/review/review.query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAOxE"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.19",
+    "version": "0.2.20",
     "description": "Supabase client initializer and data access APIs",
     "license": "MIT",
     "author": "KyLoc20",

package/src/browser.ts

@@ -241,6 +241,8 @@ export {
     MEDIA_VALUES,
     mediaLinkDedupFilters,
 } from "./shared/media";
+export type { BuildReviewLinkDraftInput } from "./shared/review";
+export { buildReviewLinkDraft, reviewLinksForTargetFilters } from "./shared/review";
 export { isHttpUrl, resolveFetchUrl } from "./shared/utils/fetch-url";
 export { getValueAtPath } from "./shared/utils/get-value-at-path";
 export type {

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 },
+    ];
+}