@voltro/plugin-economy 0.0.0-stage → 0.87.0

package/dist/iapNotifications.server.js

@@ -0,0 +1,96 @@
+import { economyError as e } from "./errors.js";
+import { captureBoundMethods as t, dataObject as n, identifier as r } from "./capture.js";
+import { iapEnvironment as i, iapTimestamp as a } from "./iap.js";
+import { canonicalDataJson as o } from "./canonicalDataJson.js";
+import { Context as s, Effect as c } from "effect";
+import { Buffer as l } from "node:buffer";
+import { createHash as u } from "node:crypto";
+//#region src/iapNotifications.server.ts
+var d = (e) => e === "ios" || e === "android" || e === "web", f = class extends s.Service()("@voltro/IapNotificationPort") {}, p = (e) => t(e, ["initialize", "verify"]), m = /* @__PURE__ */ new WeakMap(), h = (t) => {
+	let o = n(t, [
+		"channel",
+		"applicationId",
+		"environment",
+		"noticeId",
+		"sourceType",
+		"kind",
+		"occurredAt",
+		"transactionId",
+		"originalTransactionId",
+		"storeProductId"
+	], "invalid_record");
+	if (!d(o.channel) || ![
+		"one-time",
+		"subscription",
+		"voided",
+		"review",
+		"test"
+	].includes(String(o.kind))) throw e("invalid_record");
+	let s = (t) => {
+		if (typeof t != "string" || t.length === 0 || t.length > 128 || /[\u0000-\u0020\u007f]/.test(t)) throw e("invalid_record");
+		return t;
+	};
+	return Object.freeze({
+		channel: o.channel,
+		applicationId: r(o.applicationId),
+		environment: o.environment === null ? null : i(o.environment),
+		noticeId: s(o.noticeId),
+		sourceType: s(o.sourceType),
+		kind: o.kind,
+		occurredAt: a(o.occurredAt),
+		transactionId: o.transactionId === null ? null : s(o.transactionId),
+		originalTransactionId: o.originalTransactionId === null ? null : s(o.originalTransactionId),
+		storeProductId: o.storeProductId === null ? null : r(o.storeProductId)
+	});
+}, g = (e, t, n, r) => {
+	let i = h(e), a = structuredClone(t), s = Object.freeze({
+		noticeId: i.noticeId,
+		channel: i.channel
+	});
+	return m.set(s, Object.freeze({
+		notice: i,
+		fingerprint: u("sha256").update(o([i, a])).digest("hex"),
+		material: a,
+		...n === void 0 ? {} : { validate: n },
+		...r === void 0 ? {} : { prepare: r }
+	})), s;
+}, _ = (t) => {
+	let n = typeof t == "object" && t ? m.get(t) : void 0;
+	if (!n) throw e("forbidden");
+	return Object.freeze({
+		...n,
+		material: structuredClone(n.material)
+	});
+}, v = (t) => {
+	let n = typeof t == "object" && t ? m.get(t) : void 0;
+	return n ? n.validate === void 0 ? c.void : c.suspend(n.validate).pipe(c.catchDefect(() => c.fail(e("unavailable")))) : c.fail(e("forbidden"));
+}, y = (t) => {
+	let n = typeof t == "object" && t ? m.get(t) : void 0;
+	return n ? n.validate === void 0 ? c.succeed([]) : n.prepare === void 0 ? c.fail(e("unavailable")) : c.suspend(n.prepare).pipe(c.map((e) => Object.freeze([e])), c.catchDefect(() => c.fail(e("unavailable")))) : c.fail(e("forbidden"));
+}, b = (e) => _(e).notice, x = (t, r) => {
+	let i = n(t, [
+		"body",
+		"authorization",
+		"headers"
+	]);
+	if (typeof i.body != "string" || i.body.length === 0 || i.body.length > r || l.byteLength(i.body, "utf8") > r) throw e("limit_exceeded");
+	let a = i.authorization;
+	if (a !== void 0 && (typeof a != "string" || a.length === 0 || a.length > 16384 || /[\u0000-\u001f\u007f]/.test(a))) throw e("invalid_input");
+	let o;
+	if (i.headers !== void 0) {
+		let e = Object.entries(n(i.headers, Object.keys(i.headers)));
+		o = {};
+		for (let [t, n] of e.slice(0, 64)) typeof n != "string" || !/^[a-z0-9-]{1,64}$/.test(t) || n.length > 8192 || /[\u0000-\u001f\u007f]/.test(n) || (o[t] = n);
+	}
+	return Object.freeze({
+		body: i.body,
+		...a === void 0 ? {} : { authorization: a },
+		...o === void 0 ? {} : { headers: Object.freeze(o) }
+	});
+}, S = (t, n) => {
+	let r = a(t);
+	if (r > n + 6e4) throw e("invalid_record");
+	return r;
+};
+//#endregion
+export { f as IapNotificationPort, h as captureIapNotificationNotice, p as captureIapNotificationService, x as captureNotificationInput, b as iapNotificationNotice, d as isIapRefundChannel, g as issueVerifiedIapNotification, S as notificationTime, y as prepareVerifiedIapNotification, _ as readVerifiedIapNotification, v as validateVerifiedIapNotification };

