@voyantjs/promotions 0.41.3 → 0.44.0

package/README.md

@@ -4,6 +4,19 @@ Promotional offers for Voyant — auto-applied catalog discounts (badges, strike
 
 PR1 ships the schema + admin CRUD only. Catalog plane wiring lands in PR3, booking-engine integration in PR4. See `docs/architecture/promotions-architecture.md` for the full design.
 
+Storefront runtimes can wire `createPromotionsStorefrontResolvers()` into
+`@voyantjs/storefront` to expose:
+
+- `GET /v1/public/products/:productId/offers`
+- `GET /v1/public/offers/:slug`
+- `POST /v1/public/offers/:slug/apply`
+- `POST /v1/public/offers/redeem`
+
+Manual and code-gated offers use the same evaluator as quote-time pricing:
+best non-stackable discount wins, and explicitly stackable offers compose when
+the selected path is stackable. Public mutation responses include conflict
+metadata without leaking internal rule details.
+
 ## Install
 
 ```bash
@@ -32,6 +45,7 @@ const app = createApp({
 | `./routes` | Hono admin routes mounted at `/v1/admin/promotions/*` |
 | `./events` | `PROMOTION_CHANGED_EVENT` + payload types |
 | `./service` | `promotionsService` (CRUD + scope materialization) |
+| `./service-storefront` | Storefront offer discovery, apply, and redeem resolver factory |
 
 ## License
 

package/dist/service-storefront.d.ts

@@ -26,13 +26,25 @@
  *   - Only auto-applied offers (no code) appear in `listApplicableOffers`;
  *     code-gated offers are still queryable via `getOfferBySlug`.
  */
-import type { StorefrontOfferResolvers, StorefrontPromotionalOffer } from "@voyantjs/storefront";
+import type { StorefrontOfferMutationResult, StorefrontOfferResolvers, StorefrontPromotionalOffer } from "@voyantjs/storefront";
 import { type PromotionalOffer } from "./schema.js";
+import { type CodeStatus } from "./service-evaluator.js";
 import type { PromotionalOfferScope } from "./validation.js";
 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;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"service-storefront.d.ts","sourceRoot":"","sources":["../src/service-storefront.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EAAE,KAAK,gBAAgB,EAA+C,MAAM,aAAa,CAAA;AAChG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAE5D,wBAAgB,mCAAmC,IAAI,wBAAwB,CAoE9E;AAMD,iBAAS,cAAc,CAAC,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAenF;AAuBD,iBAAS,eAAe,CACtB,KAAK,EAAE,gBAAgB,EACvB,oBAAoB,EAAE,MAAM,EAAE,GAC7B,0BAA0B,CA+B5B;AAED,eAAO,MAAM,QAAQ;;;CAAsC,CAAA"}
+{"version":3,"file":"service-storefront.d.ts","sourceRoot":"","sources":["../src/service-storefront.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAGV,6BAA6B,EAE7B,wBAAwB,EACxB,0BAA0B,EAE3B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EAAE,KAAK,gBAAgB,EAA+C,MAAM,aAAa,CAAA;AAChG,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAE5D,wBAAgB,mCAAmC,IAAI,wBAAwB,CAoG9E;AAMD,iBAAS,cAAc,CAAC,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAenF;AAuBD,iBAAS,eAAe,CACtB,KAAK,EAAE,gBAAgB,EACvB,oBAAoB,EAAE,MAAM,EAAE,GAC7B,0BAA0B,CA+B5B;AAkCD,iBAAS,qBAAqB,CAC5B,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,IAAI,GACR,eAAe,GAAG,qBAAqB,GAAG,IAAI,CAIhD;AAiGD,iBAAS,kBAAkB,CACzB,MAAM,EAAE,UAAU,GACjB,WAAW,CAAC,6BAA6B,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAI7D;AA0BD,iBAAS,aAAa,CAAC,KAAK,EAAE;IAC5B,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;CACxB,GAAG,6BAA6B,CAAC,UAAU,CAAC,CAc5C;AAED,eAAO,MAAM,QAAQ;;;;;;CAMpB,CAAA"}

package/dist/service-storefront.js

@@ -28,6 +28,7 @@
  */
 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) {
@@ -63,17 +64,44 @@ export function createPromotionsStorefrontResolvers() {
             const db = resolveDb(input);
             if (!db)
                 return null;
-            const rows = await db
-                .select()
-                .from(promotionalOffers)
-                .where(and(eq(promotionalOffers.slug, input.slug), eq(promotionalOffers.active, true)))
-                .limit(1);
-            const offer = rows[0];
+            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) {
@@ -143,4 +171,152 @@ function toStorefrontDto(offer, applicableProductIds) {
         updatedAt: offer.updatedAt.toISOString(),
     };
 }
-export const __test__ = { matchesProduct, toStorefrontDto };
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/promotions",
-  "version": "0.41.3",
+  "version": "0.44.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -64,13 +64,13 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/catalog": "0.41.3",
-    "@voyantjs/core": "0.41.3",
-    "@voyantjs/db": "0.41.3",
-    "@voyantjs/hono": "0.41.3",
-    "@voyantjs/products": "0.41.3",
-    "@voyantjs/storefront": "0.41.3",
-    "@voyantjs/workflows": "0.41.3"
+    "@voyantjs/catalog": "0.44.0",
+    "@voyantjs/core": "0.44.0",
+    "@voyantjs/db": "0.44.0",
+    "@voyantjs/hono": "0.44.0",
+    "@voyantjs/products": "0.44.0",
+    "@voyantjs/storefront": "0.44.0",
+    "@voyantjs/workflows": "0.44.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",