@endora-commerce/mod-catalog 0.100.0

package/dist/backend/services/product-link.service.js

@@ -0,0 +1,297 @@
+import { ERROR_CODES, listingPriceMoney, } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { Product } from '../entities/product.entity.js';
+import { ProductLink } from '../entities/product-link.entity.js';
+import { resolvePrimaryAssetUrls } from './primary-asset-url.js';
+import { viewerOrganizationFor } from './viewer-organization.js';
+function pickLang(blob, preferred) {
+    if (preferred && blob[preferred])
+        return blob[preferred];
+    const fallback = blob['en-US'] ?? blob['en'] ?? Object.values(blob)[0] ?? '';
+    return fallback;
+}
+export class ProductLinkService {
+    emFactory;
+    commandBus;
+    listingPrices;
+    assets;
+    channelMembership;
+    organizationDetails;
+    constructor(emFactory, 
+    /** Feature 054 — audits product-link writes co-transactionally when provided. */
+    commandBus, 
+    /**
+     * Issue #132 — the pricing engine, through the `pricingService` port. A
+     * related-product tile is a listing: it prices through the same chain as the
+     * catalogue grid, not off the catalogue's legacy default-price attribute.
+     */
+    listingPrices, 
+    /**
+     * Feature 075 — `assets_library`'s read port. The two `join assets` clauses
+     * this service used to write are gone; the tile's image is resolved by the
+     * shared `resolvePrimaryAssetUrls` helper, which asks the owner for the
+     * asset row and keeps the bridge query on this module's own tables.
+     */
+    assets, 
+    /**
+     * Issue #185 — the kernel's channel-membership accessor. The storefront
+     * link read below asked `sales_channel_products` in raw SQL, which crosses
+     * the boundary while naming no import specifier and is the read
+     * Constitution XII reserves to this service.
+     *
+     * Optional only in the signature, like the two above; a link read that
+     * reaches it unwired fails loudly rather than quietly answering the
+     * cross-channel set.
+     */
+    channelMembership, 
+    /**
+     * `organizations`' read model — the customer group a group-targeted price
+     * list is selected by, which lives on the organisation row. Optional only
+     * in the signature, and never reached by an anonymous strip.
+     */
+    organizationDetails) {
+        this.emFactory = emFactory;
+        this.commandBus = commandBus;
+        this.listingPrices = listingPrices;
+        this.assets = assets;
+        this.channelMembership = channelMembership;
+        this.organizationDetails = organizationDetails;
+    }
+    #requireOrganizationDetails() {
+        if (!this.organizationDetails) {
+            throw new Error('ProductLinkService: the organization read port is not wired — a signed-in buyer cannot be priced.');
+        }
+        return this.organizationDetails;
+    }
+    #requireChannelMembership() {
+        if (!this.channelMembership) {
+            throw new Error('ProductLinkService: the channel-membership port is not wired — link tiles cannot be ' +
+                'scoped to a channel without leaking the cross-channel set.');
+        }
+        return this.channelMembership;
+    }
+    #requireAssets() {
+        if (!this.assets) {
+            throw new Error('ProductLinkService: the asset read port is not wired — link tiles cannot show an image.');
+        }
+        return this.assets;
+    }
+    #requireListingPrices() {
+        if (!this.listingPrices) {
+            throw new Error('ProductLinkService: the pricing port is not wired — link tiles cannot be priced.');
+        }
+        return this.listingPrices;
+    }
+    /** Feature 054 — run a product-link write through the Command Bus. */
+    async #audited(action, objectId, write) {
+        if (this.commandBus) {
+            return this.commandBus.run({ action, objectType: 'product_link', objectId, run: ({ em }) => write(em) });
+        }
+        const em = this.emFactory();
+        const w = await write(em);
+        await em.flush();
+        return w.result;
+    }
+    async listForAdmin(sourceProductId, kind) {
+        const em = this.emFactory();
+        const where = { sourceProductId };
+        if (kind)
+            where['kind'] = kind;
+        const rows = await em.find(ProductLink, where, {
+            orderBy: { position: 'asc', id: 'asc' },
+        });
+        return rows.map((r) => ({
+            id: r.id,
+            sourceProductId: r.sourceProductId,
+            targetProductId: r.targetProductId,
+            kind: r.kind,
+            position: r.position,
+        }));
+    }
+    async bulkCreate(sourceProductId, inputs) {
+        const em = this.emFactory();
+        // 1) Source must exist and not be archived/deleted (404 PRODUCT_NOT_FOUND).
+        const source = await em.findOne(Product, { id: sourceProductId });
+        if (!source || source.deletedAt) {
+            throw new HttpError(404, ERROR_CODES.PRODUCT_NOT_FOUND, `Product "${sourceProductId}" not found.`);
+        }
+        // 2) Self-link rejected at API layer (400). The DB CHECK is the
+        // belt-and-braces backstop, but we want the typed error code first.
+        for (const input of inputs) {
+            if (input.targetProductId === sourceProductId) {
+                throw new HttpError(400, ERROR_CODES.SELF_LINK_NOT_ALLOWED, 'A product cannot link to itself.');
+            }
+        }
+        // 3) Targets must all exist (404 TARGET_PRODUCT_NOT_FOUND); single
+        // findIn keeps it to one query.
+        const targetIds = [...new Set(inputs.map((i) => i.targetProductId))];
+        const targets = await em.find(Product, { id: { $in: targetIds } });
+        const foundIds = new Set(targets.filter((t) => !t.deletedAt).map((t) => t.id));
+        for (const id of targetIds) {
+            if (!foundIds.has(id)) {
+                throw new HttpError(404, ERROR_CODES.TARGET_PRODUCT_NOT_FOUND, `Target product "${id}" not found.`);
+            }
+        }
+        // 4) Duplicate (source, target, kind) rejected up-front (409). The
+        // DB UNIQUE is the backstop; this lets us return the typed code
+        // without parsing PG error strings.
+        const existing = await em.find(ProductLink, {
+            sourceProductId,
+            targetProductId: { $in: targetIds },
+        });
+        const existingKey = new Set(existing.map((e) => `${e.targetProductId}|${e.kind}`));
+        for (const input of inputs) {
+            if (existingKey.has(`${input.targetProductId}|${input.kind}`)) {
+                throw new HttpError(409, ERROR_CODES.LINK_ALREADY_EXISTS, `Link source=${sourceProductId} target=${input.targetProductId} kind=${input.kind} already exists.`);
+            }
+        }
+        // 5) Default position: append to the end of the (source, kind) list.
+        const nextPositionByKind = new Map();
+        const tally = await em.find(ProductLink, { sourceProductId });
+        for (const row of tally) {
+            const cur = nextPositionByKind.get(row.kind) ?? -1;
+            if (row.position > cur)
+                nextPositionByKind.set(row.kind, row.position);
+        }
+        const created = await this.#audited('product_link.bulk_create', sourceProductId, async (cem) => {
+            const rows = [];
+            for (const input of inputs) {
+                const explicit = input.position;
+                const next = (nextPositionByKind.get(input.kind) ?? -1) + 1;
+                const position = explicit !== undefined ? explicit : next;
+                nextPositionByKind.set(input.kind, position);
+                rows.push(cem.create(ProductLink, {
+                    sourceProductId,
+                    targetProductId: input.targetProductId,
+                    kind: input.kind,
+                    position,
+                }));
+            }
+            await cem.flush();
+            return { result: rows, before: null, after: { sourceProductId, count: rows.length } };
+        });
+        return created.map((r) => ({
+            id: r.id,
+            sourceProductId: r.sourceProductId,
+            targetProductId: r.targetProductId,
+            kind: r.kind,
+            position: r.position,
+        }));
+    }
+    async removeLink(sourceProductId, linkId) {
+        await this.#audited('product_link.delete', linkId, async (em) => {
+            const link = await em.findOne(ProductLink, { id: linkId, sourceProductId });
+            if (!link) {
+                throw new HttpError(404, ERROR_CODES.PRODUCT_LINK_NOT_FOUND, `Link "${linkId}" not found on source ${sourceProductId}.`);
+            }
+            const before = { sourceProductId, targetProductId: link.targetProductId, kind: link.kind };
+            em.remove(link);
+            return { result: undefined, before, after: null };
+        });
+    }
+    /**
+     * Storefront read — drops links whose target product is not active or
+     * not visible in the requested sales channel; localizes name to the
+     * caller's preferred language.
+     */
+    async listForStorefront(sourceProductId, ctx, kind) {
+        const em = this.emFactory();
+        const where = { sourceProductId };
+        if (kind)
+            where['kind'] = kind;
+        const rows = await em.find(ProductLink, where, {
+            orderBy: { position: 'asc', id: 'asc' },
+        });
+        if (rows.length === 0)
+            return [];
+        const targetIds = rows.map((r) => r.targetProductId);
+        const targets = await em.find(Product, {
+            id: { $in: targetIds },
+            status: 'active',
+        });
+        const byId = new Map(targets.map((p) => [p.id, p]));
+        // Feature 053 (FR-006 / Principle XII) — sales-channel visibility. The
+        // channel is resolved once upstream (`getResolvedChannel()`) and handed in;
+        // the membership filter is ALWAYS applied, failing closed to an empty
+        // visible set rather than leaking the full cross-channel target set.
+        // Through the kernel's accessor since issue #185: this was a `select
+        // product_id from sales_channel_products` written here, which is the one
+        // read Principle XII names the membership service for.
+        const channel = ctx.resolvedChannel;
+        const visibleIds = targets.length > 0
+            ? new Set(await this.#requireChannelMembership().filterEntityIdsInChannel(channel.id, 'product', targets.map((t) => t.id)))
+            : // No targets → nothing is visible (fail closed).
+                new Set();
+        // Primary asset urls: the gallery thumb chain, with the legacy
+        // `product_assets` fallback. Shared with `CatalogQueryService` so the chain
+        // and the `assets_library` port call have one home.
+        const assetUrlByProductId = await resolvePrimaryAssetUrls(em, this.#requireAssets(), targetIds);
+        // Sales-channel public flag controls price visibility (R-18), read off the
+        // resolved channel handed in by the route. A channel that withholds prices
+        // is not asked for them (issue #132).
+        const visibleTargets = rows
+            .filter((link) => visibleIds.has(link.targetProductId))
+            .map((link) => byId.get(link.targetProductId))
+            .filter((target) => target !== undefined);
+        const viewerOrganization = ctx.audience.organizationId === null
+            ? null
+            : await viewerOrganizationFor(this.#requireOrganizationDetails(), ctx.audience);
+        const resolvedPrices = ctx.resolvedChannel.isPublic && visibleTargets.length > 0
+            ? await this.#requireListingPrices().resolveListingPrices({
+                products: visibleTargets,
+                context: {
+                    salesChannel: {
+                        id: ctx.resolvedChannel.id,
+                        defaultCurrency: ctx.resolvedChannel.defaultCurrency,
+                    },
+                    organization: viewerOrganization,
+                },
+            })
+            : new Map();
+        const out = [];
+        for (const link of rows) {
+            if (!visibleIds.has(link.targetProductId))
+                continue;
+            const target = byId.get(link.targetProductId);
+            if (!target)
+                continue;
+            const name = pickLang(target.name, ctx.preferredLanguage);
+            const resolved = resolvedPrices.get(target.id);
+            const price = resolved === undefined ? null : listingPriceMoney(resolved);
+            out.push({
+                id: link.id,
+                kind: link.kind,
+                position: link.position,
+                product: {
+                    id: target.id,
+                    sku: target.sku,
+                    slug: target.slug,
+                    name,
+                    primaryAssetUrl: assetUrlByProductId.get(target.id) ?? null,
+                    price,
+                },
+            });
+        }
+        return out;
+    }
+    async reorderForKind(sourceProductId, kind, linkIds) {
+        await this.#audited('product_link.reorder', sourceProductId, async (em) => {
+            // Fetch all links of this (source, kind) so we can validate the input
+            // covers exactly that set.
+            const rows = await em.find(ProductLink, { sourceProductId, kind });
+            const byId = new Map(rows.map((r) => [r.id, r]));
+            for (const id of linkIds) {
+                if (!byId.has(id)) {
+                    throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, `Link "${id}" is not part of (${sourceProductId}, ${kind}).`);
+                }
+            }
+            // Apply 0..N positions in array order.
+            for (let i = 0; i < linkIds.length; i++) {
+                const link = byId.get(linkIds[i]);
+                link.position = i;
+            }
+            return { result: undefined, before: null, after: { sourceProductId, kind, count: linkIds.length } };
+        });
+    }
+}
+//# sourceMappingURL=product-link.service.js.map

