@voyant-travel/commerce 0.1.0

package/dist/promotions/service-storefront.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Storefront resolvers — populate the previously-empty
+ * `/v1/public/products/:productId/offers` and `/v1/public/offers/:slug`
+ * endpoints in `@voyant-travel/storefront` with real data.
+ *
+ * Wire via:
+ *
+ *   const storefrontModule = createStorefrontHonoModule({
+ *     offers: createPromotionsStorefrontResolvers(),
+ *   })
+ *
+ * Per docs/architecture/promotions-architecture.md §8.
+ *
+ * V1 limitations:
+ *   - Storefront calls don't carry an audience / market in the request
+ *     context, so the resolver only filters by `products` + `global`
+ *     scopes (the catalog plane handles audience-scoped projection).
+ *     `markets` and `audiences` scoped offers don't appear in this
+ *     listing endpoint.
+ *   - Locale-aware offer names: the schema doesn't store translations
+ *     yet (single-locale offer names per §12.1); `locale` is accepted
+ *     but ignored. A `promotional_offer_translations` table mirrors
+ *     `destinations_translations` if/when needed.
+ *   - `applicableDepartureIds`: always empty per §12.7 — departure-
+ *     scoped offers aren't modelled in v1.
+ *   - Only auto-applied offers (no code) appear in `listApplicableOffers`;
+ *     code-gated offers are still queryable via `getOfferBySlug`.
+ */
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+import { type PromotionalOffer } from "./schema.js";
+import { type CodeStatus } from "./service-evaluator.js";
+import type { PromotionalOfferScope } from "./validation.js";
+export interface StorefrontRequestContext {
+    db?: AnyDrizzleDb;
+    eventBus?: unknown;
+    env?: unknown;
+    context?: unknown;
+}
+export interface StorefrontPromotionalOffer {
+    id: string;
+    name: string;
+    slug: string | null;
+    description: string | null;
+    discountType: "percentage" | "fixed_amount";
+    discountValue: string;
+    currency: string | null;
+    applicableProductIds: string[];
+    applicableDepartureIds: string[];
+    validFrom: string | null;
+    validTo: string | null;
+    minTravelers: number | null;
+    imageMobileUrl: string | null;
+    imageDesktopUrl: string | null;
+    stackable: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface StorefrontOfferApplyInput {
+    productId: string;
+    departureId?: string | null;
+    bookingId?: string | null;
+    sessionId?: string | null;
+    locale?: string;
+    pax: number;
+    audience: "staff" | "customer" | "partner" | "supplier";
+    market: string;
+    basePriceCents: number;
+    currency: string;
+}
+export interface StorefrontOfferRedeemInput extends StorefrontOfferApplyInput {
+    code: string;
+}
+export interface StorefrontAppliedOffer {
+    offerId: string;
+    offerName: string;
+    discountAppliedCents: number;
+    discountedPriceCents: number;
+    currency: string;
+    discountKind: "percentage" | "fixed_amount";
+    discountPercent: number | null;
+    discountAmountCents: number | null;
+    appliedCode: string | null;
+    stackable: boolean;
+}
+export interface StorefrontOfferMutationResult {
+    status: "applied" | "not_applicable" | "invalid" | "conflict";
+    reason: "offer_not_found" | "offer_expired" | "offer_not_yet_valid" | "code_not_found" | "code_required" | "code_expired" | "code_not_yet_valid" | "scope" | "min_pax" | "eligibility" | "currency" | "no_discount" | "booking_mismatch" | "session_mismatch" | "conflict" | null;
+    offer: StorefrontPromotionalOffer | null;
+    target: {
+        bookingId: string | null;
+        sessionId: string | null;
+        productId: string;
+        departureId: string | null;
+    };
+    pricing: {
+        basePriceCents: number;
+        currency: string;
+        discountAppliedCents: number;
+        discountedPriceCents: number;
+    };
+    appliedOffers: StorefrontAppliedOffer[];
+    conflict: {
+        policy: "best_discount_wins" | "stackable_compose";
+        autoAppliedOfferIds: string[];
+        manualOfferId: string | null;
+        selectedOfferIds: string[];
+        message: string;
+    } | null;
+}
+export interface StorefrontOfferResolvers {
+    listApplicableOffers?: (input: {
+        productId: string;
+        departureId?: string;
+        locale?: string;
+    } & StorefrontRequestContext) => Promise<StorefrontPromotionalOffer[]> | StorefrontPromotionalOffer[];
+    getOfferBySlug?: (input: {
+        slug: string;
+        locale?: string;
+    } & StorefrontRequestContext) => Promise<StorefrontPromotionalOffer | null> | StorefrontPromotionalOffer | null;
+    applyOffer?: (input: {
+        slug: string;
+        body: StorefrontOfferApplyInput;
+    } & StorefrontRequestContext) => Promise<StorefrontOfferMutationResult> | StorefrontOfferMutationResult;
+    redeemOffer?: (input: {
+        body: StorefrontOfferRedeemInput;
+    } & StorefrontRequestContext) => Promise<StorefrontOfferMutationResult> | StorefrontOfferMutationResult;
+}
+export declare function createPromotionsStorefrontResolvers(): StorefrontOfferResolvers;
+declare function matchesProduct(scope: PromotionalOfferScope, inLinkTable: boolean): boolean;
+declare function toStorefrontDto(offer: PromotionalOffer, applicableProductIds: string[]): StorefrontPromotionalOffer;
+declare function currentValidityStatus(offer: PromotionalOffer, now: Date): "offer_expired" | "offer_not_yet_valid" | null;
+declare function codeStatusToReason(status: CodeStatus): NonNullable<StorefrontOfferMutationResult["reason"]> | null;
+declare function buildConflict(input: {
+    autoAppliedOfferIds: string[];
+    manualOfferId: string | null;
+    selectedOfferIds: string[];
+    manualSelected: boolean;
+}): StorefrontOfferMutationResult["conflict"];
+export declare const __test__: {
+    buildConflict: typeof buildConflict;
+    codeStatusToReason: typeof codeStatusToReason;
+    currentValidityStatus: typeof currentValidityStatus;
+    matchesProduct: typeof matchesProduct;
+    toStorefrontDto: typeof toStorefrontDto;
+};
+export {};
+//# sourceMappingURL=service-storefront.d.ts.map

package/dist/promotions/service-storefront.d.ts.map

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

package/dist/promotions/service-storefront.js

@@ -0,0 +1,326 @@
+/**
+ * Storefront resolvers — populate the previously-empty
+ * `/v1/public/products/:productId/offers` and `/v1/public/offers/:slug`
+ * endpoints in `@voyant-travel/storefront` with real data.
+ *
+ * Wire via:
+ *
+ *   const storefrontModule = createStorefrontHonoModule({
+ *     offers: createPromotionsStorefrontResolvers(),
+ *   })
+ *
+ * Per docs/architecture/promotions-architecture.md §8.
+ *
+ * V1 limitations:
+ *   - Storefront calls don't carry an audience / market in the request
+ *     context, so the resolver only filters by `products` + `global`
+ *     scopes (the catalog plane handles audience-scoped projection).
+ *     `markets` and `audiences` scoped offers don't appear in this
+ *     listing endpoint.
+ *   - Locale-aware offer names: the schema doesn't store translations
+ *     yet (single-locale offer names per §12.1); `locale` is accepted
+ *     but ignored. A `promotional_offer_translations` table mirrors
+ *     `destinations_translations` if/when needed.
+ *   - `applicableDepartureIds`: always empty per §12.7 — departure-
+ *     scoped offers aren't modelled in v1.
+ *   - Only auto-applied offers (no code) appear in `listApplicableOffers`;
+ *     code-gated offers are still queryable via `getOfferBySlug`.
+ */
+import { and, eq, gte, inArray, isNull, lte, or } from "drizzle-orm";
+import { promotionalOfferProducts, promotionalOffers } from "./schema.js";
+import { createDrizzleOfferDataSource, evaluateOffersForProduct, } from "./service-evaluator.js";
+export function createPromotionsStorefrontResolvers() {
+    return {
+        async listApplicableOffers(input) {
+            const db = resolveDb(input);
+            if (!db)
+                return [];
+            const now = new Date();
+            // Active + currently-valid + auto-applied (no code) offers.
+            const baseRows = await db
+                .select()
+                .from(promotionalOffers)
+                .where(and(eq(promotionalOffers.active, true), isNull(promotionalOffers.code), or(isNull(promotionalOffers.validFrom), lte(promotionalOffers.validFrom, now)), or(isNull(promotionalOffers.validUntil), gte(promotionalOffers.validUntil, now))));
+            if (baseRows.length === 0)
+                return [];
+            // Restrict to offers that match the product: either `global` scope
+            // (always matches) OR a product-shaped scope whose materialized
+            // link table contains this product.
+            const productLinkRows = await db
+                .select({ offerId: promotionalOfferProducts.offerId })
+                .from(promotionalOfferProducts)
+                .where(and(eq(promotionalOfferProducts.productId, input.productId), inArray(promotionalOfferProducts.offerId, baseRows.map((r) => r.id))));
+            const offersMatchingProduct = new Set(productLinkRows.map((r) => r.offerId));
+            const productLinkLookups = await loadApplicableProductIds(db, baseRows.map((r) => r.id));
+            const out = [];
+            for (const offer of baseRows) {
+                if (!matchesProduct(offer.scope, offersMatchingProduct.has(offer.id)))
+                    continue;
+                out.push(toStorefrontDto(offer, productLinkLookups.get(offer.id) ?? []));
+            }
+            return out;
+        },
+        async getOfferBySlug(input) {
+            const db = resolveDb(input);
+            if (!db)
+                return null;
+            const offer = await findActiveOfferBySlug(db, input.slug);
+            if (!offer)
+                return null;
+            const links = await loadApplicableProductIds(db, [offer.id]);
+            return toStorefrontDto(offer, links.get(offer.id) ?? []);
+        },
+        async applyOffer(input) {
+            const db = resolveDb(input);
+            if (!db)
+                return notConfiguredResult(input.body);
+            const offer = await findActiveOfferBySlug(db, input.slug);
+            if (!offer) {
+                return emptyResult(input.body, "invalid", "offer_not_found", null);
+            }
+            if (offer.code != null) {
+                return emptyResult(input.body, "invalid", "code_required", await dtoForOffer(db, offer));
+            }
+            const validity = currentValidityStatus(offer, new Date());
+            if (validity !== null) {
+                return emptyResult(input.body, "invalid", validity, await dtoForOffer(db, offer));
+            }
+            return evaluateStorefrontMutation(db, input.body, {
+                manualOffer: offer,
+                code: undefined,
+                offer: await dtoForOffer(db, offer),
+            });
+        },
+        async redeemOffer(input) {
+            const db = resolveDb(input);
+            if (!db)
+                return notConfiguredResult(input.body);
+            const offer = await findActiveOfferByCode(db, input.body.code);
+            return evaluateStorefrontMutation(db, input.body, {
+                manualOffer: offer,
+                code: input.body.code,
+                offer: offer ? await dtoForOffer(db, offer) : null,
+            });
+        },
+    };
+}
+function resolveDb(input) {
+    return input.db ?? undefined;
+}
+function matchesProduct(scope, inLinkTable) {
+    switch (scope.kind) {
+        case "global":
+            return true;
+        case "products":
+        case "categories":
+        case "destinations":
+            return inLinkTable;
+        // markets / audiences scopes don't render via this endpoint in v1
+        // (no audience / market in the request context). They're still
+        // honored by the catalog projection (PR3) when products are indexed.
+        case "markets":
+        case "audiences":
+        // Fare/cabin-grade scopes need booking-line context and are evaluated
+        // by the checkout path rather than this product-listing endpoint.
+        case "fare_codes":
+        case "cabin_grades":
+            return false;
+    }
+}
+async function loadApplicableProductIds(db, offerIds) {
+    if (offerIds.length === 0)
+        return new Map();
+    const rows = await db
+        .select({
+        offerId: promotionalOfferProducts.offerId,
+        productId: promotionalOfferProducts.productId,
+    })
+        .from(promotionalOfferProducts)
+        .where(inArray(promotionalOfferProducts.offerId, offerIds));
+    const out = new Map();
+    for (const row of rows) {
+        const list = out.get(row.offerId) ?? [];
+        list.push(row.productId);
+        out.set(row.offerId, list);
+    }
+    return out;
+}
+function toStorefrontDto(offer, applicableProductIds) {
+    return {
+        id: offer.id,
+        name: offer.name,
+        slug: offer.slug,
+        description: offer.description,
+        discountType: offer.discountType,
+        // The DTO carries `discountValue` as a string for both flavors.
+        // Percentage offers store the percent ("20"); fixed_amount offers
+        // store the cents amount as a string ("500" for $5.00).
+        discountValue: offer.discountType === "percentage"
+            ? (offer.discountPercent ?? "0")
+            : String(offer.discountAmountCents ?? 0),
+        currency: offer.currency,
+        applicableProductIds,
+        // V1: departure-scoped offers aren't modelled (per §12.7).
+        applicableDepartureIds: [],
+        validFrom: offer.validFrom?.toISOString() ?? null,
+        validTo: offer.validUntil?.toISOString() ?? null,
+        minTravelers: typeof offer.conditions === "object" && offer.conditions != null
+            ? (offer.conditions.minPax ?? null)
+            : null,
+        // V1: no merchandising images on offers (per §2 non-goals).
+        imageMobileUrl: null,
+        imageDesktopUrl: null,
+        stackable: offer.stackable,
+        createdAt: offer.createdAt.toISOString(),
+        updatedAt: offer.updatedAt.toISOString(),
+    };
+}
+async function findActiveOfferBySlug(db, slug) {
+    const rows = await db
+        .select()
+        .from(promotionalOffers)
+        .where(and(eq(promotionalOffers.slug, slug), eq(promotionalOffers.active, true)))
+        .limit(1);
+    return rows[0] ?? null;
+}
+async function findActiveOfferByCode(db, code) {
+    const rows = await db
+        .select()
+        .from(promotionalOffers)
+        .where(and(eq(promotionalOffers.active, true), eq(promotionalOffers.code, code.toLowerCase())))
+        .limit(1);
+    return rows[0] ?? null;
+}
+async function dtoForOffer(db, offer) {
+    const links = await loadApplicableProductIds(db, [offer.id]);
+    return toStorefrontDto(offer, links.get(offer.id) ?? []);
+}
+function currentValidityStatus(offer, now) {
+    if (offer.validUntil != null && offer.validUntil < now)
+        return "offer_expired";
+    if (offer.validFrom != null && offer.validFrom > now)
+        return "offer_not_yet_valid";
+    return null;
+}
+function emptyResult(input, status, reason, offer) {
+    return {
+        status,
+        reason,
+        offer,
+        target: targetFromInput(input),
+        pricing: {
+            basePriceCents: input.basePriceCents,
+            currency: input.currency,
+            discountAppliedCents: 0,
+            discountedPriceCents: input.basePriceCents,
+        },
+        appliedOffers: [],
+        conflict: null,
+    };
+}
+function notConfiguredResult(input) {
+    return emptyResult(input, "invalid", "offer_not_found", null);
+}
+async function evaluateStorefrontMutation(db, input, options) {
+    const evaluation = await evaluateOffersForProduct(createDrizzleOfferDataSource(db), {
+        productId: input.productId,
+        slice: {
+            audience: input.audience,
+            market: input.market,
+        },
+        pax: input.pax,
+        code: options.code,
+        basePriceCents: input.basePriceCents,
+        baseCurrency: input.currency,
+    });
+    const codeReason = codeStatusToReason(evaluation.codeStatus);
+    if (codeReason != null) {
+        return emptyResult(input, "invalid", codeReason, options.offer);
+    }
+    const appliedOffers = evaluation.applied.map(toStorefrontAppliedOffer);
+    const manualOfferId = options.manualOffer?.id ?? null;
+    const selectedOfferIds = appliedOffers.map((offer) => offer.offerId);
+    const manualSelected = manualOfferId ? selectedOfferIds.includes(manualOfferId) : false;
+    const autoAppliedOfferIds = appliedOffers
+        .filter((offer) => offer.appliedCode == null && offer.offerId !== manualOfferId)
+        .map((offer) => offer.offerId);
+    const conflict = manualOfferId
+        ? buildConflict({
+            autoAppliedOfferIds,
+            manualOfferId,
+            selectedOfferIds,
+            manualSelected,
+        })
+        : null;
+    if (evaluation.total.discountAppliedCents <= 0) {
+        return {
+            ...emptyResult(input, "not_applicable", "no_discount", options.offer),
+            conflict,
+        };
+    }
+    const status = manualOfferId && !manualSelected ? "conflict" : "applied";
+    return {
+        status,
+        reason: status === "conflict" ? "conflict" : null,
+        offer: options.offer,
+        target: targetFromInput(input),
+        pricing: {
+            basePriceCents: input.basePriceCents,
+            currency: input.currency,
+            discountAppliedCents: evaluation.total.discountAppliedCents,
+            discountedPriceCents: evaluation.total.discountedPriceCents,
+        },
+        appliedOffers,
+        conflict,
+    };
+}
+function codeStatusToReason(status) {
+    if (status == null || status.kind === "code_valid")
+        return null;
+    if (status.kind === "code_not_applicable")
+        return status.reason;
+    return status.kind;
+}
+function toStorefrontAppliedOffer(offer) {
+    return {
+        offerId: offer.offerId,
+        offerName: offer.offerName,
+        discountAppliedCents: offer.discountAppliedCents,
+        discountedPriceCents: offer.discountedPriceCents,
+        currency: offer.currency,
+        discountKind: offer.discountKind,
+        discountPercent: offer.discountPercent,
+        discountAmountCents: offer.discountAmountCents,
+        appliedCode: offer.appliedCode,
+        stackable: offer.stackable,
+    };
+}
+function targetFromInput(input) {
+    return {
+        bookingId: input.bookingId ?? null,
+        sessionId: input.sessionId ?? null,
+        productId: input.productId,
+        departureId: input.departureId ?? null,
+    };
+}
+function buildConflict(input) {
+    if (input.autoAppliedOfferIds.length === 0 && input.manualSelected)
+        return null;
+    const policy = input.manualSelected ? "stackable_compose" : "best_discount_wins";
+    return {
+        policy,
+        autoAppliedOfferIds: input.autoAppliedOfferIds,
+        manualOfferId: input.manualOfferId,
+        selectedOfferIds: input.selectedOfferIds,
+        message: policy === "stackable_compose"
+            ? "The manually applied offer composes with selected auto-applied offers because every selected offer is stackable."
+            : "The best discount wins when a manually applied or code offer competes with non-stackable auto-applied offers.",
+    };
+}
+export const __test__ = {
+    buildConflict,
+    codeStatusToReason,
+    currentValidityStatus,
+    matchesProduct,
+    toStorefrontDto,
+};

package/dist/promotions/service.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Promotions service — CRUD over `promotional_offers` plus link-table
+ * materialization for product-shaped scopes.
+ *
+ * Per docs/architecture/promotions-architecture.md §13 (PR1 scope):
+ *   - listOffers / getOfferById / createOffer / updateOffer / archiveOffer / deleteOffer
+ *   - recomputeOfferLinks (rebuilds `promotional_offer_products` from current scope)
+ *   - emit `promotion.changed` (when an `eventBus` is supplied via the runtime arg)
+ *
+ * The evaluator (PR2) and catalog-plane / booking-engine / scheduler wiring
+ * (PR3 + PR4 + PR3.boundary) are NOT in this PR.
+ *
+ * Cross-module reads:
+ *   - `categories` scope expands via the Product-owned `product_category_products` table
+ *   - `destinations` scope expands via the Product-owned `product_destinations` table
+ *     through a resolver seam or raw SQL fallback. Promotions does not import
+ *     Product schemas at runtime.
+ */
+import type { EventBus } from "@voyant-travel/core";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { type PromotionChangedSource } from "./events.js";
+import { type PromotionalOffer } from "./schema.js";
+import type { InsertPromotionalOffer, PromotionalOfferListQuery, PromotionalOfferScope, UpdatePromotionalOffer } from "./validation.js";
+export interface OfferMutationRuntime {
+    /**
+     * Optional event bus. When wired, every CRUD path emits
+     * `promotion.changed` so the catalog bridge reindexes affected products.
+     * Per docs/architecture/promotions-architecture.md §9.1.
+     */
+    eventBus?: EventBus;
+    /**
+     * Override the emission `source`. `createOffer` / `deleteOffer` default
+     * to `"created"` / `"deleted"`; `updateOffer` / `archiveOffer` default
+     * to `"updated"`. The boundary scheduler (PR3) overrides with
+     * `"expired"` for `validUntil` crossings.
+     */
+    source?: PromotionChangedSource;
+    /**
+     * Optional resolver for Product-owned category/destination scope expansion.
+     * Hosts that move Product authoring behind Inventory can inject the
+     * appropriate adapter here without making Promotions depend on Product
+     * schemas.
+     */
+    resolveScopeProductIds?: ResolvePromotionalOfferScopeProductIds;
+}
+export type ResolvePromotionalOfferScopeProductIds = (db: PostgresJsDatabase, scope: Extract<PromotionalOfferScope, {
+    kind: "categories" | "destinations";
+}>) => Promise<string[]>;
+/**
+ * Expand an offer's scope to the product set it covers. Used by
+ * `recomputeOfferLinks` and by the event emitter to populate
+ * `affected.productIds`.
+ *
+ * Returns `null` for slice-shaped or checkout-shaped scopes (`global`,
+ * `markets`, `audiences`, `fare_codes`, `cabin_grades`)
+ * to signal that the link table should be empty AND that the event payload
+ * should fall back to `affected: { kind: "all" }` — these scopes can match
+ * an unbounded product set and we don't enumerate them at write time
+ * (per §9.1's resolution rules).
+ */
+export declare function resolveScopeProductIds(db: PostgresJsDatabase, scope: PromotionalOfferScope, resolver?: ResolvePromotionalOfferScopeProductIds): Promise<string[] | null>;
+/**
+ * Rebuild the `promotional_offer_products` rows for an offer from its
+ * current scope. Idempotent: deletes any prior rows, inserts the
+ * freshly-resolved set. Slice-shaped scopes leave the table empty.
+ */
+export declare function recomputeOfferLinks(db: PostgresJsDatabase, offerId: string, scope: PromotionalOfferScope, runtime?: OfferMutationRuntime): Promise<{
+    productIds: string[] | null;
+}>;
+declare function listOffers(db: PostgresJsDatabase, query: PromotionalOfferListQuery): Promise<{
+    data: {
+        id: string;
+        name: string;
+        slug: string;
+        description: string | null;
+        discountType: "percentage" | "fixed_amount";
+        discountPercent: string | null;
+        discountAmountCents: number | null;
+        currency: string | null;
+        scope: {
+            kind: "global";
+        } | {
+            kind: "products";
+            productIds: string[];
+        } | {
+            kind: "categories";
+            categoryIds: string[];
+        } | {
+            kind: "destinations";
+            destinationIds: string[];
+        } | {
+            kind: "markets";
+            marketIds: string[];
+        } | {
+            kind: "audiences";
+            audiences: ("staff" | "customer" | "partner" | "supplier")[];
+        } | {
+            kind: "fare_codes";
+            fareCodes: string[];
+        } | {
+            kind: "cabin_grades";
+            cabinGradeCodes: string[];
+        };
+        conditions: {
+            minPax?: number | undefined;
+            pastGuestOnly?: boolean | undefined;
+            soloTravelerOnly?: boolean | undefined;
+            childTravelerOnly?: boolean | undefined;
+            familyOnly?: boolean | undefined;
+        };
+        validFrom: Date | null;
+        validUntil: Date | null;
+        code: string | null;
+        stackable: boolean;
+        active: boolean;
+        metadata: unknown;
+        createdAt: Date;
+        updatedAt: Date;
+    }[];
+    total: number;
+    limit: number;
+    offset: number;
+}>;
+declare function getOfferById(db: PostgresJsDatabase, id: string): Promise<PromotionalOffer | null>;
+declare function createOffer(db: PostgresJsDatabase, input: InsertPromotionalOffer, runtime?: OfferMutationRuntime): Promise<PromotionalOffer>;
+declare function updateOffer(db: PostgresJsDatabase, id: string, patch: UpdatePromotionalOffer, runtime?: OfferMutationRuntime): Promise<PromotionalOffer | null>;
+declare function archiveOffer(db: PostgresJsDatabase, id: string, runtime?: OfferMutationRuntime): Promise<PromotionalOffer | null>;
+declare function deleteOffer(db: PostgresJsDatabase, id: string, runtime?: OfferMutationRuntime): Promise<{
+    id: string;
+} | null>;
+export declare const promotionsService: {
+    listOffers: typeof listOffers;
+    getOfferById: typeof getOfferById;
+    createOffer: typeof createOffer;
+    updateOffer: typeof updateOffer;
+    archiveOffer: typeof archiveOffer;
+    deleteOffer: typeof deleteOffer;
+    recomputeOfferLinks: typeof recomputeOfferLinks;
+    resolveScopeProductIds: typeof resolveScopeProductIds;
+};
+export type PromotionsService = typeof promotionsService;
+export {};
+//# sourceMappingURL=service.d.ts.map

package/dist/promotions/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/promotions/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAA;AACpB,OAAO,EAEL,KAAK,gBAAgB,EAItB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EACV,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,iBAAiB,CAAA;AAExB,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAA;IAC/B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,sCAAsC,CAAA;CAChE;AAED,MAAM,MAAM,sCAAsC,GAAG,CACnD,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,OAAO,CAAC,qBAAqB,EAAE;IAAE,IAAI,EAAE,YAAY,GAAG,cAAc,CAAA;CAAE,CAAC,KAC3E,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAUtB;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,qBAAqB,EAC5B,QAAQ,CAAC,EAAE,sCAAsC,GAChD,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAqB1B;AA6CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,CAAC,CAS1C;AA8ED,iBAAe,UAAU,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EjF;AAUD,iBAAe,YAAY,CAAC,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAOhG;AAED,iBAAe,WAAW,CACxB,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAa3B;AAED,iBAAe,WAAW,CACxB,EAAE,EAAE,kBAAkB,EACtB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAyClC;AAED,iBAAe,YAAY,CACzB,EAAE,EAAE,kBAAkB,EACtB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAgBlC;AAED,iBAAe,WAAW,CACxB,EAAE,EAAE,kBAAkB,EACtB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAqChC;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;CAS7B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAA"}