@endora-commerce/mod-catalog 0.100.0

package/dist/backend/services/attribute-value-key.service.d.ts

@@ -0,0 +1,48 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { CatalogAttributeValueKeyApi, CatalogAttributeValueKeyMove, CatalogAttributeValueKeyRenameOptions } from '../../ports/index.js';
+/**
+ * A value-key rename `catalog` refused before writing anything.
+ *
+ * `system_attribute` — `name` and `description` are product columns, not
+ * attribute values, and an override row carrying one of them is a slot of the
+ * product's own field; neither can be the source or the target of a key move.
+ * `invalid_key` — outside the grammar every product attribute key satisfies.
+ * `target_occupied` — the caller asked to `refuse` and data is already stored
+ * under the destination.
+ */
+export declare class AttributeValueKeyError extends Error {
+    readonly code: 'system_attribute' | 'invalid_key' | 'target_occupied';
+    constructor(code: 'system_attribute' | 'invalid_key' | 'target_occupied', message: string);
+}
+/**
+ * Renames an attribute's **value key** everywhere `catalog` stores it as a
+ * string (`specs/134-paid-module-extraction/research.md` D12, *Ergonode
+ * fallback boundary* and *what a rename does to data already under its
+ * destination*).
+ *
+ * Two places, and only two: `products.attribute_values`, a JSONB map keyed by
+ * the attribute key, and `product_value_overrides.attribute_key`. Everything
+ * else in the catalogue points at an attribute by id. The definition's own key
+ * is `custom_fields`' row and is renamed through its `applyRenameKey`, in the
+ * same transaction as this call — which is why this takes the caller's
+ * `EntityManager` and runs every statement on its transaction context rather
+ * than on a connection of its own.
+ *
+ * In order, all on that transaction:
+ *
+ *   1. the destination's baseline values and override rows are read and
+ *      locked (`for update`);
+ *   2. if there are any, `refuse` throws `target_occupied` — nothing has been
+ *      written — and `displace` strips the key from those products and deletes
+ *      those override rows, keeping what it removed to return;
+ *   3. the two moves run. The destination is empty by now, so the `jsonb ||`
+ *      in the first one only adds a key and the second can meet no unique
+ *      index — the result does not depend on which products held what.
+ *
+ * No command, no audit, no cache publish: the caller's composite operation owns
+ * those, exactly as for `custom_fields`' apply seam.
+ */
+export declare class AttributeValueKeyService implements CatalogAttributeValueKeyApi {
+    renameValueKey(em: EntityManager, fromKey: string, toKey: string, options: CatalogAttributeValueKeyRenameOptions): Promise<CatalogAttributeValueKeyMove>;
+}
+//# sourceMappingURL=attribute-value-key.service.d.ts.map

package/dist/backend/services/attribute-value-key.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute-value-key.service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/attribute-value-key.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC5B,qCAAqC,EAGtC,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAE7C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,aAAa,GAAG,iBAAiB;gBAA5D,IAAI,EAAE,kBAAkB,GAAG,aAAa,GAAG,iBAAiB,EACrE,OAAO,EAAE,MAAM;CAKlB;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,wBAAyB,YAAW,2BAA2B;IACpE,cAAc,CAClB,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,qCAAqC,GAC7C,OAAO,CAAC,4BAA4B,CAAC;CAwGzC"}

package/dist/backend/services/attribute-value-key.service.js

