@voltro/plugin-economy 0.0.0-stage → 0.87.0

package/dist/subscriptionStore.testFixtures.js

@@ -0,0 +1,72 @@
+import { subscriptionTables as e } from "./subscriptionTables.entity.js";
+import { dataStoreSubscriptions as t } from "./subscriptionStore.server.js";
+import { shopAt as n, shopFixture as r } from "./shop.testFixtures.js";
+import { Effect as i } from "effect";
+import { ensureTableRegistered as a } from "@voltro/database";
+//#region src/subscriptionStore.testFixtures.ts
+var o = async (o, s = "tenant", c = {}, l = 4096) => {
+	e.forEach(a);
+	let u = await r(o, s, {}, l), d = n, f = {
+		currencies: [{
+			id: "test.gold",
+			kind: "soft"
+		}],
+		economy: u.economy,
+		inventory: u.inventory,
+		subscriptions: [{
+			id: "plus",
+			titleKey: "test.plus",
+			price: {
+				kind: "virtual",
+				options: [{
+					currency: "test.gold",
+					amount: "10"
+				}]
+			},
+			period: {
+				unit: "month",
+				count: 1
+			},
+			grants: {
+				onPurchase: { currencies: [{
+					currency: "test.gold",
+					amount: "2"
+				}] },
+				daily: { currencies: [{
+					currency: "test.gold",
+					amount: "1"
+				}] }
+			},
+			graceDays: 2,
+			disclosure: {
+				durationKey: "test.plus.duration",
+				renewalKey: "test.plus.renewal",
+				cancellationPath: "/account/subscriptions"
+			}
+		}],
+		version: "fixture.subscriptions.v1",
+		accessSource: { read: () => i.succeed({
+			eligible: !0,
+			renewalConsent: !0,
+			adjustments: []
+		}) },
+		now: () => d,
+		...c
+	};
+	return {
+		base: u,
+		options: f,
+		service: t(o, f),
+		setAt: (e) => {
+			d = e;
+		}
+	};
+}, s = (e, t = "start") => ({
+	subscriptionId: e.subscription.id,
+	subscriptionVersion: e.subscription.version,
+	subscriptionDigest: e.subscriptionDigest,
+	requestId: t,
+	...e.subscription.price.kind === "virtual" ? { currency: e.subscription.price.options[0].currency } : {}
+});
+//#endregion
+export { s as subscriptionFixtureStart, o as subscriptionStoreFixture };

package/dist/subscriptionTables.entity.js

@@ -0,0 +1,37 @@
+import { boolean as e, id as t, integer as n, json as r, table as i, text as a, timestamp as o } from "@voltro/database";
+//#region src/subscriptionTables.entity.ts
+var s = () => a().maxLength(120).externalId().sensitive("pii"), c = i("_voltro_eco_subscription_tenants", {
+	id: t({ prefix: "evt" }),
+	tenantId: s(),
+	admission: n().serverOnly()
+}).index(["tenantId"]), l = i("_voltro_eco_subscriptions", {
+	id: t({ prefix: "evd" }),
+	tenantId: s(),
+	definition: r().serverOnly(),
+	currencies: r().serverOnly(),
+	realMoney: e().serverOnly(),
+	rulesVersion: a().maxLength(120).serverOnly()
+}).index(["tenantId"]), u = i("_voltro_eco_subscription_subjects", {
+	id: t({ prefix: "evs" }),
+	tenantId: s(),
+	ownerId: a().maxLength(120).nullable().externalId().sensitive("pii"),
+	erased: e().serverOnly(),
+	admission: n().serverOnly()
+}).index(["tenantId", "ownerId"]), d = i("_voltro_eco_subscription_events", {
+	id: t({ prefix: "eve" }),
+	tenantId: s(),
+	ownerId: a().maxLength(120).nullable().externalId().sensitive("pii"),
+	ownerKey: a().maxLength(64).serverOnly(),
+	sequence: n().serverOnly(),
+	state: a().maxLength(16).oneOf(["fulfilled", "erased"]).serverOnly(),
+	digest: a().maxLength(64).nullable().serverOnly(),
+	body: r().nullable().serverOnly(),
+	createdAt: o().serverOnly()
+}).index(["tenantId", "ownerKey"]), f = [
+	c,
+	l,
+	u,
+	d
+];
+//#endregion
+export { l as subscriptionDefinitionsTable, d as subscriptionEventsTable, u as subscriptionSubjectsTable, f as subscriptionTables, c as subscriptionTenantsTable };

package/dist/subscriptions.d.ts