package/dist/backend/services/product-link.service.js.map

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

package/dist/backend/services/product-overrides.service.d.ts

@@ -0,0 +1,77 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { CommandBus } from '@endora-commerce/platform/commands';
+import type { SalesChannelMembershipPort } from '@endora-commerce/platform/kernel';
+import { ProductValueOverride } from '../entities/product-value-override.entity.js';
+import type { CatalogAttributeReadService } from './catalog-attribute-read.service.js';
+/**
+ * Feature 022 — channel-aware value-override CRUD.
+ *
+ * The bulk upsert+delete handler is the only mutator; it runs all
+ * operations in one MikroORM transaction so a single 422 rolls back
+ * every requested change (FR-030 atomicity).
+ *
+ * Validation rules (data-model.md §3.3 + §4):
+ *   - `attribute_unknown`            — key is neither a system attr nor a
+ *                                       product_attributes.key row.
+ *   - `attribute_not_channel_scoped` — caller wrote to a (channel, ...)
+ *                                       slot for an attr that has
+ *                                       channelScoped=false.
+ *   - `attribute_missing_language`   — caller wrote (channel, null) for
+ *                                       an attr that has languageScoped=
+ *                                       true (must address a specific
+ *                                       language slot).
+ *   - `channel_not_assigned_to_product` — channel is not in the
+ *                                       product's membership set.
+ *   - `language_not_in_channel`      — language is not in the channel's
+ *                                       SalesChannel.languages array.
+ *   - `value_invalid`                — value shape does not satisfy the
+ *                                       attribute's valueType.
+ */
+export type OverrideUpsertInput = {
+    attributeKey: string;
+    channelId: string;
+    languageCode: string | null;
+    value: {
+        v: unknown;
+    };
+};
+export type OverrideDeleteInput = {
+    attributeKey: string;
+    channelId: string;
+    languageCode: string | null;
+};
+export type ApplyOverridesInput = {
+    upserts: readonly OverrideUpsertInput[];
+    deletes: readonly OverrideDeleteInput[];
+};
+export type ApplyOverridesResult = {
+    productId: string;
+    applied: {
+        upserted: number;
+        deleted: number;
+    };
+    overrides: ProductValueOverride[];
+};
+export declare class ProductOverridesService {
+    #private;
+    private readonly emFactory;
+    private readonly salesChannelMembership;
+    /** Feature 054 — audits the override apply co-transactionally when provided. */
+    private readonly commandBus?;
+    /** Feature 061 — composed attribute read model (scope + value-type lookups). */
+    private readonly attributeRead?;
+    constructor(emFactory: () => EntityManager, salesChannelMembership: SalesChannelMembershipPort, 
+    /** Feature 054 — audits the override apply co-transactionally when provided. */
+    commandBus?: CommandBus | undefined, 
+    /** Feature 061 — composed attribute read model (scope + value-type lookups). */
+    attributeRead?: CatalogAttributeReadService | undefined);
+    listForProduct(productId: string): Promise<ProductValueOverride[]>;
+    /**
+     * Validate + apply a bulk write. All operations run in one
+     * transaction. The first validation failure aborts everything; the
+     * thrown HttpError carries the offending input's index in `issues`
+     * so callers can highlight the bad row.
+     */
+    applyBulk(productId: string, input: ApplyOverridesInput): Promise<ApplyOverridesResult>;
+}
+//# sourceMappingURL=product-overrides.service.d.ts.map

