@endora-commerce/mod-sales-channels 0.100.0

package/dist/backend/services/sales-channels.service.d.ts

@@ -0,0 +1,247 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type DictionaryValidator, type SalesChannelAttributionRegistryPort, type SalesChannelCreateBody, type SalesChannelUpdateBody } from '@endora-commerce/contracts';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import type { CommandBus } from '@endora-commerce/platform/commands';
+import type { EventBus } from '@endora-commerce/platform/events';
+import { SalesChannel } from '@endora-commerce/platform/kernel';
+import type { SalesChannelsCacheInvalidation } from '@endora-commerce/platform/kernel';
+import { type SetSystemDefaultChannelResult } from '../commands/set-default.command.js';
+/**
+ * SalesChannelsService — feature 005 / T017 (skeleton) + T035-T037 (US2).
+ *
+ * Admin-side CRUD + lifecycle for the Sales Channel registry. Membership
+ * mutations live in {@link SalesChannelMembershipService}; this service
+ * deals exclusively with the channel row's identity, lifecycle, and
+ * the FR-002 / FR-006 / FR-007 guards.
+ *
+ * Optimistic concurrency uses the `version` column. Update calls take
+ * an `expectedVersion` argument; mismatch raises HTTP 412
+ * `STALE_SALES_CHANNEL_WRITE` with the current version in the body so
+ * the client can refresh and retry. This matches feature 003 / 004's
+ * pattern.
+ *
+ * Every successful identity / lifecycle change writes one audit row
+ * (`sales_channel.identity.changed` / `sales_channel.lifecycle.changed`)
+ * synchronously, **drops the channel cache**, and then emits one EventBus
+ * event.
+ *
+ * That order is the whole of D-93 (issue #160). The drop used to be a
+ * subscriber — `attachSalesChannelsCacheInvalidator` listened for those two
+ * events — which made cache freshness a property of the dispatch order rather
+ * than of the write: `dictionaries` subscribes to the same two names and its
+ * Redis SCAN has already been measured pushing the invalidator past a tick
+ * (#101), and an emission inside an `EventBus.run` scope is buffered until the
+ * scope ends, so a write and a read-back in one Command could not be helped by
+ * any registration order at all. The events stay — other modules want them —
+ * and they stop being how this cache learns about this service's own write.
+ *
+ * `setDefault` is the exception and the newer pattern: it is a Command
+ * (feature 072 / D-51), so the Command Bus writes its audit row and buffers its
+ * event co-transactionally, and this class writes neither by hand.
+ */
+export interface AdminAuditContext {
+    actorAdminUserId: string | null;
+    requestId?: string | null;
+}
+export interface SalesChannelsServiceListOptions {
+    page?: number;
+    pageSize?: number;
+    activeOnly?: boolean;
+}
+export interface DeleteOptions {
+    fallbackToDefault?: boolean;
+}
+/**
+ * The channel-bridge registry, narrowed to the half this service reads
+ * (feature 120, FR-015).
+ *
+ * Declared structurally rather than imported from the platform: the registry
+ * class is published on no barrel — it is reached by container name — and the
+ * shape a consumer needs is the consumer's own declaration, which is what
+ * `ctx.cradle<C>()` asks an author for.
+ */
+export interface ChannelBridgeRead {
+    list(): ReadonlyArray<{
+        readonly entityType: string;
+        readonly table: string;
+        readonly entityIdColumn: string;
+    }>;
+}
+export declare class SalesChannelsService {
+    private readonly emFactory;
+    private readonly eventBus;
+    /**
+     * Required, and it was not (issue #251's shape, feature 075's occasion).
+     * Both roots have supplied it since feature 072 wave 2, so the absent
+     * branch was only ever run by tests — and what ran there was a hand-written
+     * `select "code" from "languages" / "currencies"`, two other modules' tables
+     * named in raw SQL, checking existence and not the active flag, and raising
+     * the 422 codes feature 017 superseded with the validator's uniform 409.
+     * Deleting that branch is the D-87 drain; making the argument required is
+     * what stops it coming back as an omission.
+     */
+    private readonly dictionaryValidator;
+    /**
+     * "Who is still attributed to this channel?", asked of the modules that
+     * record it (feature 075, D-87). Required for the same reason: the absent
+     * form of a delete guard is an open one.
+     */
+    private readonly attributionRegistry;
+    /**
+     * Which table holds each channel-scoped entity type's memberships, said by
+     * the module that owns that entity type (feature 120, FR-015).
+     *
+     * This class held its own copy of the platform's nine-entry map until
+     * D-226, justified in a comment as *"kept locally to avoid a circular
+     * import between the two services"*. That reason had been stale since
+     * feature 072's T019 moved `SalesChannelMembershipService` into the kernel:
+     * the platform names `packages/modules/sales_channels` in zero import
+     * specifiers and D-52/D-53 forbid it ever doing so. The copy was the worse
+     * of the two, because {@link findOrphansForChannel} runs a `select` against
+     * **all nine** tables on the channel-**delete** path, inside a module the
+     * platform refuses to switch off — so on an instance without `cms` deleting
+     * a channel failed on a relation that is not there.
+     *
+     * Resolved **through the container** rather than imported, by the name a
+     * composition root contributes off `composeSalesChannelsKernel`. A
+     * container resolution is not a module-graph edge, so there is nothing for
+     * a cycle to close; and the registry is a **kernel** registration rather
+     * than another module's port, so it puts nothing in this module's
+     * `dependencies` and makes no activation control a dead switch.
+     */
+    private readonly bridgeRegistry;
+    private readonly auditLogService?;
+    /**
+     * The invalidating half of the channel cache, narrowed to what a writer
+     * needs (D-93). A service that can only invalidate cannot seed the cache
+     * from the write path, which is the reader's job.
+     */
+    private readonly cache?;
+    /**
+     * Used by `setDefault` only, which is a Command (Principle XIII) rather than
+     * a hand-audited write like the rest of this class. Still optional — and
+     * `setDefault` refuses outright when it is missing, so the absence can never
+     * become an unaudited flag move.
+     */
+    private readonly commandBus?;
+    constructor(emFactory: () => EntityManager, eventBus: EventBus, 
+    /**
+     * Required, and it was not (issue #251's shape, feature 075's occasion).
+     * Both roots have supplied it since feature 072 wave 2, so the absent
+     * branch was only ever run by tests — and what ran there was a hand-written
+     * `select "code" from "languages" / "currencies"`, two other modules' tables
+     * named in raw SQL, checking existence and not the active flag, and raising
+     * the 422 codes feature 017 superseded with the validator's uniform 409.
+     * Deleting that branch is the D-87 drain; making the argument required is
+     * what stops it coming back as an omission.
+     */
+    dictionaryValidator: DictionaryValidator, 
+    /**
+     * "Who is still attributed to this channel?", asked of the modules that
+     * record it (feature 075, D-87). Required for the same reason: the absent
+     * form of a delete guard is an open one.
+     */
+    attributionRegistry: SalesChannelAttributionRegistryPort, 
+    /**
+     * Which table holds each channel-scoped entity type's memberships, said by
+     * the module that owns that entity type (feature 120, FR-015).
+     *
+     * This class held its own copy of the platform's nine-entry map until
+     * D-226, justified in a comment as *"kept locally to avoid a circular
+     * import between the two services"*. That reason had been stale since
+     * feature 072's T019 moved `SalesChannelMembershipService` into the kernel:
+     * the platform names `packages/modules/sales_channels` in zero import
+     * specifiers and D-52/D-53 forbid it ever doing so. The copy was the worse
+     * of the two, because {@link findOrphansForChannel} runs a `select` against
+     * **all nine** tables on the channel-**delete** path, inside a module the
+     * platform refuses to switch off — so on an instance without `cms` deleting
+     * a channel failed on a relation that is not there.
+     *
+     * Resolved **through the container** rather than imported, by the name a
+     * composition root contributes off `composeSalesChannelsKernel`. A
+     * container resolution is not a module-graph edge, so there is nothing for
+     * a cycle to close; and the registry is a **kernel** registration rather
+     * than another module's port, so it puts nothing in this module's
+     * `dependencies` and makes no activation control a dead switch.
+     */
+    bridgeRegistry: ChannelBridgeRead, auditLogService?: AuditPort | undefined, 
+    /**
+     * The invalidating half of the channel cache, narrowed to what a writer
+     * needs (D-93). A service that can only invalidate cannot seed the cache
+     * from the write path, which is the reader's job.
+     */
+    cache?: SalesChannelsCacheInvalidation | undefined, 
+    /**
+     * Used by `setDefault` only, which is a Command (Principle XIII) rather than
+     * a hand-audited write like the rest of this class. Still optional — and
+     * `setDefault` refuses outright when it is missing, so the absence can never
+     * become an unaudited flag move.
+     */
+    commandBus?: CommandBus | undefined);
+    getByCode(code: string): Promise<SalesChannel | null>;
+    getById(id: string): Promise<SalesChannel | null>;
+    list(options?: SalesChannelsServiceListOptions): Promise<{
+        items: SalesChannel[];
+        page: number;
+        pageSize: number;
+        total: number;
+    }>;
+    create(body: SalesChannelCreateBody, context?: AdminAuditContext): Promise<SalesChannel>;
+    update(code: string, body: SalesChannelUpdateBody, expectedVersion: number, context?: AdminAuditContext): Promise<SalesChannel>;
+    deactivate(code: string, context?: AdminAuditContext): Promise<SalesChannel>;
+    activate(code: string, context?: AdminAuditContext): Promise<SalesChannel>;
+    /**
+     * Move the `system_default` flag to `code` — feature 072 / D-51.
+     *
+     * The write itself is a Command, so the audit row, the demote-then-promote
+     * ordering and the transaction all live in `commands/set-default.command.ts`.
+     * What belongs here is the 404 for a code nobody has, produced before the
+     * transaction so an operator's typo is not an aborted transaction, and the
+     * cache drop below.
+     *
+     * Unlike the rest of this class it writes no audit row of its own: the
+     * Command Bus writes exactly one, and a second would be the double-audit the
+     * coverage check exists to catch.
+     */
+    setDefault(code: string): Promise<SetSystemDefaultChannelResult>;
+    delete(code: string, options?: DeleteOptions, context?: AdminAuditContext): Promise<void>;
+    private requireByCode;
+    private assertLanguagesValid;
+    private assertCurrenciesValid;
+    private validateLanguage;
+    private validateCurrency;
+    /**
+     * Read through the kernel's own entity rather than the raw statement this
+     * replaces (feature 075, D-87). `sales_channels` is the kernel's table since
+     * feature 072 moved the resolution machinery there, and a module relating
+     * into the kernel by ORM is the sanctioned access — it was the SQL, not the
+     * read, that crossed a boundary nothing could see. It reads through the
+     * caller's `em` on purpose: this runs inside the delete path, so the
+     * resolver's own fork would not see that path's uncommitted state.
+     */
+    private requireSystemDefaultId;
+    /**
+     * For every M:N bridge, find the entities whose ONLY channel membership is
+     * `channelId`. Returned shape is the (entityType, entityId) pair so the
+     * delete path can either refuse with a sample list or rebind to Default.
+     */
+    private findOrphansForChannel;
+    private rebindOrphansToDefault;
+    private snapshot;
+    private audit;
+    /**
+     * Drop the cache, then announce (D-93).
+     *
+     * The drop runs **after the flush**, so a concurrent read cannot re-pin the
+     * pre-commit row, and **before the emit**, so every subscriber re-reads
+     * post-invalidation state. The count is deliberately unread:
+     * `invalidateAfterWrite` answers `null` for an unreachable shared layer, and
+     * the row is written and audited by the time we are here, so there is nothing
+     * this method could truthfully do with it. Reads stay correct meanwhile — the
+     * cache bypasses the marked prefix until a later drop succeeds.
+     */
+    private emitIdentityChanged;
+    /** Same seam as {@link emitIdentityChanged}; see its comment for the ordering. */
+    private emitLifecycleChanged;
+}
+//# sourceMappingURL=sales-channels.service.d.ts.map

package/dist/backend/services/sales-channels.service.d.ts.map

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