@voltro/plugin-economy 0.0.0-stage → 0.88.0

package/dist/offerPolicies.d.ts

@@ -0,0 +1,441 @@
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+export declare interface Bundle {
+    readonly offer: ShopOffer;
+    readonly parts: readonly {
+        readonly offer: ShopOffer;
+        readonly qty: number;
+    }[];
+    readonly showValue: 'sumOfParts';
+}
+
+export declare interface BundleDefinition {
+    readonly offer: ShopOfferDefinition | ShopOffer;
+    readonly parts: readonly {
+        readonly offer: ShopOfferDefinition | ShopOffer;
+        readonly qty: number;
+    }[];
+    readonly showValue: 'sumOfParts';
+}
+
+export declare interface BundlePriceReceipt {
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly referenceId: string;
+    readonly observedAt: number;
+    readonly price: Price;
+}
+
+export declare interface BundleValueContext {
+    readonly bundle: Bundle;
+    readonly currencies: readonly CurrencyDefinition[];
+    readonly realMoney?: boolean;
+    readonly at: number;
+    readonly maxPriceAgeMs: number;
+    readonly prices: readonly BundlePriceReceipt[];
+    readonly bundlePrice: Price;
+}
+
+export declare const captureFlashTriggerReceipt: (input: unknown) => FlashTriggerReceipt;
+
+declare interface CurrencyDefinition {
+    readonly id: string;
+    readonly kind: 'soft' | 'hard';
+    readonly cap?: EconomyAmountInput;
+    readonly premium?: boolean;
+    readonly display?: {
+        readonly nameKey: string;
+    } | null;
+}
+
+/** Deterministic affinity only, not a security randomizer. The trusted identity
+ * source must preserve its canonical key across account upgrades/merges. */
+export declare const defaultExperimentBucket: ExperimentBucket;
+
+/** A trusted accepted event fixes the start; refreshing cannot create a fresh
+ * window. The source owns original-event persistence and revocation. */
+export declare const defaultFlashTriggerPolicy: FlashTriggerPolicy;
+
+/** Simple novelty + declared play-style affinity. Stable rotation tie-breaking
+ * is a merchandising rule, never security randomness or account identity. */
+export declare const defaultPersonalizedOfferSelector: PersonalizedOfferSelector;
+
+/** A value comparison must describe exactly the bundle's actual grants, without
+ * inventing an exchange rate between currencies or a discounted anchor. */
+export declare const defineBundle: (input: BundleDefinition | Bundle, currencies: readonly CurrencyDefinition[], realMoney?: boolean) => Bundle;
+
+export declare const defineFlashOffer: (input: FlashOfferDefinition | FlashOffer, currencies: readonly CurrencyDefinition[], realMoney?: boolean) => FlashOffer;
+
+/** Variants use real distinct immutable offers, never a forged storefront price.
+ * Real/mixed variants must have distinct products for every configured channel. */
+export declare const defineOfferExperiment: (input: OfferExperimentDefinition | OfferExperiment, currencies: readonly CurrencyDefinition[], realMoney?: boolean) => OfferExperiment;
+
+export declare const definePersonalizedOffers: (input: PersonalizedOffersDefinition | PersonalizedOffers, currencies: readonly CurrencyDefinition[], realMoney?: boolean) => PersonalizedOffers;
+
+/** One actual Shop declaration/writer. The first-purchase multiplier becomes
+ * immutable content; one-time counters own acceptance, never a client flag. */
+export declare const defineStarterPack: (input: StarterPackDefinition | StarterPack, currencies: readonly CurrencyDefinition[], realMoney?: boolean) => StarterPack;
+
+declare type EconomyAmountInput = string | number | bigint;
+
+declare type EconomyChannel = 'web' | 'ios' | 'android' | 'steam';
+
+/** Redacted codes; never carries owners, amounts or provider payloads. */
+declare class EconomyError extends EconomyError_base {
+}
+
+declare const EconomyError_base: Schema.Class<EconomyError, Schema.TaggedStruct<"EconomyError", {
+    readonly code: Schema.Literals<readonly ["invalid_currency", "invalid_amount", "overflow", "invalid_price", "real_money_disabled", "invalid_input", "invalid_record", "currency_cap_reached", "insufficient_funds", "conflict", "forbidden", "unavailable", "not_found", "erased", "limit_exceeded", "already_redeemed"]>;
+}>, YieldableError>;
+
+export declare type ExperimentBucket = (input: OfferExperimentContext) => string;
+
+export declare interface FlashOffer {
+    readonly id: string;
+    readonly version: string;
+    readonly offer: ShopOffer;
+    readonly triggerId: string;
+    readonly durationMs: number;
+}
+
+export declare interface FlashOfferContext {
+    readonly flash: FlashOffer;
+    readonly currencies: readonly CurrencyDefinition[];
+    readonly realMoney?: boolean;
+    readonly tenantId: string;
+    readonly ownerId: string;
+    readonly at: number;
+    readonly trigger: FlashTriggerReceipt | null;
+    readonly rulesVersion?: string;
+}
+
+export declare interface FlashOfferDefinition {
+    readonly id: string;
+    readonly version?: string | undefined;
+    readonly offer: ShopOfferDefinition | ShopOffer;
+    readonly triggerId: string;
+    readonly durationMs: number;
+}
+
+export declare type FlashTriggerPolicy = (context: FlashOfferContext) => FlashWindow | null;
+
+export declare interface FlashTriggerReceipt {
+    readonly tenantId: string;
+    readonly ownerId: string;
+    readonly authorityId: string;
+    readonly eventId: string;
+    readonly triggerId: string;
+    readonly acceptedAt: number;
+}
+
+export declare interface FlashWindow {
+    readonly from: number;
+    readonly until: number;
+}
+
+export declare interface OfferExperiment {
+    readonly id: string;
+    readonly version: string;
+    readonly from: number;
+    readonly until: number;
+    readonly variants: readonly {
+        readonly id: string;
+        readonly weight: number;
+        readonly offers: readonly ShopOffer[];
+    }[];
+    readonly metrics: readonly string[];
+}
+
+export declare interface OfferExperimentContext {
+    readonly experiment: OfferExperiment;
+    readonly tenantId: string;
+    readonly key: string;
+    readonly at: number;
+    readonly currencies: readonly CurrencyDefinition[];
+    readonly realMoney?: boolean;
+}
+
+export declare interface OfferExperimentDefinition {
+    readonly id: string;
+    readonly version?: string | undefined;
+    readonly from: number;
+    readonly until: number;
+    readonly variants: readonly {
+        readonly id: string;
+        readonly weight: number;
+        readonly offers: readonly (ShopOfferDefinition | ShopOffer)[];
+    }[];
+    readonly metrics: readonly string[];
+}
+
+/** Composes the existing trusted ShopContextSource. No new price, grant, counter,
+ * persistence or fallback writer; ordinary Shop still pins accepted intent. */
+export declare const offerPolicyContextSource: (input: OfferPolicyOptions) => ShopContextSource;
+
+export declare interface OfferPolicyFacts {
+    readonly eligible: boolean;
+    readonly adjustments: readonly VirtualPriceAdjustment[];
+    readonly firstSessionAt: number;
+    readonly experimentKey: string;
+    readonly personalization?: {
+        readonly ownedItemIds: readonly string[];
+        readonly playStyles: readonly string[];
+    };
+    readonly flashTriggers?: readonly {
+        readonly flashId: string;
+        readonly trigger: FlashTriggerReceipt | null;
+    }[];
+}
+
+export declare interface OfferPolicyOptions {
+    readonly currencies: readonly CurrencyDefinition[];
+    readonly realMoney?: boolean;
+    readonly source: OfferPolicySource;
+    readonly starterPacks?: readonly StarterPack[];
+    readonly experiments?: readonly OfferExperiment[];
+    readonly experimentBucket?: ExperimentBucket;
+    readonly personalized?: readonly PersonalizedOffers[];
+    readonly flashOffers?: readonly FlashOffer[];
+    readonly personalizedSelector?: PersonalizedOfferSelector;
+    readonly flashTrigger?: FlashTriggerPolicy;
+    readonly policyVersion?: string;
+}
+
+export declare interface OfferPolicySource {
+    readonly read: (input: Readonly<{
+        tenantId: string;
+        ownerId: string;
+        offer: ShopOffer;
+        at: number;
+    }>) => Effect.Effect<OfferPolicyFacts, EconomyError>;
+}
+
+export declare interface PersonalizedOfferContext {
+    readonly personalized: PersonalizedOffers;
+    readonly currencies: readonly CurrencyDefinition[];
+    readonly realMoney?: boolean;
+    readonly tenantId: string;
+    readonly key: string;
+    readonly at: number;
+    readonly ownedItemIds: readonly string[];
+    readonly playStyles: readonly string[];
+    readonly rulesVersion?: string;
+}
+
+export declare interface PersonalizedOffers {
+    readonly id: string;
+    readonly version: string;
+    readonly slots: number;
+    readonly rotationMs: number;
+    readonly rotationAnchorAt: number;
+    readonly pool: readonly {
+        readonly offer: ShopOffer;
+        readonly affinities: readonly string[];
+    }[];
+}
+
+export declare interface PersonalizedOffersDefinition {
+    readonly id: string;
+    readonly version?: string | undefined;
+    readonly slots: number;
+    readonly rotationMs: number;
+    readonly rotationAnchorAt: number;
+    readonly pool: readonly {
+        readonly offer: ShopOfferDefinition | ShopOffer;
+        readonly affinities?: readonly string[];
+    }[];
+}
+
+export declare type PersonalizedOfferSelector = (input: PersonalizedSelectorContext) => readonly string[];
+
+export declare interface PersonalizedSelectorContext extends PersonalizedOfferContext {
+    readonly rotation: number;
+    readonly rulesVersion: string;
+}
+
+declare type Price = {
+    readonly kind: 'virtual';
+    readonly options: readonly ResolvedVirtualPriceOption[];
+} | ({
+    readonly kind: 'real';
+} & RealPriceDefinition) | {
+    readonly kind: 'mixed';
+    readonly real: RealPriceDefinition;
+    readonly virtual: readonly ResolvedVirtualPriceOption[];
+} | {
+    readonly kind: 'free';
+};
+
+declare type PriceDefinition = {
+    readonly kind: 'virtual';
+    readonly options: readonly VirtualPriceOption[];
+} | ({
+    readonly kind: 'real';
+} & RealPriceDefinition) | {
+    readonly kind: 'mixed';
+    readonly real: RealPriceDefinition;
+    readonly virtual: readonly VirtualPriceOption[];
+} | {
+    readonly kind: 'free';
+};
+
+export declare const projectBundleValue: (input: BundleValueContext) => Readonly<{
+    offerId: string;
+    offerVersion: string;
+    comparison: "sumOfParts";
+    capturedAt: number;
+    sources: readonly Readonly<{
+        offerId: string;
+        offerVersion: string;
+        referenceId: string;
+        observedAt: number;
+    }>[];
+    comparisons: readonly {
+        readonly kind: "virtual" | "real";
+        readonly currency: string;
+        readonly partsValue: string;
+        readonly bundleAmount: string;
+        readonly saving: string;
+    }[];
+}>;
+
+declare interface RealPriceDefinition {
+    /** Integer minor-unit references; verified store receipts remain authoritative. */
+    readonly prices: Readonly<Record<string, number>>;
+    readonly storeProductIds: Partial<Readonly<Record<EconomyChannel, string>>>;
+}
+
+declare interface ResolvedVirtualPriceOption {
+    readonly currency: string;
+    readonly amount: string;
+}
+
+export declare const resolveFlashOffer: (input: FlashOfferContext, policy?: FlashTriggerPolicy) => Readonly<{
+    id: string;
+    version: string;
+    offer: ShopOffer;
+    trigger: FlashTriggerReceipt;
+    from: number;
+    until: number;
+}> | null;
+
+export declare const resolveOfferExperiment: (input: OfferExperimentContext, slot?: ExperimentBucket) => Readonly<{
+    experimentId: string;
+    version: string;
+    variantId: string;
+    offers: readonly ShopOffer[];
+}> | null;
+
+export declare const resolvePersonalizedOffers: (input: PersonalizedOfferContext, selector?: PersonalizedOfferSelector) => Readonly<{
+    id: string;
+    version: string;
+    rotation: number;
+    from: number;
+    until: number;
+    offers: readonly ShopOffer[];
+}> | null;
+
+declare interface ShopContextInput {
+    readonly subject: Subject;
+    readonly offer: ShopOffer;
+    readonly at: number;
+}
+
+declare interface ShopContextSnapshot {
+    readonly eligible: boolean;
+    readonly adjustments: readonly VirtualPriceAdjustment[];
+}
+
+/** Trusted external profile/segment/flag facts; never inside a replayable SQL callback. */
+declare interface ShopContextSource {
+    readonly read: (input: ShopContextInput) => Effect.Effect<ShopContextSnapshot, EconomyError>;
+}
+
+declare interface ShopCurrencyGrant {
+    readonly currency: string;
+    readonly amount: EconomyAmountInput;
+}
+
+declare interface ShopItemGrant {
+    readonly itemId: string;
+    readonly qty: number;
+}
+
+declare interface ShopOffer {
+    readonly id: string;
+    readonly version: string;
+    readonly titleKey: string;
+    readonly price: Price;
+    readonly items: readonly ShopItemGrant[];
+    readonly currencies: readonly {
+        readonly currency: string;
+        readonly amount: string;
+    }[];
+    readonly from: number | null;
+    readonly until: number | null;
+    readonly segment: string | null;
+    readonly flag: string | null;
+    readonly countries: readonly string[];
+    readonly limits: {
+        readonly perPlayer: number | null;
+        readonly perDay: number | null;
+        readonly global: number | null;
+    };
+    readonly oneTime: boolean;
+    readonly maxQuantity: number;
+}
+
+declare interface ShopOfferDefinition {
+    readonly id: string;
+    readonly version?: string | undefined;
+    readonly titleKey: string;
+    readonly price: PriceDefinition;
+    readonly items?: readonly ShopItemGrant[] | undefined;
+    readonly currencies?: readonly ShopCurrencyGrant[] | undefined;
+    readonly from?: number | null | undefined;
+    readonly until?: number | null | undefined;
+    readonly segment?: string | null | undefined;
+    readonly flag?: string | null | undefined;
+    readonly countries?: readonly string[] | undefined;
+    readonly limits?: {
+        readonly perPlayer?: number | null | undefined;
+        readonly perDay?: number | null | undefined;
+        readonly global?: number | null | undefined;
+    } | undefined;
+    readonly oneTime?: boolean | undefined;
+    readonly maxQuantity?: number | undefined;
+}
+
+export declare interface StarterPack {
+    readonly offer: ShopOffer;
+    readonly expiresAfterMs: number;
+}
+
+export declare const starterPackAvailable: (pack: StarterPack, firstSessionAt: number, at: number) => boolean;
+
+export declare interface StarterPackDefinition {
+    readonly offer: ShopOfferDefinition | ShopOffer;
+    readonly expiresAfterMs: number;
+    readonly bonus?: {
+        readonly currency: string;
+        readonly multiplier: number;
+    };
+}
+
+declare interface VirtualPriceAdjustment {
+    readonly currency: string;
+    /** Inclusive integer 0..10000. */
+    readonly discountBps: number;
+    /** A trusted floor, enforced independently of a custom resolver. */
+    readonly minimum: EconomyAmountInput;
+}
+
+declare interface VirtualPriceOption {
+    readonly currency: string;
+    readonly amount: EconomyAmountInput;
+}
+
+export { }