package/dist/backend/services/product-overrides.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-overrides.service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/product-overrides.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAGnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAEpF,OAAO,KAAK,EACV,2BAA2B,EAE5B,MAAM,qCAAqC,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE;QAAE,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,SAAS,EAAE,oBAAoB,EAAE,CAAC;CACnC,CAAC;AAEF,qBAAa,uBAAuB;;IAEhC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IACvC,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;gBALd,SAAS,EAAE,MAAM,aAAa,EAC9B,sBAAsB,EAAE,0BAA0B;IACnE,gFAAgF;IAC/D,UAAU,CAAC,EAAE,UAAU,YAAA;IACxC,gFAAgF;IAC/D,aAAa,CAAC,EAAE,2BAA2B,YAAA;IAiCxD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAKxE;;;;;OAKG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA+J9F"}

package/dist/backend/services/product-overrides.service.js

@@ -0,0 +1,204 @@
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { SalesChannel } from '@endora-commerce/platform/kernel';
+import { Product } from '../entities/product.entity.js';
+import { ProductValueOverride } from '../entities/product-value-override.entity.js';
+import { getAttributeScope, isSystemAttributeKey } from './system-attribute-scopes.js';
+export class ProductOverridesService {
+    emFactory;
+    salesChannelMembership;
+    commandBus;
+    attributeRead;
+    constructor(emFactory, salesChannelMembership, 
+    /** Feature 054 — audits the override apply co-transactionally when provided. */
+    commandBus, 
+    /** Feature 061 — composed attribute read model (scope + value-type lookups). */
+    attributeRead) {
+        this.emFactory = emFactory;
+        this.salesChannelMembership = salesChannelMembership;
+        this.commandBus = commandBus;
+        this.attributeRead = attributeRead;
+    }
+    #requireAttributeRead() {
+        if (!this.attributeRead) {
+            throw new Error('ProductOverridesService: CatalogAttributeReadService is not wired — attribute reads are unavailable.');
+        }
+        return this.attributeRead;
+    }
+    /**
+     * Feature 054 — run the override mutations through the Command Bus (its
+     * transaction replaces the local `em.transactional`, and the audit is
+     * co-transactional). Bus-less path keeps the local transaction.
+     */
+    async #audited(action, objectId, write) {
+        if (this.commandBus) {
+            return this.commandBus.run({ action, objectType: 'product', objectId, run: ({ em }) => write(em) });
+        }
+        const em = this.emFactory();
+        return em.transactional(async (tem) => (await write(tem)).result);
+    }
+    async listForProduct(productId) {
+        const em = this.emFactory();
+        return em.find(ProductValueOverride, { productId });
+    }
+    /**
+     * Validate + apply a bulk write. All operations run in one
+     * transaction. The first validation failure aborts everything; the
+     * thrown HttpError carries the offending input's index in `issues`
+     * so callers can highlight the bad row.
+     */
+    async applyBulk(productId, input) {
+        const em = this.emFactory();
+        const product = await em.findOne(Product, { id: productId });
+        if (!product) {
+            throw new HttpError(404, ERROR_CODES.PRODUCT_NOT_FOUND, 'Product not found.');
+        }
+        // Collect referenced channels + attribute rows in one fetch each.
+        const channelIds = Array.from(new Set([
+            ...input.upserts.map((u) => u.channelId),
+            ...input.deletes.map((d) => d.channelId),
+        ]));
+        const channels = channelIds.length === 0
+            ? []
+            : await em.find(SalesChannel, { id: { $in: channelIds } });
+        const channelById = new Map(channels.map((c) => [c.id, c]));
+        const attrKeys = Array.from(new Set([
+            ...input.upserts.map((u) => u.attributeKey),
+            ...input.deletes.map((d) => d.attributeKey),
+        ])).filter((k) => !isSystemAttributeKey(k));
+        const wantedKeys = new Set(attrKeys);
+        const attrRows = attrKeys.length === 0
+            ? []
+            : (await this.#requireAttributeRead().listAll()).filter((v) => wantedKeys.has(v.key));
+        const attrByKey = new Map(attrRows.map((r) => [r.key, r]));
+        const assignedChannels = await this.salesChannelMembership.listChannelsForEntity('product', productId);
+        const assignedChannelIds = new Set(assignedChannels.map((c) => c.id));
+        // Run validation first; if anything throws, we abort before mutating.
+        const validateEntry = (kind, idx, e) => {
+            const pathPrefix = `${kind === 'upsert' ? 'upserts' : 'deletes'}[${idx}]`;
+            const attrRow = attrByKey.get(e.attributeKey);
+            if (!isSystemAttributeKey(e.attributeKey) && !attrRow) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'attribute_unknown', [{ path: `${pathPrefix}.attributeKey`, issue: e.attributeKey }]);
+            }
+            const scope = getAttributeScope(e.attributeKey, attrRow ?? null);
+            if (!scope.channelScoped) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'attribute_not_channel_scoped', [{ path: `${pathPrefix}.attributeKey`, issue: e.attributeKey }]);
+            }
+            if (scope.languageScoped && e.languageCode === null) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'attribute_missing_language', [{ path: `${pathPrefix}.languageCode`, issue: 'null' }]);
+            }
+            if (!assignedChannelIds.has(e.channelId)) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'channel_not_assigned_to_product', [{ path: `${pathPrefix}.channelId`, issue: e.channelId }]);
+            }
+            const channel = channelById.get(e.channelId);
+            if (e.languageCode !== null) {
+                if (!channel || !channel.languages.includes(e.languageCode)) {
+                    throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'language_not_in_channel', [{ path: `${pathPrefix}.languageCode`, issue: e.languageCode }]);
+                }
+            }
+            if (kind === 'upsert') {
+                const u = e;
+                validateValueShape(u.value.v, attrRow?.valueType ?? 'string', `${pathPrefix}.value`);
+            }
+        };
+        input.upserts.forEach((u, i) => validateEntry('upsert', i, u));
+        input.deletes.forEach((d, i) => validateEntry('delete', i, d));
+        // Apply in one transaction (via the Command Bus — co-transactional audit).
+        const { upserted, deleted } = await this.#audited('product.overrides_apply', productId, async (tem) => {
+            let up = 0;
+            let del = 0;
+            for (const u of input.upserts) {
+                const where = {
+                    productId,
+                    attributeKey: u.attributeKey,
+                    channelId: u.channelId,
+                    languageCode: u.languageCode ?? null,
+                };
+                const existing = await tem.findOne(ProductValueOverride, where);
+                if (existing) {
+                    existing.value = u.value;
+                    // Touch flush; updatedAt hook handles the rest.
+                }
+                else {
+                    tem.persist(tem.create(ProductValueOverride, {
+                        productId,
+                        attributeKey: u.attributeKey,
+                        channelId: u.channelId,
+                        languageCode: u.languageCode,
+                        value: u.value,
+                    }));
+                }
+                up += 1;
+            }
+            for (const d of input.deletes) {
+                const existing = await tem.findOne(ProductValueOverride, {
+                    productId,
+                    attributeKey: d.attributeKey,
+                    channelId: d.channelId,
+                    languageCode: d.languageCode ?? null,
+                });
+                if (existing) {
+                    tem.remove(existing);
+                    del += 1;
+                }
+            }
+            return {
+                result: { upserted: up, deleted: del },
+                before: null,
+                after: { productId, upserted: up, deleted: del },
+            };
+        });
+        const all = await em.find(ProductValueOverride, { productId });
+        return { productId, applied: { upserted, deleted }, overrides: all };
+    }
+}
+/**
+ * Minimal value-shape check. Allows null (clearing); otherwise enforces
+ * a primitive shape consistent with the attribute's valueType. Stricter
+ * validation (enum option membership, price decimals, date format) is
+ * deferred — the existing attribute-write path in catalog-admin.service
+ * does the strict pass when the value lands in the global baseline, and
+ * the override path can lean on that until a follow-up centralises the
+ * rule.
+ */
+function validateValueShape(v, valueType, path) {
+    if (v === null || v === undefined)
+        return;
+    const fail = (issue) => {
+        throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'value_invalid', [
+            { path, issue },
+        ]);
+    };
+    switch (valueType) {
+        case 'string':
+        case 'enum':
+        case 'select':
+            if (typeof v !== 'string')
+                return fail(`expected string, got ${typeof v}`);
+            return;
+        case 'number':
+        case 'price':
+            if (typeof v !== 'number' || !Number.isFinite(v)) {
+                return fail(`expected finite number, got ${typeof v}`);
+            }
+            return;
+        case 'boolean':
+            if (typeof v !== 'boolean')
+                return fail(`expected boolean, got ${typeof v}`);
+            return;
+        case 'date':
+            if (typeof v !== 'string')
+                return fail(`expected ISO-date string, got ${typeof v}`);
+            return;
+        case 'multiselect':
+            if (!Array.isArray(v) || v.some((x) => typeof x !== 'string')) {
+                return fail('expected string[]');
+            }
+            return;
+        default:
+            // Unknown value types pass through; the legacy storage path will
+            // reject anything pathological.
+            return;
+    }
+}
+//# sourceMappingURL=product-overrides.service.js.map