package/dist/iapNotificationsBinding.server.js

@@ -0,0 +1,233 @@
+import { economyError as e } from "./errors.js";
+import { captureBoundMethods as t, dataObject as n, identifier as r } from "./capture.js";
+import { shopInteger as i } from "./shop.js";
+import { iapChannel as a } from "./iap.js";
+import { IapRefundEventsPort as o } from "./iapRefundEvents.js";
+import { isIapRefundChannel as s } from "./iapNotifications.server.js";
+import { iapNotificationTables as c } from "./iapNotificationTables.entity.js";
+import { iapRefundTables as l } from "./iapRefundTables.entity.js";
+import { dataStoreIapRefunds as u } from "./iapRefunds.server.js";
+import { dataStoreIapNotificationCustody as d } from "./iapNotificationStore.server.js";
+import { captureIapNotificationProcessorService as f, iapNotificationHttpRoute as p, iapNotificationProcessor as m } from "./iapNotificationProcessor.server.js";
+import { Context as h, Effect as g, Layer as _ } from "effect";
+//#region src/iapNotificationsBinding.server.ts
+var v = class extends h.Service()("@voltro/IapNotificationsSystemPort") {}, y = (e) => t(e, [
+	"initialize",
+	"processor",
+	"exportSubject",
+	"eraseSubject"
+]), b = () => g.fail(e("unavailable")), x = Object.freeze({
+	initialize: b,
+	processor: b,
+	exportSubject: b,
+	eraseSubject: b
+}), S = (h, x) => {
+	if (h === void 0) return;
+	let S = n(h, [
+		"version",
+		"pathPrefix",
+		"maxBodyBytes",
+		"bodyRetentionMs",
+		"debtPolicy",
+		"assets",
+		"assetsVersion",
+		"maxNoticeRows",
+		"maxRefundRows",
+		"cipher",
+		"service",
+		"refundEvents",
+		"refundDisposition",
+		"onChange"
+	]), C = r(S.version);
+	if (C === "default.v1") throw e("invalid_input");
+	let w = S.service === void 0 ? void 0 : y(S.service);
+	if (x.replacedIap && !w || w && [
+		"bodyRetentionMs",
+		"debtPolicy",
+		"assets",
+		"assetsVersion",
+		"maxNoticeRows",
+		"maxRefundRows",
+		"cipher",
+		"onChange"
+	].some((e) => S[e] !== void 0) || S.onChange !== void 0 && typeof S.onChange != "function") throw e("invalid_input");
+	let T = S.onChange;
+	if (!w && (S.refundEvents !== void 0 || S.refundDisposition !== void 0) || x.replacedIap && S.refundDisposition !== void 0) throw e("invalid_input");
+	let E = S.refundEvents === void 0 ? void 0 : t(S.refundEvents, [
+		"pending",
+		"read",
+		"acknowledge"
+	]), D = S.refundDisposition === void 0 ? void 0 : t(S.refundDisposition, ["read"]), O = S.pathPrefix ?? "/_voltro/economy/iap";
+	if (typeof O != "string" || !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/.test(O) || O.length > 210) throw e("invalid_input");
+	let k = i(S.maxBodyBytes ?? 262144, 1024, 1048576), A = Object.freeze([...new Set(x.channels.map(a))]);
+	if (!A.length || !w && (A.some((e) => !s(e)) || x.declarations.some((e) => !e.createNotifications || !e.createCurrentState))) throw e("invalid_input");
+	let j = w ? null : i(S.bodyRetentionMs, 1, 31536e6), M = w ? null : i(S.maxNoticeRows ?? 1e4, 1, 1e5), N = w ? null : i(S.maxRefundRows ?? 1e4, 1, 1e5), P = w ? null : S.debtPolicy;
+	if (!w && P !== "allowNegative" && P !== "blockSpend") throw e("invalid_input");
+	let F = S.assets === void 0 ? void 0 : t(S.assets, [
+		"prepare",
+		"validate",
+		"audit"
+	]), I = F ? r(S.assetsVersion) : null;
+	if (I === "default.v1" || !w && x.itemOrders && !F || !F && S.assetsVersion !== void 0) throw e("invalid_input");
+	let L = S.cipher === void 0 ? void 0 : t(S.cipher, ["read"]);
+	for (let e of A) r(x.namespace + ".notice." + e);
+	let R, z = 0, B = /* @__PURE__ */ new Map(), V, H = () => R !== void 0 && x.isActive(), U = (t) => g.try({
+		try: () => a(t),
+		catch: () => e("invalid_input")
+	}).pipe(g.flatMap((e) => g.suspend(() => {
+		if (!H() || !A.includes(e)) return b();
+		let t = z;
+		return (w ? w.processor(e) : B.has(e) ? g.succeed(B.get(e)) : b()).pipe(g.map((e) => {
+			let n = f(e), r = (e) => g.suspend(() => H() && z === t ? g.suspend(e).pipe(g.flatMap((e) => H() && z === t ? g.succeed(e) : b())) : b());
+			return Object.freeze({
+				initialize: () => r(n.initialize),
+				ingest: (e) => r(() => n.ingest(e)),
+				process: (e) => r(() => n.process(e)),
+				pending: () => r(n.pending),
+				prune: () => r(n.prune),
+				exportSubject: (e) => r(() => n.exportSubject(e)),
+				eraseSubject: (e) => r(() => n.eraseSubject(e))
+			});
+		}), g.catchDefect(() => b()));
+	}))), W = (e) => g.suspend(() => {
+		let t = z;
+		return H() ? g.suspend(e).pipe(g.flatMap((e) => H() && z === t ? g.succeed(e) : b()), g.catchDefect(() => b())) : b();
+	}), G = () => g.suspend(() => {
+		let e = z;
+		return R ? (w ? w.initialize() : g.gen(function* () {
+			for (let e of B.values()) yield* e.initialize();
+		})).pipe(g.flatMap(() => z === e && R ? g.void : b()), g.catchDefect(() => b())) : b();
+	}), K = Object.freeze({
+		initialize: G,
+		processor: U,
+		exportSubject: (e) => W(() => w ? w.exportSubject(structuredClone(e)) : g.gen(function* () {
+			let t = [];
+			for (let [n, r] of B) t.push({
+				channel: n,
+				data: yield* r.exportSubject(e)
+			});
+			return { deployments: t };
+		})),
+		eraseSubject: (e) => W(() => w ? w.eraseSubject(structuredClone(e)) : g.gen(function* () {
+			for (let t of B.values()) yield* t.eraseSubject(e);
+		}))
+	}), q = A.map((e) => {
+		let t = Object.freeze({
+			initialize: () => U(e).pipe(g.flatMap((e) => e.initialize())),
+			ingest: (t) => U(e).pipe(g.flatMap((e) => e.ingest(t))),
+			process: (t) => U(e).pipe(g.flatMap((e) => e.process(t))),
+			pending: () => U(e).pipe(g.flatMap((e) => e.pending())),
+			prune: () => U(e).pipe(g.flatMap((e) => e.prune())),
+			exportSubject: (t) => U(e).pipe(g.flatMap((e) => e.exportSubject(t))),
+			eraseSubject: (t) => U(e).pipe(g.flatMap((e) => e.eraseSubject(t)))
+		}), n = x.deliver;
+		return p({
+			path: O + "/" + e,
+			maxBodyBytes: k,
+			processor: t,
+			...n ? { deliver: (t) => n(e, t) } : {}
+		});
+	}), J = (t, n, r) => {
+		if (R && R !== t) throw Error("IAP notification system cannot cross app stores");
+		if (R = t, z++, B = /* @__PURE__ */ new Map(), V = void 0, !w) {
+			if (!n) throw e("unavailable");
+			V = u(t, {
+				realMoney: !0,
+				namespace: x.namespace,
+				debtPolicy: P,
+				orders: n,
+				economy: x.economy,
+				assets: F,
+				assetsVersion: I ?? void 0,
+				maxHistoryRows: N
+			});
+			for (let { declaration: i, context: a } of r) {
+				if (!s(i.channel) || !i.createNotifications || !i.createCurrentState) throw e("invalid_input");
+				let r = {
+					realMoney: !0,
+					channel: i.channel,
+					environment: i.environment,
+					applicationId: i.applicationId
+				}, o = d(t, {
+					namespace: x.namespace + ".notice." + i.channel,
+					deployment: r,
+					orders: n,
+					bodyRetentionMs: j,
+					maxRows: M,
+					maxBodyBytes: k,
+					now: a.now,
+					cipher: L
+				});
+				B.set(i.channel, m({
+					deployment: r,
+					orders: n,
+					custody: o,
+					refunds: V,
+					notifications: i.createNotifications(a),
+					current: i.createCurrentState(a),
+					...T ? { changed: T } : {}
+				}));
+			}
+		}
+	}, Y = Object.freeze({
+		pending: (e) => W(() => {
+			let t = E ?? V?.events;
+			return t ? t.pending(structuredClone(e)) : b();
+		}),
+		read: (e, t) => W(() => {
+			let n = E ?? V?.events;
+			return n ? n.read(structuredClone(e), t) : b();
+		}),
+		acknowledge: (e, t, n) => W(() => {
+			let r = E ?? V?.events;
+			return r ? r.acknowledge(structuredClone(e), t, n) : b();
+		})
+	}), X = w ? E ? "custom" : null : "sql", Z = w ? D ? "custom" : null : "sql", Q = Z === null ? void 0 : Object.freeze({ read: async (t, n) => {
+		let r = z, i = D?.read ?? V?.readDisposition;
+		if (!H() || !i) throw e("unavailable");
+		let a = await i(t, n);
+		if (!H() || z !== r) throw e("unavailable");
+		return a;
+	} }), $ = X === null ? _.succeed(v, K) : _.merge(_.succeed(v, K), _.succeed(o, Y)), ee = Object.freeze({
+		backend: w ? "custom" : "sql",
+		version: C,
+		channels: A,
+		httpPaths: q.map((e) => e.path),
+		eventQueue: X,
+		orderDisposition: Z,
+		debtPolicy: P,
+		itemParticipant: w ? "app-owned" : F ? "prepared-sql" : "none",
+		assetsVersion: I,
+		budgets: {
+			maxBodyBytes: k,
+			bodyRetentionMs: j,
+			noticeRows: M,
+			refundRows: N
+		}
+	});
+	return Object.freeze({
+		service: K,
+		events: X === null ? void 0 : Y,
+		dispositionSource: Q,
+		bind: J,
+		initialize: G,
+		layer: $,
+		httpRoutes: q,
+		status: ee,
+		tables: w ? [] : [...c, ...l],
+		roles: w ? [] : [
+			"iapNotificationNamespaces",
+			"iapNotificationSubjects",
+			"iapNotifications",
+			"iapRefundNamespaces",
+			"iapRefundSubjects",
+			"iapRefundOrders",
+			"iapRefundAdjustments"
+		],
+		deactivate: () => {
+			z++, R = void 0, B = /* @__PURE__ */ new Map(), V = void 0;
+		}
+	});
+};
+//#endregion
+export { v as IapNotificationsSystemPort, S as bindIapNotificationsSystem, y as captureIapNotificationsSystemService, x as unavailableIapNotifications };

