target-supabase-sdk 0.2.21 → 0.2.23

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/task/task-node.ts

@@ -2,7 +2,7 @@ import { isOptimisticLockResponse } from "../core.api";
 import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/node-runtime.base";
 import { createLogger, createScope, type LoggerWithScope, withModule } from "../shared/log";
 import { getErrorMessage, toError } from "../shared/utils/error.utils";
-import { patchChangeTaskStatus, patchClaimTask } from "./task.api";
+import { type PatchClaimTaskPayload, patchChangeTaskStatus, patchClaimTask } from "./task.api";
 import { CRITICAL_UNKNOWN_TASK_TRACE_ID, LOG_TOPIC_TASK } from "./task.constant";
 import { TaskStatusAction } from "./task.interface";
 import { TaskManager, type TaskRunResult } from "./task-manager";
@@ -19,6 +19,11 @@ class TaskNode extends BaseNodeRuntime {
         return [...this._availableTaskList];
     }
 
+    /** Optional claim filters passed to {@link patchClaimTask} (e.g. name prefix per task type). */
+    protected getPatchClaimTaskOptions(): Pick<PatchClaimTaskPayload, "namePrefixList"> {
+        return {};
+    }
+
     constructor() {
         super("taskNode");
     }
@@ -63,6 +68,7 @@ class TaskNode extends BaseNodeRuntime {
             nodeId,
             availableTaskList: [...availableTaskList],
             traceId: loopTraceId,
+            ...this.getPatchClaimTaskOptions(),
         });
         if (claimError) {
             if (isOptimisticLockResponse(claimError)) {

package/src/task/task.api.ts

@@ -5,12 +5,15 @@ import {
     OPTIMISTIC_LOCK_ERROR_CODE,
     OPTIMISTIC_LOCK_FAILED_MESSAGE,
     type QueryFilter,
+    type TargetFilterBuilder,
     updateTargetDetails,
     validateWithSchema,
 } from "../core.api";
 import { generateResponse, type SupabaseResponse } from "../core.interface";
 import { createLogger, type LoggerWithScope } from "../shared/log";
 import { getErrorMessage } from "../shared/utils/error.utils";
+import { escapeIlikePattern } from "../shared/utils/postgrest.utils";
+import { supabase } from "../supabase";
 import { LOG_TOPIC_TASK } from "./task.constant";
 import { CategoryTask, ResultCode, type Task, type TaskDetails, TaskStatus, TaskStatusAction } from "./task.interface";
 
@@ -112,12 +115,28 @@ export type PatchTaskProgressPayload = z.infer<typeof patchTaskProgressSchema>;
 
 export const patchClaimTaskSchema = z.object({
     nodeId: nodeIdSchema,
+    /** Task `value` must be in this list (always applied). */
     availableTaskList: z.array(z.string()).min(1),
     traceId: traceIdSchema,
+    /**
+     * Optional second axis on `name` (AND with `availableTaskList`, not coupled to `value`).
+     * When non-empty: `name` must equal a prefix or start with `prefix:`; query uses PostgREST `ilike`.
+     */
+    namePrefixList: z.array(z.string().trim().min(1)).optional(),
 });
 
 export type PatchClaimTaskPayload = z.infer<typeof patchClaimTaskSchema>;
 
+/** `name === prefix` or `name.startsWith(prefix + ':')` via `name ilike 'prefix%'`. */
+function buildClaimTaskNamePrefixFilterBuilder(namePrefixes: string[]): TargetFilterBuilder {
+    const base = supabase.client.from("target").select("*");
+    if (namePrefixes.length === 1) {
+        return base.ilike("name", `${escapeIlikePattern(namePrefixes[0])}%`);
+    }
+    const nameOrParts = namePrefixes.map((prefix) => `name.ilike.${escapeIlikePattern(prefix)}%`);
+    return base.or(nameOrParts.join(","));
+}
+
 // ─── Optimistic lock helpers ─────────────────────────────────────────────────
 
 function lockOnStatus(...allowed: TaskStatus[]): QueryFilter[] {
@@ -338,7 +357,11 @@ export const patchTaskProgress = validateWithSchema(
 /**
  * Discover and claim one TODO task for this node.
  *
- * Flow: oldest TODO in `availableTaskList` (FIFO by `created_at`) → {@link claimTaskById}.
+ * Match criteria (all required): `details.status = TODO`, `value ∈ availableTaskList`, and when
+ * `namePrefixList` is non-empty, `name` matches any listed prefix. Those filters are independent
+ * (AND); omitting `namePrefixList` does not relax the `value` constraint.
+ *
+ * Flow: oldest matching row (FIFO by `created_at`) → {@link claimTaskById}.
  * Equivalent to `patchChangeTaskStatus({ id, action: CLAIM, nodeId })` when `id` is already known.
  *
  * Returns `data: null` when no TODO task matches.
@@ -347,25 +370,49 @@ export const patchTaskProgress = validateWithSchema(
 export const patchClaimTask = validateWithSchema(
     patchClaimTaskSchema,
     "patchClaimTaskSchema",
-)(async ({ nodeId, availableTaskList, traceId }): Promise<SupabaseResponse<Task | null>> => {
+)(async ({ nodeId, availableTaskList, traceId, namePrefixList }): Promise<SupabaseResponse<Task | null>> => {
     const logger = createLogger({ module: "patchClaimTask", traceId, labels: { nodeId } });
 
+    const namePrefixes = (namePrefixList ?? []).map((prefix) => prefix.trim()).filter((prefix) => prefix !== "");
+
+    function taskNameMatchesPrefixList(name: string): boolean {
+        return namePrefixes.some((prefix) => name === prefix || name.startsWith(`${prefix}:`));
+    }
+
     let todoTask: Task;
     try {
-        const { data: taskCandidates } = await getTargetList<Task>({
-            category: CategoryTask.TASK,
-            filterList: [
-                { field: TASK_STATUS_FIELD, operator: "eq", value: TaskStatus.TODO },
-                { field: "value", operator: "in", value: availableTaskList },
-            ],
-            limit: 1,
-            orderBy: { field: "created_at", ascending: true },
-        });
-        const possibleTask = taskCandidates?.[0] ?? null;
-        if (possibleTask == null) {
-            return generateResponse.success(null);
+        if (namePrefixes.length === 0) {
+            const { data: taskCandidates } = await getTargetList<Task>({
+                category: CategoryTask.TASK,
+                filterList: [
+                    { field: TASK_STATUS_FIELD, operator: "eq", value: TaskStatus.TODO },
+                    { field: "value", operator: "in", value: availableTaskList },
+                ],
+                limit: 1,
+                orderBy: { field: "created_at", ascending: true },
+            });
+            const possibleTask = taskCandidates?.[0] ?? null;
+            if (possibleTask == null) {
+                return generateResponse.success(null);
+            }
+            todoTask = possibleTask;
+        } else {
+            const { data: taskCandidates } = await getTargetList<Task>({
+                category: CategoryTask.TASK,
+                filterList: [
+                    { field: TASK_STATUS_FIELD, operator: "eq", value: TaskStatus.TODO },
+                    { field: "value", operator: "in", value: availableTaskList },
+                ],
+                limit: 1,
+                orderBy: { field: "created_at", ascending: true },
+                filterBuilder: buildClaimTaskNamePrefixFilterBuilder(namePrefixes),
+            });
+            const possibleTask = taskCandidates?.find((task) => taskNameMatchesPrefixList(task.name)) ?? null;
+            if (possibleTask == null) {
+                return generateResponse.success(null);
+            }
+            todoTask = possibleTask;
         }
-        todoTask = possibleTask;
     } catch (error) {
         const message = getErrorMessage(error);
         logger.error("獲取 TODO 任務失敗", { topic: LOG_TOPIC_TASK, data: { error: message, availableTaskList } });