package/dist/backend/services/product-overrides.service.js.map

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

package/dist/backend/services/product-scope-context.service.d.ts

@@ -0,0 +1,36 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { LanguageReadPort, ProductScopeContextResponse } from '@endora-commerce/contracts';
+import type { SalesChannelMembershipPort } from '@endora-commerce/platform/kernel';
+import { ProductEditorPreference } from '../entities/product-editor-preference.entity.js';
+import type { ProductEditorPreferencesService } from './product-editor-preferences.service.js';
+/**
+ * Feature 022 — assembles the response of
+ * `GET /admin/products/:id/scope-context`.
+ *
+ * Combines:
+ *   - the product's assigned channels (via SalesChannelMembershipPort),
+ *     each carrying its language list (`SalesChannel.languages` JSONB),
+ *   - the union of those languages,
+ *   - the platform's primary admin language (LanguageService.getDefault()),
+ *   - the editor's remembered context (ProductEditorPreference).
+ *
+ * If the product has zero assigned channels, `languagesUnion` falls
+ * back to every active platform language so the editor can still
+ * translate the global baseline.
+ */
+export declare class ProductScopeContextService {
+    private readonly emFactory;
+    private readonly salesChannelMembership;
+    private readonly languageService;
+    private readonly editorPreferences;
+    constructor(emFactory: () => EntityManager, salesChannelMembership: SalesChannelMembershipPort, languageService: LanguageReadPort, editorPreferences: ProductEditorPreferencesService);
+    getContext(productId: string, adminUserId: string): Promise<ProductScopeContextResponse>;
+    /**
+     * Validate that a remembered preference is still applicable for the
+     * given product. Used by the PUT editor-preference endpoint.
+     */
+    assertChannelAssignedToProduct(productId: string, channelId: string): Promise<void>;
+    /** Re-export for tests + consumers needing direct entity access. */
+    preferenceEntityClass(): typeof ProductEditorPreference;
+}
+//# sourceMappingURL=product-scope-context.service.d.ts.map