package/dist/iapNotificationsSystemPort.fixture.js

@@ -0,0 +1,51 @@
+import { economyError as e } from "./errors.js";
+import { IapNotificationsSystemPort as t } from "./iapNotificationsBinding.server.js";
+import { iapInstalledNotificationsFixture as n } from "./iapInstalledNotifications.testFixtures.js";
+import { Effect as r, Layer as i } from "effect";
+import { InMemoryDataStore as a } from "@voltro/runtime";
+//#region src/iapNotificationsSystemPort.fixture.ts
+var o = /* @__PURE__ */ new WeakMap(), s = r.tryPromise({
+	try: () => n(new a(), "fixture.notifications.system"),
+	catch: () => e("unavailable")
+}).pipe(r.flatMap((e) => e.activate().pipe(r.map(() => {
+	let t = e.plugin.economy.iapNotifications();
+	return o.set(t, e), Object.freeze({
+		service: t,
+		plugin: e.plugin,
+		user: e.base.user(),
+		intent: e.base.intent,
+		body: e.body,
+		privacy: {
+			tenantId: e.base.scope.tenantId,
+			subjectId: e.base.scope.ownerId,
+			kind: "guest"
+		},
+		close: e.close().pipe(r.orDie)
+	});
+})))), c = i.effectContext(r.acquireRelease(s, (e) => e.close).pipe(r.flatMap((e) => i.build(e.plugin.services)))), l = Object.freeze({
+	kind: "port",
+	tag: t,
+	fakeLayer: c,
+	probe: {
+		run: () => r.scoped(r.gen(function* () {
+			let n = yield* t, i = o.get(n);
+			if (!i) return yield* r.fail(e("unavailable"));
+			yield* i.plugin.economy.iap().redeem(i.base.user(), i.base.intent);
+			let a = yield* n.processor("ios"), s = yield* a.ingest({ body: i.body }), c = yield* a.ingest({ body: i.body });
+			return {
+				processed: s?.state === "processed",
+				replay: c !== null && s?.id === c.id,
+				providerCalls: i.reads(),
+				pending: (yield* a.pending()).length
+			};
+		}).pipe(r.provide(c))),
+		expected: {
+			processed: !0,
+			replay: !0,
+			providerCalls: 1,
+			pending: 0
+		}
+	}
+});
+//#endregion
+export { c as iapNotificationsSystemFakeLayer, s as iapNotificationsSystemPortFixture, l as iapNotificationsSystemPortSystemFixture };