@@ -0,0 +1,118 @@
+import { customFieldDefinitionSchema, isSystemAttributeKey } from '@endora-commerce/contracts';
+/**
+ * A value-key rename `catalog` refused before writing anything.
+ *
+ * `system_attribute` — `name` and `description` are product columns, not
+ * attribute values, and an override row carrying one of them is a slot of the
+ * product's own field; neither can be the source or the target of a key move.
+ * `invalid_key` — outside the grammar every product attribute key satisfies.
+ * `target_occupied` — the caller asked to `refuse` and data is already stored
+ * under the destination.
+ */
+export class AttributeValueKeyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AttributeValueKeyError';
+    }
+}
+/**
+ * Renames an attribute's **value key** everywhere `catalog` stores it as a
+ * string (`specs/134-paid-module-extraction/research.md` D12, *Ergonode
+ * fallback boundary* and *what a rename does to data already under its
+ * destination*).
+ *
+ * Two places, and only two: `products.attribute_values`, a JSONB map keyed by
+ * the attribute key, and `product_value_overrides.attribute_key`. Everything
+ * else in the catalogue points at an attribute by id. The definition's own key
+ * is `custom_fields`' row and is renamed through its `applyRenameKey`, in the
+ * same transaction as this call — which is why this takes the caller's
+ * `EntityManager` and runs every statement on its transaction context rather
+ * than on a connection of its own.
+ *
+ * In order, all on that transaction:
+ *
+ *   1. the destination's baseline values and override rows are read and
+ *      locked (`for update`);
+ *   2. if there are any, `refuse` throws `target_occupied` — nothing has been
+ *      written — and `displace` strips the key from those products and deletes
+ *      those override rows, keeping what it removed to return;
+ *   3. the two moves run. The destination is empty by now, so the `jsonb ||`
+ *      in the first one only adds a key and the second can meet no unique
+ *      index — the result does not depend on which products held what.
+ *
+ * No command, no audit, no cache publish: the caller's composite operation owns
+ * those, exactly as for `custom_fields`' apply seam.
+ */
+export class AttributeValueKeyService {
+    async renameValueKey(em, fromKey, toKey, options) {
+        for (const key of [fromKey, toKey]) {
+            if (isSystemAttributeKey(key)) {
+                throw new AttributeValueKeyError('system_attribute', `"${key}" is a product field, not an attribute value key; nothing was renamed.`);
+            }
+            if (!customFieldDefinitionSchema.shape.key.safeParse(key).success) {
+                throw new AttributeValueKeyError('invalid_key', `"${key}" is not a valid attribute key.`);
+            }
+        }
+        if (fromKey === toKey) {
+            return { products: 0, overrides: 0, displaced: { values: [], overrides: [] } };
+        }
+        // command-coverage-ignore: owner-published rename seam — runs on the caller's
+        // transactional EM. Its one caller is a system-invariant repair with no
+        // operator and no actor (a connector re-keying the attributes it derived,
+        // committed atomically with `custom_fields`' definition rename and the
+        // connector's own repair checkpoint); an audit entry for it would have
+        // nobody to attribute. Contract: specs/134-paid-module-extraction/research.md D12.
+        const connection = em.getConnection();
+        const ctx = em.getTransactionContext();
+        const occupiedValues = (await connection.execute(`select "id" as product_id, "attribute_values" -> ?::text as value
+         from "products"
+        where jsonb_exists("attribute_values", ?::text)
+        for update`, [toKey, toKey], 'all', ctx));
+        const occupiedOverrides = (await connection.execute(`select "product_id", "channel_id", "language_code", "value"
+         from "product_value_overrides"
+        where "attribute_key" = ?
+        for update`, [toKey], 'all', ctx));
+        let displacedValues = [];
+        let displacedOverrides = [];
+        if (occupiedValues.length > 0 || occupiedOverrides.length > 0) {
+            if (options.occupied === 'refuse') {
+                throw new AttributeValueKeyError('target_occupied', `"${toKey}" already holds ${occupiedValues.length} product value(s) and ` +
+                    `${occupiedOverrides.length} override row(s); nothing was renamed.`);
+            }
+            if (occupiedValues.length > 0) {
+                await connection.execute(`update "products" set "attribute_values" = "attribute_values" - ?::text
+            where jsonb_exists("attribute_values", ?::text)`, [toKey, toKey], 'run', ctx);
+                displacedValues = occupiedValues.map((row) => ({
+                    productId: row.product_id,
+                    value: row.value,
+                }));
+            }
+            if (occupiedOverrides.length > 0) {
+                const removed = (await connection.execute(`delete from "product_value_overrides" where "attribute_key" = ?
+            returning "product_id", "channel_id", "language_code", "value"`, [toKey], 'all', ctx));
+                displacedOverrides = removed.map((row) => ({
+                    productId: row.product_id,
+                    channelId: row.channel_id,
+                    languageCode: row.language_code,
+                    value: row.value,
+                }));
+            }
+        }
+        const products = await connection.execute(`update "products"
+          set "attribute_values" = ("attribute_values" - ?::text) || jsonb_build_object(?::text, "attribute_values" -> ?::text)
+        where jsonb_exists("attribute_values", ?::text)`, [fromKey, toKey, fromKey, fromKey], 'run', ctx);
+        const overrides = await connection.execute(`update "product_value_overrides" set "attribute_key" = ? where "attribute_key" = ?`, [toKey, fromKey], 'run', ctx);
+        return {
+            products: affectedRowsOf(products),
+            overrides: affectedRowsOf(overrides),
+            displaced: { values: displacedValues, overrides: displacedOverrides },
+        };
+    }
+}
+function affectedRowsOf(result) {
+    const affected = result?.affectedRows;
+    return typeof affected === 'number' ? affected : 0;
+}
+//# sourceMappingURL=attribute-value-key.service.js.map

