@stewardhq/sdk 0.2.0 → 0.5.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,10 +71,1011 @@ 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;
+			members.forEach((member, i) => 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",
+	"payment_receipt",
+	"payment_failed",
+	"cancel_scheduled",
+	"subscription_ended",
+	"access_suspended",
+	"subscription_terminated",
+	"invoice_issued",
+	"invoice_payment_due",
+	"price_change_notice"
+];
+const EmailTemplateSchema = z.enum(EMAIL_TEMPLATES);
+/** `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()
+});
+/** Payload schema per billing core template. */
+const EMAIL_PAYLOAD_SCHEMAS = Object.freeze({
+	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",
+	"subscription.payment_failed": "payment_failed",
+	"subscription.cancel_scheduled": "cancel_scheduled",
+	"subscription.canceled": "subscription_ended",
+	"subscription.expired": "subscription_ended",
+	"subscription.suspended": "access_suspended",
+	"subscription.terminated": "subscription_terminated",
+	"invoice.issued": "invoice_issued"
+});
+function emailTemplateOf(type) {
+	return EMAIL_TEMPLATE_BY_EVENT[type] ?? null;
+}
+const EMAIL_LOCALES = ["tr", "en"];
+/** Upper bound of product-provided recipients per account. */
+const MAX_NOTIFICATION_EMAILS = 10;
+const NotificationEmailsSchema = z.array(z.email().max(254)).max(10).transform((emails) => uniqueEmails(emails));
+/** Case-insensitive de-duplication; keeps the first spelling and the order. */
+function uniqueEmails(emails) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const email of emails) {
+		const key = email.trim().toLowerCase();
+		if (key === "" || seen.has(key)) continue;
+		seen.add(key);
+		out.push(email.trim());
+	}
+	return out;
+}
+/** Profile email first, then the account's notification emails. */
+function emailRecipients(profileEmail, notificationEmails) {
+	return uniqueEmails([...profileEmail ? [profileEmail] : [], ...notificationEmails]);
+}
+function emailLocaleOf(accountLocale, lastCheckoutLocale, defaultLocale) {
+	const known = (value) => EMAIL_LOCALES.includes(value ?? "");
+	if (known(accountLocale)) return accountLocale;
+	if (known(lastCheckoutLocale)) return lastCheckoutLocale;
+	return defaultLocale;
+}
+const ExtraTextValueSchema = z.string().trim().min(1).max(1e3);
+const EmailExtraTextSchema = z.object({
+	tr: ExtraTextValueSchema.optional(),
+	en: ExtraTextValueSchema.optional()
+});
+const EmailTemplateSettingsSchema = z.object({
+	/** false: steward does not send this template (the product sends its own). */
+	enabled: z.boolean().default(true),
+	/** Plain-text paragraph appended to the template body, per locale. */
+	extraText: EmailExtraTextSchema.optional()
+});
+const EmailTemplatesSchema = z.object(Object.fromEntries(EMAIL_TEMPLATES.map((t) => [t, EmailTemplateSettingsSchema.optional()])));
+const EmailSenderSchema = z.object({
+	/** Display name; defaults to `branding.name`. */
+	name: z.string().trim().min(1).max(100).optional(),
+	/** Sender address; defaults to the deployment's `STEWARD_EMAIL_FROM`. Its domain needs SPF/DKIM. */
+	address: z.email().max(254).optional()
+});
+/** Placeholders a billing path may use. */
+const BILLING_PATH_PLACEHOLDERS = ["{LOCALE}", "{ACCOUNT_REF}"];
+const BillingPathSchema = z.string().max(500).regex(/^\/(?!\/)[^\s\\]*$/, "an absolute path under appUrl (starts with a single /)").refine((path) => (path.match(/\{[^}]*\}/g) ?? []).every((p) => BILLING_PATH_PLACEHOLDERS.includes(p)), "only {LOCALE} and {ACCOUNT_REF} placeholders");
+const EmailSettingsSchema = z.object({
+	from: EmailSenderSchema.optional(),
+	/** Reply-To; defaults to `branding.supportEmail`. */
+	replyTo: z.email().max(254).optional(),
+	/** Product billing page under `appUrl`, e.g. `/{LOCALE}/app/orgs/{ACCOUNT_REF}/billing`; without it buttons open `appUrl`. */
+	billingPath: BillingPathSchema.optional(),
+	templates: EmailTemplatesSchema.default({})
+});
+const EmailSettingsPatchSchema = z.object({
+	from: EmailSenderSchema.strict().nullable().optional(),
+	replyTo: z.email().max(254).nullable().optional(),
+	billingPath: BillingPathSchema.nullable().optional(),
+	templates: z.object(Object.fromEntries(EMAIL_TEMPLATES.map((t) => [t, z.object({
+		enabled: z.boolean().optional(),
+		extraText: EmailExtraTextSchema.strict().optional()
+	}).strict().nullable().optional()]))).strict().optional()
+}).strict();
+/** Pure merge of a validated patch (see the patch rules above). */
+function applyEmailSettingsPatch(current, patch) {
+	if (patch === null) return EmailSettingsSchema.parse({});
+	const next = {
+		...current,
+		templates: { ...current.templates }
+	};
+	for (const [key, value] of Object.entries(patch)) {
+		if (value === void 0) continue;
+		if (key === "templates") {
+			const templates = next.templates;
+			for (const [template, settings] of Object.entries(value)) {
+				if (settings === void 0) continue;
+				if (settings === null) delete templates[template];
+				else templates[template] = settings;
+			}
+		} else if (value === null) delete next[key];
+		else next[key] = value;
+	}
+	return EmailSettingsSchema.parse(next);
+}
+function emailTemplateSettings(settings, template) {
+	return settings.templates[template] ?? { enabled: true };
+}
+/**
+* Button target: `appUrl` + `billingPath` with placeholders filled (the ref is URL-encoded).
+* Null without `appUrl`, or when the result would leave the `appUrl` origin.
+*/
+function billingPageUrl(appUrl, billingPath, locale, accountRef) {
+	if (appUrl === void 0) return null;
+	let base;
+	try {
+		base = new URL(appUrl);
+	} catch {
+		return null;
+	}
+	if (billingPath === void 0) return base.toString();
+	const path = billingPath.replaceAll("{LOCALE}", locale).replaceAll("{ACCOUNT_REF}", encodeURIComponent(accountRef));
+	try {
+		const url = new URL(path, base.origin);
+		return url.origin === base.origin ? url.toString() : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* 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 for the event's subscription (which need not be the
+* primary one when the account has several).
+*/
+function isEmailRelevant(template, facts) {
+	const sub = liveSubscriptionOf(facts.state, facts.subscriptionId);
+	switch (template) {
+		case "subscription_started":
+		case "payment_receipt":
+		case "subscription_terminated":
+		case "price_change_notice": return true;
+		case "invoice_payment_due": return facts.invoicePaymentStatus === "unpaid";
+		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";
+	}
+}
+//#endregion
 //#region ../contract/src/accounts.ts
+const AccountLocaleSchema = z.enum(EMAIL_LOCALES);
 const AccountUpsertInputSchema = z.object({
 	displayName: z.string().min(1).max(200),
-	metadata: MetadataSchema.default({})
+	metadata: MetadataSchema.default({}),
+	/**
+	* Extra recipients of billing emails besides the billing profile email (e.g. the
+	* organization owners). Omitted: unchanged (older clients keep working); `[]` clears.
+	*/
+	notificationEmails: NotificationEmailsSchema.optional(),
+	/** Language of billing emails. Omitted: unchanged; `null`: latest checkout's, else the product default. */
+	locale: AccountLocaleSchema.nullable().optional()
 });
 const BillingProfileKindSchema = z.enum(["individual", "company"]);
 const BillingProfileSchema = z.object({
@@ -92,6 +1118,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(),
@@ -111,11 +1141,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(),
@@ -124,7 +1159,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. */
@@ -137,6 +1175,38 @@ const AccountOpenCheckoutSchema = z.object({
 	amountMinor: AmountMinorSchema,
 	expiresAt: DateTimeSchema
 });
+/**
+* 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(),
@@ -155,14 +1225,27 @@ 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()
 });
 const AccountSchema = z.object({
 	ref: ExternalRefSchema,
 	displayName: z.string(),
 	metadata: MetadataSchema,
 	createdAt: DateTimeSchema,
-	snapshot: EntitlementSnapshotSchema
+	snapshot: EntitlementSnapshotSchema,
+	/** Extra billing email recipients (older steward: absent → `[]`). */
+	notificationEmails: z.array(z.string()).default([]),
+	/** Billing email language set by the product; null: not set. */
+	locale: AccountLocaleSchema.nullable().default(null)
 });
 const AccountDeleteResponseSchema = z.object({
 	ref: ExternalRefSchema,
@@ -181,6 +1264,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). */
@@ -214,7 +1302,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,
@@ -271,6 +1361,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). */
@@ -296,7 +1431,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;
 }