package/dist/iapPlugin.testFixtures.js

@@ -0,0 +1,60 @@
+import { iapVerificationPort as e } from "./iapVerification.server.js";
+import { iapCompletionPort as t } from "./iapCompletion.server.js";
+import { economyPlugin as n } from "./plugin.js";
+import { iapStoreFixture as r } from "./iapStore.testFixtures.js";
+import { Effect as i } from "effect";
+//#region src/iapPlugin.testFixtures.ts
+var a = {
+	app: {
+		name: "iap-fixture",
+		type: "api",
+		voltroVersion: "0.83.1"
+	},
+	config: {},
+	env: {},
+	logger: {
+		info() {},
+		warn() {},
+		error() {},
+		debug() {}
+	}
+}, o = async (o, s, c = "test.tenant", l) => {
+	let u = await r(o, c), d = 0, f = 0, p = {
+		version: "iap.fixture.v1",
+		products: [u.definition],
+		namespace: u.options.namespace,
+		systemAccount: u.options.systemAccount,
+		admission: u.options.admission,
+		inventory: u.inventory,
+		providers: [{
+			channel: "ios",
+			environment: "sandbox",
+			applicationId: u.verificationOptions.applicationId,
+			create: (t) => e(t, {
+				initialize: () => (d++, s ? s() : i.void),
+				verify: () => (f++, i.succeed({
+					...u.facts,
+					transactionId: u.transactionId
+				}))
+			}),
+			...l ? { createCompletion: (e) => t(e, l) } : {}
+		}]
+	}, m = n({
+		currencies: u.currencies,
+		realMoney: !0,
+		now: () => u.at,
+		iap: p
+	});
+	return await m.bindDataStore?.(o), {
+		base: u,
+		plugin: m,
+		options: p,
+		store: o,
+		activate: () => m.onActivate(a),
+		close: i.suspend(() => m.onDeactivate(a)),
+		initializations: () => d,
+		verifications: () => f
+	};
+};
+//#endregion
+export { a as iapFixtureLifecycle, o as iapPluginFixture };

