@endora-commerce/mod-comparisons 0.0.0-stage → 0.100.0

package/dist/backend/services/comparison-pdf-renderer.js.map

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

package/dist/backend/services/comparison-service.d.ts

@@ -0,0 +1,339 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type CatalogAttributeReadPort, type CatalogGalleryPort, type CatalogProductReadPort, type ComparisonOwnerView, type ComparisonDisplayMode, type CustomerAccountReadPort, type ListingPricePort, type OrganizationDetailsPort, type ProductAudience } from '@endora-commerce/contracts';
+import type { SalesChannelMembershipPort } from '@endora-commerce/platform/kernel';
+import type { SettingsReadPort } from '@endora-commerce/platform/kernel';
+import { Comparison } from '../entities/comparison.entity.js';
+import type { ShareTokenGenerator } from './share-token-generator.js';
+import type { ComparableAttributeProjection } from './comparable-attribute-projection.js';
+/**
+ * ComparisonService — feature 007 / T023 + T024.
+ *
+ * Stateful service owning the Comparison resource. Every cross-module read
+ * goes through a published port — {@link CatalogProductReadPort},
+ * {@link CatalogAttributeReadPort}, {@link ListingPricePort} and
+ * {@link SettingsReadPort}. The products a comparison holds are `catalog`'s
+ * rows, not this module's: reading them with `em.find(Product, …)` was a query
+ * nothing could gate, so a comparison kept resolving names and availability
+ * out of a module an operator had switched off (feature 075, Phase C).
+ *
+ * Behaviour summary (per `data-model.md`, `research.md`, and
+ * `contracts/public-comparisons-crud.md`):
+ *
+ *   - `getForOwner` returns the caller's live Comparison or `null`. No
+ *     side effects.
+ *   - `addProduct` enforces `compare.max_products` on add (R-7). Throws
+ *     {@link ComparisonFullError} when the cap would be exceeded.
+ *     Idempotent on duplicates: re-adding a product already in the set
+ *     is a no-op that returns the current comparison.
+ *   - `removeProduct` throws {@link ProductNotInComparisonError} when
+ *     the product is not in the set; emptying the set is allowed.
+ *   - `setDisplayMode` only updates the persisted mode; refuses with
+ *     {@link ComparisonNotFoundError} when the caller has no comparison.
+ *   - `deleteForOwner` hard-deletes; cascades onto `comparison_products`
+ *     by FK. Invalidates the share token (the row is gone — the share
+ *     endpoint will return 404).
+ *   - `findByShareToken` resolves the token in O(1) via the UNIQUE
+ *     index. Used in US2 for the recipient view.
+ *   - `buildOwnerView` produces the on-the-wire shape for `GET /me`
+ *     (and is reused for the share-token recipient view in US2 and the
+ *     admin detail view in US5).
+ */
+/**
+ * Who is reading a comparison.
+ *
+ * Two kinds rather than one `ProductAudience`, because an administrator is not
+ * a buyer and there is no audience that means "may see everything": the
+ * predicate in {@link isProductVisibleTo} answers for a *shopper*, and every
+ * audience an administrator could be given would drop the organisation-
+ * restricted rows the audit screen exists to show. Making that an explicit
+ * kind is what keeps it from being expressed as a permissive audience
+ * somebody later reuses on a storefront path.
+ */
+export type ComparisonViewer = {
+    readonly kind: 'buyer';
+    readonly audience: ProductAudience;
+} | {
+    readonly kind: 'administrator';
+};
+/**
+ * The most restrictive viewer there is — the public. The right default for a
+ * caller that has not been taught to resolve its reader, for the same reason
+ * {@link ANONYMOUS_PRODUCT_AUDIENCE} is: everything it may see, every other
+ * viewer may see too.
+ */
+export declare const ANONYMOUS_COMPARISON_VIEWER: ComparisonViewer;
+export declare class ComparisonService {
+    #private;
+    private readonly emFactory;
+    private readonly projection;
+    private readonly tokens;
+    /**
+     * `catalog`'s product read model. Not optional: a comparison is a list of
+     * products, so a service that cannot read one has nothing to answer with —
+     * where the settings and pricing arguments below have a defined fallback,
+     * this has none.
+     */
+    private readonly catalogProducts;
+    /**
+     * The sanctioned bridge accessor (Constitution XII), for the assortment
+     * gate `addProduct` owes (issue #259). Required for the same reason
+     * `catalogProducts` is: an optional one would spell "this rig wired no
+     * membership service" and "this channel publishes the product" as the same
+     * answer.
+     */
+    private readonly channelMembership;
+    /**
+     * Feature 075 / D-87 — `catalog`'s gallery read model, for the base image
+     * of each column. Required for the same reason `catalogProducts` is: the
+     * alternative to a wired port is not "a comparison without pictures", it is
+     * a service that cannot tell an operator who set no base image from a rig
+     * that wired no owner.
+     *
+     * `baseImageUrls`, not `list`: the read is a batch, it must tolerate an id
+     * whose product has since been removed, and the value a column renders is a
+     * **url**, which `catalog` resolves through the asset port it holds. Those
+     * three are exactly why the single join this replaced could not be swapped
+     * for the per-product port that already existed.
+     */
+    private readonly catalogGallery;
+    /**
+     * Optional settings service. When undefined, `compare.max_products`
+     * defaults to {@link DEFAULT_COMPARE_MAX_PRODUCTS} on every call —
+     * useful for foundation tests that pre-date Settings wiring.
+     */
+    private readonly settingsService?;
+    /**
+     * Feature 061 — the catalog's composed attribute read model (Principle I:
+     * replaces the former direct `ProductAttribute` entity find).
+     */
+    private readonly catalogAttributes?;
+    /**
+     * Issue #132 — the pricing engine, through the `pricingService` port. A
+     * comparison exists so a buyer can put prices side by side, so the figures
+     * in its columns have to be the ones a price list stands behind.
+     */
+    private readonly listingPrices?;
+    /**
+     * `organizations`' read model, for the one field the pricing engine needs
+     * beyond the viewer's organisation id: the customer group it belongs to,
+     * which a group-targeted price list is selected by. Without it a buyer's
+     * comparison column and their own cart line would resolve against
+     * different lists and quote different figures for one product.
+     */
+    private readonly organizationDetails?;
+    /**
+     * Feature 087 Group B / D-187 — `customer_accounts`' read model, for the
+     * one field the owner stamp needs: the organisation the owning account
+     * belongs to.
+     *
+     * The organisation is derived from the **row**, never from the ambient
+     * request context, and that is what makes one implementation serve both
+     * write paths: `addProduct` runs on a storefront request and
+     * `adoptAnonymousComparison` runs inside another module's login hook, where
+     * there is no comparison caller to read a context from.
+     *
+     * Optional in the constructor and required at the two call sites, in the
+     * shape {@link organizationDetails} already takes here. A rig that wired no
+     * port cannot stamp, and the honest answer to that is a refusal at the
+     * write rather than a row `comparisons_organization_attribution_chk` will
+     * reject with a message about a constraint the caller never heard of.
+     */
+    private readonly customerAccounts?;
+    constructor(emFactory: () => EntityManager, projection: ComparableAttributeProjection, tokens: ShareTokenGenerator, 
+    /**
+     * `catalog`'s product read model. Not optional: a comparison is a list of
+     * products, so a service that cannot read one has nothing to answer with —
+     * where the settings and pricing arguments below have a defined fallback,
+     * this has none.
+     */
+    catalogProducts: CatalogProductReadPort, 
+    /**
+     * The sanctioned bridge accessor (Constitution XII), for the assortment
+     * gate `addProduct` owes (issue #259). Required for the same reason
+     * `catalogProducts` is: an optional one would spell "this rig wired no
+     * membership service" and "this channel publishes the product" as the same
+     * answer.
+     */
+    channelMembership: SalesChannelMembershipPort, 
+    /**
+     * Feature 075 / D-87 — `catalog`'s gallery read model, for the base image
+     * of each column. Required for the same reason `catalogProducts` is: the
+     * alternative to a wired port is not "a comparison without pictures", it is
+     * a service that cannot tell an operator who set no base image from a rig
+     * that wired no owner.
+     *
+     * `baseImageUrls`, not `list`: the read is a batch, it must tolerate an id
+     * whose product has since been removed, and the value a column renders is a
+     * **url**, which `catalog` resolves through the asset port it holds. Those
+     * three are exactly why the single join this replaced could not be swapped
+     * for the per-product port that already existed.
+     */
+    catalogGallery: CatalogGalleryPort, 
+    /**
+     * Optional settings service. When undefined, `compare.max_products`
+     * defaults to {@link DEFAULT_COMPARE_MAX_PRODUCTS} on every call —
+     * useful for foundation tests that pre-date Settings wiring.
+     */
+    settingsService?: SettingsReadPort | undefined, 
+    /**
+     * Feature 061 — the catalog's composed attribute read model (Principle I:
+     * replaces the former direct `ProductAttribute` entity find).
+     */
+    catalogAttributes?: CatalogAttributeReadPort | undefined, 
+    /**
+     * Issue #132 — the pricing engine, through the `pricingService` port. A
+     * comparison exists so a buyer can put prices side by side, so the figures
+     * in its columns have to be the ones a price list stands behind.
+     */
+    listingPrices?: ListingPricePort | undefined, 
+    /**
+     * `organizations`' read model, for the one field the pricing engine needs
+     * beyond the viewer's organisation id: the customer group it belongs to,
+     * which a group-targeted price list is selected by. Without it a buyer's
+     * comparison column and their own cart line would resolve against
+     * different lists and quote different figures for one product.
+     */
+    organizationDetails?: OrganizationDetailsPort | undefined, 
+    /**
+     * Feature 087 Group B / D-187 — `customer_accounts`' read model, for the
+     * one field the owner stamp needs: the organisation the owning account
+     * belongs to.
+     *
+     * The organisation is derived from the **row**, never from the ambient
+     * request context, and that is what makes one implementation serve both
+     * write paths: `addProduct` runs on a storefront request and
+     * `adoptAnonymousComparison` runs inside another module's login hook, where
+     * there is no comparison caller to read a context from.
+     *
+     * Optional in the constructor and required at the two call sites, in the
+     * shape {@link organizationDetails} already takes here. A rig that wired no
+     * port cannot stamp, and the honest answer to that is a refusal at the
+     * write rather than a row `comparisons_organization_attribution_chk` will
+     * reject with a message about a constraint the caller never heard of.
+     */
+    customerAccounts?: CustomerAccountReadPort | undefined);
+    getForOwner(owner: ComparisonOwner): Promise<Comparison | null>;
+    /**
+     * Resolve a share token to its comparison, across customers.
+     *
+     * `Comparison` is `@CustomerScoped`, so the ambient filter confines this read
+     * to the caller's own rows — which is right for every other method here and
+     * is the one thing a share link has to cross. An **anonymous** recipient
+     * already crossed it by accident: the composition roots run anonymous
+     * requests under `systemTenantContext('actor:anonymous')`, so the filter is a
+     * no-op for them, while a *signed-in* recipient got a 404 on a link that
+     * worked when they were logged out. That is the shape a guard takes when a
+     * deliberate cross-tenant grant is left implicit.
+     *
+     * So it is explicit, through the one sanctioned crossing (feature 050,
+     * FR-005): the token is the authorization, exactly as it is on the public
+     * product-feed endpoint, and the widening covers this single lookup by a
+     * unique index and nothing after it. **What the recipient then sees is not
+     * widened at all** — `buildOwnerView` filters the products by their own
+     * audience and prices them for their own organisation.
+     */
+    findByShareToken(token: string): Promise<Comparison | null>;
+    /**
+     * Anonymous → authenticated merge (research.md R-2 / spec FR-005).
+     * Called from the post-login hook with the cookie-bound
+     * `anonymousToken` the caller was carrying. Behaviour:
+     *
+     *   - customer has no Comparison → reassign the anonymous one
+     *     (set customer_account_id, clear anonymous_token).
+     *   - customer already has a Comparison → discard the anonymous one
+     *     (the customer's existing curated set wins, per R-2 — merging
+     *     two sets is more surprising than honouring the persistent
+     *     identity).
+     *
+     * No-op when neither side resolves.
+     *
+     * **This is the one place in the platform where a comparison becomes owned**
+     * — `Cart` has no counterpart, because its anonymous merge *completes* the
+     * anonymous cart rather than re-owning it. So it is the write feature 087's
+     * invariant would have been forgotten at: the row arrives here with a null
+     * `organization_id` that was correct while it was anonymous, and the
+     * organisation is set in the same unit of work as the account, from the same
+     * account. Nothing here is conditional on the column being null — an
+     * anonymous row's organisation is null by construction, and if it ever is
+     * not, the account it is being handed to is the truth.
+     */
+    adoptAnonymousComparison(customerAccountId: string, anonymousToken: string): Promise<void>;
+    /**
+     * True when the supplied owner identity matches the Comparison's
+     * stored owner. Used by the share-token endpoint to populate
+     * `meta.viewerIsOwner`.
+     */
+    isOwnedBy(comparison: Comparison, owner: ComparisonOwner | null): boolean;
+    addProduct(owner: ComparisonOwner, salesChannelId: string, productId: string, 
+    /**
+     * Who is comparing (issue #227). Defaulted to the anonymous audience so a
+     * composition that has not been taught to resolve its caller refuses a
+     * restricted product rather than adding it — the fail-closed end. The
+     * public route passes the real one.
+     */
+    audience?: ProductAudience): Promise<Comparison>;
+    removeProduct(owner: ComparisonOwner, productId: string): Promise<Comparison>;
+    setDisplayMode(owner: ComparisonOwner, mode: ComparisonDisplayMode): Promise<Comparison>;
+    deleteForOwner(owner: ComparisonOwner): Promise<void>;
+    /**
+     * Build the wire-format `ComparisonOwnerView` for the given comparison
+     * in the viewer's sales-channel context. Reusable across the three
+     * consumers (owner / recipient / admin); the recipient + admin views
+     * pass `viewerIsOwner=false` and consume only the slice they need.
+     *
+     * **The viewer's identity decides what the viewer sees. Always.** A share
+     * token grants access to the *comparison*, never to anything in it, so it
+     * settles two questions the same way:
+     *
+     *  - **the prices** — the owner sees their organisation's figures, a
+     *    signed-in recipient from another organisation sees **theirs**, and an
+     *    anonymous recipient sees the channel's. That is what makes a shared
+     *    link trustworthy: the numbers are true for whoever is looking, and a
+     *    recipient who acted on the sender's negotiated price would be acting on
+     *    a price nobody will sell them at.
+     *  - **the products** — a row restricted to the sender's organisation is not
+     *    disclosed to a recipient outside it, while a recipient who *is* on the
+     *    allow-list sees it. The owner was entitled to add it (`addProduct`
+     *    enforces that, issue #227); a second reader has an entitlement of their
+     *    own, and a product may be restricted after it was added.
+     *
+     * The two run in that order — filter, then price — because a price resolved
+     * for a row the reader may not see is work done to produce a figure that must
+     * not be sent.
+     */
+    buildOwnerView(comparison: Comparison, viewerSalesChannelId: string, 
+    /**
+     * Who is looking. Defaulted to the anonymous buyer so a caller that has not
+     * been taught to resolve its reader shows the public set at the channel
+     * price — the answer every reader may see — rather than one buyer's.
+     */
+    viewer?: ComparisonViewer): Promise<ComparisonOwnerView>;
+    /**
+     * Read `compare.max_products` from Settings; fall back to the manifest
+     * default on any error (Settings hiccup must not break the storefront).
+     */
+    private resolveMaxProducts;
+}
+export type ComparisonOwner = {
+    kind: 'customer';
+    customerAccountId: string;
+} | {
+    kind: 'anonymous';
+    anonymousToken: string;
+};
+export declare class ComparisonFullError extends Error {
+    readonly max: number;
+    constructor(max: number);
+}
+export declare class ComparisonNotFoundError extends Error {
+    constructor();
+}
+export declare class ProductNotInComparisonError extends Error {
+    readonly productId: string;
+    constructor(productId: string);
+}
+export declare class ProductNotFoundError extends Error {
+    readonly productId: string;
+    constructor(productId: string);
+}
+//# sourceMappingURL=comparison-service.d.ts.map

package/dist/backend/services/comparison-service.d.ts.map

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