@@ -347,4 +1493,4 @@ const PingSchema = z.object({
 	endpointId: IdSchema
 });
 //#endregion
-export { CodeSchema as A, IntervalSchema as B, BillingProfileSchema as C, API_VERSION as D, SubscriptionSummarySchema as E, EntitlementsSchema as F, ErrorCategorySchema as I, ErrorResponseSchema as L, DateTimeSchema as M, ERROR_CATEGORIES as N, ActorRefSchema as O, EntitlementValueSchema as P, ExternalRefSchema as R, BillingProfileKindSchema as S, SubscriptionStatusSchema as T, MetadataSchema as V, AccountScheduledChangeSchema as _, EVENT_TYPES as a, AccountSubscriptionStateSchema as b, PING_EVENT_TYPE as c, ACCOUNT_INCLUDES as d, AccessStateSchema as f, AccountProfileStateSchema as g, AccountOpenCheckoutSchema as h, EVENT_DETAIL_SCHEMAS as i, CurrencySchema as j, AmountMinorSchema as k, PingSchema as l, AccountDunningStateSchema as m, ApiVersionSchema as n, EventIdSchema as o, AccountDeleteResponseSchema as p, BillingEventSchema as r, LEGACY_EVENT_TYPES as s, AnyBillingEventSchema as t, isEventType as u, AccountSchema as v, EntitlementSnapshotSchema as w, AccountUpsertInputSchema as x, AccountStateSchema as y, IdSchema as z };
+export { emailRecipients as $, canonicalMeterFilter as $t, SubscriptionStatusSchema as A, isEventTimestampInRange as An, METER_FILTER_MAX_DEPTH as At, EmailSettingsPatchSchema as B, ErrorCategorySchema as Bn, MeterCreditEntrySchema as Bt, AccountSchema as C, EventsIngestInputSchema as Cn, DecimalUnitsStringSchema as Ct, BillingProfileKindSchema as D, IngestRejectCodeSchema as Dn, METER_CHARGE_STATUSES as Dt, AccountUpsertInputSchema as E, IngestEventSchema as En, METER_AGGREGATION_KINDS as Et, EMAIL_PAYLOAD_SCHEMAS as F, CurrencySchema as Fn, MeterChargeLineSchema as Ft, MAX_NOTIFICATION_EMAILS as G, IdSchema as Gn, MeterLowAtSchema as Gt, EmailTemplateSchema as H, ExternalRefSchema as Hn, MeterDefSchema as Ht, EMAIL_TEMPLATES as I, DateTimeSchema as In, MeterChargeListSchema as It, PriceChangeNoticeEmailSchema as J, InvoicePaymentStatusSchema as Jn, MeterPeriodStatusSchema as Jt, NoticedMeteredRateSchema as K, IntervalSchema as Kn, MeterPeriodListSchema as Kt, EMAIL_TEMPLATE_BY_EVENT as L, ERROR_CATEGORIES as Ln, MeterChargeSchema as Lt, BILLING_PATH_PLACEHOLDERS as M, ActorRefSchema as Mn, METER_PERIOD_STATUSES as Mt, BillingPathSchema as N, AmountMinorSchema as Nn, METER_STANDINGS as Nt, BillingProfileSchema as O, IngestRejectionSchema as On, METER_CREDIT_ENTRY_KINDS as Ot, EMAIL_LOCALES as P, CodeSchema as Pn, MeterAggregationSchema as Pt, emailLocaleOf as Q, MeteredPriceSchema as Qt, EmailExtraTextSchema as R, EntitlementValueSchema as Rn, MeterChargeStatusSchema as Rt, AccountScheduledChangeSchema as S, EventNameSchema as Sn, DEFAULT_METER_LOW_AT as St, AccountSubscriptionStateSchema as T, INGEST_REJECT_CODES as Tn, MAX_METER_UNITS as Tt, EmailTemplateSettingsSchema as U, INVOICE_BILLING_REASONS as Un, MeterFilterSchema as Ut, EmailSettingsSchema as V, ErrorResponseSchema as Vn, MeterCreditPropertiesSchema as Vt, InvoicePaymentDueEmailSchema as W, INVOICE_PAYMENT_STATUSES as Wn, MeterLabelSchema as Wt, applyEmailSettingsPatch as X, MeterUnitsSchema as Xt, PriceChangeNoticeMeteredRateSchema as Y, MetadataSchema as Yn, MeterStandingSchema as Yt, billingPageUrl as Z, MeteredPriceDefSchema as Zt, AccountMeterStateSchema as _, EVENT_TIMESTAMP_MAX_SKEW_MINUTES as _n, isMeterCreditBenefit as _t, EVENT_TYPES as a, isMicroPrecise as an, AccountBenefitSchema as at, AccountOpenInvoiceSchema as b, EventMetadataSchema as bn, CatalogMeterSchema as bt, LEGACY_EVENT_TYPES as c, plainDecimalOf as cn, BenefitDescriptionSchema as ct, isEventType as d, EVENTS_INGEST_MAX_EVENTS as dn, CatalogBenefitSchema as dt, meterFilterClauseOf as en, emailTemplateOf as et, ACCOUNT_INCLUDES as f, EVENT_METADATA_KEY_MAX_LENGTH as fn, FeatureFlagBenefitDefSchema as ft, AccountLocaleSchema as g, EVENT_TIMESTAMP_MAX_AGE_DAYS as gn, isFeatureFlagBenefit as gt, AccountDunningStateSchema as h, EVENT_NAME_MAX_LENGTH as hn, featureValueMatchesType as ht, EVENT_DETAIL_SCHEMAS as i, fromMicroUnits as in, uniqueEmails as it, SubscriptionSummarySchema as j, API_VERSION as jn, METER_FILTER_OPERATORS as jt, EntitlementSnapshotSchema as k, hasControlCharacters as kn, METER_FILTER_MAX_CONDITIONS as kt, PING_EVENT_TYPE as l, toMicroUnits as ln, BenefitSourceSchema as lt, AccountDeleteResponseSchema as m, EVENT_METADATA_STRING_MAX_LENGTH as mn, MeterCreditBenefitDefSchema as mt, ApiVersionSchema as n, MICRO_UNITS_PER_UNIT as nn, isEmailRelevant as nt, EventIdSchema as o, microToDecimalString as on, BENEFIT_TYPES as ot, AccessStateSchema as p, EVENT_METADATA_MAX_PAIRS as pn, FeatureFlagPropertiesSchema as pt, NotificationEmailsSchema as q, InvoiceBillingReasonSchema as qn, MeterPeriodSchema as qt, BillingEventSchema as r, UNIT_DECIMALS as rn, liveSubscriptionOf as rt, FULL_STATE_EVENT_TYPES as s, parseMicroUnits as sn, BenefitDefSchema as st, AnyBillingEventSchema as t, InvalidUnitValueError as tn, emailTemplateSettings as tt, PingSchema as u, EVENTS_INGEST_MAX_BYTES as un, BenefitTypeSchema as ut, AccountMetersStateSchema as v, EventExternalIdSchema as vn, AccountMeterSchema as vt, AccountStateSchema as w, EventsIngestResultSchema as wn, MAX_METERED_PRICE_PER_UNITS as wt, AccountProfileStateSchema as x, EventMetadataValueSchema as xn, CreditGrantInputSchema as xt, AccountOpenCheckoutSchema as y, EventMetadataKeySchema as yn, AccountMetersSchema as yt, EmailSenderSchema as z, EntitlementsSchema as zn, MeterCreditEntryKindSchema as zt };