target-supabase-sdk 0.2.18 → 0.2.19

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

@@ -0,0 +1,33 @@
+import type { TargetDraft } from "../../core.interface";
+import type { Link } from "../../link/link.interface";
+import { type FeedSource, type FeedValue } from "./feed.interface";
+export interface BuildFeedLinkDraftInput {
+    value: FeedValue;
+    /** Dots are normalized to spaces in {@link buildFeedLinkName} before joining with `feedKey`. */
+    platformName: string;
+    feedKey: string;
+    source: FeedSource;
+    locator: string;
+    /**
+     * Written to `original.storageProvider`. Must be empty when `source` is `.public`;
+     * required when `source` is `.local` or `.oss`.
+     */
+    storageProvider?: string;
+    description?: string;
+    preview?: string;
+    /** Locators for related resources of the same feed; stored on `original.twinList`. */
+    twinList?: string[];
+    tagList?: string[];
+}
+/** Trim entries and drop empties; `undefined` when input omitted. */
+export declare function normalizeFeedTwinList(twinList?: string[]): string[] | undefined;
+/** `original.storageProvider` from optional input and required `source` tier. */
+export declare function resolveFeedOriginalStorageProvider(source: FeedSource, storageProvider?: string): string;
+/** Merge user tags with required `source`; strip any other feed source tags from user input. */
+export declare function buildFeedTagList(source: FeedSource, tagList?: string[]): string[];
+/**
+ * Assemble a feed {@link Link} draft (`category=link`, `loaderKey === value`).
+ * Does not validate locator reachability or write to Supabase.
+ */
+export declare function buildFeedLinkDraft(input: BuildFeedLinkDraftInput): TargetDraft<Link>;
+//# sourceMappingURL=feed.build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.build.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAGH,KAAK,UAAU,EACf,KAAK,SAAS,EAGjB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,SAAS,CAAC;IACjB,gGAAgG;IAChG,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAK/E;AAED,iFAAiF;AACjF,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAcvG;AAED,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAKjF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,WAAW,CAAC,IAAI,CAAC,CA+BpF"}

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

@@ -0,0 +1,35 @@
+/**
+ * Feed Link protocol — Link rows with value/loaderKey in {@link FEED_VALUES}.
+ * No separate Target category; category remains `link`.
+ */
+export declare const FEED_VALUES: readonly ["feed.image", "feed.audio", "feed.video", "feed.image-list"];
+/** Discriminator stored in both `Link.value` and `details.loaderKey`. */
+export type FeedValue = (typeof FEED_VALUES)[number];
+/**
+ * Feed lifecycle tier — exactly one must appear in `tagList` (via `buildFeedTagList`).
+ *
+ * Leading `.` marks **system** tags (distinct from user-defined `tagList` entries).
+ */
+export declare const FEED_SOURCE_TAGS: readonly [".public", ".local", ".oss"];
+export type FeedSource = (typeof FEED_SOURCE_TAGS)[number];
+/** `registerFeed` only transitions `.public` → `.local` or `.oss`. */
+export declare const FEED_INGEST_SOURCES: readonly [".local", ".oss"];
+export type FeedIngestSource = (typeof FEED_INGEST_SOURCES)[number];
+export declare function isFeedIngestSource(value: string): value is FeedIngestSource;
+/** `Link.details.original` for feed Links. */
+export interface FeedOriginal {
+    /**
+     * Backend / host id when {@link FeedSource} is `.local` or `.oss` (e.g. `LOCAL_STORAGE_PROVIDER`).
+     * Empty string when source is `.public`.
+     */
+    storageProvider: string;
+    locator: string;
+    /**
+     * Locators for sibling resources of the same feed (e.g. other media types).
+     * Omitted when not supplied on create.
+     */
+    twinList?: string[];
+}
+export declare function isFeedValue(value: string): value is FeedValue;
+export declare function isFeedSource(value: string): value is FeedSource;
+//# sourceMappingURL=feed.interface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,WAAW,wEAAyE,CAAC;AAElG,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wCAAyC,CAAC;AAEvE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,6BAA8B,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D"}

package/dist/shared/feed/feed.name.d.ts

