@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/user-data-rights/run-export-jobs.d.ts

@@ -28,29 +28,23 @@ export declare const tokenCrud: import("@cosmicdrift/kumiko-types/event-store-ex
     readonly useCount: unknown;
 }>;
 /**
- * Notification-Callback fuer den done-Pfad. Pattern matched
- * auth-routes.PasswordResetConfig.sendResetEmail. Plain-Token bleibt
- * ephemeral (nicht in DB/event-store/jobRunsTable). App-Author wired
- * den Callback an seinen Email-Provider:
- *   - existing `delivery.notify` (multi-channel + delivery_attempts-Log)
- *   - `mailFoundation.send` direkt
- *   - Custom Resend/SES/etc.
+ * Notification callback for the done path. The plain token remains ephemeral
+ * and is never stored in the database or event store. The application wires
+ * this callback to its email provider, such as `delivery.notify`,
+ * `mailFoundation.send`, or a custom Resend/SES integration.
  *
- * **Best-effort:** Throw vom Callback bubbelt zum r.job-Wrap; jobs-
- * Feature persistiert den Worker-Run als failed in jobRunsTable. Der
- * Failed-Pfad wird in `jobs/__tests__/jobs-feature.integration.ts`
- * Scenario 2 gepinnt — wir verweisen darauf statt end-zu-end zu
- * duplizieren. Operator sieht's im /jobs-Dashboard, kann via
- * jobs:write:retry den Worker-Run erneut anstossen (Job selbst bleibt
- * done; retry findet keinen pending mehr, aber Audit-Log zeigt den
- * Failure).
+ * **Best-effort:** a throw from the callback bubbles to the r.job wrap, and the
+ * jobs feature records the worker run as failed in jobRunsTable while the export
+ * job stays done. That failed path is covered by Scenario 2 in
+ * `jobs/__tests__/jobs-feature.integration.test.ts` instead of being duplicated
+ * end to end here. Operators see the failure in the /jobs dashboard and can
+ * re-run the worker via jobs:write:retry.
  *
- * **Plain-Token-Recovery bei Email-Fail:** plain ist ephemeral. Wenn
- * der Callback throwt, ist der plain verloren. Operator-Eingriff
- * noetig: Job auf pending flippen — NUR das. Die Token-Row NICHT
- * loeschen (eventloser Read-Side-Delete → Rebuild-Kollision, fw#832);
- * der naechste Worker-Run rotiert das Token in place auf demselben
- * Aggregat. Atom 5b (Re-issue-handler) wird das automatisieren.
+ * **Recovering the plain token after an email failure:** the plain token is
+ * ephemeral, so it is lost when the callback throws. Flip the job back to
+ * pending and nothing else: do not delete the token row, because an eventless
+ * read-side delete collides with projection rebuilds. The next worker run
+ * rotates the token in place on the same aggregate.
  */
 export type SendExportReadyEmailFn = (args: {
     readonly userId: string;
@@ -76,23 +70,26 @@ export interface RunExportJobsArgs {
     readonly db: DbConnection;
     readonly registry: Registry;
     /**
-     * Per-Tenant Storage-Provider-Builder. App-Bootstrap liefert den
-     * file-foundation-Resolver via `createFileProviderForTenant` —
-     * Worker bekommt eine kleinere Surface ohne HandlerContext-Dep.
+     * Builds a storage provider for a tenant. The application supplies the
+     * `createFileProviderForTenant` resolver so the worker does not depend on
+     * HandlerContext.
      */
     readonly buildStorageProvider: (tenantId: TenantId) => Promise<FileStorageProvider>;
-    /** Now-Injection — Tests pinnen den Wert ohne Date-Mock. */
+    /** Injected time lets tests avoid mocking the system clock. */
     readonly now: Instant;
-    /** S2.U3 Atom 5 — Email-Notification beim done-flip. Optional;
-     *  wenn nicht gesetzt, sendet der Worker keine notification (User
-     *  kann aber via export-status.query polln + UI-Klick). */
+    /**
+     * Optional notification on the done transition. When absent, callers can
+     * poll `export-status.query` and let the user trigger the download.
+     */
     readonly sendExportReadyEmail?: SendExportReadyEmailFn;
-    /** Optional Email beim failed-flip. */
+    /** Optional notification on the failed transition. */
     readonly sendExportFailedEmail?: SendExportFailedEmailFn;
-    /** Base-URL fuer den Magic-Link. App-Author setzt das (z.B.
-     *  "https://app.example.com/user-export/by-token"). Worker baut
-     *  a URL fragment (not a query param — see issue #1271) and passes that
-     *  Callback durch. Required wenn sendExportReadyEmail gesetzt. */
+    /**
+     * Base URL for the magic link, for example
+     * "https://app.example.com/user-export/by-token". The worker appends the
+     * token as a URL fragment rather than a query parameter. Required when
+     * `sendExportReadyEmail` is provided.
+     */
     readonly appExportDownloadUrl?: string;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly escapeHatchAuditLog?: Logger;
@@ -110,21 +107,20 @@ export interface ExportJobError {
     readonly message: string;
 }
 export interface RunExportJobsResult {
-    /** Job-IDs die in diesem Pass von pending → done geflippt wurden. */
+    /** IDs of jobs transitioned from pending to done in this pass. */
     readonly completedJobIds: readonly string[];
-    /** Job-IDs die in diesem Pass von pending → failed geflippt wurden. */
+    /** IDs of jobs transitioned from pending to failed in this pass. */
     readonly failedJobIds: readonly string[];
-    /** Job-IDs die als stuck-running auf failed geflippt wurden (Stale-Pass). */
+    /** IDs of stuck running jobs transitioned to failed by stale detection. */
     readonly staleFailedJobIds: readonly string[];
-    /** Job-IDs deren downloadStorageKey im Cleanup-Pass geloescht wurde. */
+    /** IDs of jobs whose downloadStorageKey was deleted during cleanup. */
     readonly cleanedJobIds: readonly string[];
     readonly errors: readonly ExportJobError[];
     /**
-     * Plain-Tokens fuer in diesem Pass completed-Jobs. Map<jobId, plain>.
-     * Atom 5 (Notification) liest das + versendet plain per Email.
-     * NIEMALS persistiert — nur in-memory zwischen Worker-Run und
-     * Notification-Hook. NACH dem Run ist plain nur via DB-Hash
-     * verifizierbar (Atom 4b's Download-Endpoint).
+     * Plain tokens for jobs completed in this pass, keyed by job ID. These
+     * values are passed to the notification hook only in memory and are never
+     * persisted; after the run, the download endpoint can verify only the
+     * corresponding database hash.
      */
     readonly tokenByJobId: ReadonlyMap<string, string>;
 }