@@ -0,0 +1,394 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+export declare const captureSubscriptionReceiptIntent: (input: SubscriptionReceiptInput) => SubscriptionReceiptInput;
+
+export declare const captureSubscriptionsService: (input: SubscriptionsService) => SubscriptionsService;
+
+declare interface CurrencyDefinition {
+    readonly id: string;
+    readonly kind: 'soft' | 'hard';
+    readonly cap?: EconomyAmountInput;
+    readonly premium?: boolean;
+    readonly display?: {
+        readonly nameKey: string;
+    } | null;
+}
+
+/** Pure decision only. claimedDays must come from complete authoritative SQL
+ * grant receipts; a player cannot submit this context to a value-write route. */
+export declare const defaultSubscriptionDailyGrant: SubscriptionDailyGrantPolicy;
+
+/** UTC calendar windows anchored to original purchase, never the previously
+ * clamped renewal date. Thus Jan31 -> Feb28/29 -> Mar31 without monthly drift. */
+export declare const defaultSubscriptionPeriod: SubscriptionPeriodResolver;
+
+/** Content only. No entitlement, charge, automatic renewal or consent follows
+ * from declaring a price. Required UI copy/path must be rendered by a consumer. */
+export declare const defineSubscription: (input: SubscriptionDefinition | Subscription, declarations: readonly CurrencyDefinition[], realMoney?: boolean) => Subscription;
+
+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>;
+
+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';
+};
+
+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 resolveSubscriptionDailyGrant: (input: SubscriptionDailyContext, slot?: SubscriptionDailyGrantPolicy) => Readonly<{
+    eligible: boolean;
+    day: number;
+}>;
+
+/** A custom window may narrow the canonical period, never overlap/extend it.
+ * Actual accepted entitlement/renewal identity remains the SQL owner's duty. */
+export declare const resolveSubscriptionPeriod: (input: SubscriptionPeriodContext, slot?: SubscriptionPeriodResolver) => SubscriptionWindow;
+
+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;
+}
+
+declare interface ShopOrderReceipt {
+    readonly orderId: string;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly offerDigest: string;
+    readonly quantity: number;
+    readonly at: number;
+    readonly pricePaid: {
+        readonly kind: 'free';
+    } | {
+        readonly kind: 'virtual';
+        readonly currency: string;
+        readonly amount: string;
+    };
+    readonly transfers: readonly {
+        readonly txId: string;
+        readonly currency: string;
+        readonly amount: string;
+        readonly at: number;
+    }[];
+    readonly grants: readonly {
+        readonly operationId: string;
+        readonly kind: 'grant';
+        readonly changes: readonly {
+            readonly instanceId: string;
+            readonly delta: number;
+        }[];
+        readonly at: number;
+    }[];
+}
+
+export declare interface Subscription {
+    readonly id: string;
+    readonly version: string;
+    readonly titleKey: string;
+    readonly price: Price;
+    readonly period: Readonly<{
+        unit: 'day' | 'week' | 'month';
+        count: number;
+    }>;
+    readonly grants: Readonly<{
+        onPurchase: SubscriptionGift;
+        daily: SubscriptionGift;
+    }>;
+    readonly graceDays: number;
+    readonly coolingOff: Readonly<{
+        days: number;
+        overrideReason: string | null;
+    }>;
+    readonly disclosure: Readonly<{
+        durationKey: string;
+        renewalKey: string;
+        cancellationPath: string;
+    }>;
+}
+
+export declare interface SubscriptionActiveView {
+    readonly entitlementId: string;
+    readonly subscription: Subscription;
+    readonly subscriptionDigest: string;
+    readonly originAt: number;
+    readonly periodIndex: number;
+    readonly window: SubscriptionEntitlement;
+    readonly currency: string | null;
+    readonly renews: boolean;
+    readonly cancelledAt: number | null;
+}
+
+export declare interface SubscriptionCancelInput {
+    readonly entitlementId: string;
+    readonly requestId: string;
+}
+
+export declare interface SubscriptionCancellationReceipt {
+    readonly operationId: string;
+    readonly entitlementId: string;
+    readonly at: number;
+    readonly renews: false;
+}
+
+export declare interface SubscriptionDailyContext {
+    readonly entitlement: SubscriptionEntitlement;
+    readonly at: number;
+    readonly claimedDays: readonly number[];
+    readonly rulesVersion?: string;
+}
+
+export declare type SubscriptionDailyGrantPolicy = (input: SubscriptionDailyContext) => boolean;
+
+export declare interface SubscriptionDailyInput {
+    readonly entitlementId: string;
+    readonly requestId: string;
+}
+
+export declare interface SubscriptionDefinition {
+    readonly id: string;
+    readonly version?: string | undefined;
+    readonly titleKey: string;
+    readonly price: PriceDefinition;
+    readonly period: {
+        readonly unit: 'day' | 'week' | 'month';
+        readonly count: number;
+    };
+    readonly grants: {
+        readonly onPurchase?: SubscriptionGiftDefinition;
+        readonly daily?: SubscriptionGiftDefinition | undefined;
+    };
+    readonly graceDays?: number;
+    readonly coolingOff?: {
+        readonly days: number;
+        readonly overrideReason?: string | null;
+    };
+    readonly disclosure: {
+        readonly durationKey: string;
+        readonly renewalKey: string;
+        readonly cancellationPath: string;
+    };
+}
+
+export declare interface SubscriptionEntitlement {
+    readonly startsAt: number;
+    readonly expiresAt: number;
+    readonly graceUntil: number;
+    readonly state: 'active' | 'grace' | 'expired';
+}
+
+export declare const subscriptionEntitlementIntent: (input: SubscriptionDailyInput | SubscriptionCancelInput) => Readonly<{
+    entitlementId: string;
+    requestId: string;
+}>;
+
+export declare interface SubscriptionGift {
+    readonly items: ShopOffer['items'];
+    readonly currencies: ShopOffer['currencies'];
+}
+
+export declare interface SubscriptionGiftDefinition {
+    readonly items?: ShopOfferDefinition['items'] | undefined;
+    readonly currencies?: ShopOfferDefinition['currencies'] | undefined;
+}
+
+export declare type SubscriptionObservation = {
+    readonly requestId: string;
+    readonly state: 'not-observed';
+} | {
+    readonly requestId: string;
+    readonly state: 'fulfilled';
+    readonly receipt: SubscriptionValueReceipt | SubscriptionCancellationReceipt;
+};
+
+export declare interface SubscriptionPeriodContext {
+    readonly subscription: Subscription;
+    readonly currencies: readonly CurrencyDefinition[];
+    readonly realMoney?: boolean;
+    readonly originAt: number;
+    readonly index: number;
+    readonly rulesVersion?: string;
+}
+
+export declare type SubscriptionPeriodResolver = (input: SubscriptionPeriodContext) => SubscriptionWindow;
+
+export declare type SubscriptionReceiptInput = {
+    readonly kind: 'start';
+    readonly intent: SubscriptionStartInput;
+} | {
+    readonly kind: 'renew' | 'daily' | 'cancel';
+    readonly intent: SubscriptionDailyInput;
+};
+
+export declare interface SubscriptionRenewInput {
+    readonly tenantId: string;
+    readonly ownerId: string;
+    readonly entitlementId: string;
+    readonly requestId: string;
+}
+
+export declare const subscriptionRenewIntent: (input: SubscriptionRenewInput) => Readonly<{
+    tenantId: string;
+    ownerId: string;
+    entitlementId: string;
+    requestId: string;
+}>;
+
+export declare class SubscriptionsPort extends SubscriptionsPort_base {
+}
+
+declare const SubscriptionsPort_base: Context.ServiceClass<SubscriptionsPort, "@voltro/SubscriptionsPort", SubscriptionsService>;
+
+/** Renew is a trusted server intention. Implementations must deny players and
+ * enforce one accepted renewal per entitlement/period independently of nonce.
+ * Calendar/daily strategies alone cannot establish durable idempotency. */
+export declare interface SubscriptionsService {
+    readonly list: (subject: Subject) => Effect.Effect<readonly SubscriptionView[], EconomyError>;
+    readonly active: (subject: Subject) => Effect.Effect<readonly SubscriptionActiveView[], EconomyError>;
+    readonly start: (subject: Subject, input: SubscriptionStartInput) => Effect.Effect<SubscriptionValueReceipt, EconomyError>;
+    readonly renew: (subject: Subject, input: SubscriptionRenewInput) => Effect.Effect<SubscriptionValueReceipt, EconomyError>;
+    readonly claimDaily: (subject: Subject, input: SubscriptionDailyInput) => Effect.Effect<SubscriptionValueReceipt, EconomyError>;
+    readonly cancel: (subject: Subject, input: SubscriptionCancelInput) => Effect.Effect<SubscriptionCancellationReceipt, EconomyError>;
+    readonly receipt: (subject: Subject, input: SubscriptionReceiptInput) => Effect.Effect<SubscriptionObservation, EconomyError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, EconomyError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, EconomyError>;
+}
+
+/** Player intentions contain observed identities, never charge amounts, dates,
+ * provider receipts, claimed days, entitlement state or renewal authority. */
+export declare interface SubscriptionStartInput {
+    readonly subscriptionId: string;
+    readonly subscriptionVersion: string;
+    readonly subscriptionDigest: string;
+    readonly requestId: string;
+    readonly currency?: string | undefined;
+}
+
+export declare const subscriptionStartIntent: (input: SubscriptionStartInput) => Readonly<{
+    subscriptionId: string;
+    subscriptionVersion: string;
+    subscriptionDigest: string;
+    requestId: string;
+    currency: string | null;
+}>;
+
+export declare interface SubscriptionValueReceipt {
+    readonly operationId: string;
+    readonly entitlementId: string;
+    readonly kind: 'start' | 'renew' | 'daily';
+    readonly at: number;
+    readonly periodIndex: number;
+    readonly day: number | null;
+    readonly window: SubscriptionEntitlement;
+    readonly value: ShopOrderReceipt;
+}
+
+export declare interface SubscriptionView {
+    readonly subscription: Subscription;
+    readonly subscriptionDigest: string;
+}
+
+export declare interface SubscriptionWindow {
+    readonly startsAt: number;
+    readonly expiresAt: number;
+}
+
+declare interface VirtualPriceOption {
+    readonly currency: string;
+    readonly amount: EconomyAmountInput;
+}
+
+export { }

