@stewardhq/sdk 0.2.0 → 0.5.0

package/dist/_chunks/src.js

@@ -1,4 +1,4 @@
-import { A as CodeSchema, B as IntervalSchema, C as BillingProfileSchema, F as EntitlementsSchema, M as DateTimeSchema, O as ActorRefSchema, R as ExternalRefSchema, S as BillingProfileKindSchema, T as SubscriptionStatusSchema, a as EVENT_TYPES, j as CurrencySchema, k as AmountMinorSchema, o as EventIdSchema, v as AccountSchema, y as AccountStateSchema, z as IdSchema } from "./events.js";
+import { A as SubscriptionStatusSchema, B as EmailSettingsPatchSchema, Bt as MeterCreditEntrySchema, C as AccountSchema, Ct as DecimalUnitsStringSchema, D as BillingProfileKindSchema, Fn as CurrencySchema, Gn as IdSchema, Hn as ExternalRefSchema, Ht as MeterDefSchema, I as EMAIL_TEMPLATES, In as DateTimeSchema, Jn as InvoicePaymentStatusSchema, Kn as IntervalSchema, Mn as ActorRefSchema, Nn as AmountMinorSchema, O as BillingProfileSchema, Pn as CodeSchema, Qt as MeteredPriceSchema, V as EmailSettingsSchema, Vt as MeterCreditPropertiesSchema, X as applyEmailSettingsPatch, Zt as MeteredPriceDefSchema, a as EVENT_TYPES, bt as CatalogMeterSchema, cn as plainDecimalOf, dt as CatalogBenefitSchema, en as meterFilterClauseOf, ht as featureValueMatchesType, ln as toMicroUnits, nn as MICRO_UNITS_PER_UNIT, o as EventIdSchema, qn as InvoiceBillingReasonSchema, st as BenefitDefSchema, w as AccountStateSchema, yt as AccountMetersSchema, zn as EntitlementsSchema } from "./events.js";
 import { z } from "zod";
 //#region ../contract/src/catalog.ts
 const FeatureTypeSchema = z.enum([
@@ -11,14 +11,34 @@ const FeatureDefSchema = z.object({
 	type: FeatureTypeSchema,
 	description: z.string().max(500).optional()
 });
+const PlanRankSchema = z.number().int().nonnegative();
+/** Upper bound of benefits a plan lists. */
+const MAX_PLAN_BENEFITS = 100;
+/** Plan in the catalog sync input. */
 const PlanDefSchema = z.object({
 	code: CodeSchema,
 	name: z.string().min(1).max(200),
-	/** Yükseltme/düşürme sırası: büyük olan üst plan. */
-	rank: z.number().int().nonnegative(),
+	/**
+	* Upgrade order of the pre-benefits entitlement rule (higher = upper plan). Optional since
+	* billing core (M35): default 0; the benefits resolution does not read it.
+	*/
+	rank: PlanRankSchema.default(0),
 	/** Self-servis satın alınabilir mi (false: yalnızca grant ile verilir). */
 	sellable: z.boolean(),
-	entitlements: EntitlementsSchema
+	entitlements: EntitlementsSchema,
+	/** Codes of catalog `benefits` the plan includes, in display order (billing core; default empty). */
+	benefits: z.array(CodeSchema).max(100).default([])
+});
+/** Plan as returned by `GET /v1/catalog`. */
+const CatalogPlanSchema = z.object({
+	code: CodeSchema,
+	name: z.string().min(1).max(200),
+	/** Stored value (0 when the catalog omitted it); kept for older clients (M35). */
+	rank: PlanRankSchema.default(0),
+	sellable: z.boolean(),
+	entitlements: EntitlementsSchema,
+	/** Present only for a product that defines benefits. */
+	benefits: z.array(CodeSchema).optional()
 });
 const PriceDefSchema = z.object({
 	planCode: CodeSchema,
@@ -31,11 +51,25 @@ const PriceDefSchema = z.object({
 	/** Baz puan: %20 = 2000. */
 	taxRateBps: z.number().int().min(0).max(1e4)
 });
+/** Upper bound of benefit definitions in one catalog. */
+const MAX_CATALOG_BENEFITS = 200;
+/** Upper bound of meters in one catalog. */
+const MAX_CATALOG_METERS = 100;
+/** Upper bound of metered prices in one catalog. */
+const MAX_CATALOG_METERED_PRICES = 500;
+/** Issue `params.code` of a metered price whose tax terms differ from the plan's base price (M20). */
+const METERED_PRICE_TAX_MISMATCH = "metered_price_tax_mismatch";
 const CatalogSyncInputSchema = z.object({
 	defaultPlanCode: CodeSchema,
 	features: z.array(FeatureDefSchema),
 	plans: z.array(PlanDefSchema).min(1),
-	prices: z.array(PriceDefSchema)
+	prices: z.array(PriceDefSchema),
+	/** Benefit definitions by code (billing core; default empty). */
+	benefits: z.record(CodeSchema, BenefitDefSchema).default({}),
+	/** Meter definitions by code (metering; default empty). */
+	meters: z.record(CodeSchema, MeterDefSchema).default({}),
+	/** Metered prices (metering; default empty). */
+	meteredPrices: z.array(MeteredPriceDefSchema).default([])
 }).superRefine((c, ctx) => {
 	const features = new Set(c.features.map((f) => f.key));
 	const plans = new Set(c.plans.map((p) => p.code));
@@ -62,6 +96,78 @@ const CatalogSyncInputSchema = z.object({
 		],
 		message: "tanımsız feature"
 	});
+	const benefitCodes = Object.keys(c.benefits);
+	if (benefitCodes.length > 200) ctx.addIssue({
+		code: "custom",
+		path: ["benefits"],
+		message: `at most 200 benefits`
+	});
+	for (const [i, p] of c.plans.entries()) {
+		const listed = /* @__PURE__ */ new Set();
+		for (const [j, code] of p.benefits.entries()) {
+			if (!Object.hasOwn(c.benefits, code)) ctx.addIssue({
+				code: "custom",
+				path: [
+					"plans",
+					i,
+					"benefits",
+					j
+				],
+				message: `undefined benefit: ${code}`
+			});
+			if (listed.has(code)) ctx.addIssue({
+				code: "custom",
+				path: [
+					"plans",
+					i,
+					"benefits",
+					j
+				],
+				message: `duplicate benefit: ${code}`
+			});
+			listed.add(code);
+		}
+	}
+	const featureTypes = new Map(c.features.map((f) => [f.key, f.type]));
+	for (const code of benefitCodes) {
+		const benefit = c.benefits[code];
+		if (benefit.type === "meter_credit") {
+			if (!Object.hasOwn(c.meters, benefit.properties.meter)) ctx.addIssue({
+				code: "custom",
+				path: [
+					"benefits",
+					code,
+					"properties",
+					"meter"
+				],
+				message: `undefined meter: ${benefit.properties.meter}`
+			});
+			continue;
+		}
+		for (const [key, value] of Object.entries(benefit.properties)) {
+			const type = featureTypes.get(key);
+			if (type === void 0) ctx.addIssue({
+				code: "custom",
+				path: [
+					"benefits",
+					code,
+					"properties",
+					key
+				],
+				message: "undefined feature"
+			});
+			else if (!featureValueMatchesType(type, value)) ctx.addIssue({
+				code: "custom",
+				path: [
+					"benefits",
+					code,
+					"properties",
+					key
+				],
+				message: `value does not match feature type ${type}`
+			});
+		}
+	}
 	const seen = /* @__PURE__ */ new Set();
 	for (const [i, p] of c.prices.entries()) {
 		if (!plans.has(p.planCode)) ctx.addIssue({
@@ -81,6 +187,61 @@ const CatalogSyncInputSchema = z.object({
 		});
 		seen.add(key);
 	}
+	if (Object.keys(c.meters).length > 100) ctx.addIssue({
+		code: "custom",
+		path: ["meters"],
+		message: `at most 100 meters`
+	});
+	if (c.meteredPrices.length > 500) ctx.addIssue({
+		code: "custom",
+		path: ["meteredPrices"],
+		message: `at most 500 metered prices`
+	});
+	const meteredSeen = /* @__PURE__ */ new Set();
+	for (const [i, mp] of c.meteredPrices.entries()) {
+		if (!plans.has(mp.planCode)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"meteredPrices",
+				i,
+				"planCode"
+			],
+			message: `undefined plan: ${mp.planCode}`
+		});
+		if (!Object.hasOwn(c.meters, mp.meter)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"meteredPrices",
+				i,
+				"meter"
+			],
+			message: `undefined meter: ${mp.meter}`
+		});
+		const key = `${mp.planCode}/${mp.meter}/${mp.currency}`;
+		if (meteredSeen.has(key)) ctx.addIssue({
+			code: "custom",
+			path: ["meteredPrices", i],
+			message: `duplicate metered price key: ${key}`
+		});
+		meteredSeen.add(key);
+		if (!plans.has(mp.planCode)) continue;
+		const base = c.prices.filter((p) => p.planCode === mp.planCode && p.currency === mp.currency);
+		if (base.length === 0) ctx.addIssue({
+			code: "custom",
+			path: [
+				"meteredPrices",
+				i,
+				"currency"
+			],
+			message: `plan ${mp.planCode} has no base price in ${mp.currency}`
+		});
+		else if (base.some((p) => p.taxInclusive !== mp.taxInclusive || p.taxRateBps !== mp.taxRateBps)) ctx.addIssue({
+			code: "custom",
+			path: ["meteredPrices", i],
+			message: `${METERED_PRICE_TAX_MISMATCH}: taxInclusive and taxRateBps must equal the base prices of plan ${mp.planCode} in ${mp.currency}`,
+			params: { code: METERED_PRICE_TAX_MISMATCH }
+		});
+	}
 });
 const PriceSchema = PriceDefSchema.extend({
 	id: IdSchema,
@@ -91,9 +252,15 @@ const CatalogSchema = z.object({
 	product: CodeSchema,
 	defaultPlanCode: CodeSchema,
 	features: z.array(FeatureDefSchema),
-	plans: z.array(PlanDefSchema),
+	plans: z.array(CatalogPlanSchema),
 	/** Varsayılan olarak yalnızca aktif fiyatlar. */
-	prices: z.array(PriceSchema)
+	prices: z.array(PriceSchema),
+	/** Active (not archived) benefit definitions by code; present only for a product that defines benefits. */
+	benefits: z.record(CodeSchema, CatalogBenefitSchema).optional(),
+	/** Active (not archived) meters by code; present only for a product that defines meters (metering). */
+	meters: z.record(CodeSchema, CatalogMeterSchema).optional(),
+	/** Active metered prices; present only for a product that defines meters (metering). */
+	meteredPrices: z.array(MeteredPriceSchema).optional()
 });
 const CatalogSyncResultSchema = z.object({
 	/** Aynı girdiyle tekrar senkron: hiçbir şey değişmedi. */
@@ -111,7 +278,21 @@ const CatalogSyncResultSchema = z.object({
 		priceId: IdSchema,
 		provider: z.string(),
 		code: z.string()
-	}))
+	})),
+	/** Benefits created, changed or unarchived by this sync. */
+	changedBenefits: z.array(CodeSchema).optional(),
+	/** Benefits removed from the catalog and archived by this sync. */
+	archivedBenefits: z.array(CodeSchema).optional(),
+	/** Prices whose amount or tax terms were updated in place (the price id is kept; history in `price_changes`). */
+	updatedPrices: z.array(IdSchema).optional(),
+	/** Meters created, changed (labels, `lowAt`, display) or unarchived by this sync. */
+	changedMeters: z.array(CodeSchema).optional(),
+	/** Meters removed from the catalog and archived by this sync (their history stays). */
+	archivedMeters: z.array(CodeSchema).optional(),
+	createdMeteredPrices: z.array(IdSchema).optional(),
+	/** Metered prices whose amount, cap or tax terms were updated in place (the id is kept). */
+	updatedMeteredPrices: z.array(IdSchema).optional(),
+	deactivatedMeteredPrices: z.array(IdSchema).optional()
 });
 /** `POST /v1/admin/accounts/refresh` — ürünün tüm hesaplarının snapshot'ı yeniden hesaplanır. */
 const AccountsRefreshResultSchema = z.object({ 
@@ -163,6 +344,43 @@ const BrandingSchema = z.object({
 	accentColor: AccentColorSchema.optional(),
 	supportEmail: SupportEmailSchema.optional()
 });
+const DEFAULT_PAYMENT_DUE_DAYS = 7;
+const DEFAULT_MIN_INVOICE_MINOR = 1e3;
+const PaymentDueDaysSchema = z.number().int().min(1).max(60);
+const BillingSettingsSchema = z.object({
+	paymentDueDays: PaymentDueDaysSchema.default(7),
+	minInvoiceMinor: AmountMinorSchema.default(DEFAULT_MIN_INVOICE_MINOR),
+	allowMultipleSubscriptions: z.boolean().default(false)
+});
+/** Patch of `settings.billing`: an omitted field is unchanged, `null` restores its default. */
+const BillingSettingsPatchSchema = z.object({
+	paymentDueDays: PaymentDueDaysSchema.nullable().optional(),
+	minInvoiceMinor: AmountMinorSchema.nullable().optional(),
+	allowMultipleSubscriptions: z.boolean().nullable().optional()
+}).strict();
+const DEFAULT_EVENT_RETENTION_DAYS = 120;
+const DEFAULT_LATE_GRACE_MINUTES = 60;
+const METER_CHARGE_MODES = [
+	"off",
+	"dry_run",
+	"live"
+];
+const MeterChargeModeSchema = z.enum(METER_CHARGE_MODES);
+const DEFAULT_METER_CHARGE_MODE = "dry_run";
+const EventRetentionDaysSchema = z.number().int().min(45).max(400);
+const LateGraceMinutesSchema = z.number().int().min(0).max(1440);
+const EventsSettingsSchema = z.object({ retentionDays: EventRetentionDaysSchema.default(120) });
+const MeteringSettingsSchema = z.object({
+	lateGraceMinutes: LateGraceMinutesSchema.default(60),
+	chargeMode: MeterChargeModeSchema.default(DEFAULT_METER_CHARGE_MODE)
+});
+/** Patch of `settings.events`: an omitted field is unchanged, `null` restores its default. */
+const EventsSettingsPatchSchema = z.object({ retentionDays: EventRetentionDaysSchema.nullable().optional() }).strict();
+/** Patch of `settings.metering`: an omitted field is unchanged, `null` restores its default. */
+const MeteringSettingsPatchSchema = z.object({
+	lateGraceMinutes: LateGraceMinutesSchema.nullable().optional(),
+	chargeMode: MeterChargeModeSchema.nullable().optional()
+}).strict();
 const ProductSettingsSchema = z.object({
 	/** Checkout'ları alan ödeme sağlayıcısı. Operatör ayarıdır (pod CLI); yönetim ucundan yazılmaz. */
 	provider: z.string().min(1).default("iyzico"),
@@ -175,8 +393,28 @@ const ProductSettingsSchema = z.object({
 	branding: BrandingSchema.default({}),
 	/** Açık checkout oturumunun ömrü (sağlayıcının form ömrü daha kısaysa o geçerli). */
 	checkoutTtlMinutes: TtlMinutesSchema.default(30),
-	portalTtlMinutes: TtlMinutesSchema.default(30)
+	portalTtlMinutes: TtlMinutesSchema.default(30),
+	/** Billing emails sent by steward (`emails.ts`). */
+	emails: EmailSettingsSchema.default({ templates: {} }),
+	/** Billing behavior (billing core); absent = defaults (`billingSettingsOf`). */
+	billing: BillingSettingsSchema.optional(),
+	/** Raw event retention (metering); absent = defaults (`eventsSettingsOf`). */
+	events: EventsSettingsSchema.optional(),
+	/** Meter periods and overage pricing (metering); absent = defaults (`meteringSettingsOf`). */
+	metering: MeteringSettingsSchema.optional()
 });
+/** `settings.billing` with defaults filled in. */
+function billingSettingsOf(settings) {
+	return settings.billing ?? BillingSettingsSchema.parse({});
+}
+/** `settings.events` with defaults filled in. */
+function eventsSettingsOf(settings) {
+	return settings.events ?? EventsSettingsSchema.parse({});
+}
+/** `settings.metering` with defaults filled in. */
+function meteringSettingsOf(settings) {
+	return settings.metering ?? MeteringSettingsSchema.parse({});
+}
 const BrandingPatchSchema = z.object({
 	name: BrandingNameSchema.nullable().optional(),
 	logoUrl: LogoUrlSchema.nullable().optional(),
@@ -193,8 +431,21 @@ const ProductSettingsPatchSchema = z.object({
 	termsUrl: WebUrlSchema.nullable().optional(),
 	branding: BrandingPatchSchema.nullable().optional(),
 	checkoutTtlMinutes: TtlMinutesSchema.optional(),
-	portalTtlMinutes: TtlMinutesSchema.optional()
+	portalTtlMinutes: TtlMinutesSchema.optional(),
+	emails: EmailSettingsPatchSchema.nullable().optional(),
+	/** Merges per field; `billing: null` restores every default. */
+	billing: BillingSettingsPatchSchema.nullable().optional(),
+	/** Merges per field; `events: null` restores every default. */
+	events: EventsSettingsPatchSchema.nullable().optional(),
+	/** Merges per field; `metering: null` restores every default. */
+	metering: MeteringSettingsPatchSchema.nullable().optional()
 }).strict();
+/** Settings sections patched field by field (`null` section: every default back). */
+const MERGED_SECTIONS = /* @__PURE__ */ new Set([
+	"billing",
+	"events",
+	"metering"
+]);
 /**
 * Doğrulanmış yamayı ayarlara uygular (saf). Sonuç şemadan geçer; alan kuralları
 * yamada zaten denetlendiği için yalnızca programlama hatasında fırlatır.
@@ -210,6 +461,15 @@ function applySettingsPatch(current, patch) {
 				else if (fieldValue !== void 0) branding[field] = fieldValue;
 			}
 			next.branding = branding;
+		} else if (key === "emails") next.emails = applyEmailSettingsPatch(current.emails, value);
+		else if (MERGED_SECTIONS.has(key)) {
+			if (value === null) delete next[key];
+			else {
+				const section = { ...current[key] ?? {} };
+				for (const [field, fieldValue] of Object.entries(value)) if (fieldValue === null) delete section[field];
+				else if (fieldValue !== void 0) section[field] = fieldValue;
+				next[key] = section;
+			}
 		} else if (value === null) delete next[key];
 		else next[key] = value;
 	}
@@ -228,6 +488,16 @@ function isReturnUrlAllowed(settings, returnUrl) {
 //#endregion
 //#region ../contract/src/checkout.ts
 const ReturnUrlSchema = z.url({ protocol: /^https?$/ });
+/**
+* Identity number sent to the payment provider (and, when the invoice needs one, used on the
+* invoice) for an INDIVIDUAL buyer (M31): steward never asks for or stores a TCKN; the Turkish
+* "final consumer" placeholder goes instead. A company buyer's VKN comes from the billing profile.
+*
+* It deliberately FAILS the TCKN checksum (`isValidTckn("11111111111") === false`): never run it
+* through a TCKN validator and never show it as a customer's TCKN. Kept here, not in a provider
+* adapter, because another provider may need a different rule.
+*/
+const INDIVIDUAL_IDENTITY_PLACEHOLDER = "11111111111";
 /** Accepted document — content lives in the product, steward keeps only the trace. */
 const ConsentSchema = z.object({
 	document: z.string().min(1).max(100),
@@ -345,7 +615,7 @@ function originOf(value) {
 	}
 }
 /**
-* Browser redirect for a checkout outcome — the service and the fake steward share it.
+* Browser redirect for a checkout outcome — used by the service.
 * Placeholders in `successUrl` (`{CHECKOUT_ID}` `{STATUS}` `{ACCOUNT_REF}` `{LOCALE}`) are
 * filled with URL-encoded values; nothing is appended, so a URL without placeholders is used
 * as-is. An encoded value cannot change the origin; it is still checked, and if the origin
@@ -369,7 +639,8 @@ const CHECKOUT_ERRORS = [
 	"return_url_not_allowed",
 	"provider_not_configured",
 	"provider_error",
-	"account_deleted"
+	"account_deleted",
+	"meter_already_billed"
 ];
 //#endregion
 //#region ../contract/src/portal.ts
@@ -399,9 +670,11 @@ const SubscriptionSchema = z.object({
 	planCode: CodeSchema,
 	priceId: IdSchema,
 	interval: IntervalSchema,
+	/** Amount per period; billing core (M36): the subscription's locked amount. */
 	amountMinor: AmountMinorSchema,
 	currency: CurrencySchema,
 	provider: z.string(),
+	/** Legacy provider-managed subscription reference; `""` for a steward-managed subscription (billing core, M30). */
 	providerSubscriptionRef: z.string(),
 	cancelAtPeriodEnd: z.boolean(),
 	cancelAt: DateTimeSchema.nullable(),
@@ -420,6 +693,28 @@ const CancelSubscriptionInputSchema = z.object({
 	/** Sağlayıcıda zaten iptal edildiyse (panelden) sağlayıcı çağrısını atla. */
 	skipProvider: z.boolean().default(false)
 });
+/**
+* `POST /v1/subscriptions/{id}/change` (billing core MF9): schedule a change for the next period
+* boundary (`AccountState.subscription.scheduledChange`); the next renewal invoice is written from
+* the new terms. `planCode` / `interval` pick another price of the subscription's currency;
+* `price: "current"` re-locks the current amount of the (possibly updated) price and the plan's
+* current metered rates — a metered price added later is attached only this way (M20, M36). At
+* least one of the three. `when` is required so other timings can be added later. A second change
+* replaces the first; asking for the current plan and interval while a change is pending takes it
+* back ("keep my plan"; a move to the current price the operator announced stays).
+* Errors: 404 `subscription_not_found`; 409 `already_subscribed` (another live subscription of the
+* account holds the target plan or is moving to it), `meter_already_billed` (the target prices a
+* meter another live subscription bills; for `price: "current"` only when that is the only
+* difference); 422 `plan_not_found`, `plan_not_sellable`, `subscription_change_invalid` (no such
+* price, nothing changes, the subscription is not live, has a cancellation scheduled or is a legacy
+* provider subscription).
+*/
+const SubscriptionChangeInputSchema = z.object({
+	planCode: CodeSchema.optional(),
+	interval: IntervalSchema.optional(),
+	price: z.literal("current").optional(),
+	when: z.literal("next_period")
+}).refine((c) => c.planCode !== void 0 || c.interval !== void 0 || c.price !== void 0, { message: "planCode, interval or price is required" });
 const PaymentSchema = z.object({
 	id: IdSchema,
 	subscriptionId: IdSchema,
@@ -431,19 +726,28 @@ const PaymentSchema = z.object({
 	periodEnd: DateTimeSchema.nullable(),
 	occurredAt: DateTimeSchema
 });
+/** Upper bound of named benefits in one grant. */
+const MAX_GRANT_BENEFITS = 100;
 const GrantCreateInputSchema = z.object({
 	planCode: CodeSchema.optional(),
-	/** Plan değerlerinin üzerine yazılan tek tek haklar. */
+	/** Single values written over the merged entitlements (applied last; may lower). */
 	overrides: EntitlementsSchema.default({}),
+	/**
+	* Catalog benefit codes granted independently of a plan (billing core, M32), e.g. only "sso".
+	* An unknown or archived code is rejected with 422 `benefit_not_found`.
+	*/
+	benefitCodes: z.array(CodeSchema).max(100).optional(),
 	reason: z.string().min(3).max(500),
 	startsAt: DateTimeSchema.optional(),
 	endsAt: DateTimeSchema.optional()
-}).refine((g) => g.planCode !== void 0 || Object.keys(g.overrides).length > 0, { message: "planCode ya da en az bir override gerekli" });
+}).refine((g) => g.planCode !== void 0 || Object.keys(g.overrides).length > 0 || (g.benefitCodes?.length ?? 0) > 0, { message: "planCode, benefitCodes or at least one override is required" });
 const GrantSchema = z.object({
 	id: IdSchema,
 	accountRef: ExternalRefSchema,
 	planCode: CodeSchema.nullable(),
 	overrides: EntitlementsSchema,
+	/** Named benefits the grant gives (billing core; absent when none or from an older steward). */
+	benefitCodes: z.array(CodeSchema).optional(),
 	reason: z.string(),
 	actorRef: ActorRefSchema.nullable(),
 	startsAt: DateTimeSchema,
@@ -468,7 +772,11 @@ const InvoiceLineSchema = z.object({
 	description: z.string(),
 	quantity: z.number().int().positive(),
 	unitAmountMinor: AmountMinorSchema,
-	amountMinor: AmountMinorSchema
+	amountMinor: AmountMinorSchema,
+	meter: CodeSchema.optional(),
+	units: DecimalUnitsStringSchema.optional(),
+	priceAmountMinor: AmountMinorSchema.optional(),
+	pricePerUnits: z.number().int().positive().optional()
 });
 const InvoiceSchema = z.object({
 	id: IdSchema,
@@ -495,7 +803,12 @@ const InvoiceSchema = z.object({
 	/** Manuel faturanın notu (ör. sözleşme ya da teklif referansı). */
 	note: z.string().nullable().optional(),
 	voidedAt: DateTimeSchema.nullable().optional(),
-	voidReason: z.string().nullable().optional()
+	voidReason: z.string().nullable().optional(),
+	billingReason: InvoiceBillingReasonSchema.nullable().optional(),
+	paymentStatus: InvoicePaymentStatusSchema.nullable().optional(),
+	/** Billing period the invoice covers. */
+	periodStart: DateTimeSchema.nullable().optional(),
+	periodEnd: DateTimeSchema.nullable().optional()
 });
 const InvoiceIssueInputSchema = z.object({
 	number: z.string().min(1).max(100),
@@ -534,6 +847,28 @@ const ManualInvoiceInputSchema = z.object({
 /** `POST /v1/invoices/{id}/void` — yalnızca manuel fatura; numara serbest kalmaz, belge silinmez. */
 const InvoiceVoidInputSchema = z.object({ reason: z.string().trim().min(3).max(500) });
 /**
+* `POST /v1/invoices/{id}/payment-sessions` — opens steward's hosted pay page for an unpaid
+* invoice (the product's own "Pay invoice" button; emails and the portal link to the same page).
+* 409 `invoice_not_payable` when the invoice is not unpaid.
+*/
+const InvoicePaymentSessionCreateInputSchema = z.object({
+	/** `tr` | `en`; defaults to the account's email locale, else the product's `defaultLocale`. */
+	locale: z.enum(SETTINGS_LOCALES).optional(),
+	/** Where the page returns after the outcome; its origin must be allowed by product settings. Defaults to `appUrl`. */
+	returnUrl: z.url({ protocol: /^https?$/ }).max(2e3).optional()
+});
+/** Pay page session: redirect the customer to `url` (it carries the page key; do not log it). */
+const InvoicePaymentSessionSchema = z.object({
+	id: IdSchema,
+	url: z.string(),
+	expiresAt: DateTimeSchema
+});
+/**
+* `POST /v1/invoices/{id}/waive` — an operator forgives an unpaid invoice (`paymentStatus:
+* "waived"`, e.g. before deleting the account). 409 `invoice_not_waivable` otherwise.
+*/
+const InvoiceWaiveInputSchema = z.object({ reason: z.string().trim().min(3).max(500) });
+/**
 * Vergi dahil tutardan matrah ve vergiyi ayrıştırır (tam sayı, kuruşa
 * yuvarlama). Toplam her zaman korunur: subtotal + tax === total.
 */
@@ -638,6 +973,45 @@ const ManualInvoiceResponseSchema = InvoiceSchema.extend(withAccount);
 const InvoiceVoidResponseSchema = InvoiceSchema.extend(withAccount);
 /** `GET /v1/checkout-sessions/{id}` — `account` yalnızca oturum `completed` ise. */
 const CheckoutSessionResponseSchema = CheckoutSessionSchema.extend(withAccount);
+/** `POST /v1/invoices/{id}/waive` (billing core): the waived invoice and the state after it (`openInvoices` shrinks). */
+const InvoiceWaiveResponseSchema = InvoiceSchema.extend(withAccount);
+/** `POST /v1/subscriptions/{id}/change` (billing core MF9): the subscription and the state with `scheduledChange`. */
+const ChangeSubscriptionResponseSchema = SubscriptionSchema.extend(withAccount);
+/** `POST /v1/subscriptions/{id}/uncancel` (billing core MF9): the scheduled cancellation is taken back. */
+const UncancelSubscriptionResponseSchema = SubscriptionSchema.extend(withAccount);
+/**
+* `POST /v1/accounts/{ref}/credits` (metering MF2): the ledger entry written, the meters after it
+* and (K5) the account state after it (a credit may change a meter's standing).
+*/
+const CreditGrantResponseSchema = z.object({
+	entry: MeterCreditEntrySchema,
+	meters: AccountMetersSchema,
+	...withAccount
+});
+/**
+* Known `GET /v1/me` capabilities (M27): what this steward understands beyond the 0.2 contract.
+* `steward catalog push` sends a catalog with `benefits` only when `benefits` is listed (an older
+* steward would silently drop the key); phase 2 adds `events` (`POST /v1/events/ingest`), `meters`
+* (catalog `meters`, `meter_credit` benefits, `GET …/meters`, credits) and `overage` (metered
+* prices, meter charges). A steward lists a capability only once it implements it. Open set.
+*/
+const STEWARD_CAPABILITIES = [
+	"benefits",
+	"events",
+	"meters",
+	"overage"
+];
+/** `GET /v1/me`: the key's product and scope (setup check). `capabilities` absent from older steward. */
+const MeResponseSchema = z.object({
+	product: z.string(),
+	keyName: z.string(),
+	scope: z.enum([
+		"product",
+		"admin",
+		"checkout"
+	]),
+	capabilities: z.array(z.string()).optional()
+});
 /** Değişiklik yapan her istekte zorunlu başlıklar. */
 const HEADER_IDEMPOTENCY_KEY = "idempotency-key";
 const HEADER_ACTOR_REF = "x-actor-ref";
@@ -685,10 +1059,16 @@ const ERROR_CODES = Object.freeze({
 	override_type_mismatch: spec(422, "validation"),
 	/** Grant girdisindeki plan katalogda yok. */
 	plan_not_found: spec(422, "validation"),
+	/** Grant `benefitCodes`: a code is not an active (not archived) catalog benefit of the product. */
+	benefit_not_found: spec(422, "validation"),
 	invalid_window: spec(422, "validation"),
 	already_subscribed: spec(409, "conflict"),
 	already_canceled: spec(409, "conflict"),
-	/** `PUT …/plan` `mode: "strict"`: canlı aboneliğin planı hedefi geçiyor; hiçbir şey yazılmadı. */
+	/**
+	* LEGACY — no longer produced (billing core, M35: no plan rank). Steward before the billing core
+	* answered `PUT …/plan` `mode: "strict"` with it when a live subscription's plan outranked the
+	* target. Kept so clients that handle it keep compiling.
+	*/
 	subscription_plan_higher: spec(409, "conflict"),
 	plan_not_sellable: spec(422, "validation"),
 	/**
@@ -714,6 +1094,35 @@ const ERROR_CODES = Object.freeze({
 	invoice_not_voidable: spec(409, "conflict"),
 	/** Void: ödemeli fatura; iptali iade yolundadır (F4d). */
 	invoice_has_payment: spec(409, "conflict"),
+	/** `DELETE /v1/accounts/:ref`: the account has an unpaid invoice; pay or waive it first. */
+	invoice_open: spec(409, "conflict"),
+	/** Pay page session: the invoice is not unpaid (paid, waived, uncollectible, or not an invoice-first invoice). */
+	invoice_not_payable: spec(409, "conflict"),
+	/** Waive: the invoice is not unpaid. */
+	invoice_not_waivable: spec(409, "conflict"),
+	/**
+	* `POST /v1/subscriptions/:id/change`: the requested change is not possible — no active price for
+	* the target plan/interval in the subscription's currency, nothing would change, or the
+	* subscription is not live. Plan lookup errors keep their codes (`plan_not_found`, `plan_not_sellable`).
+	*/
+	subscription_change_invalid: spec(422, "validation"),
+	/**
+	* `POST /v1/subscriptions/:id/uncancel`: the live subscription has no cancellation scheduled for
+	* the period end (an ended or immediately canceled one is `already_canceled`).
+	*/
+	cancel_not_scheduled: spec(409, "conflict"),
+	/** `POST /v1/events/ingest`: more than 1 000 events (or a body over 1 MiB) in one batch; split it. */
+	batch_too_large: spec(422, "validation"),
+	/** `POST /v1/events/ingest`: the unprocessed event backlog is too large; `Retry-After`, keep the batch queued (M11). */
+	events_backlog: spec(503, "unavailable", true),
+	/** Catalog sync: a meter's filter or aggregation changed after its first period opened; use a new meter code (M4). */
+	meter_locked: spec(422, "conflict"),
+	/** Credit grant (or another meter lookup): the code is not an active catalog meter of the product. */
+	meter_not_found: spec(422, "validation"),
+	/** Catalog sync: a metered price's tax terms differ from the plan's base price in that currency (M20). */
+	metered_price_tax_mismatch: spec(422, "validation"),
+	/** A second live subscription would bill the same meter's overage (M20: one billing subscription per meter). */
+	meter_already_billed: spec(409, "conflict"),
 	internal_error: spec(500, "unavailable", true),
 	/** `/health`: veritabanına ulaşılamıyor. */
 	database_unavailable: spec(503, "unavailable", true),
@@ -735,6 +1144,297 @@ function errorCodeSpec(code) {
 	return isKnownErrorCode(code) ? ERROR_CODES[code] : null;
 }
 //#endregion
+//#region ../contract/src/meter-rules.ts
+const METADATA_PREFIX = "metadata.";
+function propertyValue(event, property) {
+	if (property === "name") return event.name;
+	const key = property.slice(9);
+	const metadata = event.metadata;
+	return metadata !== void 0 && metadata !== null && Object.hasOwn(metadata, key) ? metadata[key] : void 0;
+}
+const isScalar = (value) => typeof value === "string" || typeof value === "number" && Number.isFinite(value) || typeof value === "boolean";
+/**
+* Whether an event matches a meter filter (syntax and semantics: `meters.ts`). A condition on an
+* absent metadata key is false for every operator; `eq` needs the same type; `like` is a
+* case-sensitive substring. Throws on a filter the schema would reject.
+*/
+function matchesFilter(event, filter) {
+	if ("and" in filter && Array.isArray(filter.and)) return filter.and.every((f) => matchesFilter(event, f));
+	if ("or" in filter && Array.isArray(filter.or)) return filter.or.some((f) => matchesFilter(event, f));
+	const clause = meterFilterClauseOf(filter);
+	if (clause === null) throw new Error("invalid meter filter condition");
+	const value = propertyValue(event, clause.property);
+	if (!isScalar(value)) return false;
+	const operand = clause.value;
+	switch (clause.operator) {
+		case "eq": return typeof value === typeof operand && value === operand;
+		case "ne": return !(typeof value === typeof operand && value === operand);
+		case "gt": return typeof value === "number" && value > operand;
+		case "gte": return typeof value === "number" && value >= operand;
+		case "lt": return typeof value === "number" && value < operand;
+		case "lte": return typeof value === "number" && value <= operand;
+		case "like": return typeof value === "string" && value.includes(operand);
+		case "not_like": return !(typeof value === "string" && value.includes(operand));
+	}
+}
+function contributionOf(event, aggregation) {
+	if (aggregation.kind === "count") return { kind: "count" };
+	const value = propertyValue(event, `${METADATA_PREFIX}${aggregation.key}`);
+	if (aggregation.kind === "unique") {
+		if (typeof value === "string") return {
+			kind: "unique",
+			value: `s:${value}`
+		};
+		if (typeof value === "number" && Number.isFinite(value)) return {
+			kind: "unique",
+			value: `n:${plainDecimalOf(value)}`
+		};
+		if (typeof value === "boolean") return {
+			kind: "unique",
+			value: `b:${value}`
+		};
+		return { kind: "invalid_value" };
+	}
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return { kind: "invalid_value" };
+	return {
+		kind: aggregation.kind,
+		micro: toMicroUnits(value)
+	};
+}
+/**
+* A meter's value over a set of events (reference computation; the service recomputes a closing
+* period from raw events with the same result, M8): `count` → matching events, `sum` → total,
+* `max` → the largest value (0 when none), `unique` → distinct values. `matched` counts events
+* that passed the filter (invalid ones included), `invalid` those without a usable value.
+*/
+function consumptionOf(events, meter) {
+	let matched = 0;
+	let invalid = 0;
+	let total = 0n;
+	const distinct = /* @__PURE__ */ new Set();
+	for (const event of events) {
+		if (!matchesFilter(event, meter.filter)) continue;
+		matched += 1;
+		const c = contributionOf(event, meter.aggregation);
+		switch (c.kind) {
+			case "invalid_value":
+				invalid += 1;
+				break;
+			case "count":
+				total += MICRO_UNITS_PER_UNIT;
+				break;
+			case "sum":
+				total += c.micro;
+				break;
+			case "max":
+				if (c.micro > total) total = c.micro;
+				break;
+			case "unique": distinct.add(c.value);
+		}
+	}
+	return {
+		consumedMicro: meter.aggregation.kind === "unique" ? BigInt(distinct.size) * MICRO_UNITS_PER_UNIT : total,
+		matched,
+		invalid
+	};
+}
+function nonNegative(name, value) {
+	if (value < 0n) throw new RangeError(`${name} must not be negative`);
+}
+/**
+* The credit rule (M5; decided 2026-09-19): the granted `meter_credit` benefits per meter code.
+* - Several benefits on one meter sum their units AND their rollover caps (plan + add-on).
+* - A benefit code granted by several layers counts once (its first counted grant).
+* - The default plan's credit for a meter counts only when no other layer credits that meter
+*   (`options.defaultPlanCode`): free 50k + team 2M → 2M, free only → 50k.
+* - Benefits of another type, without a code, or whose properties do not parse are ignored.
+* The service (`AccountState.meters.includedUnits`, cycle grants) and the SDK (`stateOf`,
+* `Meters()` fallback) both use this function. Vectors: `credits.json`.
+*/
+function meterCreditsOf(benefits, options = {}) {
+	const defaultSource = options.defaultPlanCode ? `plan:${options.defaultPlanCode}` : null;
+	const parsed = [];
+	for (const benefit of benefits) {
+		if (benefit.type !== "meter_credit" || typeof benefit.code !== "string") continue;
+		const properties = MeterCreditPropertiesSchema.safeParse(benefit.properties);
+		if (!properties.success) continue;
+		const { meter, units, rolloverCapUnits } = properties.data;
+		parsed.push({
+			code: benefit.code,
+			source: benefit.source ?? null,
+			isDefault: defaultSource !== null && benefit.source === defaultSource,
+			meter,
+			unitsMicro: toMicroUnits(units),
+			rolloverCapMicro: rolloverCapUnits === void 0 ? null : toMicroUnits(rolloverCapUnits)
+		});
+	}
+	const creditedElsewhere = new Set(parsed.filter((b) => !b.isDefault).map((b) => b.meter));
+	const credits = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	for (const benefit of parsed) {
+		if (seen.has(benefit.code) || benefit.isDefault && creditedElsewhere.has(benefit.meter)) continue;
+		seen.add(benefit.code);
+		const entry = credits.get(benefit.meter) ?? {
+			unitsMicro: 0n,
+			rolloverCapMicro: null,
+			benefits: []
+		};
+		entry.unitsMicro += benefit.unitsMicro;
+		if (benefit.rolloverCapMicro !== null) entry.rolloverCapMicro = (entry.rolloverCapMicro ?? 0n) + benefit.rolloverCapMicro;
+		entry.benefits.push({
+			code: benefit.code,
+			source: benefit.source,
+			unitsMicro: benefit.unitsMicro,
+			rolloverCapMicro: benefit.rolloverCapMicro
+		});
+		credits.set(benefit.meter, entry);
+	}
+	return credits;
+}
+/** `max(0, consumed − credited)` (M21). */
+function overageOf(input) {
+	const overage = input.consumedMicro - input.creditedMicro;
+	return overage > 0n ? overage : 0n;
+}
+/**
+* Credit standing of a meter (M14): no credit (`creditedMicro` 0) → `ok`; balance
+* (`credited − consumed`) ≤ 0 → `exhausted`; consumption ≥ `lowAt` × credit → `low` (`lowAt`
+* null disables `low`); else `ok`. Exact integer comparison (`lowAt` read as micro units).
+* `billable` does not change the standing — it describes the credit; a billable meter goes
+* `low`/`exhausted` too and only the gate stays open (M15).
+*/
+function standingOf(input) {
+	nonNegative("creditedMicro", input.creditedMicro);
+	nonNegative("consumedMicro", input.consumedMicro);
+	if (input.lowAt !== null && !(input.lowAt > 0 && input.lowAt <= 1)) throw new RangeError("lowAt must be in (0, 1]");
+	if (input.creditedMicro === 0n) return "ok";
+	if (input.creditedMicro - input.consumedMicro <= 0n) return "exhausted";
+	if (input.lowAt !== null && input.consumedMicro * 1000000n >= toMicroUnits(input.lowAt) * input.creditedMicro) return "low";
+	return "ok";
+}
+/**
+* Credit carried into the next period (M6): `min(max(closing balance, 0), cap)`; `capMicro`
+* null (rollover off) → 0. Debt never carries.
+*/
+function rolloverOf(input) {
+	if (input.capMicro === null) return 0n;
+	nonNegative("capMicro", input.capMicro);
+	const balance = input.closingBalanceMicro > 0n ? input.closingBalanceMicro : 0n;
+	return balance < input.capMicro ? balance : input.capMicro;
+}
+function daysInUtcMonth(year, month) {
+	const d = /* @__PURE__ */ new Date(0);
+	d.setUTCFullYear(year, month + 1, 0);
+	return d.getUTCDate();
+}
+/**
+* `from` + `months` months in UTC with the month-end clamp of the service's `addInterval`
+* (`service/src/periods.ts`, date-fns `addMonths` on `UTCDate`): the day of month is kept, or the
+* last day of a shorter month (Jan 31 + 1 → Feb 28/29); the time of day is kept.
+*/
+function addUtcMonths(from, months) {
+	if (!Number.isInteger(months)) throw new RangeError("months must be an integer");
+	const total = from.getUTCMonth() + months;
+	const year = from.getUTCFullYear() + Math.floor(total / 12);
+	const month = (total % 12 + 12) % 12;
+	const out = new Date(from.getTime());
+	out.setUTCFullYear(year, month, Math.min(from.getUTCDate(), daysInUtcMonth(year, month)));
+	return out;
+}
+/**
+* The monthly meter period containing `at` (M7): `[anchor + n months, anchor + (n + 1) months)`,
+* start inclusive, end exclusive, where every boundary is computed FROM THE ANCHOR (`addUtcMonths`;
+* Jan 31 → Feb 28 → Mar 31, no drift) — the same grid as the billing cycle's `nextPeriodEnd` for a
+* monthly subscription. `n` may be negative (`at` before the anchor). UTC throughout.
+*/
+function periodBoundsOf(anchor, at) {
+	if (Number.isNaN(anchor.getTime()) || Number.isNaN(at.getTime())) throw new RangeError("invalid date");
+	let n = (at.getUTCFullYear() - anchor.getUTCFullYear()) * 12 + (at.getUTCMonth() - anchor.getUTCMonth());
+	while (addUtcMonths(anchor, n).getTime() > at.getTime()) n -= 1;
+	while (addUtcMonths(anchor, n + 1).getTime() <= at.getTime()) n += 1;
+	return {
+		start: addUtcMonths(anchor, n),
+		end: addUtcMonths(anchor, n + 1)
+	};
+}
+function nonNegativeInteger(name, value, min = 0) {
+	if (!Number.isSafeInteger(value) || value < min) throw new RangeError(`${name} must be an integer ≥ ${min}`);
+	return BigInt(value);
+}
+/** The overage amount before the cap (BigInt, half up) and the cap (null: none); validates the price. */
+function pricedOverage(input) {
+	const amount = nonNegativeInteger("amountMinor", input.amountMinor);
+	const perUnits = nonNegativeInteger("perUnits", input.perUnits, 1);
+	const cap = input.capMinor === void 0 || input.capMinor === null ? null : nonNegativeInteger("capMinor", input.capMinor);
+	if (input.overageMicro <= 0n) return {
+		minor: 0n,
+		cap
+	};
+	const numerator = input.overageMicro * amount;
+	const denominator = perUnits * MICRO_UNITS_PER_UNIT;
+	let minor = numerator / denominator;
+	if (2n * (numerator % denominator) >= denominator) minor += 1n;
+	return {
+		minor,
+		cap
+	};
+}
+/**
+* Overage amount in minor units (M21): `round_half_up(overage × amountMinor / perUnits)` on micro
+* units with BigInt — proportional (no block rounding), always whole minor units — then clipped
+* by `capMinor`. Tax terms are the price's (gross when tax-inclusive).
+*/
+function rateOverage(input) {
+	const { minor: uncapped, cap } = pricedOverage(input);
+	const minor = cap !== null && uncapped > cap ? cap : uncapped;
+	if (minor > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("overage amount exceeds the safe integer range");
+	return Number(minor);
+}
+/**
+* Whether the period's priced overage reached the rate's `capMinor` (M15: the SDK gate closes on a
+* billable meter once the cap is reached — further use would be free): there is overage
+* (`overageMicro` > 0) and its amount before the cap (`rateOverage` without `capMinor`) is ≥ the
+* cap. No cap → false. Same validation as `rateOverage`.
+*/
+function overageCapReached(input) {
+	const { minor, cap } = pricedOverage(input);
+	return cap !== null && input.overageMicro > 0n && minor >= cap;
+}
+/**
+* Totals and stored lines of an invoice (or meter charge) with overage lines: the manual invoice
+* rule (`manualInvoiceTotals`) with every line at quantity 1 — ONE rounding at invoice level
+* (tax-inclusive: the total is kept and split with `splitInclusiveTax`, the net spread over the
+* lines by largest remainder; exclusive: tax added on the sum). Stored lines are net and keep
+* their meter fields (`meter`, `units`, `priceAmountMinor`, `pricePerUnits`).
+*/
+function meterChargeTotals(lines, terms) {
+	for (const line of lines) nonNegativeInteger("amountMinor", line.amountMinor);
+	const totals = manualInvoiceTotals({
+		lines: lines.map((l) => ({
+			description: l.description,
+			quantity: 1,
+			unitAmountMinor: l.amountMinor
+		})),
+		taxRateBps: terms.taxRateBps,
+		taxInclusive: terms.taxInclusive
+	});
+	return {
+		subtotalMinor: totals.subtotalMinor,
+		taxMinor: totals.taxMinor,
+		totalMinor: totals.totalMinor,
+		lines: totals.lines.map((line, i) => {
+			const source = lines[i];
+			return {
+				...line,
+				...source.meter !== void 0 ? { meter: source.meter } : {},
+				...source.units !== void 0 ? { units: source.units } : {},
+				...source.priceAmountMinor !== void 0 ? { priceAmountMinor: source.priceAmountMinor } : {},
+				...source.pricePerUnits !== void 0 ? { pricePerUnits: source.pricePerUnits } : {}
+			};
+		})
+	};
+}
+//#endregion
 //#region ../contract/src/plan.ts
 const PLAN_SET_MODES = ["ensure", "strict"];
 const PlanSetModeSchema = z.enum(PLAN_SET_MODES);
@@ -905,7 +1605,69 @@ const DoctorCatalogSchema = z.object({
 	/** Satışa açık planların (`sellable`) bugün checkout'ta satılabilen aktif fiyatları. */
 	sellablePrices: z.number().int().nonnegative(),
 	/** Satışa açık planların satılamayan aktif fiyatları (satışa kapalı planların fiyatları sayılmaz). */
-	unsellablePrices: z.array(DoctorUnsellablePriceSchema)
+	unsellablePrices: z.array(DoctorUnsellablePriceSchema),
+	/**
+	* Live subscriptions whose locked amount (or tax inclusion) differs from the current price of
+	* their key (M36): they keep paying what they locked until explicitly moved. Absent from older steward.
+	*/
+	priceDriftSubscriptions: z.number().int().nonnegative().optional()
+});
+/** Billing core facts (M30). Absent from older steward. */
+const DoctorBillingSchema = z.object({ 
+/**
+* Live subscriptions that still carry a provider subscription reference (created by the removed
+* iyzico subscription path). Steward never invoices them and the provider may still charge them:
+* cancel each in the provider panel, then immediately in steward. Should be 0.
+*/
+legacyProviderSubscriptions: z.number().int().nonnegative() });
+/**
+* Event ingest and rollup facts (metering phase 2, M29; only for a product that defines meters).
+* Absent from older steward. Names and meter codes only: no metadata, no account refs.
+*/
+const DoctorEventsSchema = z.object({
+	/** Non-archived meters. */
+	meters: z.number().int().nonnegative(),
+	/** Meters whose already received events are still being counted in (`backfilling`). */
+	backfillingMeters: z.array(z.string()),
+	/** This product's events not rolled up yet (counted up to just above the back-pressure limit). */
+	backlogRows: z.number().int().nonnegative(),
+	/** Age of this product's oldest event not rolled up yet, seconds (0 when none). */
+	rollupLagSeconds: z.number().nonnegative(),
+	/** The deployment's backlog is over the limits: `POST /v1/events/ingest` answers `503 events_backlog`. */
+	backlogged: z.boolean(),
+	/** Events of the last 7 days examined for the fields below (newest first, bounded). */
+	sampledEvents: z.number().int().nonnegative(),
+	/** Event names of the sample that no meter selects (top 5 by count). Normal: events are generic (M2). */
+	unmatchedEventNames: z.array(z.object({
+		name: z.string(),
+		events: z.number().int().nonnegative()
+	})),
+	/** Per meter, sampled events it selects that carry no usable value (M4 `invalid_value`). */
+	invalidValues: z.array(z.object({
+		meter: z.string(),
+		events: z.number().int().nonnegative()
+	})),
+	/** Non-archived meters with no usage in their current periods and no selected event in the sample. */
+	metersWithoutEvents: z.array(z.string())
+});
+/** Rollup lag above which the doctor warns (the `rollup lag > 60 s` alert, M29). */
+const DOCTOR_ROLLUP_LAG_WARN_SECONDS = 60;
+/**
+* Overage facts (metering MF5, M20/M21): present when the catalog has a metered price or the
+* product has meter charges. Absent from older steward.
+*/
+const DoctorOverageSchema = z.object({
+	/** `settings.metering.chargeMode`: `off` | `dry_run` | `live` (open set for newer steward). */
+	chargeMode: z.string(),
+	/** Active metered prices of the catalog. */
+	meteredPrices: z.number().int().nonnegative(),
+	/**
+	* Live subscriptions without a locked rate for a metered price of their plan: a metered price
+	* added after a subscription started is not attached to it (M20), so its overage is not billed.
+	*/
+	unratedSubscriptions: z.number().int().nonnegative(),
+	/** Charges below the minimum invoice amount waiting for their subscription's next invoice. */
+	carriedCharges: z.number().int().nonnegative()
 });
 const DOCTOR_PROVIDER_ENVIRONMENTS = [
 	"sandbox",
@@ -930,7 +1692,7 @@ const DoctorProviderSchema = z.object({
 	lastError: z.object({
 		/** Sağlayıcı hata kodu, ör. `iyzico:timeout`, `iyzico:1001`. */
 		code: z.string(),
-		/** `ensure_price` | `create_checkout` | `retrieve_checkout` | `retrieve_subscription` | `cancel_subscription` | `retry_payment`. */
+		/** Provider operation, e.g. `create_payment_checkout`, `retrieve_payment_checkout`, `retrieve_payment` (open set). */
 		operation: z.string(),
 		at: DateTimeSchema
 	}).nullable()
@@ -967,6 +1729,17 @@ const DoctorEndpointSchema = z.object({
 	lastDelivery: WebhookLastDeliverySchema.nullable(),
 	diagnosis: z.string()
 });
+/** Billing emails (issue #15). */
+const DoctorEmailsSchema = z.object({
+	/** The deployment has a mail transport (`STEWARD_SMTP_URL`). */
+	transportConfigured: z.boolean(),
+	/** A sender address is known (`settings.emails.from.address` or the deployment default). */
+	senderConfigured: z.boolean(),
+	/** Templates the product turned off. */
+	disabledTemplates: z.array(z.string()),
+	/** Emails are sent: transport and sender configured, at least one template on. */
+	ready: z.boolean()
+});
 const DoctorReportSchema = z.object({
 	/** `error` önemde uyarı yok. */
 	ok: z.boolean(),
@@ -984,8 +1757,28 @@ const DoctorReportSchema = z.object({
 	dunning: z.object({ 
 	/** true: dunning adımları yalnızca iz yazar (askı/sonlandırma yok). */
 dryRun: z.boolean() }),
+	/** Absent in reports of steward versions without billing emails. */
+	emails: DoctorEmailsSchema.optional(),
+	/** Absent in reports of steward versions before the billing core. */
+	billing: DoctorBillingSchema.optional(),
+	/** Event ingest and rollup (metering); absent for a product without meters and from older steward. */
+	events: DoctorEventsSchema.optional(),
+	/** Metering MF5; absent without metered prices and from older steward. */
+	overage: DoctorOverageSchema.optional(),
 	warnings: z.array(DoctorWarningSchema)
 });
+/** Email readiness from settings and the deployment's transport (pure). */
+function emailReadinessOf(settings, transport) {
+	const templates = settings.emails?.templates ?? {};
+	const disabledTemplates = EMAIL_TEMPLATES.filter((t) => templates[t]?.enabled === false);
+	const senderConfigured = settings.emails?.from?.address !== void 0 || transport.defaultFromConfigured;
+	return {
+		transportConfigured: transport.configured,
+		senderConfigured,
+		disabledTemplates: [...disabledTemplates],
+		ready: transport.configured && senderConfigured && disabledTemplates.length < EMAIL_TEMPLATES.length
+	};
+}
 /** Bekleyen en eski teslimat bundan eskiyse `endpoint_pending_backlog` (K23 alarmıyla aynı eşik). */
 const DOCTOR_PENDING_BACKLOG_MS = 36e5;
 /** Son denenmiş teslimattan endpoint teşhisi (saf). */
@@ -1044,14 +1837,15 @@ function buildDoctorReport(facts) {
 	};
 	const { catalog, provider, settings, dunning } = facts;
 	if (!catalog.synced) warn("error", "catalog_not_synced", "katalog senkronlanmamış: `PUT /v1/admin/catalog` (steward catalog push)");
-	const byReason = (reason) => catalog.unsellablePrices.filter((p) => p.reason === reason);
-	const unsynced = byReason("provider_price_missing");
-	if (unsynced.length > 0) warn("error", "price_not_synced_with_provider", `${unsynced.length} fiyatın sağlayıcıda karşılığı yok (checkout plan_not_sellable döner): katalog senkronunu yeniden koşun`);
-	const otherUnsellable = catalog.unsellablePrices.filter((p) => p.reason !== "provider_price_missing" && p.reason !== "provider_not_configured");
+	const otherUnsellable = catalog.unsellablePrices.filter((p) => p.reason !== "provider_not_configured");
 	if (otherUnsellable.length > 0) {
 		const reasons = [...new Set(otherUnsellable.map((p) => p.reason))].join(", ");
 		warn("warning", "price_unsellable", `${otherUnsellable.length} fiyat satılamaz (${reasons})`);
 	}
+	const drift = catalog.priceDriftSubscriptions ?? 0;
+	if (drift > 0) warn("info", "price_drift", `${drift} live subscription(s) keep a locked amount that differs from the current price; moving them to the current price is an explicit operation`);
+	const legacy = facts.billing?.legacyProviderSubscriptions ?? 0;
+	if (legacy > 0) warn("error", "legacy_provider_subscription", `${legacy} live subscription(s) still have a provider subscription: steward never invoices them and the provider may still charge them; cancel each in the provider panel, then immediately in steward`);
 	if (!provider.configured) warn("error", "provider_not_configured", `ödeme sağlayıcısı ${provider.id} bu deployment'ta yapılandırılmamış`);
 	else if (provider.healthy === false) warn("warning", "provider_unhealthy", `ödeme sağlayıcısı ${provider.id} art arda erişilemedi (yanıtı veren pod'un gözlemi)`);
 	const returnOrigins = returnOriginsOf(settings);
@@ -1073,7 +1867,27 @@ function buildDoctorReport(facts) {
 		if (endpoint.dead > 0) warn("warning", "endpoint_dead_deliveries", `${endpoint.dead} teslimattan vazgeçildi (dead): etkilenen hesaplar için resync`, endpoint.id);
 		if (endpoint.oldestPendingAt !== null && facts.checkedAt.getTime() - Date.parse(endpoint.oldestPendingAt) > 36e5) warn("warning", "endpoint_pending_backlog", `${endpoint.pending} teslimat bekliyor; en eskisi bir saatten eski`, endpoint.id);
 	}
+	const emails = facts.emailTransport ? emailReadinessOf(settings, facts.emailTransport) : void 0;
+	if (emails && emails.disabledTemplates.length < EMAIL_TEMPLATES.length) {
+		if (!emails.transportConfigured) warn("warning", "email_not_configured", "email is not configured: steward sends no billing emails (STEWARD_SMTP_URL)");
+		else if (!emails.senderConfigured) warn("warning", "email_sender_missing", "no email sender: set `settings.emails.from.address` or STEWARD_EMAIL_FROM");
+		if (settings.emails?.billingPath === void 0) warn("info", "email_billing_link_missing", "`settings.emails.billingPath` is not set: email buttons open `appUrl`");
+	}
 	if (dunning.dryRun) warn("info", "dunning_dry_run", "dunning dry-run: adımlar yalnızca iz yazar, askı ve sonlandırma uygulanmaz");
+	const ev = facts.events;
+	if (ev) {
+		if (ev.backlogged) warn("warning", "events_backlog", "the event backlog is over the limits: ingest answers 503 events_backlog (the SDK keeps batches queued)");
+		if (ev.rollupLagSeconds > 60) warn("warning", "meter_rollup_lag", `the oldest event waiting for the rollup is ${ev.rollupLagSeconds} s old (${ev.backlogRows} waiting): meters lag behind`);
+		for (const { meter, events } of ev.invalidValues) warn("warning", "events_invalid_value", `meter ${meter}: ${events} recent event(s) carry no usable value (sum/max need a finite, non-negative number; unique needs the key) and add nothing`);
+		if (ev.metersWithoutEvents.length > 0) warn("info", "meter_without_events", `no recent event counts in meter(s) ${ev.metersWithoutEvents.join(", ")}: check the event name and filter`);
+		if (ev.unmatchedEventNames.length > 0) warn("info", "events_unmatched", `recent events no meter selects: ${ev.unmatchedEventNames.map((u) => `${u.name} (${u.events})`).join(", ")} — normal when no meter is meant for them`);
+	}
+	const overage = facts.overage;
+	if (overage && overage.meteredPrices > 0) {
+		if (overage.chargeMode === "off") warn("warning", "overage_charge_mode_off", "metering.chargeMode is off: the catalog has metered prices but overage is neither priced nor invoiced");
+		else if (overage.chargeMode === "dry_run") warn("info", "overage_dry_run", "metering.chargeMode is dry_run: overage is priced into meter charges (GET /v1/accounts/:ref/meter-charges) but not invoiced; switch to live after one full cycle");
+	}
+	if (overage && overage.unratedSubscriptions > 0) warn("info", "overage_unrated_subscriptions", `${overage.unratedSubscriptions} live subscription(s) have no locked rate for a metered price of their plan (added after they started, M20): their overage is not billed until they move to the current terms`);
 	return {
 		ok: !warnings.some((w) => w.severity === "error"),
 		checkedAt: facts.checkedAt.toISOString(),
@@ -1087,8 +1901,12 @@ function buildDoctorReport(facts) {
 		hosted,
 		endpoints,
 		dunning,
+		...emails ? { emails } : {},
+		...facts.billing ? { billing: facts.billing } : {},
+		...facts.events ? { events: facts.events } : {},
+		...overage ? { overage } : {},
 		warnings
 	};
 }
 //#endregion
-export { InvoiceIssueInputSchema as $, webhookEndpointUrlProblem as A, BrandingSchema as At, AccountDetailSchema as B, applySettingsPatch as Bt, WebhookEndpointListSchema as C, CheckoutSessionSchema as Ct, WebhookLastDeliverySchema as D, ProviderPayloadSchema as Dt, WebhookEndpointStatusSchema as E, MAX_CHECKOUT_CONSENT_DOCS as Et, PlanSetWarningSchema as F, ReturnOriginSchema as Ft, HEADER_ACTOR_REF as G, CatalogSyncInputSchema as Gt, CancelSubscriptionResponseSchema as H, returnOriginsOf as Ht, ResyncResultSchema as I, SETTINGS_LOCALES as It, HEADER_REQUEST_ID as J, FeatureTypeSchema as Jt, HEADER_API_VERSION as K, CatalogSyncResultSchema as Kt, ERROR_CODES as L, SettingsLocaleSchema as Lt, PlanSetInputSchema as M, DEFAULT_PORTAL_TTL_MINUTES as Mt, PlanSetModeSchema as N, ProductSettingsPatchSchema as Nt, WebhookSecretSchema as O, checkoutRedirectUrl as Ot, PlanSetResponseSchema as P, ProductSettingsSchema as Pt, ManualInvoiceResponseSchema as Q, errorCodeSpec as R, TtlMinutesSchema as Rt, WebhookEndpointCreateInputSchema as S, CheckoutSessionCreatedSchema as St, WebhookEndpointSchema as T, ConsentSchema as Tt, CheckoutSessionResponseSchema as U, AccountsRefreshResultSchema as Ut, AccountUpsertResponseSchema as V, isReturnUrlAllowed as Vt, GrantCreateResponseSchema as W, CatalogSchema as Wt, InvoiceIssueResponseSchema as X, PriceDefSchema as Xt, HEADER_SDK as Y, PlanDefSchema as Yt, InvoiceVoidResponseSchema as Z, PriceSchema as Zt, hostedReadinessOf as _, PortalSessionSchema as _t, DOCTOR_SEVERITIES as a, ManualInvoiceInputSchema as at, WEBHOOK_ENDPOINT_STATUSES as b, CheckoutPrefillSchema as bt, DoctorHostedSchema as c, splitInclusiveTax as ct, DoctorSettingsSchema as d, GrantSchema as dt, InvoiceLineSchema as et, DoctorSeveritySchema as f, PaymentSchema as ft, endpointDiagnosisOf as g, PortalSessionCreateInputSchema as gt, buildDoctorReport as h, PORTAL_SESSION_ERRORS as ht, DOCTOR_REQUIRED_LEGAL_LINKS as i, MANUAL_INVOICE_MAX_AMOUNT_MINOR as it, PLAN_SET_MODES as j, DEFAULT_CHECKOUT_TTL_MINUTES as jt, generateWebhookSecret as k, BrandingPatchSchema as kt, DoctorProviderSchema as l, CancelSubscriptionInputSchema as lt, DoctorWarningSchema as m, SubscriptionSchema as mt, DOCTOR_PROVIDER_ENVIRONMENTS as n, InvoiceStatusSchema as nt, DoctorCatalogSchema as o, ManualInvoiceLineInputSchema as ot, DoctorUnsellablePriceSchema as p, StatsSchema as pt, HEADER_IDEMPOTENCY_KEY as q, FeatureDefSchema as qt, DOCTOR_REQUIRED_BRANDING as r, InvoiceVoidInputSchema as rt, DoctorEndpointSchema as s, manualInvoiceTotals as st, DOCTOR_PENDING_BACKLOG_MS as t, InvoiceSchema as tt, DoctorReportSchema as u, GrantCreateInputSchema as ut, DEFAULT_ENDPOINT_EVENT_TYPES as v, CHECKOUT_ERRORS as vt, WebhookEndpointRotateInputSchema as w, CheckoutStatusSchema as wt, WEBHOOK_SECRET_PREFIX as x, CheckoutSessionCreateInputSchema as xt, EventTypeSchema as y, CheckoutConsentInputSchema as yt, isKnownErrorCode as z, WebUrlSchema as zt };
+export { rolloverOf as $, CheckoutStatusSchema as $t, WebhookEndpointRotateInputSchema as A, TtlMinutesSchema as An, InvoiceWaiveInputSchema as At, PlanSetResponseSchema as B, CatalogSchema as Bn, PaymentSchema as Bt, hostedReadinessOf as C, MeteringSettingsSchema as Cn, InvoiceIssueInputSchema as Ct, WEBHOOK_SECRET_PREFIX as D, ReturnOriginSchema as Dn, InvoiceSchema as Dt, WEBHOOK_ENDPOINT_STATUSES as E, ProductSettingsSchema as En, InvoicePaymentSessionSchema as Et, generateWebhookSecret as F, isReturnUrlAllowed as Fn, splitInclusiveTax as Ft, contributionOf as G, MAX_CATALOG_BENEFITS as Gn, PortalSessionCreateInputSchema as Gt, ResyncResultSchema as H, CatalogSyncResultSchema as Hn, SubscriptionChangeInputSchema as Ht, webhookEndpointUrlProblem as I, meteringSettingsOf as In, CancelSubscriptionInputSchema as It, meterCreditsOf as J, MAX_PLAN_BENEFITS as Jn, CheckoutConsentInputSchema as Jt, matchesFilter as K, MAX_CATALOG_METERED_PRICES as Kn, PortalSessionSchema as Kt, PLAN_SET_MODES as L, returnOriginsOf as Ln, GrantCreateInputSchema as Lt, WebhookEndpointStatusSchema as M, applySettingsPatch as Mn, ManualInvoiceInputSchema as Mt, WebhookLastDeliverySchema as N, billingSettingsOf as Nn, ManualInvoiceLineInputSchema as Nt, WebhookEndpointCreateInputSchema as O, SETTINGS_LOCALES as On, InvoiceStatusSchema as Ot, WebhookSecretSchema as P, eventsSettingsOf as Pn, manualInvoiceTotals as Pt, rateOverage as Q, PriceSchema as Qn, CheckoutSessionSchema as Qt, PlanSetInputSchema as R, AccountsRefreshResultSchema as Rn, GrantSchema as Rt, endpointDiagnosisOf as S, MeteringSettingsPatchSchema as Sn, UncancelSubscriptionResponseSchema as St, EventTypeSchema as T, ProductSettingsPatchSchema as Tn, InvoicePaymentSessionCreateInputSchema as Tt, addUtcMonths as U, FeatureDefSchema as Un, SubscriptionSchema as Ut, PlanSetWarningSchema as V, CatalogSyncInputSchema as Vn, StatsSchema as Vt, consumptionOf as W, FeatureTypeSchema as Wn, PORTAL_SESSION_ERRORS as Wt, overageOf as X, PlanDefSchema as Xn, CheckoutSessionCreateInputSchema as Xt, overageCapReached as Y, METERED_PRICE_TAX_MISMATCH as Yn, CheckoutPrefillSchema as Yt, periodBoundsOf as Z, PriceDefSchema as Zn, CheckoutSessionCreatedSchema as Zt, DoctorSeveritySchema as _, EventsSettingsPatchSchema as _n, InvoiceVoidResponseSchema as _t, DOCTOR_ROLLUP_LAG_WARN_SECONDS as a, BillingSettingsPatchSchema as an, AccountUpsertResponseSchema as at, buildDoctorReport as b, METER_CHARGE_MODES as bn, MeResponseSchema as bt, DoctorCatalogSchema as c, BrandingSchema as cn, CheckoutSessionResponseSchema as ct, DoctorEventsSchema as d, DEFAULT_LATE_GRACE_MINUTES as dn, HEADER_ACTOR_REF as dt, ConsentSchema as en, standingOf as et, DoctorHostedSchema as f, DEFAULT_METER_CHARGE_MODE as fn, HEADER_API_VERSION as ft, DoctorSettingsSchema as g, EventRetentionDaysSchema as gn, InvoiceIssueResponseSchema as gt, DoctorReportSchema as h, DEFAULT_PORTAL_TTL_MINUTES as hn, HEADER_SDK as ht, DOCTOR_REQUIRED_LEGAL_LINKS as i, checkoutRedirectUrl as in, AccountDetailSchema as it, WebhookEndpointSchema as j, WebUrlSchema as jn, MANUAL_INVOICE_MAX_AMOUNT_MINOR as jt, WebhookEndpointListSchema as k, SettingsLocaleSchema as kn, InvoiceVoidInputSchema as kt, DoctorEmailsSchema as l, DEFAULT_CHECKOUT_TTL_MINUTES as ln, CreditGrantResponseSchema as lt, DoctorProviderSchema as m, DEFAULT_PAYMENT_DUE_DAYS as mn, HEADER_REQUEST_ID as mt, DOCTOR_PROVIDER_ENVIRONMENTS as n, MAX_CHECKOUT_CONSENT_DOCS as nn, errorCodeSpec as nt, DOCTOR_SEVERITIES as o, BillingSettingsSchema as on, CancelSubscriptionResponseSchema as ot, DoctorOverageSchema as p, DEFAULT_MIN_INVOICE_MINOR as pn, HEADER_IDEMPOTENCY_KEY as pt, meterChargeTotals as q, MAX_CATALOG_METERS as qn, CHECKOUT_ERRORS as qt, DOCTOR_REQUIRED_BRANDING as r, ProviderPayloadSchema as rn, isKnownErrorCode as rt, DoctorBillingSchema as s, BrandingPatchSchema as sn, ChangeSubscriptionResponseSchema as st, DOCTOR_PENDING_BACKLOG_MS as t, INDIVIDUAL_IDENTITY_PLACEHOLDER as tn, ERROR_CODES as tt, DoctorEndpointSchema as u, DEFAULT_EVENT_RETENTION_DAYS as un, GrantCreateResponseSchema as ut, DoctorUnsellablePriceSchema as v, EventsSettingsSchema as vn, InvoiceWaiveResponseSchema as vt, DEFAULT_ENDPOINT_EVENT_TYPES as w, PaymentDueDaysSchema as wn, InvoiceLineSchema as wt, emailReadinessOf as x, MeterChargeModeSchema as xn, STEWARD_CAPABILITIES as xt, DoctorWarningSchema as y, LateGraceMinutesSchema as yn, ManualInvoiceResponseSchema as yt, PlanSetModeSchema as z, CatalogPlanSchema as zn, MAX_GRANT_BENEFITS as zt };