@stewardhq/sdk 0.3.0 → 0.6.0

package/dist/_chunks/events.js

@@ -23,6 +23,31 @@ const EntitlementValueSchema = z.union([
 ]);
 const EntitlementsSchema = z.record(CodeSchema, EntitlementValueSchema);
 const MetadataSchema = z.record(z.string().max(64), z.string().max(500));
+/**
+* Why an invoice was written (Polar `billing_reason`): `subscription_create` first period,
+* `subscription_cycle` renewal (phase 2 adds overage lines to it), `subscription_update` plan
+* change, `purchase` reserved (one-off purchases are deferred), `manual` staff-written.
+*/
+const INVOICE_BILLING_REASONS = [
+	"subscription_create",
+	"subscription_cycle",
+	"subscription_update",
+	"purchase",
+	"manual"
+];
+const InvoiceBillingReasonSchema = z.enum(INVOICE_BILLING_REASONS);
+/**
+* Collection state of an invoice written before payment: `unpaid` (open, has `dueAt`), `paid`,
+* `uncollectible` (given up after dunning), `waived` (operator forgave it). Invoices written the
+* pre-billing-core way (after a payment, manual invoices) carry no payment status.
+*/
+const INVOICE_PAYMENT_STATUSES = [
+	"unpaid",
+	"paid",
+	"uncollectible",
+	"waived"
+];
+const InvoicePaymentStatusSchema = z.enum(INVOICE_PAYMENT_STATUSES);
 const ERROR_CATEGORIES = [
 	"validation",
 	"not_found",
@@ -46,6 +71,763 @@ const ErrorResponseSchema = z.object({
 	requestId: z.string().optional().catch(void 0)
 });
 //#endregion
+//#region ../contract/src/ingest.ts
+/** Most events in one ingest batch (M11). */
+const EVENTS_INGEST_MAX_EVENTS = 1e3;
+/** Largest ingest request body in bytes (M11; enforced on the route, not by the schema). */
+const EVENTS_INGEST_MAX_BYTES = 1048576;
+const EVENT_NAME_MAX_LENGTH = 128;
+const EVENT_METADATA_MAX_PAIRS = 50;
+const EVENT_METADATA_KEY_MAX_LENGTH = 40;
+const EVENT_METADATA_STRING_MAX_LENGTH = 500;
+/** How far back an event `timestamp` may lie, relative to its receipt (M18). */
+const EVENT_TIMESTAMP_MAX_AGE_DAYS = 35;
+/** How far ahead an event `timestamp` may lie, relative to its receipt (clock skew, M18). */
+const EVENT_TIMESTAMP_MAX_SKEW_MINUTES = 5;
+/** Whether a string contains C0 control characters or DEL (kept out of names and keys shown in logs and doctor). */
+function hasControlCharacters(value) {
+	for (let i = 0; i < value.length; i++) {
+		const c = value.charCodeAt(i);
+		if (c < 32 || c === 127) return true;
+	}
+	return false;
+}
+const noControlCharacters = (value) => !hasControlCharacters(value);
+/** Event name (free text, e.g. `ai.completion`); meters select events by it. */
+const EventNameSchema = z.string().min(1).max(128).refine(noControlCharacters, "no control characters");
+/** Product-chosen dedup key of an event, unique within the product (`cmpl_<id>`, `req_<id>`; M10). */
+const EventExternalIdSchema = z.string().regex(/^[A-Za-z0-9_.:-]{8,200}$/, "8–200 characters: letters, digits and _ . : -");
+/** Metadata key; a meter filter reads it as `metadata.<key>`. `__proto__` is reserved. */
+const EventMetadataKeySchema = z.string().min(1).max(40).refine(noControlCharacters, "no control characters").refine((key) => key !== "__proto__", "reserved key");
+const EventMetadataValueSchema = z.union([
+	z.string().max(500),
+	z.number(),
+	z.boolean()
+]);
+const EventMetadataSchema = z.record(EventMetadataKeySchema, EventMetadataValueSchema).refine((metadata) => Object.keys(metadata).length <= 50, `at most 50 metadata pairs`);
+/** One event the product sends (product → steward; not a webhook `BillingEvent`). */
+const IngestEventSchema = z.object({
+	/** The account's `externalRef`; the account must exist (`accounts.upsert` first, M12). */
+	accountRef: ExternalRefSchema,
+	name: EventNameSchema,
+	externalId: EventExternalIdSchema,
+	/** When it happened; default: when steward received it. Assigns the event to a meter period (M18). */
+	timestamp: DateTimeSchema.optional(),
+	metadata: EventMetadataSchema.optional()
+});
+/** `POST /v1/events/ingest` body. */
+const EventsIngestInputSchema = z.object({ events: z.array(IngestEventSchema).min(1).max(EVENTS_INGEST_MAX_EVENTS) });
+/** Per-event rejection codes this version knows (M12). The result schema accepts others too. */
+const INGEST_REJECT_CODES = [
+	"account_not_found",
+	"account_deleted",
+	"timestamp_out_of_range"
+];
+const IngestRejectCodeSchema = z.enum(INGEST_REJECT_CODES);
+/**
+* Rejection code in a result: a known `IngestRejectCode` or a code a newer steward added (open
+* set, so an older client never fails a whole ingest result on it).
+*/
+const RejectCodeReadSchema = z.string().min(1).max(100);
+const IngestRejectionSchema = z.object({
+	/** Position of the event in the request's `events`. */
+	index: z.number().int().nonnegative(),
+	externalId: z.string(),
+	code: RejectCodeReadSchema
+});
+/**
+* `POST /v1/events/ingest` result (200): `inserted` new events, `duplicates` already stored
+* (`externalId` seen before), `rejected` per event (sorted by `index`; the SDK does not retry them).
+*/
+const EventsIngestResultSchema = z.object({
+	inserted: z.number().int().nonnegative(),
+	duplicates: z.number().int().nonnegative(),
+	rejected: z.array(IngestRejectionSchema)
+});
+const DAY_MS = 864e5;
+const MINUTE_MS = 6e4;
+/**
+* Whether an event `timestamp` is accepted for an event received at `receivedAt` (M18):
+* [received − 35 days, received + 5 minutes], both ends inclusive. Outside: `timestamp_out_of_range`.
+*/
+function isEventTimestampInRange(timestamp, receivedAt) {
+	const at = timestamp.getTime();
+	const received = receivedAt.getTime();
+	if (Number.isNaN(at) || Number.isNaN(received)) return false;
+	return at >= received - 35 * DAY_MS && at <= received + 5 * MINUTE_MS;
+}
+//#endregion
+//#region ../contract/src/micro-units.ts
+/** Decimal places of a meter unit value (10⁻⁶). */
+const UNIT_DECIMALS = 6;
+/** Micro units in one unit. */
+const MICRO_UNITS_PER_UNIT = 1000000n;
+/** A unit value that is not a finite, non-negative decimal (M4 `invalid_value`). */
+var InvalidUnitValueError = class extends RangeError {
+	code = "invalid_value";
+	constructor(value) {
+		super(`invalid unit value: ${typeof value === "string" ? JSON.stringify(value.slice(0, 50)) : String(value)}`);
+		this.name = "InvalidUnitValueError";
+	}
+};
+/** Decimal text: optional minus, digits, optional fraction, optional exponent (`1e-7`, `1.5e+21`). */
+const DECIMAL_TEXT = /^(-)?(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+/** Longest decimal string accepted (a `numeric(30,6)` text is 32 characters). */
+const MAX_TEXT_LENGTH = 400;
+/** Exponents beyond this are outside the double range (a JS number never reaches them). */
+const MAX_EXPONENT = 400;
+function decimalParts(text) {
+	if (text.length > MAX_TEXT_LENGTH) return null;
+	const m = DECIMAL_TEXT.exec(text);
+	if (!m) return null;
+	const exponent = m[4] === void 0 ? 0 : Number(m[4]);
+	if (!Number.isSafeInteger(exponent) || Math.abs(exponent) > MAX_EXPONENT) return null;
+	const fraction = m[3] ?? "";
+	return {
+		negative: m[1] === "-",
+		digits: BigInt(`${m[2]}${fraction}`),
+		scale: fraction.length - exponent
+	};
+}
+function numberParts(value) {
+	return Number.isFinite(value) ? decimalParts(String(value)) : null;
+}
+const pow10 = (n) => 10n ** BigInt(n);
+/** `digits × 10^(6 - scale)`, rounded half up when digits are dropped. */
+function microOf(parts) {
+	const shift = 6 - parts.scale;
+	if (shift >= 0) return parts.digits * pow10(shift);
+	const divisor = pow10(-shift);
+	const quotient = parts.digits / divisor;
+	return 2n * (parts.digits % divisor) >= divisor ? quotient + 1n : quotient;
+}
+/**
+* Micro units (10⁻⁶) of a finite, non-negative decimal, or `null` when the value is not one.
+* A number is read from its canonical decimal text (`String(value)`); a string must be a plain
+* decimal (`"12"`, `"0.25"`, `"1e-7"`, Postgres `numeric` text). Beyond 6 decimals: half up.
+*/
+function parseMicroUnits(value) {
+	const parts = typeof value === "number" ? numberParts(value) : typeof value === "string" ? decimalParts(value) : null;
+	if (parts === null) return null;
+	if (parts.negative && parts.digits !== 0n) return null;
+	return microOf(parts);
+}
+/**
+* Micro units (10⁻⁶) of a finite, non-negative decimal: `toMicroUnits(0.25) === 250000n`,
+* `toMicroUnits("123.4567895") === 123456790n` (half up), `toMicroUnits(1e-7) === 0n`.
+* Throws `InvalidUnitValueError` (`code: "invalid_value"`) for a negative, non-finite or
+* non-decimal value.
+*/
+function toMicroUnits(value) {
+	const micro = parseMicroUnits(value);
+	if (micro === null) throw new InvalidUnitValueError(value);
+	return micro;
+}
+/**
+* Canonical decimal text of micro units: no exponent, no leading zeros, no trailing fraction zeros
+* (`1500000000n` → `"1500"`, `250000n` → `"0.25"`, `-1500000n` → `"-1.5"`). Invoice line `units`.
+*/
+function microToDecimalString(micro) {
+	const negative = micro < 0n;
+	const abs = negative ? -micro : micro;
+	const whole = (abs / MICRO_UNITS_PER_UNIT).toString();
+	const fraction = (abs % MICRO_UNITS_PER_UNIT).toString().padStart(6, "0").replace(/0+$/, "");
+	return `${negative ? "-" : ""}${whole}${fraction === "" ? "" : `.${fraction}`}`;
+}
+/**
+* Micro units as a JSON number (API responses): the double nearest to the exact decimal, so any
+* value up to 15 significant digits round-trips (`toMicroUnits(fromMicroUnits(x)) === x`).
+*/
+function fromMicroUnits(micro) {
+	return Number(microToDecimalString(micro));
+}
+/**
+* Plain decimal text of a finite number, without exponent: `1e21` → `"1000000000000000000000"`,
+* `1e-7` → `"0.0000001"`, `-0` → `"0"`. Throws for a non-finite number.
+*/
+function plainDecimalOf(value) {
+	const parts = numberParts(value);
+	if (parts === null) throw new InvalidUnitValueError(value);
+	if (parts.digits === 0n) return "0";
+	const sign = parts.negative ? "-" : "";
+	if (parts.scale <= 0) return `${sign}${(parts.digits * pow10(-parts.scale)).toString()}`;
+	const text = parts.digits.toString().padStart(parts.scale + 1, "0");
+	const whole = text.slice(0, text.length - parts.scale).replace(/^0+(?=\d)/, "");
+	const fraction = text.slice(text.length - parts.scale).replace(/0+$/, "");
+	return `${sign}${whole}${fraction === "" ? "" : `.${fraction}`}`;
+}
+/**
+* Whether a number is a finite value with at most 6 decimals, i.e. exactly representable in micro
+* units (catalog credits, credit grants and `lowAt` must be; event values are rounded instead).
+*/
+function isMicroPrecise(value) {
+	const parts = numberParts(value);
+	if (parts === null) return false;
+	if (parts.scale <= 6) return true;
+	return parts.digits % pow10(parts.scale - 6) === 0n;
+}
+//#endregion
+//#region ../contract/src/meters.ts
+const METER_FILTER_OPERATORS = [
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"like",
+	"not_like"
+];
+/** Deepest nesting of `and`/`or` groups. */
+const METER_FILTER_MAX_DEPTH = 3;
+/** Most conditions in one filter. */
+const METER_FILTER_MAX_CONDITIONS = 20;
+const METADATA_PREFIX = "metadata.";
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isOperator = (value) => METER_FILTER_OPERATORS.includes(value);
+function valueIssue(property, operator, value) {
+	const isName = property === "name";
+	if (isName && ![
+		"eq",
+		"ne",
+		"like",
+		"not_like"
+	].includes(operator)) return `operator ${operator} does not apply to name`;
+	switch (operator) {
+		case "eq":
+		case "ne":
+			if (isName) return typeof value === "string" && value.length <= 128 ? null : `name ${operator} needs a string of at most 128 characters`;
+			if (typeof value === "string") return value.length <= 500 ? null : `at most 500 characters`;
+			if (typeof value === "number") return Number.isFinite(value) ? null : "a finite number";
+			return typeof value === "boolean" ? null : `${operator} needs a string, number or boolean`;
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte": return typeof value === "number" && Number.isFinite(value) ? null : `${operator} needs a finite number`;
+		case "like":
+		case "not_like": return typeof value === "string" && value.length >= 1 && value.length <= 500 ? null : `${operator} needs a non-empty string of at most 500 characters`;
+	}
+}
+function propertyIssue(property) {
+	if (property === "name") return null;
+	if (!property.startsWith(METADATA_PREFIX)) return `unknown property ${JSON.stringify(property.slice(0, 50))}: use name or metadata.<key>`;
+	return EventMetadataKeySchema.safeParse(property.slice(9)).success ? null : `invalid metadata key in ${JSON.stringify(property.slice(0, 60))}`;
+}
+/**
+* The explicit form of a condition, or `null` when it is not a valid condition (the schema reports
+* why). `{name: "x"}` → `{property: "name", operator: "eq", value: "x"}`.
+*/
+function meterFilterClauseOf(condition) {
+	if (!isPlainObject(condition)) return null;
+	const keys = Object.keys(condition);
+	if (keys.length !== 1) return null;
+	const property = keys[0];
+	if (property === "and" || property === "or" || propertyIssue(property) !== null) return null;
+	const raw = condition[property];
+	let operator = "eq";
+	let value = raw;
+	if (isPlainObject(raw)) {
+		const ops = Object.keys(raw);
+		if (ops.length !== 1 || !isOperator(ops[0])) return null;
+		operator = ops[0];
+		value = raw[operator];
+	}
+	if (valueIssue(property, operator, value) !== null) return null;
+	return {
+		property,
+		operator,
+		value
+	};
+}
+/** Structural issues of a filter (empty when valid). */
+function meterFilterIssues(filter) {
+	const issues = [];
+	let conditions = 0;
+	let deepest = 0;
+	const visit = (node, path, depth) => {
+		if (!isPlainObject(node)) {
+			issues.push({
+				path,
+				message: "a filter is an object: a condition or an and/or group"
+			});
+			return;
+		}
+		const keys = Object.keys(node);
+		if (keys.includes("and") || keys.includes("or")) {
+			if (keys.length !== 1) {
+				issues.push({
+					path,
+					message: "a group has exactly one key: and or or"
+				});
+				return;
+			}
+			const key = keys[0];
+			const members = node[key];
+			deepest = Math.max(deepest, depth + 1);
+			if (!Array.isArray(members) || members.length === 0) {
+				issues.push({
+					path: [...path, key],
+					message: `${key} needs a non-empty array of filters`
+				});
+				return;
+			}
+			if (depth + 1 > 3) return;
+			for (const [i, member] of members.entries()) visit(member, [
+				...path,
+				key,
+				i
+			], depth + 1);
+			return;
+		}
+		conditions += 1;
+		if (keys.length !== 1) {
+			issues.push({
+				path,
+				message: "a condition has exactly one property (combine conditions with and)"
+			});
+			return;
+		}
+		const property = keys[0];
+		const problem = propertyIssue(property);
+		if (problem !== null) {
+			issues.push({
+				path: [...path, property],
+				message: problem
+			});
+			return;
+		}
+		const raw = node[property];
+		if (isPlainObject(raw)) {
+			const ops = Object.keys(raw);
+			if (ops.length !== 1 || !isOperator(ops[0])) {
+				issues.push({
+					path: [...path, property],
+					message: `exactly one operator of ${METER_FILTER_OPERATORS.join(", ")}`
+				});
+				return;
+			}
+			const issue = valueIssue(property, ops[0], raw[ops[0]]);
+			if (issue !== null) issues.push({
+				path: [
+					...path,
+					property,
+					ops[0]
+				],
+				message: issue
+			});
+			return;
+		}
+		const issue = valueIssue(property, "eq", raw);
+		if (issue !== null) issues.push({
+			path: [...path, property],
+			message: issue
+		});
+	};
+	visit(filter, [], 0);
+	if (deepest > 3) issues.push({
+		path: [],
+		message: `and/or groups nest at most 3 deep`
+	});
+	if (conditions > 20) issues.push({
+		path: [],
+		message: `at most 20 conditions`
+	});
+	return issues;
+}
+/** Meter filter (see the syntax above). Validates structure; the value is kept as given. */
+const MeterFilterSchema = z.custom().superRefine((value, ctx) => {
+	for (const issue of meterFilterIssues(value)) ctx.addIssue({
+		code: "custom",
+		path: issue.path,
+		message: issue.message
+	});
+});
+/**
+* Canonical form of a valid filter: every condition explicit (`{name: "x"}` → `{name: {eq: "x"}}`),
+* a fresh object. Two filters that differ only by the shorthand have the same canonical JSON
+* (the lock check, M4, compares canonical filters). Throws on an invalid filter.
+*/
+function canonicalMeterFilter(filter) {
+	if ("and" in filter && Array.isArray(filter.and)) return { and: filter.and.map(canonicalMeterFilter) };
+	if ("or" in filter && Array.isArray(filter.or)) return { or: filter.or.map(canonicalMeterFilter) };
+	const clause = meterFilterClauseOf(filter);
+	if (clause === null) throw new Error("invalid meter filter condition");
+	return { [clause.property]: { [clause.operator]: clause.value } };
+}
+/**
+* What a meter computes over its matching events in a period (M4; no `min`/`avg`):
+* `count` events; `sum` / `max` of the finite, non-negative number at `metadata.<key>` (decimals
+* allowed); `unique` count of distinct values at `metadata.<key>`. An event without a usable
+* value adds nothing to that meter (`invalid_value`, shown by doctor).
+*/
+const METER_AGGREGATION_KINDS = [
+	"count",
+	"sum",
+	"max",
+	"unique"
+];
+const MeterAggregationSchema = z.discriminatedUnion("kind", [
+	z.object({ kind: z.literal("count") }),
+	z.object({
+		kind: z.literal("sum"),
+		key: EventMetadataKeySchema
+	}),
+	z.object({
+		kind: z.literal("max"),
+		key: EventMetadataKeySchema
+	}),
+	z.object({
+		kind: z.literal("unique"),
+		key: EventMetadataKeySchema
+	})
+]);
+/** Largest unit amount in a definition (credit, rollover cap, credit grant): exact as a JSON number. */
+const MAX_METER_UNITS = 0x38d7ea4c68000;
+/** Default `lowAt` (M14): standing becomes `low` at 80% of the credit. */
+const DEFAULT_METER_LOW_AT = .8;
+const microPrecise = (value) => isMicroPrecise(value);
+/** A positive unit amount in a definition: at most 6 decimals (M4), at most `MAX_METER_UNITS`. */
+const MeterUnitsSchema = z.number().positive().max(MAX_METER_UNITS).refine(microPrecise, "at most 6 decimal places");
+const LabelTextSchema = z.string().trim().min(1).max(100).refine((value) => !hasControlCharacters(value), "no control characters");
+/** Customer-facing text per locale (hosted checkout and portal). Both locales are required. */
+const MeterLabelSchema = z.object({
+	tr: LabelTextSchema,
+	en: LabelTextSchema
+});
+/** Share of the credit at which standing becomes `low`: 0 < x ≤ 1, at most 6 decimals. */
+const MeterLowAtSchema = z.number().gt(0).lte(1).refine(microPrecise, "at most 6 decimal places");
+const MeterDefFieldsSchema = z.object({
+	/** Shorthand: only events with this name (`filter` `{name: {eq: event}}`); with `filter`, both must hold. */
+	event: EventNameSchema.optional(),
+	filter: MeterFilterSchema.optional(),
+	aggregation: MeterAggregationSchema,
+	label: MeterLabelSchema,
+	/** Unit name, e.g. `{tr: "token", en: "tokens"}`. */
+	unitLabel: MeterLabelSchema.optional(),
+	/** Display divisor on hosted pages, e.g. 1000 → "12.5K tokens" (display only). */
+	displayPer: z.number().int().min(1).max(1e9).optional(),
+	/** Standing `low` threshold (M14); default 0.8; `null` disables `low`. */
+	lowAt: MeterLowAtSchema.nullable().default(DEFAULT_METER_LOW_AT)
+});
+function combinedFilter(event, filter) {
+	const byName = { name: { eq: event ?? "" } };
+	if (filter === void 0) return byName;
+	const canonical = canonicalMeterFilter(filter);
+	if (event === void 0) return canonical;
+	return "and" in canonical && Array.isArray(canonical.and) ? { and: [byName, ...canonical.and] } : { and: [byName, canonical] };
+}
+/**
+* Meter definition (catalog sync input; the record key is the meter code). Input takes `event`
+* and/or `filter`; the output has only `filter`, canonical, `event` folded in (`{and: [{name:
+* {eq: event}}, …filter]}`). Filter and aggregation lock once the meter's first period opened
+* (`422 meter_locked`; M4): a change means a new code.
+*/
+const MeterDefSchema = MeterDefFieldsSchema.superRefine((def, ctx) => {
+	if (def.event === void 0 && def.filter === void 0) {
+		ctx.addIssue({
+			code: "custom",
+			path: ["filter"],
+			message: "event or filter is required"
+		});
+		return;
+	}
+	if (def.event !== void 0 && def.filter !== void 0 && meterFilterIssues(def.filter).length === 0) for (const issue of meterFilterIssues(combinedFilter(def.event, def.filter))) ctx.addIssue({
+		code: "custom",
+		path: ["filter", ...issue.path],
+		message: `with event: ${issue.message}`
+	});
+}).transform(({ event, filter, ...rest }) => ({
+	filter: combinedFilter(event, filter),
+	...rest
+}));
+/**
+* A meter as returned by `GET /v1/catalog` (active meters). Lenient for forward compatibility: a
+* newer steward may use filter or aggregation forms this version does not define; narrow `filter`
+* with `MeterFilterSchema` and `aggregation` with `MeterAggregationSchema`.
+*/
+const CatalogMeterSchema = z.object({
+	filter: z.unknown(),
+	aggregation: z.looseObject({
+		kind: z.string().min(1).max(64),
+		key: z.string().optional()
+	}),
+	label: MeterLabelSchema,
+	unitLabel: MeterLabelSchema.optional(),
+	displayPer: z.number().int().positive().optional(),
+	lowAt: z.number().nullable()
+});
+/**
+* `meter_credit` benefit properties (M5, M6): `units` granted at the start of every meter period
+* (plan + add-ons for the same meter add up; the default plan's credit only when no other layer
+* credits the meter — `meterCreditsOf`); `rolloverCapUnits` turns rollover on — the unused
+* balance carries over up to the cap (absent: unused credit expires; debt never carries).
+*/
+const MeterCreditPropertiesSchema = z.object({
+	meter: CodeSchema,
+	units: MeterUnitsSchema,
+	rolloverCapUnits: MeterUnitsSchema.optional()
+});
+/** Largest `perUnits` of a metered price. */
+const MAX_METERED_PRICE_PER_UNITS = 0xe8d4a51000;
+/**
+* Metered price (catalog sync input; MF5, M20): overage above the credit is billed
+* `amountMinor` per `perUnits` units ("₺12,50 / 1.000 token" = `{amountMinor: 1250, perUnits:
+* 1000}`; an integer pair, no decimal unit price). Key `(planCode, meter, currency)`. Tax terms
+* must equal the plan's base prices in that currency (`metered_price_tax_mismatch`). `capMinor`
+* caps the overage amount per meter period. Mutable in place like base prices (M36); a
+* subscription locks the rate it started with.
+*/
+const MeteredPriceDefSchema = z.object({
+	planCode: CodeSchema,
+	meter: CodeSchema,
+	currency: CurrencySchema,
+	amountMinor: AmountMinorSchema,
+	perUnits: z.number().int().min(1).max(MAX_METERED_PRICE_PER_UNITS),
+	/** Same meaning as `PriceDef.taxInclusive`; must equal the plan's base price. */
+	taxInclusive: z.boolean(),
+	/** Basis points (20% = 2000); must equal the plan's base price. */
+	taxRateBps: z.number().int().min(0).max(1e4),
+	capMinor: AmountMinorSchema.optional()
+});
+/** Metered price as returned by `GET /v1/catalog` (active ones). */
+const MeteredPriceSchema = MeteredPriceDefSchema.extend({
+	id: IdSchema,
+	active: z.boolean(),
+	capMinor: AmountMinorSchema.nullable().optional(),
+	createdAt: DateTimeSchema
+});
+/**
+* Credit standing of a meter in its period (M14): `low` once consumption reaches `lowAt` × credit,
+* `exhausted` once the balance is ≤ 0; a meter without credit is always `ok`. Standing describes
+* the credit only: a billable meter (metered price) keeps working past `exhausted` (M15).
+*/
+const METER_STANDINGS = [
+	"ok",
+	"low",
+	"exhausted"
+];
+const MeterStandingSchema = z.enum(METER_STANDINGS);
+/** Units in a response: a JSON number with at most 6 decimals (`fromMicroUnits`). */
+const UnitsNumberSchema = z.number();
+const NonNegativeUnitsNumberSchema = z.number().nonnegative();
+/**
+* Units as a decimal string (invoice lines, meter charges): non-negative, at most 6 decimals.
+* Steward writes the canonical form (`microToDecimalString`: no exponent, no trailing zeros).
+*/
+const DecimalUnitsStringSchema = z.string().regex(/^\d{1,24}(\.\d{1,6})?$/, "non-negative decimal with at most 6 decimals");
+/** One meter of `GET /v1/accounts/:ref/meters`: the meter's OPEN period (periods are per meter, M7). */
+const AccountMeterSchema = z.object({
+	periodStart: DateTimeSchema,
+	periodEnd: DateTimeSchema,
+	/**
+	* Units the account's `meter_credit` benefits grant per period (`meterCreditsOf`); `null` when
+	* none does — such a meter is not gated by credit (M15).
+	*/
+	includedUnits: NonNegativeUnitsNumberSchema.nullable(),
+	consumedUnits: NonNegativeUnitsNumberSchema,
+	/** Credit of the period: cycle grants, rollover, plan-change top-ups, manual grants. */
+	creditedUnits: NonNegativeUnitsNumberSchema,
+	/** `creditedUnits − consumedUnits`; negative past the credit. */
+	balance: UnitsNumberSchema,
+	/** `max(0, consumedUnits − creditedUnits)`. */
+	overageUnits: NonNegativeUnitsNumberSchema,
+	standing: MeterStandingSchema,
+	/** A live subscription has a metered rate for this meter: overage is billed, the gate stays open (M15) until `capReached`. */
+	billable: z.boolean(),
+	/** Estimated overage amount of the open period (billable meters); otherwise null. */
+	amountDueMinor: AmountMinorSchema.nullable(),
+	currency: CurrencySchema.nullable(),
+	/**
+	* The period's priced overage reached the locked rate's `capMinor` (`overageCapReached`): further
+	* use is not billed, so the gate closes (M15). False when not billable or the rate has no cap.
+	* Absent from an older steward (read as false).
+	*/
+	capReached: z.boolean().optional()
+});
+/**
+* `GET /v1/accounts/:ref/meters` (M13): a meter READ, not a second state model — no version, no
+* events. ETag = the account's `meters_seq` (rollup and credit writes); `If-None-Match` → 304.
+* `rolledUpThrough`: events received before this moment are counted.
+*/
+const AccountMetersSchema = z.object({
+	ref: ExternalRefSchema,
+	asOf: DateTimeSchema,
+	rolledUpThrough: DateTimeSchema,
+	meters: z.record(CodeSchema, AccountMeterSchema)
+});
+const METER_PERIOD_STATUSES = [
+	"open",
+	"closing",
+	"closed"
+];
+const MeterPeriodStatusSchema = z.enum(METER_PERIOD_STATUSES);
+/** A meter period (`GET /v1/accounts/:ref/meters/periods`; closed periods, newest first). */
+const MeterPeriodSchema = z.object({
+	meter: CodeSchema,
+	periodStart: DateTimeSchema,
+	periodEnd: DateTimeSchema,
+	status: MeterPeriodStatusSchema,
+	/** Subscription the period is anchored to (M7); null for the account anchor. */
+	subscriptionId: IdSchema.nullable(),
+	consumedUnits: NonNegativeUnitsNumberSchema,
+	creditedUnits: NonNegativeUnitsNumberSchema,
+	overageUnits: NonNegativeUnitsNumberSchema,
+	closedAt: DateTimeSchema.nullable()
+});
+const MeterPeriodListSchema = z.object({
+	ref: ExternalRefSchema,
+	periods: z.array(MeterPeriodSchema)
+});
+/**
+* `POST /v1/accounts/:ref/credits` (M5): a one-off credit for the meter's open period (goodwill,
+* campaign). Needs no benefit; recorded in the append-only credit ledger with the actor.
+* Unknown meter: `422 meter_not_found`.
+*/
+const CreditGrantInputSchema = z.object({
+	meter: CodeSchema,
+	units: MeterUnitsSchema,
+	reason: z.string().trim().min(3).max(500)
+});
+/** Credit ledger entry kinds (M5). Entries are never rewritten. */
+const METER_CREDIT_ENTRY_KINDS = [
+	"cycle_grant",
+	"rollover",
+	"plan_change",
+	"manual_grant",
+	"adjustment"
+];
+const MeterCreditEntryKindSchema = z.enum(METER_CREDIT_ENTRY_KINDS);
+const MeterCreditEntrySchema = z.object({
+	id: IdSchema,
+	meter: CodeSchema,
+	kind: MeterCreditEntryKindSchema,
+	/** Signed units (an adjustment may be negative). */
+	units: UnitsNumberSchema,
+	periodStart: DateTimeSchema,
+	reason: z.string().nullable(),
+	actorRef: z.string().nullable(),
+	createdAt: DateTimeSchema
+});
+const METER_CHARGE_STATUSES = [
+	"dry_run",
+	"carried",
+	"invoiced"
+];
+const MeterChargeStatusSchema = z.enum(METER_CHARGE_STATUSES);
+/** One priced meter of a charge (M21): overage × locked rate, capped. Units are decimal strings. */
+const MeterChargeLineSchema = z.object({
+	meter: CodeSchema,
+	consumedUnits: DecimalUnitsStringSchema,
+	creditedUnits: DecimalUnitsStringSchema,
+	overageUnits: DecimalUnitsStringSchema,
+	priceAmountMinor: AmountMinorSchema,
+	pricePerUnits: z.number().int().min(1),
+	capMinor: AmountMinorSchema.nullable(),
+	/** `rateOverage(...)`: tax terms of the price (gross when tax-inclusive). */
+	amountMinor: AmountMinorSchema
+});
+/**
+* Pricing record of a closed meter period (M21; money data, never rewritten). Totals use the
+* invoice rule (`meterChargeTotals`, one rounding). `status`: `dry_run` (chargeMode `dry_run`:
+* recorded, not invoiced), `carried` (below `billing.minInvoiceMinor` on an overage-only invoice:
+* carried into the next invoice), `invoiced` (`invoiceId` set). `carriedInMinor`: earlier carried
+* amounts included here.
+*/
+const MeterChargeSchema = z.object({
+	id: IdSchema,
+	subscriptionId: IdSchema.nullable(),
+	periodStart: DateTimeSchema,
+	periodEnd: DateTimeSchema,
+	currency: CurrencySchema,
+	taxInclusive: z.boolean(),
+	taxRateBps: z.number().int().min(0).max(1e4),
+	lines: z.array(MeterChargeLineSchema),
+	subtotalMinor: AmountMinorSchema,
+	taxMinor: AmountMinorSchema,
+	totalMinor: AmountMinorSchema,
+	carriedInMinor: AmountMinorSchema,
+	status: MeterChargeStatusSchema,
+	invoiceId: IdSchema.nullable(),
+	createdAt: DateTimeSchema
+});
+/** `GET /v1/accounts/:ref/meter-charges` (newest first). */
+const MeterChargeListSchema = z.object({
+	ref: ExternalRefSchema,
+	charges: z.array(MeterChargeSchema)
+});
+//#endregion
+//#region ../contract/src/benefits.ts
+/** Benefit types this contract version defines. */
+const BENEFIT_TYPES = ["feature_flag", "meter_credit"];
+const BenefitTypeSchema = z.enum(BENEFIT_TYPES);
+const DescriptionTextSchema = z.string().trim().min(1).max(500);
+/** Customer-facing description per locale (hosted checkout and portal "what's included"). */
+const BenefitDescriptionSchema = z.object({
+	tr: DescriptionTextSchema.optional(),
+	en: DescriptionTextSchema.optional()
+});
+/** `feature_flag` properties: catalog feature key → value (K4 typing; checked against `features` on catalog sync). */
+const FeatureFlagPropertiesSchema = z.record(CodeSchema, EntitlementValueSchema);
+const FeatureFlagBenefitDefSchema = z.object({
+	type: z.literal("feature_flag"),
+	properties: FeatureFlagPropertiesSchema,
+	description: BenefitDescriptionSchema.optional()
+});
+/** `meter_credit` definition (metering phase 2): the meter must be a catalog meter (checked on catalog sync). */
+const MeterCreditBenefitDefSchema = z.object({
+	type: z.literal("meter_credit"),
+	properties: MeterCreditPropertiesSchema,
+	description: BenefitDescriptionSchema.optional()
+});
+/** Catalog benefit definition (catalog sync input), discriminated by `type`. */
+const BenefitDefSchema = z.discriminatedUnion("type", [FeatureFlagBenefitDefSchema, MeterCreditBenefitDefSchema]);
+/**
+* Benefit definition as returned by `GET /v1/catalog`. `type` is an open set (a newer steward may
+* return types this version does not define); narrow with `type === "feature_flag"`.
+*/
+const CatalogBenefitSchema = z.object({
+	type: z.string().min(1).max(64),
+	properties: z.record(z.string(), z.unknown()),
+	description: BenefitDescriptionSchema.optional()
+});
+/**
+* Where a granted benefit comes from, e.g. `plan:<code>` (default plan or a live subscription's
+* plan), `grant:<id>` (a grant), `override` (account overrides). Open set: informational.
+*/
+const BenefitSourceSchema = z.string().min(1).max(200);
+/**
+* A benefit granted to the account (`AccountState.benefits[]`; Polar granted benefit).
+* `code` is the catalog benefit code; `null` for an implicit benefit that has no catalog code
+* (a plan's entitlement matrix, account overrides). `type` is an open set (see
+* `CatalogBenefitSchema`); `properties` are the values granted.
+*/
+const AccountBenefitSchema = z.object({
+	code: CodeSchema.nullable(),
+	type: z.string().min(1).max(64),
+	properties: z.record(z.string(), z.unknown()),
+	source: BenefitSourceSchema,
+	grantedAt: DateTimeSchema
+});
+/** Narrows a granted benefit to `feature_flag` (type and property values checked). */
+function isFeatureFlagBenefit(benefit) {
+	return benefit.type === "feature_flag" && FeatureFlagPropertiesSchema.safeParse(benefit.properties).success;
+}
+/** Narrows a granted benefit to `meter_credit` (type and properties checked). */
+function isMeterCreditBenefit(benefit) {
+	return benefit.type === "meter_credit" && MeterCreditPropertiesSchema.safeParse(benefit.properties).success;
+}
+/**
+* Whether a value fits a feature type (K4): `limit` → integer ≥ 0 or `null` (unlimited),
+* `boolean` → boolean, `string` → string. `null` is only valid for `limit`.
+*/
+function featureValueMatchesType(type, value) {
+	switch (type) {
+		case "limit": return value === null || typeof value === "number" && Number.isInteger(value) && value >= 0;
+		case "boolean": return typeof value === "boolean";
+		case "string": return typeof value === "string";
+	}
+}
+//#endregion
 //#region ../contract/src/emails.ts
 const EMAIL_TEMPLATES = [
 	"subscription_started",
@@ -55,10 +837,97 @@ const EMAIL_TEMPLATES = [
 	"subscription_ended",
 	"access_suspended",
 	"subscription_terminated",
-	"invoice_issued"
+	"invoice_issued",
+	"invoice_payment_due",
+	"price_change_notice",
+	"bank_transfer_instructions"
 ];
 const EmailTemplateSchema = z.enum(EMAIL_TEMPLATES);
-/** Which event triggers which template. Events not listed send no email. */
+/** `invoice_payment_due`: summary of an unpaid invoice, its due date and the hosted pay page link. */
+const InvoicePaymentDueEmailSchema = z.object({
+	invoiceId: IdSchema,
+	/** Invoice number once issued; drafts have none. */
+	number: z.string().nullable(),
+	billingReason: InvoiceBillingReasonSchema,
+	planName: z.string().nullable(),
+	totalMinor: AmountMinorSchema,
+	currency: CurrencySchema,
+	periodStart: DateTimeSchema.nullable(),
+	periodEnd: DateTimeSchema.nullable(),
+	dueAt: DateTimeSchema,
+	/** Steward's hosted pay page for this invoice. */
+	payUrl: z.url({ protocol: /^https?$/ }),
+	/** false: the invoice was just written; true: a reminder before the due date. */
+	reminder: z.boolean()
+});
+/** A metered (overage) rate as a notice shows it: `amountMinor` per `perUnits` units, at most `capMinor` per usage period. */
+const NoticedMeteredRateSchema = z.object({
+	amountMinor: AmountMinorSchema,
+	perUnits: z.number().int().positive(),
+	capMinor: AmountMinorSchema.nullable()
+});
+/**
+* One meter whose overage rate changes with the move to the current terms (metering M20, M36): the
+* subscription's locked rate and the plan's current one, in the notice's currency and tax terms.
+* The meter's labels as they were when the notice was written (the e-mail is never recomputed).
+*/
+const PriceChangeNoticeMeteredRateSchema = z.object({
+	meter: CodeSchema,
+	label: MeterLabelSchema,
+	unitLabel: MeterLabelSchema.nullable(),
+	/** The meter's `displayPer` (price lines are shown per that many units); null: per the rate's `perUnits`. */
+	displayPer: z.number().int().positive().nullable(),
+	/** The locked rate; null: the meter is not billed yet (a metered price added to the plan later). */
+	oldRate: NoticedMeteredRateSchema.nullable(),
+	/** The current rate; null: the meter is no longer billed. */
+	newRate: NoticedMeteredRateSchema.nullable()
+});
+/**
+* `price_change_notice`: a subscription moves to the current terms of its plan from `effectiveAt` —
+* its per-period amount and/or its metered rates (`meteredRates`: only the meters whose rate
+* changes; absent when none does). Old and new amount are equal when only metered rates change.
+*/
+const PriceChangeNoticeEmailSchema = z.object({
+	subscriptionId: IdSchema,
+	planCode: CodeSchema,
+	planName: z.string(),
+	interval: IntervalSchema,
+	currency: CurrencySchema,
+	oldAmountMinor: AmountMinorSchema,
+	newAmountMinor: AmountMinorSchema,
+	/** Both amounts are VAT inclusive (true) or exclusive (false), as the price. */
+	taxInclusive: z.boolean(),
+	effectiveAt: DateTimeSchema,
+	meteredRates: z.array(PriceChangeNoticeMeteredRateSchema).optional()
+});
+/**
+* `bank_transfer_instructions` (bank transfer plan H12): how to pay a checkout by bank transfer —
+* the deployment's bank account for the currency, the exact amount, the account's order code to
+* write in the description and the deadline. `reminder`: sent the day before the deadline.
+*/
+const BankTransferInstructionsEmailSchema = z.object({
+	checkoutSessionId: IdSchema,
+	planName: z.string(),
+	totalMinor: AmountMinorSchema,
+	currency: CurrencySchema,
+	beneficiary: z.string(),
+	bank: z.string().nullable(),
+	iban: z.string(),
+	/** The account's order code (`XXXX-XXXX-X`). */
+	code: z.string(),
+	deadline: DateTimeSchema,
+	reminder: z.boolean()
+});
+/** Payload schema per billing core template. */
+const EMAIL_PAYLOAD_SCHEMAS = Object.freeze({
+	bank_transfer_instructions: BankTransferInstructionsEmailSchema,
+	invoice_payment_due: InvoicePaymentDueEmailSchema,
+	price_change_notice: PriceChangeNoticeEmailSchema
+});
+/**
+* Which event triggers which template. Events not listed send no email. The billing core
+* templates (`invoice_payment_due`, `price_change_notice`) are not triggered by an event type alone.
+*/
 const EMAIL_TEMPLATE_BY_EVENT = Object.freeze({
 	"subscription.activated": "subscription_started",
 	"subscription.renewed": "payment_receipt",
@@ -183,21 +1052,35 @@ function billingPageUrl(appUrl, billingPath, locale, accountRef) {
 	}
 }
 /**
+* The event's subscription among the account's live subscriptions at send time, or null when it
+* is not live. Looked up by id in `subscriptions` (billing core, M34: any live subscription, not
+* only the primary one); a state without that list (older steward) has only the primary
+* `subscription`.
+*/
+function liveSubscriptionOf(state, subscriptionId) {
+	if (subscriptionId === null) return null;
+	if (state.subscriptions !== void 0) return state.subscriptions.find((s) => s.id === subscriptionId) ?? null;
+	return state.subscription?.id === subscriptionId ? state.subscription : null;
+}
+/**
 * Whether the email still describes the account at send time. Receipts, the welcome email
 * (legal confirmation) and the final termination notice always go; the others only while
-* the situation they describe still holds.
+* the situation they describe still holds for the event's subscription (which need not be the
+* primary one when the account has several).
 */
 function isEmailRelevant(template, facts) {
-	const live = facts.state.subscription;
-	const same = live !== null && live.id === facts.subscriptionId;
+	const sub = liveSubscriptionOf(facts.state, facts.subscriptionId);
 	switch (template) {
 		case "subscription_started":
 		case "payment_receipt":
-		case "subscription_terminated": return true;
-		case "payment_failed": return same && live.status === "past_due";
-		case "cancel_scheduled": return same && live.cancelAtPeriodEnd;
-		case "subscription_ended": return live === null;
-		case "access_suspended": return same && live.status === "suspended";
+		case "subscription_terminated":
+		case "price_change_notice": return true;
+		case "invoice_payment_due": return facts.invoicePaymentStatus === "unpaid";
+		case "bank_transfer_instructions": return facts.transferPending === true;
+		case "payment_failed": return sub?.status === "past_due";
+		case "cancel_scheduled": return sub?.cancelAtPeriodEnd === true;
+		case "subscription_ended": return facts.state.subscriptions !== void 0 ? sub === null : facts.state.subscription === null;
+		case "access_suspended": return sub?.status === "suspended";
 		case "invoice_issued": return facts.invoiceStatus === "issued";
 	}
 }
@@ -256,6 +1139,10 @@ const SubscriptionSummarySchema = z.object({
 	status: SubscriptionStatusSchema,
 	planCode: CodeSchema,
 	interval: IntervalSchema,
+	/**
+	* Amount the subscription pays per period. Billing core (M36): the subscription's LOCKED amount
+	* (copied when it started); a later in-place price change does not alter it.
+	*/
 	amountMinor: AmountMinorSchema,
 	currency: CurrencySchema,
 	currentPeriodEnd: DateTimeSchema.nullable(),
@@ -275,11 +1162,16 @@ const AccountDunningStateSchema = z.object({
 	/** Sıradaki dunning aksiyonunun zamanı; kalmadıysa null. */
 	nextActionAt: DateTimeSchema.nullable()
 });
-/** Dönem sonunda uygulanacak plan değişikliği. F4b'ye kadar her zaman null. */
+/**
+* Change applied at the period end (`POST /v1/subscriptions/:id/change`, MF9). Null until then.
+* `price: "current"` on the same plan shows the same `planCode`/`interval` with the new `amountMinor`.
+*/
 const AccountScheduledChangeSchema = z.object({
 	planCode: CodeSchema,
 	interval: IntervalSchema,
-	effectiveAt: DateTimeSchema
+	effectiveAt: DateTimeSchema,
+	/** Amount locked from `effectiveAt` (billing core; absent from older steward). */
+	amountMinor: AmountMinorSchema.optional()
 });
 const AccountSubscriptionStateSchema = SubscriptionSummarySchema.extend({
 	cancelAtPeriodEnd: z.boolean(),
@@ -288,7 +1180,10 @@ const AccountSubscriptionStateSchema = SubscriptionSummarySchema.extend({
 	currentPeriodStart: DateTimeSchema.nullable(),
 	/** Abonelik dunning'de değilse null. */
 	dunning: AccountDunningStateSchema.nullable(),
-	/** F4b (`POST /v1/subscriptions/:id/change`) gelene kadar her zaman null. */
+	/**
+	* The pending plan/interval/price change (billing core MF9: `POST /v1/subscriptions/:id/change`,
+	* the portal's Change plan, the operator's `reprice-subscriptions`); null when none.
+	*/
 	scheduledChange: AccountScheduledChangeSchema.nullable()
 });
 /** Hesabın açık (tamamlanmamış, süresi dolmamış) checkout oturumu. */
@@ -299,8 +1194,46 @@ const AccountOpenCheckoutSchema = z.object({
 	intervalCount: z.number().int().min(1),
 	currency: CurrencySchema,
 	amountMinor: AmountMinorSchema,
-	expiresAt: DateTimeSchema
+	expiresAt: DateTimeSchema,
+	/**
+	* Bank transfer plan (H6): `bank_transfer` when the session waits for the customer's transfer
+	* until `expiresAt` (the product shows "payment pending" with `AccountState.bankTransferCode`).
+	* Absent otherwise (a card checkout's state is unchanged).
+	*/
+	paymentMethod: z.enum(["card", "bank_transfer"]).optional()
+});
+/**
+* An unpaid invoice of the account (billing core, M22/M34): renewal or final invoices written
+* before payment. Account level (not under a subscription) so the final invoice of an ended
+* subscription stays visible; the product can show a banner before `dueAt`.
+*/
+const AccountOpenInvoiceSchema = z.object({
+	id: IdSchema,
+	/** Null for an invoice not tied to a subscription. */
+	subscriptionId: IdSchema.nullable(),
+	billingReason: InvoiceBillingReasonSchema,
+	totalMinor: AmountMinorSchema,
+	currency: CurrencySchema,
+	dueAt: DateTimeSchema
 });
+/**
+* Low-churn meter facts of the account state (metering, M13; Polar `active_meters`, coarse). One
+* entry per catalog meter. Balances and period bounds are NOT here (they change with every event;
+* read them with `GET /v1/accounts/:ref/meters`): this block changes when the plan changes, a
+* threshold is crossed or a new period resets the standing — never per event.
+*/
+const AccountMeterStateSchema = z.object({
+	/**
+	* Units the account's `meter_credit` benefits grant per period (`meterCreditsOf`: benefits sum;
+	* the default plan's credit only when no other layer credits the meter); `null`: no credit (not
+	* gated by credit, M15).
+	*/
+	includedUnits: z.number().nonnegative().nullable(),
+	/** A live subscription bills overage of this meter (metered rate): the gate stays open (M15) until the rate's cap is reached. */
+	billable: z.boolean(),
+	standing: MeterStandingSchema
+});
+const AccountMetersStateSchema = z.record(CodeSchema, AccountMeterStateSchema);
 /** Fatura profili özeti: yalnızca var mı ve türü (alanlar PII, burada yok). */
 const AccountProfileStateSchema = z.object({
 	present: z.boolean(),
@@ -319,7 +1252,21 @@ const AccountStateSchema = EntitlementSnapshotSchema.extend({
 	catalogVersion: z.string().nullable(),
 	subscription: AccountSubscriptionStateSchema.nullable(),
 	openCheckout: AccountOpenCheckoutSchema.nullable(),
-	profile: AccountProfileStateSchema
+	profile: AccountProfileStateSchema,
+	subscriptions: z.array(AccountSubscriptionStateSchema).optional(),
+	openInvoices: z.array(AccountOpenInvoiceSchema).optional(),
+	benefits: z.array(AccountBenefitSchema).optional(),
+	/**
+	* Metering phase 2 (M13): per catalog meter `{includedUnits, billable, standing}`. Present only
+	* for a product whose catalog defines meters (the state of other products, and so its version
+	* and fingerprint, stays exactly as before).
+	*/
+	meters: AccountMetersStateSchema.optional(),
+	/**
+	* Bank transfer plan (H4, H6): the account's order code the customer writes in the transfer
+	* description (`XXXX-XXXX-X`); present once the account chose bank transfer, then permanent.
+	*/
+	bankTransferCode: z.string().optional()
 });
 const AccountSchema = z.object({
 	ref: ExternalRefSchema,
@@ -349,6 +1296,11 @@ const ACCOUNT_INCLUDES = [
 const EventIdSchema = z.string().regex(/^evt_[0-9a-f-]{36}$/);
 const ApiVersionSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
 const sub = { subscriptionId: IdSchema };
+/** `benefit_grant.*` detail base: the grant log row id and the granted benefit (as in `AccountState.benefits[]`). */
+const benefitGrant = {
+	grantId: IdSchema,
+	benefit: AccountBenefitSchema
+};
 const EVENT_DETAIL_SCHEMAS = {
 	"account.updated": z.object({ 
 	/** Snapshot'ın hangi alanları değişti (planCode, accessState, entitlements, subscription). */
@@ -368,7 +1320,13 @@ changed: z.array(z.string()) }),
 		interval: IntervalSchema,
 		amountMinor: AmountMinorSchema,
 		currency: CurrencySchema,
-		actorRef: z.string().nullable()
+		actorRef: z.string().nullable(),
+		/**
+		* Upgrade (bank transfer plan H16): the subscription this one replaced — canceled immediately in
+		* the same transaction (`cancelReason` `replaced_by_checkout`, no `subscription.canceled` of its
+		* own). Absent when the checkout replaced nothing.
+		*/
+		replacedSubscriptionId: IdSchema.optional()
 	}),
 	"subscription.renewed": z.object({
 		...sub,
@@ -382,7 +1340,9 @@ changed: z.array(z.string()) }),
 		paymentId: IdSchema.nullable(),
 		/** Dunning'in kaçıncı başarısız denemesi (1'den başlar). */
 		attempt: z.number().int().positive(),
-		nextRetryAt: DateTimeSchema.nullable()
+		nextRetryAt: DateTimeSchema.nullable(),
+		/** Billing core (M23): the unpaid invoice past its due date that started dunning; absent on the legacy provider path. */
+		invoiceId: IdSchema.optional()
 	}),
 	"subscription.suspended": z.object({
 		...sub,
@@ -439,6 +1399,51 @@ changed: z.array(z.string()) }),
 	"account.deleted": z.object({
 		deletedAt: DateTimeSchema,
 		actorRef: z.string().nullable()
+	}),
+	"invoice.paid": z.object({
+		invoiceId: IdSchema,
+		subscriptionId: IdSchema.nullable(),
+		paymentId: IdSchema,
+		/** Null for an invoice written the pre-billing-core way (after a payment). */
+		billingReason: InvoiceBillingReasonSchema.nullable(),
+		totalMinor: AmountMinorSchema,
+		currency: CurrencySchema,
+		paidAt: DateTimeSchema
+	}),
+	"benefit_grant.created": z.object({ ...benefitGrant }),
+	"benefit_grant.updated": z.object({
+		...benefitGrant,
+		previousProperties: z.record(z.string(), z.unknown())
+	}),
+	"benefit_grant.revoked": z.object({
+		...benefitGrant,
+		revokedAt: DateTimeSchema
+	}),
+	"benefit_grant.cycled": z.object({
+		...benefitGrant,
+		periodStart: DateTimeSchema,
+		periodEnd: DateTimeSchema
+	}),
+	"meter.threshold_crossed": z.object({
+		meter: CodeSchema,
+		standing: MeterStandingSchema,
+		previous: MeterStandingSchema,
+		periodStart: DateTimeSchema,
+		periodEnd: DateTimeSchema,
+		consumedUnits: z.number().nonnegative(),
+		creditedUnits: z.number().nonnegative()
+	}),
+	"meter.period_closed": z.object({
+		periodStart: DateTimeSchema,
+		periodEnd: DateTimeSchema,
+		subscriptionId: IdSchema.nullable(),
+		meters: z.array(z.object({
+			meter: CodeSchema,
+			consumedUnits: z.number().nonnegative(),
+			creditedUnits: z.number().nonnegative(),
+			overageUnits: z.number().nonnegative()
+		})).min(1),
+		meterChargeId: IdSchema.nullable()
 	})
 };
 /** Tüm event tipleri (yenileri dahil). */
@@ -464,7 +1469,18 @@ const LEGACY_EVENT_TYPES = Object.freeze([
 	"invoice.created",
 	"invoice.issued"
 ]);
-const FULL_STATE_EVENT_TYPES = /* @__PURE__ */ new Set(["account.state_changed", "account.deleted"]);
+/** Event types whose `data.account` is the full `AccountState` (the others: the entitlement snapshot). */
+const FULL_STATE_EVENT_TYPES = /* @__PURE__ */ new Set([
+	"account.state_changed",
+	"account.deleted",
+	"invoice.paid",
+	"benefit_grant.created",
+	"benefit_grant.updated",
+	"benefit_grant.revoked",
+	"benefit_grant.cycled",
+	"meter.threshold_crossed",
+	"meter.period_closed"
+]);
 function accountSchemaOf(type) {
 	return FULL_STATE_EVENT_TYPES.has(type) ? AccountStateSchema : EntitlementSnapshotSchema;
 }
@@ -515,4 +1531,4 @@ const PingSchema = z.object({
 	endpointId: IdSchema
 });
 //#endregion
-export { CurrencySchema as $, EMAIL_LOCALES as A, NotificationEmailsSchema as B, BillingProfileKindSchema as C, SubscriptionSummarySchema as D, SubscriptionStatusSchema as E, EmailSettingsPatchSchema as F, emailTemplateOf as G, billingPageUrl as H, EmailSettingsSchema as I, uniqueEmails as J, emailTemplateSettings as K, EmailTemplateSchema as L, EMAIL_TEMPLATE_BY_EVENT as M, EmailExtraTextSchema as N, BILLING_PATH_PLACEHOLDERS as O, EmailSenderSchema as P, CodeSchema as Q, EmailTemplateSettingsSchema as R, AccountUpsertInputSchema as S, EntitlementSnapshotSchema as T, emailLocaleOf as U, applyEmailSettingsPatch as V, emailRecipients as W, ActorRefSchema as X, API_VERSION as Y, AmountMinorSchema as Z, AccountProfileStateSchema as _, EVENT_TYPES as a, ErrorResponseSchema as at, AccountStateSchema as b, PING_EVENT_TYPE as c, IntervalSchema as ct, ACCOUNT_INCLUDES as d, DateTimeSchema as et, AccessStateSchema as f, AccountOpenCheckoutSchema as g, AccountLocaleSchema as h, EVENT_DETAIL_SCHEMAS as i, ErrorCategorySchema as it, EMAIL_TEMPLATES as j, BillingPathSchema as k, PingSchema as l, MetadataSchema as lt, AccountDunningStateSchema as m, ApiVersionSchema as n, EntitlementValueSchema as nt, EventIdSchema as o, ExternalRefSchema as ot, AccountDeleteResponseSchema as p, isEmailRelevant as q, BillingEventSchema as r, EntitlementsSchema as rt, LEGACY_EVENT_TYPES as s, IdSchema as st, AnyBillingEventSchema as t, ERROR_CATEGORIES as tt, isEventType as u, AccountScheduledChangeSchema as v, BillingProfileSchema as w, AccountSubscriptionStateSchema as x, AccountSchema as y, MAX_NOTIFICATION_EMAILS as z };
+export { emailLocaleOf as $, MeteredPriceSchema as $t, SubscriptionStatusSchema as A, hasControlCharacters as An, METER_FILTER_MAX_CONDITIONS as At, EmailSenderSchema as B, EntitlementsSchema as Bn, MeterCreditEntryKindSchema as Bt, AccountSchema as C, EventNameSchema as Cn, DEFAULT_METER_LOW_AT as Ct, BillingProfileKindSchema as D, IngestEventSchema as Dn, METER_AGGREGATION_KINDS as Dt, AccountUpsertInputSchema as E, INGEST_REJECT_CODES as En, MAX_METER_UNITS as Et, EMAIL_LOCALES as F, CodeSchema as Fn, MeterAggregationSchema as Ft, InvoicePaymentDueEmailSchema as G, INVOICE_PAYMENT_STATUSES as Gn, MeterLabelSchema as Gt, EmailSettingsSchema as H, ErrorResponseSchema as Hn, MeterCreditPropertiesSchema as Ht, EMAIL_PAYLOAD_SCHEMAS as I, CurrencySchema as In, MeterChargeLineSchema as It, NotificationEmailsSchema as J, InvoiceBillingReasonSchema as Jn, MeterPeriodSchema as Jt, MAX_NOTIFICATION_EMAILS as K, IdSchema as Kn, MeterLowAtSchema as Kt, EMAIL_TEMPLATES as L, DateTimeSchema as Ln, MeterChargeListSchema as Lt, BILLING_PATH_PLACEHOLDERS as M, API_VERSION as Mn, METER_FILTER_OPERATORS as Mt, BankTransferInstructionsEmailSchema as N, ActorRefSchema as Nn, METER_PERIOD_STATUSES as Nt, BillingProfileSchema as O, IngestRejectCodeSchema as On, METER_CHARGE_STATUSES as Ot, BillingPathSchema as P, AmountMinorSchema as Pn, METER_STANDINGS as Pt, billingPageUrl as Q, MeteredPriceDefSchema as Qt, EMAIL_TEMPLATE_BY_EVENT as R, ERROR_CATEGORIES as Rn, MeterChargeSchema as Rt, AccountScheduledChangeSchema as S, EventMetadataValueSchema as Sn, CreditGrantInputSchema as St, AccountSubscriptionStateSchema as T, EventsIngestResultSchema as Tn, MAX_METERED_PRICE_PER_UNITS as Tt, EmailTemplateSchema as U, ExternalRefSchema as Un, MeterDefSchema as Ut, EmailSettingsPatchSchema as V, ErrorCategorySchema as Vn, MeterCreditEntrySchema as Vt, EmailTemplateSettingsSchema as W, INVOICE_BILLING_REASONS as Wn, MeterFilterSchema as Wt, PriceChangeNoticeMeteredRateSchema as X, MetadataSchema as Xn, MeterStandingSchema as Xt, PriceChangeNoticeEmailSchema as Y, InvoicePaymentStatusSchema as Yn, MeterPeriodStatusSchema as Yt, applyEmailSettingsPatch as Z, MeterUnitsSchema as Zt, AccountMeterStateSchema as _, EVENT_TIMESTAMP_MAX_AGE_DAYS as _n, isFeatureFlagBenefit as _t, EVENT_TYPES as a, fromMicroUnits as an, uniqueEmails as at, AccountOpenInvoiceSchema as b, EventMetadataKeySchema as bn, AccountMetersSchema as bt, LEGACY_EVENT_TYPES as c, parseMicroUnits as cn, BenefitDefSchema as ct, isEventType as d, EVENTS_INGEST_MAX_BYTES as dn, BenefitTypeSchema as dt, canonicalMeterFilter as en, emailRecipients as et, ACCOUNT_INCLUDES as f, EVENTS_INGEST_MAX_EVENTS as fn, CatalogBenefitSchema as ft, AccountLocaleSchema as g, EVENT_NAME_MAX_LENGTH as gn, featureValueMatchesType as gt, AccountDunningStateSchema as h, EVENT_METADATA_STRING_MAX_LENGTH as hn, MeterCreditBenefitDefSchema as ht, EVENT_DETAIL_SCHEMAS as i, UNIT_DECIMALS as in, liveSubscriptionOf as it, SubscriptionSummarySchema as j, isEventTimestampInRange as jn, METER_FILTER_MAX_DEPTH as jt, EntitlementSnapshotSchema as k, IngestRejectionSchema as kn, METER_CREDIT_ENTRY_KINDS as kt, PING_EVENT_TYPE as l, plainDecimalOf as ln, BenefitDescriptionSchema as lt, AccountDeleteResponseSchema as m, EVENT_METADATA_MAX_PAIRS as mn, FeatureFlagPropertiesSchema as mt, ApiVersionSchema as n, InvalidUnitValueError as nn, emailTemplateSettings as nt, EventIdSchema as o, isMicroPrecise as on, AccountBenefitSchema as ot, AccessStateSchema as p, EVENT_METADATA_KEY_MAX_LENGTH as pn, FeatureFlagBenefitDefSchema as pt, NoticedMeteredRateSchema as q, IntervalSchema as qn, MeterPeriodListSchema as qt, BillingEventSchema as r, MICRO_UNITS_PER_UNIT as rn, isEmailRelevant as rt, FULL_STATE_EVENT_TYPES as s, microToDecimalString as sn, BENEFIT_TYPES as st, AnyBillingEventSchema as t, meterFilterClauseOf as tn, emailTemplateOf as tt, PingSchema as u, toMicroUnits as un, BenefitSourceSchema as ut, AccountMetersStateSchema as v, EVENT_TIMESTAMP_MAX_SKEW_MINUTES as vn, isMeterCreditBenefit as vt, AccountStateSchema as w, EventsIngestInputSchema as wn, DecimalUnitsStringSchema as wt, AccountProfileStateSchema as x, EventMetadataSchema as xn, CatalogMeterSchema as xt, AccountOpenCheckoutSchema as y, EventExternalIdSchema as yn, AccountMeterSchema as yt, EmailExtraTextSchema as z, EntitlementValueSchema as zn, MeterChargeStatusSchema as zt };