package/dist/iapPort.fixture.js

@@ -0,0 +1,75 @@
+import { IapPort as e, createIapReceiptReference as t } from "./iap.js";
+import { IapSystemPort as n } from "./iapBinding.server.js";
+import { EconomyPort as r } from "./port.js";
+import { iapTestFixture as i } from "./iap.testFixtures.js";
+import { iapPluginFixture as a } from "./iapPlugin.testFixtures.js";
+import { Effect as o, Layer as s, Result as c } from "effect";
+import { InMemoryDataStore as l } from "@voltro/runtime";
+//#region src/iapPort.fixture.ts
+var u = o.promise(() => a(new l(), void 0, "fixture", {
+	initialize: () => o.void,
+	complete: (e) => o.succeed({
+		orderId: e.orderId,
+		channel: "ios",
+		operation: "finish",
+		observedAt: e.at
+	})
+})).pipe(o.flatMap((e) => e.activate().pipe(o.as(e)))), d = s.effectContext(o.acquireRelease(u, (e) => e.close).pipe(o.flatMap((e) => s.build(e.plugin.services)))), f = Object.freeze({
+	kind: "port",
+	tag: e,
+	fakeLayer: d,
+	probe: {
+		run: () => o.scoped(o.gen(function* () {
+			let a = yield* e, s = yield* n, c = yield* r, l = i().intent, u = {
+				type: "user",
+				kind: "guest",
+				id: "test.player",
+				tenantId: "fixture"
+			}, d = yield* a.redeem(u, l), f = yield* a.redeem(u, l), p = yield* o.promise(() => t(l)), m = yield* a.receipt(u, p), h = yield* s.complete(u, l), g = yield* c.mine(u);
+			return {
+				original: d.orderId === f.orderId,
+				state: m.state,
+				completion: h.orderId === d.orderId,
+				balance: g[0]?.balance
+			};
+		}).pipe(o.provide(d))),
+		expected: {
+			original: !0,
+			state: "fulfilled",
+			completion: !0,
+			balance: "20"
+		}
+	}
+}), p = Object.freeze({
+	kind: "port",
+	tag: n,
+	fakeLayer: d,
+	probe: {
+		run: () => o.scoped(o.gen(function* () {
+			let e = yield* n, t = {
+				type: "user",
+				kind: "guest",
+				id: "fixture.account",
+				tenantId: "fixture"
+			}, r = yield* e.account(t, "ios"), i = yield* e.account(t, "ios");
+			yield* e.eraseSubject({
+				tenantId: t.tenantId,
+				subjectId: t.id,
+				kind: "guest"
+			});
+			let a = yield* e.account(t, "ios").pipe(o.result);
+			return {
+				stable: r === i,
+				publicUuid: /^[a-f0-9-]{36}$/.test(r),
+				erased: c.isFailure(a) && a.failure.code === "erased"
+			};
+		}).pipe(o.provide(d))),
+		expected: {
+			stable: !0,
+			publicUuid: !0,
+			erased: !0
+		}
+	}
+});
+//#endregion
+export { d as iapFakeLayer, u as iapPortFixture, f as iapPortSystemFixture, p as iapSystemPortSystemFixture };