package/dist/subscriptions.fixture.js

@@ -0,0 +1,97 @@
+import { defaultSubscriptionDailyGrant as e, defaultSubscriptionPeriod as t, defineSubscription as n, resolveSubscriptionDailyGrant as r, resolveSubscriptionPeriod as i } from "./subscriptions.js";
+import { Effect as a } from "effect";
+//#region src/subscriptions.fixture.ts
+var o = () => {
+	let e = Object.freeze([{
+		id: "test.gold",
+		kind: "soft",
+		cap: "1000000"
+	}]), t = n({
+		id: "test.plus",
+		titleKey: "test.plus",
+		price: {
+			kind: "virtual",
+			options: [{
+				currency: "test.gold",
+				amount: "10"
+			}]
+		},
+		period: {
+			unit: "month",
+			count: 1
+		},
+		grants: {
+			onPurchase: { currencies: [{
+				currency: "test.gold",
+				amount: "2"
+			}] },
+			daily: { currencies: [{
+				currency: "test.gold",
+				amount: "1"
+			}] }
+		},
+		graceDays: 3,
+		disclosure: {
+			durationKey: "test.plus.duration",
+			renewalKey: "test.plus.renewal",
+			cancellationPath: "/account/subscriptions"
+		}
+	}, e);
+	return Object.freeze({
+		subscription: t,
+		currencies: e,
+		realMoney: !1,
+		originAt: Date.UTC(2024, 0, 31, 12),
+		index: 0
+	});
+}, s = o(), c = t(s), l = Object.freeze({
+	kind: "slot",
+	defaultImplementation: t,
+	defaultProbe: {
+		run: () => a.sync(() => i(s)),
+		expected: c
+	},
+	overrideProbe: {
+		run: () => a.sync(() => i({
+			...s,
+			rulesVersion: "test.narrow.v1"
+		}, (e) => ({
+			...t(e),
+			expiresAt: c.expiresAt - 1
+		}))),
+		expected: {
+			...c,
+			expiresAt: c.expiresAt - 1
+		}
+	}
+}), u = Object.freeze({
+	entitlement: Object.freeze({
+		...c,
+		graceUntil: c.expiresAt + 2592e5,
+		state: "active"
+	}),
+	at: s.originAt,
+	claimedDays: Object.freeze([])
+}), d = Object.freeze({
+	kind: "slot",
+	defaultImplementation: e,
+	defaultProbe: {
+		run: () => a.sync(() => r(u)),
+		expected: {
+			eligible: !0,
+			day: Math.floor(s.originAt / 864e5)
+		}
+	},
+	overrideProbe: {
+		run: () => a.sync(() => r({
+			...u,
+			rulesVersion: "test.deny.v1"
+		}, () => !1)),
+		expected: {
+			eligible: !1,
+			day: Math.floor(s.originAt / 864e5)
+		}
+	}
+});
+//#endregion
+export { d as subscriptionDailySystemFixture, o as subscriptionFixture, l as subscriptionPeriodSystemFixture };