pixivflow 3.3.0 → 3.4.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "private": true
 }

package/dist/scheduler/CandidateSearchParams.d.ts

@@ -25,7 +25,23 @@ export interface CandidateSearchParams {
         platform?: string;
         account?: string;
     };
-    query: {
+    /**
+     * Scope selector: which of the producer's CONFIGURED targets this job runs
+     * for. It selects an existing target — it never overrides that target's
+     * delivery wiring or plan identity (see `ManualJobAdmission.resolveTarget`).
+     * It is deliberately NOT part of the stored retrieval view: the admission
+     * lifts it into `CandidateSearchJobRequest.targetSelector`, so a job that only
+     * names a target runs that target exactly as configured. This is what makes
+     * the generic `POST /jobs` face equivalent to the legacy refetch entry point,
+     * whose target used to live in the request path.
+     */
+    target_id?: string;
+    /**
+     * Retrieval override. Optional: omitting it (with or without `target_id`)
+     * means "run the resolved target's own configured search", which is what every
+     * pre-protocol refetch did.
+     */
+    query?: {
         tags: string[];
         expand?: boolean;
     };

package/dist/scheduler/CandidateSearchParams.js

@@ -42,18 +42,27 @@ function clamp(value, min, max) {
  * where the target is known.
  */
 function applyCandidateSearchParams(target, params) {
-    const tags = params.query.tags;
+    const tags = params.query?.tags;
     const limit = params.constraints?.limit !== undefined ? clamp(params.constraints.limit, 1, exports.CANDIDATE_SEARCH_SCAN_LIMIT_MAX) : target.limit;
     const scanLimit = params.constraints?.scan_limit !== undefined
         ? clamp(params.constraints.scan_limit, limit ?? 1, exports.CANDIDATE_SEARCH_SCAN_LIMIT_MAX)
         : target.candidateScanLimit;
-    return {
+    const constrained = {
         ...target,
-        tag: tags.join(' '),
-        ...(tags.length > 1 && params.query.expand === true ? { tagRelation: 'or' } : {}),
         ...(limit !== undefined ? { limit } : {}),
         ...(scanLimit !== undefined ? { candidateScanLimit: scanLimit } : {}),
     };
+    // `query` is optional: a job may carry only a scope selector and/or
+    // constraints, in which case the retrieval side stays exactly as the target is
+    // configured. (`parseCandidateSearchParamsJson` already yields `null` for such
+    // a stored view, so this is the belt to that braces.)
+    if (!tags || tags.length === 0)
+        return constrained;
+    return {
+        ...constrained,
+        tag: tags.join(' '),
+        ...(tags.length > 1 && params.query?.expand === true ? { tagRelation: 'or' } : {}),
+    };
 }
 /**
  * Map `constraints.exclude` onto the existing per-run duplicate history.

package/dist/scheduler/JobFacade.d.ts

@@ -128,6 +128,13 @@ export interface ParsedTask {
     correlationId?: string;
     /** `params.source.account` — the Pixiv resource identity to assert. */
     account?: string;
+    /**
+     * `params.target_id` — which CONFIGURED target this job runs for. A selector,
+     * never an override: the admission resolves it against the same enabled plans
+     * and targets the legacy path used. Absent means "the deployment must have
+     * exactly one manual-eligible target".
+     */
+    targetSelector?: string;
     /** `params` — the occurrence-scoped retrieval view. */
     params: CandidateSearchParams;
     /**

package/dist/scheduler/JobFacade.js

@@ -46,6 +46,7 @@ const MAX_CALLBACK_URL_LENGTH = 2000;
 const MAX_TAG_LENGTH = 100;
 const MAX_TAGS = 20;
 const MAX_EXCLUSIONS = 100;
+const MAX_TARGET_ID_LENGTH = 200;
 /** The only job type this producer serves today. */
 exports.JOB_TYPE_CANDIDATE_SEARCH = 'candidate_search';
 /** `$defs/ProtocolVersion` — this producer speaks exactly one version. */
@@ -268,15 +269,44 @@ function parseTaskBody(body) {
         }
     }
     const params = parseCandidateSearchParams(body.params);
+    // `params.target_id` is a SCOPE selector, not part of the retrieval view: it
+    // selects one of the targets this deployment already configures and never
+    // rewrites the target's delivery wiring or plan identity. It is lifted out
+    // here so the stored `paramsJson` stays a pure retrieval view — a job carrying
+    // only a selector therefore behaves exactly like the legacy refetch route,
+    // which ran the target as configured.
+    const targetSelector = parseTargetSelector(body.params);
     return {
         idempotencyKey,
         ...(correlationId !== undefined ? { correlationId } : {}),
         ...(params.source?.account !== undefined ? { account: params.source.account } : {}),
+        ...(targetSelector !== undefined ? { targetSelector } : {}),
         params,
         ...(deadlineMs !== undefined ? { deadlineMs } : {}),
         ...(callbackUrl !== undefined ? { callbackUrl } : {}),
     };
 }
+/**
+ * `params.target_id` — the explicit target scope of a generic `candidate_search`.
+ *
+ * Optional and additive: absent means "the deployment must have exactly one
+ * manual-eligible target", which is the pre-existing behaviour.
+ */
+function parseTargetSelector(raw) {
+    if (!isPlainObject(raw))
+        return undefined;
+    const value = raw.target_id;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw invalid('params.target_id must be a non-empty string');
+    }
+    const selector = value.trim();
+    if (selector.length > MAX_TARGET_ID_LENGTH) {
+        throw invalid(`params.target_id must be at most ${MAX_TARGET_ID_LENGTH} characters`);
+    }
+    return selector;
+}
 /** `$defs/CandidateSearchParams`, validated field by field. */
 function parseCandidateSearchParams(raw) {
     if (!isPlainObject(raw)) {
@@ -302,32 +332,39 @@ function parseCandidateSearchParams(raw) {
             source = { platform };
         }
     }
-    const query = raw.query;
-    if (!isPlainObject(query)) {
-        throw invalid('params.query must be a JSON object');
-    }
-    const tags = query.tags;
-    if (!Array.isArray(tags) || tags.length === 0) {
-        throw invalid('params.query.tags must be a non-empty array of strings');
-    }
-    if (tags.length > MAX_TAGS) {
-        throw invalid(`params.query.tags must contain at most ${MAX_TAGS} tags`);
-    }
-    for (const tag of tags) {
-        if (typeof tag !== 'string' || tag.trim() === '' || tag.length > MAX_TAG_LENGTH) {
+    // `query` is optional: a job may carry only a scope selector
+    // (`params.target_id`) and/or constraints, in which case the resolved target
+    // runs exactly as configured — the same semantics the legacy refetch route
+    // always had. When present it is validated exactly as before.
+    let query;
+    if (raw.query !== undefined && raw.query !== null) {
+        if (!isPlainObject(raw.query)) {
+            throw invalid('params.query must be a JSON object');
+        }
+        const tags = raw.query.tags;
+        if (!Array.isArray(tags) || tags.length === 0) {
             throw invalid('params.query.tags must be a non-empty array of strings');
         }
-    }
-    if (query.expand !== undefined && query.expand !== null && typeof query.expand !== 'boolean') {
-        throw invalid('params.query.expand must be a boolean');
+        if (tags.length > MAX_TAGS) {
+            throw invalid(`params.query.tags must contain at most ${MAX_TAGS} tags`);
+        }
+        for (const tag of tags) {
+            if (typeof tag !== 'string' || tag.trim() === '' || tag.length > MAX_TAG_LENGTH) {
+                throw invalid('params.query.tags must be a non-empty array of strings');
+            }
+        }
+        if (raw.query.expand !== undefined && raw.query.expand !== null && typeof raw.query.expand !== 'boolean') {
+            throw invalid('params.query.expand must be a boolean');
+        }
+        query = {
+            tags: tags.map((tag) => tag.trim()),
+            ...(raw.query.expand === true ? { expand: true } : {}),
+        };
     }
     const constraints = parseConstraints(raw.constraints);
     return {
         ...(source !== undefined ? { source } : {}),
-        query: {
-            tags: tags.map((tag) => tag.trim()),
-            ...(query.expand === true ? { expand: true } : {}),
-        },
+        ...(query !== undefined ? { query } : {}),
         ...(constraints !== undefined ? { constraints } : {}),
     };
 }
@@ -395,7 +432,18 @@ function buildCapabilities(config, now = Date.now()) {
                 // durable stream and `POST /jobs/:id/events/ack` persists the cursor
                 // (`src/scheduler/JobEventStream.ts`), and a Task's `callback_url`
                 // receives `$defs/Event` bodies through the existing outbox.
-                features: ['events', 'progress', 'cancel', 'idempotency', 'exclude', 'tag_expansion'],
+                // `target_selector` declares `params.target_id`: a job may name which
+                // configured target it runs for, and may omit `params.query` entirely —
+                // both are what makes this face a drop-in for the legacy refetch route.
+                features: [
+                    'events',
+                    'progress',
+                    'cancel',
+                    'idempotency',
+                    'exclude',
+                    'tag_expansion',
+                    'target_selector',
+                ],
                 queued_timeout_ms: budgets.queuedTimeoutMs,
                 stall_timeout_ms: budgets.stallTimeoutMs,
                 heartbeat_interval_ms: SlotCoordinator_1.SLOT_HEARTBEAT_MS,

package/dist/scheduler/ManualJobAdmission.d.ts

@@ -30,8 +30,11 @@ export declare const MANUAL_CANDIDATE_SEARCH_SLOT_NAME = "\u5BA1\u6838\u7FA4\u91
 /**
  * A consumer-initiated candidate search, normalized from whichever adapter
  * received it. `targetId` exists only for the legacy path (the old endpoint
- * carries the target in its URL); the generic job surface resolves the target
- * from configuration instead, optionally narrowed by `account`.
+ * carries the target in its URL); the generic job surface instead names the
+ * target explicitly with `targetSelector` (`params.target_id`) or, when it names
+ * none, resolves the unique manual-eligible target from configuration. Both are
+ * SELECTORS over the configured targets — neither can override delivery wiring or
+ * plan identity.
  */
 export interface CandidateSearchJobRequest {
     /** Consumer idempotency key; becomes the durable `manual_request_id`. */
@@ -40,6 +43,8 @@ export interface CandidateSearchJobRequest {
     correlationId?: string;
     /** Legacy adapter only: target id taken from the request path. */
     targetId?: string;
+    /** Generic adapter only: `params.target_id`, an explicit target selector. */
+    targetSelector?: string;
     /** Generic adapter only: `params.source.account` resource identity. */
     account?: string;
     /**
@@ -90,8 +95,11 @@ export declare class ManualJobAdmission {
     /**
      * Legacy: the target comes from the URL and must resolve to exactly one
      * enabled plan (the historic `unknown target` / `ambiguous target` rules).
-     * Generic: the target is discovered from configuration — every enabled plan's
-     * selected target that actually wires manual candidate-search delivery.
+     * Generic with `params.target_id`: the same rules, applied to the selector the
+     * caller named — a selector picks an existing target, it never rewrites one.
+     * Generic without any selector: the target is discovered from configuration —
+     * every enabled plan's selected target that actually wires manual
+     * candidate-search delivery, which must be exactly one.
      */
     private resolveTarget;
     /**

package/dist/scheduler/ManualJobAdmission.js

@@ -60,7 +60,7 @@ class ManualJobAdmission {
         const legacy = request.targetId !== undefined;
         const config = this.deps.config();
         this.assertAccount(config, request.account);
-        const admission = this.resolveTarget(config, request.targetId);
+        const admission = this.resolveTarget(config, request.targetId, request.targetSelector);
         const { plan, target } = admission;
         this.assertParamsApplyToTarget(target, request.params);
         const derivedSlotId = `${plan.id}@manual-${key.toLowerCase()}`;
@@ -109,34 +109,40 @@ class ManualJobAdmission {
     /**
      * Legacy: the target comes from the URL and must resolve to exactly one
      * enabled plan (the historic `unknown target` / `ambiguous target` rules).
-     * Generic: the target is discovered from configuration — every enabled plan's
-     * selected target that actually wires manual candidate-search delivery.
+     * Generic with `params.target_id`: the same rules, applied to the selector the
+     * caller named — a selector picks an existing target, it never rewrites one.
+     * Generic without any selector: the target is discovered from configuration —
+     * every enabled plan's selected target that actually wires manual
+     * candidate-search delivery, which must be exactly one.
      */
-    resolveTarget(config, targetId) {
-        if (targetId !== undefined) {
+    resolveTarget(config, targetId, targetSelector) {
+        const explicit = targetId ?? targetSelector;
+        if (explicit !== undefined) {
             const plans = (config.schedules ?? []).filter((plan) => plan.enabled !== false &&
-                (0, schedules_1.selectScheduleTargets)(config.targets, plan).some((target) => target.id === targetId));
+                (0, schedules_1.selectScheduleTargets)(config.targets, plan).some((target) => target.id === explicit));
             if (plans.length === 0) {
                 throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 404, {
                     message: 'unknown target',
-                    detail: { reason: 'unknown_target', target_id: targetId },
+                    detail: { reason: 'unknown_target', target_id: explicit },
                 });
             }
             if (plans.length !== 1) {
                 throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 409, {
                     message: 'ambiguous target',
-                    detail: { reason: 'ambiguous_target', target_id: targetId },
+                    detail: { reason: 'ambiguous_target', target_id: explicit },
                 });
             }
             const plan = plans[0];
-            const target = (0, schedules_1.selectScheduleTargets)(config.targets, plan).find((item) => item.id === targetId && Boolean(item.id));
+            const target = (0, schedules_1.selectScheduleTargets)(config.targets, plan).find((item) => item.id === explicit && Boolean(item.id));
             if (!target || !target.id) {
                 throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 404, {
                     message: 'unknown target',
-                    detail: { reason: 'unknown_target', target_id: targetId },
+                    detail: { reason: 'unknown_target', target_id: explicit },
                 });
             }
-            this.assertManualWiring(config, target, target.id, true);
+            // `legacy` only selects the historic diagnostic vocabulary: the URL-borne
+            // target is the old path, `params.target_id` is the generic one.
+            this.assertManualWiring(config, target, target.id, targetId !== undefined);
             return { plan, target, targetId: target.id };
         }
         const candidates = [];

package/dist/scheduler/ManualJobService.js

@@ -47,6 +47,7 @@ class ManualJobService {
             idempotencyKey: task.idempotencyKey,
             ...(task.correlationId !== undefined ? { correlationId: task.correlationId } : {}),
             ...(task.account !== undefined ? { account: task.account } : {}),
+            ...(task.targetSelector !== undefined ? { targetSelector: task.targetSelector } : {}),
             params: task.params,
         });
         // The admission event (and the declared callback_url) are recorded against

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUILD = void 0;
 // GENERATED by scripts/write-version.js — do not edit manually.
-exports.BUILD = { version: '3.3.0', commit: 'ed16abe8e473' };
+exports.BUILD = { version: '3.4.0', commit: '5d231179a9b3' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow-webui-backend",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "PixivFlow WebUI Backend - CommonJS module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixivflow",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "🎨 Pixiv 下载、筛选与自动收集工具 - 批量下载插画和小说、按标签/热度/日期筛选、定时任务与可靠 HTTP 交付 | Pixiv downloader and automation toolkit with filtering, scheduling and reliable HTTP delivery",
   "repository": {
     "type": "git",