@@ -0,0 +1,8 @@
+/** Normalize `platformName` so `Link.name` stays `{platform}.{feedKey}` with a single separator dot. */
+export declare function sanitizeFeedPlatformName(platformName: string): string;
+/**
+ * Default dedup `Link.name` for feed Links: `{platformName}.{feedKey}`.
+ * Dots in `platformName` are replaced with spaces before joining (see {@link sanitizeFeedPlatformName}).
+ */
+export declare function buildFeedLinkName(platformName: string, feedKey: string): string;
+//# sourceMappingURL=feed.name.d.ts.map

package/dist/shared/feed/feed.name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.name.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.name.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAU/E"}

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

@@ -0,0 +1,8 @@
+import type { QueryFilter } from "../../core.interface";
+import type { FeedValue } from "./feed.interface";
+/** Dedup key: `category=link` + `value` + `name` (matches register / find). */
+export declare function feedLinkDedupFilters(input: {
+    value: FeedValue;
+    name: string;
+}): QueryFilter[];
+//# sourceMappingURL=feed.query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feed.query.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/feed.query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CAO7F"}

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/feed/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/dist/shared/feed/node/feed.access.d.ts

@@ -0,0 +1,34 @@
+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;
+}
+/**
+ * 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 declare function checkFeedLocalAvailability(input: CheckFeedLocalAvailabilityInput): Promise<FeedAvailabilityResult>;
+/**
+ * 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 declare function checkFeedOssAvailability(locator: string): Promise<FeedAvailabilityResult>;
+//# sourceMappingURL=feed.access.d.ts.map

package/dist/shared/feed/node/feed.access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.access.d.ts","sourceRoot":"","sources":["../../../../src/shared/feed/node/feed.access.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,+BAA+B;IAC5C,KAAK,EAAE,SAAS,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC5C,KAAK,EAAE,+BAA+B,GACvC,OAAO,CAAC,sBAAsB,CAAC,CA0CjC;AAoBD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAsB/F"}

package/dist/shared/feed/node/feed.service.d.ts

@@ -0,0 +1,23 @@
+import { type FeedIngestSource } from "../feed.interface";
+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;
+}
+/**
+ * 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 declare function registerFeed(input: RegisterFeedInput): Promise<RegisterFeedResult>;
+//# sourceMappingURL=feed.service.d.ts.map

package/dist/shared/feed/node/feed.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.service.d.ts","sourceRoot":"","sources":["../../../../src/shared/feed/node/feed.service.ts"],"names":[],"mappings":"AAKA,OAAO,EACH,KAAK,gBAAgB,EAKxB,MAAM,mBAAmB,CAAC;AAK3B,MAAM,WAAW,iBAAiB;IAC9B,qGAAqG;IACrG,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,gGAAgG;IAChG,OAAO,EAAE,OAAO,CAAC;CACpB;AAmDD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+FxF"}

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

package/dist/shared/feed/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/shared/feed/node/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,+BAA+B,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACrF,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

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

package/src/browser.ts

@@ -189,7 +189,14 @@ export {
     unregisterService,
     unregisterServiceAtShutdown,
 } from "./service/index";
-
+export type { BuildFeedLinkDraftInput, FeedOriginal, FeedSource, FeedValue } from "./shared/feed";
+export {
+    buildFeedLinkDraft,
+    buildFeedLinkName,
+    FEED_VALUES,
+    feedLinkDedupFilters,
+    isFeedValue,
+} from "./shared/feed";
 export type { FetchInitFactory, FetchRetryOptions } from "./shared/http/fetch-retry";
 export {
     fetchBinaryWithRetry,

package/src/node.ts

@@ -158,6 +158,20 @@ export {
     telegramFileDownloadUrl,
 } from "./node/telegram";
 export { RepoManager } from "./repo/repo-manager";
+export type {
+    CheckFeedLocalAvailabilityInput,
+    FeedAvailabilityResult,
+    FeedIngestSource,
+    RegisterFeedInput,
+    RegisterFeedResult,
+} from "./shared/feed/node";
+export {
+    checkFeedLocalAvailability,
+    checkFeedOssAvailability,
+    FEED_INGEST_SOURCES,
+    isFeedIngestSource,
+    registerFeed,
+} from "./shared/feed/node";
 export { runCollectLogTick } from "./shared/log/spool/collector";
 export { LOG_SPOOL_SERVICE_ID_ENV } from "./shared/log/spool/config";
 export type { LogSpoolCoordinator, LogSpoolCoordinatorOptions } from "./shared/log/spool/coordinator";

package/src/shared/feed/README.md

@@ -0,0 +1,163 @@
+# Feed Links (`shared/feed`)
+
+Feed is a **convention on `Link`**, not a new Target category (`category` stays `link`).
+
+```text
+src/shared/feed/
+  index.ts              ← browser-safe barrel ONLY (never export ./node)
+  feed.interface.ts
+  feed.build.ts
+  feed.name.ts
+  feed.query.ts
+  README.md
+  node/                 ← Node-only (ingest / availability)
+    index.ts            ← barrel for src/node.ts only
+    feed.access.ts
+    feed.service.ts
+```
+
+## Package entry split
+
+| Consumer import | What you get | Source |
+|-----------------|--------------|--------|
+| `from "target-supabase-sdk"` | Draft, name, tag merge, dedup filters | `shared/feed/index.ts` → `browser.ts` |
+| `from "target-supabase-sdk/node"` | + `registerFeed`, availability checks | `shared/feed/node/` → `node.ts` |
+
+**Do not** re-export `./node` from `index.ts` / `browser.ts`.
+
+```typescript
+// Default / browser — create draft, dedup, recognize feed Links
+import {
+  buildFeedLinkDraft,
+  buildFeedLinkName,
+  feedLinkDedupFilters,
+  FEED_VALUES,
+  isFeedValue,
+} from "target-supabase-sdk";
+
+// Node — ingest after .public draft exists
+import { registerFeed, FEED_INGEST_SOURCES } from "target-supabase-sdk/node";
+```
+
+---
+
+## Lifecycle
+
+1. **Create (browser or any host)** — `buildFeedLinkDraft` with `source: ".public"`, public `locator` (often a platform URL), `original.storageProvider: ""`. Persist via `postTarget` / `createTarget`.
+2. **Ingest (Node)** — `registerFeed` on an existing row `id`: validate the new locator, then promote `tagList` from `.public` to `.local` or `.oss` and update `original.storageProvider` + `locator`. Preserves `twinList` and other non-source tags.
+
+---
+
+## Link field rules
+
+| Field | Rule |
+|-------|------|
+| `value` | `feed.image` \| `feed.audio` \| `feed.video` \| `feed.image-list` |
+| `details.loaderKey` | Always equals `value` |
+| `name` | `{platformName}.{feedKey}` via `buildFeedLinkName` |
+| Dedup | `category=link` + `value` + `name` (`feedLinkDedupFilters`) |
+| `tagList` | Exactly one feed **system** source tag (`.public` \| `.local` \| `.oss`) |
+| `description` / `preview` | Optional; default `""` |
+
+### Naming
+
+- `sanitizeFeedPlatformName` replaces `.` in `platformName` with spaces before ``${platform}.${feedKey}``.
+
+---
+
+## `details.original`
+
+| Key | `.public` draft | After ingest |
+|-----|-----------------|--------------|
+| `storageProvider` | `""` | Backend id (required for `.local` / `.oss`) |
+| `locator` | Public / platform locator | Validated path (`.local`) or URL (`.oss`) |
+| `twinList` | Optional sibling locators | Unchanged by `registerFeed` |
+
+---
+
+## System vs user tags
+
+Leading `.` marks **system** tags (not user tags).
+
+| Tag | Meaning |
+|-----|---------|
+| `.public` | Public-network link; ingest when stable copy exists |
+| `.local` | In Target on this device (`LOCAL_STORAGE_PROVIDER` + absolute file/dir path) |
+| `.oss` | In Target on shared storage (HTTP(S) locator must respond) |
+
+`buildFeedTagList` strips `.public` / `.local` / `.oss` from user input and appends the chosen `source` once.
+
+---
+
+## Register flow (`registerFeed`)
+
+**Input**
+
+| Field | Rule |
+|-------|------|
+| `id` | Existing feed Link row |
+| `source` | `.local` or `.oss` only |
+| `storageProvider` | Non-empty (validated by `resolveFeedOriginalStorageProvider`) |
+| `locator` | New canonical locator after ingest |
+| `localStorageProvider` | **Required** when `source` is `.local` (typically `process.env.LOCAL_STORAGE_PROVIDER`). Ignored for `.oss`. |
+
+**Steps**
+
+1. Load target by `id`; must be `category=link` with `isFeedValue(value)` and `loaderKey === value`.
+2. **Idempotent** — if `tagList` already has the target `source` and `original` matches `storageProvider` + `locator` → `{ id, updated: false }`.
+3. Require `tagList` to include `.public` (not already ingested with different state).
+4. **Availability**
+   - `.local` — `checkFeedLocalAvailability`: `storageProvider === localStorageProvider`, absolute path, file (or directory for `feed.image-list`) exists and is non-empty where applicable.
+   - `.oss` — `checkFeedOssAvailability`: `http(s)` URL; `HEAD`, then `GET` with `Range: bytes=0-0` if `HEAD` is not supported.
+5. **Update** — `updateTarget` with optimistic lock `details->original->>storageProvider` eq `""` (still `.public` tier). Sets `tagList` via `buildFeedTagList`, updates `original.storageProvider` and `locator`, keeps `twinList`.
+
+**Errors (representative)**
+
+| Condition | Result |
+|-----------|--------|
+| Not a feed Link | throw |
+| Already `.local`/`.oss` with different locator | throw |
+| Missing `.public` tag | throw |
+| Locator check fails | throw |
+| Concurrent ingest (storageProvider already set) | optimistic lock failure |
+
+```typescript
+import { registerFeed } from "target-supabase-sdk/node";
+
+const { id, updated } = await registerFeed({
+  id: feedLinkId,
+  source: ".local",
+  storageProvider: process.env.LOCAL_STORAGE_PROVIDER!,
+  locator: "D:\\\\data\\\\feeds\\\\bilibili.12345.mp4",
+  localStorageProvider: process.env.LOCAL_STORAGE_PROVIDER!,
+});
+```
+
+---
+
+## Env (Node hosts)
+
+| Variable | Role |
+|----------|------|
+| `LOCAL_STORAGE_PROVIDER` | This machine’s storage id; pass as both `storageProvider` and `localStorageProvider` for `.local` ingest on this host |
+
+Same variable as media register — see `src/shared/media/README.md`.
+
+---
+
+## Design notes / limitations
+
+| Topic | Current behavior | Possible follow-up |
+|-------|------------------|-------------------|
+| OSS auth | Only anonymous `HEAD`/`GET` | Signed URLs or provider-specific probes |
+| `.local` on another host | Fails availability (by design, like media) | Remote agent ingest |
+| `twinList` on ingest | Not re-validated | Optional probe per twin |
+| Re-ingest / migrate `.local` → `.oss` | Not supported | New API with lock on prior source tag |
+
+---
+
+## Related
+
+- `.cursor/skills/feed-link/SKILL.md`
+- Media register pattern: `src/shared/media/README.md`
+- Optimistic lock: `.cursor/skills/optimistic-lock-update/SKILL.md`

package/src/shared/feed/feed.build.ts

@@ -0,0 +1,101 @@
+import type { TargetDraft } from "../../core.interface";
+import { buildLinkTargetDraft } from "../../link/link.build";
+import type { Link } from "../../link/link.interface";
+import {
+    FEED_SOURCE_TAGS,
+    type FeedOriginal,
+    type FeedSource,
+    type FeedValue,
+    isFeedSource,
+    isFeedValue,
+} from "./feed.interface";
+import { buildFeedLinkName } from "./feed.name";
+
+export interface BuildFeedLinkDraftInput {
+    value: FeedValue;
+    /** Dots are normalized to spaces in {@link buildFeedLinkName} before joining with `feedKey`. */
+    platformName: string;
+    feedKey: string;
+    source: FeedSource;
+    locator: string;
+    /**
+     * Written to `original.storageProvider`. Must be empty when `source` is `.public`;
+     * required when `source` is `.local` or `.oss`.
+     */
+    storageProvider?: string;
+    description?: string;
+    preview?: string;
+    /** Locators for related resources of the same feed; stored on `original.twinList`. */
+    twinList?: string[];
+    tagList?: string[];
+}
+
+/** Trim entries and drop empties; `undefined` when input omitted. */
+export function normalizeFeedTwinList(twinList?: string[]): string[] | undefined {
+    if (twinList === undefined) {
+        return undefined;
+    }
+    return twinList.map((entry) => entry.trim()).filter((entry) => entry !== "");
+}
+
+/** `original.storageProvider` from optional input and required `source` tier. */
+export function resolveFeedOriginalStorageProvider(source: FeedSource, storageProvider?: string): string {
+    const trimmed = storageProvider?.trim() ?? "";
+    if (source === ".public") {
+        if (trimmed !== "") {
+            throw new Error("resolveFeedOriginalStorageProvider: storageProvider must be empty when source is .public");
+        }
+        return "";
+    }
+    if (trimmed === "") {
+        throw new Error(
+            "resolveFeedOriginalStorageProvider: storageProvider is required when source is .local or .oss",
+        );
+    }
+    return trimmed;
+}
+
+/** Merge user tags with required `source`; strip any other feed source tags from user input. */
+export function buildFeedTagList(source: FeedSource, tagList?: string[]): string[] {
+    const sourceSet = new Set<string>(FEED_SOURCE_TAGS);
+    const user = tagList ?? [];
+    const filtered = user.filter((tag) => !sourceSet.has(tag));
+    return [...filtered, source];
+}
+
+/**
+ * Assemble a feed {@link Link} draft (`category=link`, `loaderKey === value`).
+ * Does not validate locator reachability or write to Supabase.
+ */
+export function buildFeedLinkDraft(input: BuildFeedLinkDraftInput): TargetDraft<Link> {
+    if (!isFeedValue(input.value)) {
+        throw new Error(`buildFeedLinkDraft: unsupported feed value: ${String(input.value)}`);
+    }
+    if (!isFeedSource(input.source)) {
+        throw new Error(`buildFeedLinkDraft: unsupported feed source: ${String(input.source)}`);
+    }
+
+    const name = buildFeedLinkName(input.platformName, input.feedKey);
+    const locator = input.locator.trim();
+    if (locator === "") {
+        throw new Error("buildFeedLinkDraft: locator is empty");
+    }
+
+    const twinList = normalizeFeedTwinList(input.twinList);
+    const storageProvider = resolveFeedOriginalStorageProvider(input.source, input.storageProvider);
+    const original: FeedOriginal = {
+        storageProvider,
+        locator,
+        ...(twinList !== undefined ? { twinList } : {}),
+    };
+
+    return buildLinkTargetDraft({
+        name,
+        value: input.value,
+        description: input.description ?? "",
+        preview: input.preview ?? "",
+        loaderKey: input.value,
+        tagList: buildFeedTagList(input.source, input.tagList),
+        original,
+    });
+}