package/dist/backend/services/attribute-value-key.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute-value-key.service.js","sourceRoot":"","sources":["../../../src/backend/services/attribute-value-key.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/audit-references.d.ts

@@ -0,0 +1,13 @@
+import type { AuditReferenceRegistryPort } from '@endora-commerce/contracts';
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * What a `product` audit row is called, and where the admin app shows it
+ * (feature 075, D-87 drain).
+ *
+ * `audit_logs` used to run `select id, sku, name from products` for its
+ * dashboard card and spell `/catalog/products/{id}` into its own switch
+ * statement — a reader naming this module's table and this module's admin route.
+ * Both are answered here now, over this module's own entity.
+ */
+export declare function registerCatalogAuditReferences(registry: AuditReferenceRegistryPort, emFactory: () => EntityManager): void;
+//# sourceMappingURL=audit-references.d.ts.map

package/dist/backend/services/audit-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-references.d.ts","sourceRoot":"","sources":["../../../src/backend/services/audit-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,0BAA0B,EACpC,SAAS,EAAE,MAAM,aAAa,GAC7B,IAAI,CAoBN"}

package/dist/backend/services/audit-references.js

@@ -0,0 +1,51 @@
+import { Product } from '../entities/product.entity.js';
+/**
+ * What a `product` audit row is called, and where the admin app shows it
+ * (feature 075, D-87 drain).
+ *
+ * `audit_logs` used to run `select id, sku, name from products` for its
+ * dashboard card and spell `/catalog/products/{id}` into its own switch
+ * statement — a reader naming this module's table and this module's admin route.
+ * Both are answered here now, over this module's own entity.
+ */
+export function registerCatalogAuditReferences(registry, emFactory) {
+    registry.register({
+        ownerModuleId: 'catalog',
+        referenceType: 'product',
+        resolve: async (ids) => {
+            const rows = await emFactory().find(Product, { id: { $in: [...ids] } }, { fields: ['id', 'sku', 'name'] });
+            return rows.map((row) => ({
+                id: row.id,
+                // The SKU is the fallback rather than a second field: a product with no
+                // translated name still has to render as something an operator
+                // recognises, and the audit card has one line to do it in.
+                label: pickTranslation(row.name) ?? row.sku,
+                url: `/catalog/products/${row.id}`,
+            }));
+        },
+    });
+}
+/**
+ * The language fallback chain the audit card has always used. Kept in that order
+ * deliberately — moving `en-US` ahead of `en` would silently re-label existing
+ * rows on a deployment that stores both.
+ */
+function pickTranslation(value) {
+    if (!value)
+        return null;
+    // Pre-multilingual rows stored a bare string. `Object.values` over one yields
+    // its characters, so the guard is what stops a name rendering as `E`.
+    if (typeof value === 'string')
+        return value.length > 0 ? value : null;
+    for (const key of ['en', 'en-US', 'pl', 'pl-PL']) {
+        const v = value[key];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    for (const v of Object.values(value)) {
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    return null;
+}
+//# sourceMappingURL=audit-references.js.map

package/dist/backend/services/audit-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-references.js","sourceRoot":"","sources":["../../../src/backend/services/audit-references.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAoC,EACpC,SAA8B;IAE9B,QAAQ,CAAC,QAAQ,CAAC;QAChB,aAAa,EAAE,SAAS;QACxB,aAAa,EAAE,SAAS;QACxB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACrB,MAAM,IAAI,GAAG,MAAM,SAAS,EAAE,CAAC,IAAI,CACjC,OAAO,EACP,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,EAAE,EACzB,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAClC,CAAC;YACF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACxB,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,wEAAwE;gBACxE,+DAA+D;gBAC/D,2DAA2D;gBAC3D,KAAK,EAAE,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,GAAG;gBAC3C,GAAG,EAAE,qBAAqB,GAAG,CAAC,EAAE,EAAE;aACnC,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CACtB,KAAyD;IAEzD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,8EAA8E;IAC9E,sEAAsE;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,KAAK,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/backend/services/bulk-operation-queue.d.ts

@@ -0,0 +1,26 @@
+import { Queue, Worker, type Processor, type QueueOptions, type WorkerOptions } from 'bullmq';
+import type { Redis } from 'ioredis';
+/**
+ * BullMQ queue manager for catalog bulk operations (product bulk-edit and
+ * `search_reindex`), per Constitution Principle X (Scalable Queue Consumers).
+ *
+ * - The producer ({@link BulkOperationService.create}) persists a `pending`
+ *   row and enqueues `{ operationId }` here — it never inline-executes the job.
+ * - The consumer is a BullMQ {@link Worker} that claims the operation
+ *   atomically (BullMQ job lock + the row's conditional `pending → running`
+ *   UPDATE) and runs the idempotent handler, so N ≥ 2 worker instances never
+ *   double-process a job.
+ * - The worker is a **separable entrypoint**: co-located in the API process by
+ *   default (single-VPS posture) but startable as its own process via
+ *   `pnpm --filter backend run worker` without code changes.
+ */
+export interface BulkOperationJobData {
+    /** Primary key of the {@link BulkOperation} row to process. */
+    operationId: string;
+}
+export declare const BULK_OPERATION_QUEUE_NAME = "catalog.bulk-operation";
+/** Stable job name; the row is the source of truth, so a single name suffices. */
+export declare const BULK_OPERATION_JOB_NAME = "process";
+export declare function createBulkOperationQueue(redis: Redis, overrides?: Partial<QueueOptions>): Queue<BulkOperationJobData>;
+export declare function createBulkOperationWorker(redis: Redis, processor: Processor<BulkOperationJobData>, overrides?: Partial<WorkerOptions>): Worker<BulkOperationJobData>;
+//# sourceMappingURL=bulk-operation-queue.d.ts.map

package/dist/backend/services/bulk-operation-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-operation-queue.d.ts","sourceRoot":"","sources":["../../../src/backend/services/bulk-operation-queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE9F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,yBAAyB,2BAA2B,CAAC;AAElE,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAKjD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,KAAK,EACZ,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAChC,KAAK,CAAC,oBAAoB,CAAC,CAY7B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,CAAC,oBAAoB,CAAC,EAC1C,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GACjC,MAAM,CAAC,oBAAoB,CAAC,CAgB9B"}

package/dist/backend/services/bulk-operation-queue.js

@@ -0,0 +1,34 @@
+import { Queue, Worker } from 'bullmq';
+import { enterSystemScope } from '@endora-commerce/platform/kernel';
+export const BULK_OPERATION_QUEUE_NAME = 'catalog.bulk-operation';
+/** Stable job name; the row is the source of truth, so a single name suffices. */
+export const BULK_OPERATION_JOB_NAME = 'process';
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BACKOFF = { type: 'exponential', delay: 2_000 };
+export function createBulkOperationQueue(redis, overrides) {
+    const options = {
+        connection: redis,
+        defaultJobOptions: {
+            attempts: DEFAULT_ATTEMPTS,
+            backoff: DEFAULT_BACKOFF,
+            removeOnComplete: { count: 500 },
+            removeOnFail: { count: 5_000 },
+        },
+        ...overrides,
+    };
+    return new Queue(BULK_OPERATION_QUEUE_NAME, options);
+}
+export function createBulkOperationWorker(redis, processor, overrides) {
+    const options = {
+        connection: redis,
+        // Bulk operations are heavy (one drains a whole selection); keep a small
+        // concurrency per instance and scale out by adding worker processes.
+        concurrency: 2,
+        ...overrides,
+    };
+    // Feature 072 (T033) — the job establishes its own scope. A bulk operation
+    // writes through the Command Bus, which derives its actor from the ambient
+    // context, so "no context" was never a safe state here.
+    return new Worker(BULK_OPERATION_QUEUE_NAME, (job) => enterSystemScope('catalog: bulk operation', () => processor(job)), options);
+}
+//# sourceMappingURL=bulk-operation-queue.js.map

package/dist/backend/services/bulk-operation-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-operation-queue.js","sourceRoot":"","sources":["../../../src/backend/services/bulk-operation-queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAyD,MAAM,QAAQ,CAAC;AAC9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAuBpE,MAAM,CAAC,MAAM,yBAAyB,GAAG,wBAAwB,CAAC;AAElE,kFAAkF;AAClF,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAEjD,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,eAAe,GAAG,EAAE,IAAI,EAAE,aAAsB,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAEvE,MAAM,UAAU,wBAAwB,CACtC,KAAY,EACZ,SAAiC;IAEjC,MAAM,OAAO,GAAiB;QAC5B,UAAU,EAAE,KAAK;QACjB,iBAAiB,EAAE;YACjB,QAAQ,EAAE,gBAAgB;YAC1B,OAAO,EAAE,eAAe;YACxB,gBAAgB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE;YAChC,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;SAC/B;QACD,GAAG,SAAS;KACb,CAAC;IACF,OAAO,IAAI,KAAK,CAAuB,yBAAyB,EAAE,OAAO,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAY,EACZ,SAA0C,EAC1C,SAAkC;IAElC,MAAM,OAAO,GAAkB;QAC7B,UAAU,EAAE,KAAK;QACjB,yEAAyE;QACzE,qEAAqE;QACrE,WAAW,EAAE,CAAC;QACd,GAAG,SAAS;KACb,CAAC;IACF,2EAA2E;IAC3E,2EAA2E;IAC3E,wDAAwD;IACxD,OAAO,IAAI,MAAM,CACf,yBAAyB,EACzB,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,yBAAyB,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAC1E,OAAO,CACR,CAAC;AACJ,CAAC"}

package/dist/backend/services/bulk-operation.service.d.ts

@@ -0,0 +1,195 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type AdminUserReadPort, type EmailMailerPort } from '@endora-commerce/contracts';
+import type { CommandBus } from '@endora-commerce/platform/commands';
+import { type BulkOperationLogEntry, type BulkOperationPayload, type BulkOperationStatus } from '../entities/bulk-operation.entity.js';
+import type { CatalogBulkUpdateService, BulkUpdateOutcome } from './catalog-bulk-update.service.js';
+/** The bell entry a finished bulk operation writes for the admin who asked. */
+export interface BulkNotificationInput {
+    audience: 'admin_user';
+    targetAdminUserId: string;
+    kind: string;
+    subjectType?: string | null;
+    subjectId?: string | null;
+    title: string;
+    body?: string | null;
+    linkPath?: string | null;
+}
+/**
+ * `admin_notifications`' port, as this module reaches it.
+ *
+ * Resolving it asks a gate, so it either records or throws — it cannot answer
+ * "the operator switched the bell off", which is why the degrade lives in the
+ * recorder below rather than here (D-61's rejected alternative).
+ */
+export interface BulkNotificationPort {
+    record(input: BulkNotificationInput): Promise<unknown>;
+}
+/**
+ * What this module actually holds — the degrade in the return type (D-60).
+ *
+ * `not-present` is the operator having switched `admin_notifications` off. It
+ * is composed before the port is reached, so the `catch` around the write is
+ * left with what a `catch` should be left with: a failed write.
+ */
+export type BulkNotificationOutcome = 'recorded' | 'not-present';
+export interface BulkNotificationRecorder {
+    record(input: BulkNotificationInput): Promise<BulkNotificationOutcome>;
+}
+/**
+ * Wraps the gated port in the presence decision, so absence is *decided* rather
+ * than caught (D-60; Constitution XVII).
+ *
+ * A function rather than an object literal at the composition site on purpose:
+ * `check-port-catches.ts` follows the port **through the value**, and an object
+ * literal is where that trail deliberately stops.
+ */
+export declare function presenceAwareBulkRecorder(adminNotifications: BulkNotificationPort): BulkNotificationRecorder;
+export interface CreateBulkOperationInput {
+    requestedByAdminUserId: string;
+    payload: BulkOperationPayload;
+    type?: string;
+}
+export interface SerializedBulkOperation {
+    id: string;
+    type: string;
+    status: BulkOperationStatus;
+    requestedByAdminUserId: string;
+    total: number;
+    processed: number;
+    succeeded: number;
+    skipped: number;
+    failed: number;
+    touchedFields: string[];
+    results: BulkUpdateOutcome[] | null;
+    logs: BulkOperationLogEntry[] | null;
+    error: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+    reversible: boolean;
+    undoStatus: 'none' | 'reverted' | 'partially_reverted';
+    undoneAt: string | null;
+}
+export interface ListBulkOperationsInput {
+    status?: BulkOperationStatus[];
+    limit?: number;
+    offset?: number;
+}
+export interface ListBulkOperationsResult {
+    items: SerializedBulkOperation[];
+    total: number;
+}
+/**
+ * Runs a full Meilisearch reindex (the `search:reindex` CLI equivalent) and
+ * reports how many documents landed. Wired from the composition root so the
+ * catalog module stays decoupled from the search module's indexer.
+ */
+export type SearchReindexRunner = () => Promise<{
+    /** Total documents pushed across every channel index. */
+    documentCount: number;
+}>;
+export declare class BulkOperationService {
+    #private;
+    private readonly emFactory;
+    private readonly bulkUpdateService;
+    private readonly deps;
+    /**
+     * Feature 054 — when injected, product bulk edits capture per-product revert
+     * state and expose an audited, conflict-aware undo (US2). Optional so bus-less
+     * constructions (some tests) keep the pre-054 behavior.
+     */
+    private readonly commandBus?;
+    /** Single-flight guard so overlapping sweep ticks don't double-process. */
+    private draining;
+    constructor(emFactory: () => EntityManager, bulkUpdateService: CatalogBulkUpdateService, deps?: {
+        notificationService?: BulkNotificationRecorder;
+        mailer?: EmailMailerPort;
+        /**
+         * Feature 075 — who requested the operation, read through `admin_users`'
+         * port instead of `em.findOne(AdminUser, …)` against its table. Only the
+         * e-mail address is used, to tell the requester their run finished.
+         *
+         * Optional in the shape, like the two above, because a composition that
+         * neither notifies nor mails never reaches it.
+         */
+        adminUsers?: AdminUserReadPort;
+        /**
+         * Producer hook: hands the new operation's id to the durable queue.
+         * Called once per `create()` with the persisted row's id. Failures are
+         * swallowed by the caller — the `pending` row is the source of truth and
+         * the worker's boot reconciliation re-enqueues anything left behind.
+         */
+        onEnqueued?: (operationId: string) => void | Promise<void>;
+        /**
+         * Runs a full Meilisearch reindex for `search_reindex` operations.
+         * When omitted, such operations fail with a clear "not configured"
+         * message rather than silently no-op'ing.
+         */
+        reindexRunner?: SearchReindexRunner;
+    }, 
+    /**
+     * Feature 054 — when injected, product bulk edits capture per-product revert
+     * state and expose an audited, conflict-aware undo (US2). Optional so bus-less
+     * constructions (some tests) keep the pre-054 behavior.
+     */
+    commandBus?: CommandBus | undefined);
+    create(input: CreateBulkOperationInput): Promise<SerializedBulkOperation>;
+    /**
+     * Consumer entry point invoked by the BullMQ worker for one queued
+     * operation. Atomically claims the row (`pending → running`); if the claim
+     * affects no row the operation was already taken or finished, so this is a
+     * no-op — making the handler idempotent under redelivery/retries and safe at
+     * N ≥ 2 worker instances.
+     */
+    processById(operationId: string): Promise<void>;
+    /**
+     * Ids of every operation still `pending`. Used by the worker at boot to
+     * re-enqueue rows that were created while no producer/queue was reachable
+     * (e.g. an enqueue failure, or a row predating this deployment).
+     */
+    findPendingIds(): Promise<string[]>;
+    list(input?: ListBulkOperationsInput): Promise<ListBulkOperationsResult>;
+    get(id: string): Promise<SerializedBulkOperation | null>;
+    /**
+     * Drain every `pending` operation. Safe to call repeatedly and
+     * concurrently — the single-flight guard ensures one drain at a time.
+     */
+    processPending(): Promise<{
+        processed: number;
+    }>;
+    /**
+     * Atomically flip the oldest `pending` row to `running` and return its
+     * id. The conditional UPDATE means even if two drains race past the
+     * in-process guard (e.g. across worker restarts) only one wins a row.
+     */
+    private claimNextPending;
+    private processOne;
+    /**
+     * Runs a `search_reindex` operation: a full Meilisearch reindex (the
+     * `search:reindex` CLI equivalent). Counts every reindexed document as
+     * both processed and succeeded; failure surfaces on the row + notifications.
+     */
+    private processReindex;
+    private notify;
+    /**
+     * Undo a reversible bulk edit: restore every affected product whose current
+     * state still matches the operation's captured after-state; refuse (report,
+     * never clobber) any product changed since. Runs as an audited `bulk.undo`
+     * Command and is idempotent-safe on re-invocation (FR-006/FR-007/FR-014).
+     */
+    undo(operationId: string): Promise<UndoOutcome>;
+}
+/** Undo result surfaced to the route (mapped to 200/404/409). */
+export type UndoOutcome = {
+    ok: true;
+    reverted: string[];
+    conflicts: {
+        recordId: string;
+        reason: string;
+    }[];
+    undoStatus: 'reverted' | 'partially_reverted' | 'none';
+} | {
+    ok: false;
+    code: 'NOT_FOUND' | 'NOT_REVERSIBLE' | 'ALREADY_REVERTED';
+};
+//# sourceMappingURL=bulk-operation.service.d.ts.map

package/dist/backend/services/bulk-operation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-operation.service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/bulk-operation.service.ts"],"names":[],"mappings":"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"}