package/dist/offerPolicies.fixture.js

@@ -0,0 +1,53 @@
+import { defaultExperimentBucket as e, defineOfferExperiment as t, resolveOfferExperiment as n } from "./offerPolicies.js";
+import { Effect as r } from "effect";
+// src/offerPolicies.fixture.ts
+var i = () => {
+	let e = [{
+		id: "test.gold",
+		kind: "soft"
+	}], n = t({
+		id: "test.experiment",
+		from: 0,
+		until: 864e5,
+		metrics: ["purchase.completed"],
+		variants: ["a", "b"].map((e, t) => ({
+			id: e,
+			weight: 1,
+			offers: [{
+				id: "offer." + e,
+				titleKey: "test.offer",
+				price: {
+					kind: "virtual",
+					options: [{
+						currency: "test.gold",
+						amount: t ? "9" : "7"
+					}]
+				},
+				currencies: [{
+					currency: "test.gold",
+					amount: "1"
+				}]
+			}]
+		}))
+	}, e);
+	return Object.freeze({
+		experiment: n,
+		currencies: e,
+		tenantId: "fixture",
+		key: "canonical.a",
+		at: 1,
+		realMoney: !1
+	});
+}, a = i(), o = Object.freeze({
+	kind: "slot",
+	defaultImplementation: e,
+	defaultProbe: {
+		run: () => r.sync(() => n(a)?.variantId),
+		expected: "b"
+	},
+	overrideProbe: {
+		run: () => r.sync(() => n(a, () => "a")?.variantId),
+		expected: "a"
+	}
+});
+export { o as experimentBucketSystemFixture, i as offerExperimentFixture };