package/src/shared/feed/feed.interface.ts

@@ -0,0 +1,50 @@
+/**
+ * Feed Link protocol — Link rows with value/loaderKey in {@link FEED_VALUES}.
+ * No separate Target category; category remains `link`.
+ */
+
+export const FEED_VALUES = ["feed.image", "feed.audio", "feed.video", "feed.image-list"] as const;
+
+/** Discriminator stored in both `Link.value` and `details.loaderKey`. */
+export type FeedValue = (typeof FEED_VALUES)[number];
+
+/**
+ * Feed lifecycle tier — exactly one must appear in `tagList` (via `buildFeedTagList`).
+ *
+ * Leading `.` marks **system** tags (distinct from user-defined `tagList` entries).
+ */
+export const FEED_SOURCE_TAGS = [".public", ".local", ".oss"] as const;
+
+export type FeedSource = (typeof FEED_SOURCE_TAGS)[number];
+
+/** `registerFeed` only transitions `.public` → `.local` or `.oss`. */
+export const FEED_INGEST_SOURCES = [".local", ".oss"] as const;
+
+export type FeedIngestSource = (typeof FEED_INGEST_SOURCES)[number];
+
+export function isFeedIngestSource(value: string): value is FeedIngestSource {
+    return (FEED_INGEST_SOURCES as readonly string[]).includes(value);
+}
+
+/** `Link.details.original` for feed Links. */
+export interface FeedOriginal {
+    /**
+     * Backend / host id when {@link FeedSource} is `.local` or `.oss` (e.g. `LOCAL_STORAGE_PROVIDER`).
+     * Empty string when source is `.public`.
+     */
+    storageProvider: string;
+    locator: string;
+    /**
+     * Locators for sibling resources of the same feed (e.g. other media types).
+     * Omitted when not supplied on create.
+     */
+    twinList?: string[];
+}
+
+export function isFeedValue(value: string): value is FeedValue {
+    return (FEED_VALUES as readonly string[]).includes(value);
+}
+
+export function isFeedSource(value: string): value is FeedSource {
+    return (FEED_SOURCE_TAGS as readonly string[]).includes(value);
+}

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";