package/dist/iapProviderCapture.server.js

@@ -0,0 +1,18 @@
+import { economyError as e } from "./errors.js";
+import { dataObject as t } from "./capture.js";
+import { iapTimestamp as n } from "./iap.js";
+//#region src/iapProviderCapture.server.ts
+var r = (n) => {
+	if (typeof n != "object" || !n || Array.isArray(n)) throw e("invalid_record");
+	let r = Object.keys(n);
+	if (r.length > 128) throw e("limit_exceeded");
+	return t(n, r, "invalid_record");
+}, i = (t, n = 512) => {
+	if (typeof t != "string" || t.length === 0 || t.length > n || /[\u0000-\u0020\u007f]/.test(t)) throw e("invalid_record");
+	return t;
+}, a = (t) => {
+	if (typeof t != "string" || t.length > 48 || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(t)) throw e("invalid_record");
+	return n(Date.parse(t));
+};
+//#endregion
+export { r as iapProviderRecord, i as iapProviderText, a as iapProviderTimestamp };

package/dist/iapRecovery.d.ts

@@ -0,0 +1,146 @@
+/** Caller supplies real browser storage/Web Locks. Missing capabilities refuse; no memory fallback. */
+export declare const browserIapPurchaseJournal: (storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, locks: Pick<LockManager, "request">) => IapPurchaseJournal;
+
+/** One shared acknowledged-intention/lock/scope algorithm; no automatic restore, redemption or finish. */
+export declare const createIapPurchaseRecovery: (journal: IapPurchaseJournal, sourceInput: IapReceiptRecoverySource, transportInput: IapPurchaseRecoveryTransport) => IapPurchaseRecovery;
+
+declare type EconomyChannel = 'web' | 'ios' | 'android' | 'steam';
+
+declare interface IapCompletionReceipt {
+    readonly orderId: string;
+    readonly channel: EconomyChannel;
+    readonly operation: 'acknowledge' | 'consume' | 'finalize' | 'finish';
+    readonly observedAt: number;
+}
+
+declare type IapOrderObservation = {
+    readonly requestId: string;
+    readonly state: 'not-observed' | 'pending';
+} | {
+    readonly requestId: string;
+    readonly state: 'fulfilled';
+    readonly receipt: IapOrderReceipt;
+    readonly refund?: IapRefundDisposition;
+} | {
+    readonly requestId: string;
+    readonly state: 'partially-refunded' | 'refunded';
+    readonly receipt: IapOrderReceipt;
+    readonly refund: IapRefundDisposition;
+};
+
+declare interface IapOrderReceipt {
+    readonly orderId: string;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly quantity: number;
+    readonly at: number;
+    readonly pricePaid: IapPaidAmount | null;
+    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;
+    }[];
+}
+
+/** Provider units retain their own decimal scale. Reference prices are never substituted. */
+declare interface IapPaidAmount {
+    readonly currency: string;
+    readonly units: string;
+    readonly scale: number;
+}
+
+/** Native implementations must provide actual durable acknowledgement and a cross-session/cross-client lock. */
+export declare type IapPurchaseJournal = IntentionJournal<IapReceiptReference>;
+
+export declare interface IapPurchaseRecovery {
+    readonly selectScope: (scope: string | undefined) => void;
+    readonly pending: () => Promise<IapPurchaseReference | undefined>;
+    /** Hash captured evidence and acknowledge its reference before any server mutation. */
+    readonly begin: (originalIntent: IapReceiptIntent) => Promise<IapPurchaseReference>;
+    /** Explicit retry of the stored reference; restore and match the actual evidence before any mutation. */
+    readonly retry: (originalReference: IapReceiptReference) => Promise<IapPurchaseSettlement>;
+    /** Fulfilled/refunded/partially-refunded alone is nonterminal for provider completion recovery. */
+    readonly observe: (observation: IapRecoveryObservation) => Promise<IapPurchaseReference | undefined>;
+}
+
+export declare interface IapPurchaseRecoveryTransport {
+    readonly read: (reference: IapReceiptReference) => Promise<IapOrderObservation>;
+    readonly redeem: (intent: IapReceiptIntent) => Promise<IapOrderReceipt>;
+    /** Explicit actual provider observation. For StoreKit, native transaction.finish after SQL acceptance. */
+    readonly complete: (intent: IapReceiptIntent, accepted: IapOrderReceipt) => Promise<IapCompletionReceipt>;
+}
+
+export declare type IapPurchaseReference = IntentionReference<IapReceiptReference>;
+
+export declare interface IapPurchaseSettlement {
+    readonly receipt: IapOrderReceipt;
+    readonly completion: IapCompletionReceipt;
+}
+
+declare interface IapReceiptIntent {
+    readonly channel: EconomyChannel;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly requestId: string;
+    /** Opaque store evidence. Never log or persist this in player receipts. */
+    readonly receipt: string;
+}
+
+export declare interface IapReceiptRecoverySource {
+    /** Restore the exact original from the actual store/secure authority. Never browser-journal plaintext. */
+    readonly restore: (reference: IapReceiptReference) => Promise<IapReceiptIntent>;
+}
+
+/** Read-only original-intention reference. Never send raw receipts in query parameters. */
+declare interface IapReceiptReference {
+    readonly channel: EconomyChannel;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly requestId: string;
+    readonly receiptDigest: string;
+}
+
+export declare type IapRecoveryObservation = IapOrderObservation | {
+    readonly requestId: string;
+    readonly state: 'completed';
+    readonly receipt: IapOrderReceipt;
+    readonly completion: IapCompletionReceipt;
+};
+
+/** Accepted SQL refund history only. This projection never authorizes a grant or completion. */
+declare interface IapRefundDisposition {
+    readonly sequence: number;
+    readonly state: 'active' | 'partially-refunded' | 'revoked';
+    readonly refundNumerator: number;
+    readonly refundDenominator: number;
+    readonly observedAt: number;
+}
+
+declare interface IntentionJournal<I> {
+    readonly withLocked: <A>(scope: string, work: (slot: IntentionSlot<I>) => Promise<A>) => Promise<A>;
+}
+
+/** Internal shared acknowledged-intention algorithm. Domain adapters own receipt authority. */
+declare interface IntentionReference<I> {
+    readonly version: 1;
+    readonly scope: string;
+    readonly request: I;
+}
+
+declare interface IntentionSlot<I> {
+    readonly read: () => IntentionReference<I> | undefined;
+    readonly write: (value: IntentionReference<I>) => void;
+    readonly clear: (value: IntentionReference<I>) => void;
+}
+
+export { }