@stewardhq/sdk 0.1.0-rc.0 → 0.3.0

package/README.md

@@ -17,7 +17,7 @@ ESM, Node ≥ 22. Tek çalışma zamanı bağımlılığı zod.
 
 | Import | İçerik |
 | --- | --- |
-| `@stewardhq/sdk` | Tüm şema/tipler + istemciler (`createSteward`, `createCatalogCache`, `stateCache`, fırlatmayan `createBillingClient`) + yardımcılar: hata sınıfları, `httpStatusFor`, `errorMessages`/`messageFor`, `defineCatalog`, `formatPrice`/`taxBreakdown`, `isValidTckn`/`isValidVkn`/`isE164` |
+| `@stewardhq/sdk` | Tüm şema/tipler + fırlatan istemci `createSteward`, hesap durumu önbelleği `stateCache`, `defineCatalog`, hata sınıfları + `httpStatusFor`, `isValidTckn`/`isValidVkn`/`isE164` |
 | `@stewardhq/sdk/contract` | Yalnızca şemalar ve tipler |
 | `@stewardhq/sdk/webhook` | `signWebhook` / `verifyWebhook` / `verifyWebhookRaw` (Node HMAC, senkron) |
 | `@stewardhq/sdk/webhook/web` | Aynı API WebCrypto ile (async; edge/workerd/tarayıcı) |
@@ -127,7 +127,7 @@ import { Checkout } from "@stewardhq/sdk/server";
 const checkout = Checkout({
   steward, cache: state,
   // mutlak; origin steward ayarında izinli (appUrl + extraReturnOrigins). Yer tutucular varsa
-  // steward yalnızca onları doldurur, yoksa ?session=&status= ekler.
+  // steward yalnızca onları doldurur; yoksa adres aynen kullanılır (parametre eklenmez).
   successUrl: `${process.env.APP_URL}/{LOCALE}/app/orgs/{ACCOUNT_REF}/billing?checkout={CHECKOUT_ID}`,
   consents: (locale) => legalDocs(locale),  // [{document, version, url}] ya da dizi; sayfada onaylatılır
   // cancelUrl (yoksa ayar appUrl), locale ve currency (yoksa ürün ayarı)
@@ -155,9 +155,8 @@ app.get("/v1/orgs/:orgId/billing/checkout/:id", async (c) =>          // dönü
 | Yanıtta `url` yok (F2b öncesi steward) | `StewardContractError` |
 
 Kullanıcı sayfayı kapatırsa oturum süresi dolunca (`checkoutTtlMinutes`) steward kapatır;
-ürün sonucu `account.state_changed` ile öğrenir. `profile` + `identityNumber` taşıyan eski gövde
-(`steward.checkoutSessions.create`) açılışta sağlayıcı formu döndürmeye devam eder (N3 + 1
-release sonra kaldırılır).
+ürün sonucu `account.state_changed` ile öğrenir. `steward.checkoutSessions.create` de yalnızca
+hosted gövdeyi kabul eder; fatura profili yalnızca hosted checkout ve portal sayfalarında yazılır.
 
 Hosted müşteri portalı (`/server`) — abonelik durumu, dönem sonunda iptal, ödemeyi yeniden dene,
 fatura listesi/PDF ve kurumsal fatura profili steward'ın sayfasında; ürün yalnızca yetkiyi
@@ -211,22 +210,20 @@ await steward.grants.create(accountRef, { planCode: "team", reason: "kurumsal s
 
 | Kaynak | Metotlar |
 | --- | --- |
-| `accounts` | `upsert(ref, input)`, `get(ref, {include?})`, `state(ref)`, `readState(ref, {etag?})` (304 → `{notModified: true}`), `entitlements(ref)`, `putBillingProfile(ref, profile)`, `setPlan(ref, {planCode \| null, reason, mode?, endsAt?, overrides?})` → `{grant, account, warnings}` (canlı abonelik planı hedefi geçiyorsa `mode: "ensure"` uyarı, `"strict"` `subscription_plan_higher`), `resync(ref)` → `{queued, eventId}` (saklı durum `account.state_changed`, `cause: "resync"`), `delete(ref)` → `{ref, deletedAt}` (KVKK anonimleştirme; faturalar kalır; önce canlı abonelik `immediate` iptal — yoksa `subscription_active`, formu açık checkout'ta `checkout_in_progress`; sonra hesabın her ucu `account_deleted` 410) |
+| `accounts` | `upsert(ref, input)`, `get(ref, {include?})`, `state(ref)`, `readState(ref, {etag?})` (304 → `{notModified: true}`), `setPlan(ref, {planCode \| null, reason, mode?, endsAt?, overrides?})` → `{grant, account, warnings}` (canlı abonelik planı hedefi geçiyorsa `mode: "ensure"` uyarı, `"strict"` `subscription_plan_higher`), `resync(ref)` → `{queued, eventId}` (saklı durum `account.state_changed`, `cause: "resync"`), `delete(ref)` → `{ref, deletedAt}` (KVKK anonimleştirme; faturalar kalır; önce canlı abonelik `immediate` iptal — yoksa `subscription_active`, formu açık checkout'ta `checkout_in_progress`; sonra hesabın her ucu `account_deleted` 410) |
 | `checkoutSessions` | `create(ref, input)`, `get(id)` |
 | `portalSessions` | `create(ref, {locale?, returnUrl?})` → `{id, url, expiresAt}` (hosted müşteri portalı; `CustomerPortal()` bunu sarar) |
 | `subscriptions` | `cancel(id, input)` |
 | `grants` | `create(ref, input)`, `revoke(id)` |
 | `invoices` | `issue(id, input)`, `document(id)` → `{contentType, bytes}`, `createManual(ref, {lines, currency, taxRateBps, taxInclusive?, dueAt?, note?})` (manuel taslak; profil gerekir, `issue` ile kesilir), `void(id, {reason})` (yalnızca manuel fatura; `invoice.voided` yalnızca filtresinde isteyen endpoint'e) |
 | `catalog` | `get()`, `read({etag?})` |
-| `events` | `list({accountRef?, cursor?, limit?})`, `redeliver(id)` |
 | — | `stats()`, `me()`, `doctor()` → kurulum teşhisi (`GET /v1/doctor`; aşağıda) |
 | `admin` | `catalog.sync(input)`, `accounts.refresh()`, `settings.{get(), update(patch)}`, `endpoints.{list(), create(input), rotate(id, {secret}), deactivate(id)}` — `STEWARD_ADMIN_URL` + `STEWARD_ADMIN_API_KEY` (ya da `adminBaseUrl`/`adminApiKey`) ister; yoksa çağrıda `StewardConfigError` |
-| `raw` | Fırlatmayan, tekrar denemeyen sözleşme istemcisi (`createBillingClient`; `{ ok, data }` / `{ ok: false, status, error }`) |
 
 - **Mutasyonlar** son argümanda `{ idempotencyKey?, actorRef? }` alır. Anahtar
   verilmezse çağrı başına üretilir; `actorRef` verilmezse `createSteward`'daki varsayılan gider.
   İkisi de yoksa ya da biçimi geçersizse (`tür[:kimlik]`) istek **gitmez**: `StewardConfigError`
-  (`code` servisinkiyle aynı: `actor_ref_required` / `invalid_actor_ref`). `raw` bu denetimi yapmaz.
+  (`code` servisinkiyle aynı: `actor_ref_required` / `invalid_actor_ref`).
 - **Yalnızca yönetim:** `STEWARD_URL` ve `STEWARD_API_KEY` ikisi de yoksa ve `STEWARD_ADMIN_URL` +
   `STEWARD_ADMIN_API_KEY` (ya da `adminBaseUrl`/`adminApiKey`) verilmişse istemci kurulur (CLI, katalog
   senkronu): `admin.*` çalışır, iki kapsama açık `doctor()` ve `me()` admin anahtarıyla gider, ürün uçları
@@ -279,16 +276,6 @@ const report = await steward.doctor();
 Kodlar ve teşhisler açık kümedir (bilinmeyeni yalnızca gösterin). `provider.healthy` ve
 `lastError` yanıtı veren steward pod'unun gözlemidir.
 
-Katalog önbelleği — TTL içinde bellekten, sonra `If-None-Match` (304 gövdeyi korur);
-eşzamanlı çağrılar tek istek; başarılı okumadan sonraki hatada bayat değer + `logger.warn`:
-
-```ts
-import { createCatalogCache } from "@stewardhq/sdk";
-
-const catalogCache = createCatalogCache(steward, { ttlMs: 60_000, logger });
-const { plans, prices } = await catalogCache.get();
-```
-
 Katalog — kodda tipli tanım; eksik/fazla hak, yanlış tip (`limit` → tam sayı ya da
 `null` = sınırsız, `flag` → boolean, `text` → string) ve tanımsız plana fiyat derleme
 hatasıdır, tipler atlatılırsa tanım anında `StewardConfigError` fırlatır (TypeScript ≥ 5.4):
@@ -317,25 +304,24 @@ const placeholder = catalog.stateOf("org_1", "team", { accessState: "active", di
 katalogda yoksa varsayılan plandan) alır, asla "sınırsız" üretmez; `onFallback`
 ile alarm verilebilir. Snapshot yoksa varsayılan planın hakları.
 
-Hatalar ve metinler — ürün API'sinin durum kodu ve kullanıcı metni:
+Hatalar — ürün API'sinin durum kodu:
 
 ```ts
-import { httpStatusFor, messageFor, StewardError } from "@stewardhq/sdk";
+import { httpStatusFor, StewardError } from "@stewardhq/sdk";
 
 if (error instanceof StewardError) {
   const { status, headers } = httpStatusFor(error, { logger }); // already_subscribed 409, rate_limited 503 + Retry-After…
-  return Response.json({ error: error.code, message: messageFor(error.code, locale) }, { status, headers });
+  return Response.json({ error: error.code }, { status, headers });
 }
 ```
 
 Tabloda olmayan kod `category`'ye göre eşlenir (`not_found` 404, `conflict` 409,
 `provider` 502, `unavailable` 503; `validation`/`config` 500 + ERROR log).
-`errorMessages.{tr,en}` sözleşmenin `ERROR_CODES` kaydındaki her kodu ve istemci
-kodlarını (`network_error`, `timeout`, `invalid_response`, `config_error`) kapsar.
+Kullanıcıya gösterilen metin ürünündür (`error.code` → kendi i18n'iniz); `error.message`
+log içindir (steward'ın mesajı, yoksa kod). Fiyat gösterimi hosted checkout/portal
+sayfalarındadır; SDK para biçimlendirme yardımcısı taşımaz.
 
-Para ve doğrulayıcılar: `formatPrice(price, "tr")` → `₺1.250,00 · KDV dahil`;
-`taxBreakdown(price)` servisin faturadaki matrah/KDV ayrıştırmasıyla kuruşu kuruşuna
-aynıdır. `isValidTckn`, `isValidVkn` (sağlama hanesi), `isE164(value, {country: "TR"}?)`
+Doğrulayıcılar: `isValidTckn`, `isValidVkn` (sağlama hanesi), `isE164(value, {country: "TR"}?)`
 değeri olduğu gibi denetler (boşluk kırpmaz).
 
 Testler (`/testing`, Node) — sahte steward sunucu açmaz, `fetch` verir; başlıkları
@@ -352,7 +338,7 @@ const fake = createFakeSteward({
 });
 fake.connect((req) => webhooks.handle(req));           // alıcı sonradan (ya da webhook.handler); uygulama fake'ten sonra kurulabilir
 const steward = fake.steward;                          // ya da ürünün kendi createSteward({ fetch: fake.fetch, baseUrl: fake.baseUrl, … })
-await steward.accounts.upsert("org_1", { displayName: "Org" });
+await steward.accounts.upsert("org_1", { displayName: "Org", notificationEmails: ["owner@acme.com"] }); // billing email recipients (optional)
 const session = await steward.checkoutSessions.create("org_1", input);
 await fake.simulate.checkoutCompleted(session.id);     // ya da checkoutFailed; hosted oturumda checkoutCanceled da
 
@@ -378,19 +364,25 @@ await fake.simulate.renewal("org_1", { fail: true });  // saat dönem sonuna; pa
 await fake.simulate.advance({ days: 7 });              // zamanlanmış işler kendi anında (dunning, dönem sonu iptali, checkout süresi, grant penceresi, portal oturumu silme)
 fake.simulate.outage(true, { mode: "503" });           // ya da "network": fetch reddeder
 await fake.simulate.deliver("account.state_changed", { ref: "org_1", duplicate: true, outOfOrder: true });
+fake.simulate.redeliver(eventId);                      // operatörün pod CLI `redeliver-event`'i: aynı event sonraki flush'ta yeniden
+
+fake.emails("org_1");                                  // billing emails steward would send: [{ template, to, locale, eventId, … }]
 
 const { request } = signedEvent("subscription.renewed", { accountRef: "org_1" }, { secret });
 await webhooks.handle(request());
 ```
 
-`fake.requests` gelen istekleri, `fake.events(ref?)` yayınlanan event'leri tutar. Endpoint `webhook`
+`fake.requests` gelen istekleri, `fake.events(ref?)` yayınlanan event'leri tutar. `fake.emails(ref?)`
+steward'ın göndereceği faturalandırma e-postalarını servisle aynı kurallarla (şablon, gönderim anındaki
+alaka, alıcılar, dil, kapatılmış şablon) listeler; içerik render edilmez ve gönderim gecikmesizdir
+([e-postalar](../docs/integrate/emails.md#test)). Endpoint `webhook`
 seçeneğiyle oluşturmada açılır; filtre verilmezse yönetim ucunun yeni ürüne verdiği
 `["account.state_changed"]`, `eventTypes: "legacy"` pod CLI'nın filtresiz (15 eski tip) endpoint'i.
 Alıcı bağlanmadan `flush`/`deliver` fırlatır (event'ler outbox'ta bekler); `connect` alıcıyı değiştirir.
 Sahtenin bilerek farklı olduğu yerler: teslimat asenkron değil (`flush()`), `dead`
 olmaz ve geri çekilme beklenmez; sağlayıcı hata vermez; dönüş origin'i (`settings.appUrl`,
 `settings.extraReturnOrigins` ya da kısayolu `returnOrigins`) hiç ayarlanmazsa her
-`returnUrl` kabul; `admin.endpoints` ile açılan endpoint yalnızca kayıttır (teslimat
+`successUrl`/`cancelUrl`/`returnUrl` kabul; `admin.endpoints` ile açılan endpoint yalnızca kayıttır (teslimat
 `webhook` seçeneğinin alıcısına gider, `lastDelivery` hep null; `doctor()`'da teşhisi
 `no_deliveries`, sağlayıcı `fake` ve sağlıklı); dunning'de yeniden deneme
 sonucu `renewal` ile gelir; her yanıt `X-Request-Id` (hata gövdesinde `requestId`) taşır;
@@ -419,14 +411,16 @@ sonuçlandırmaz: servisteki gibi sonuç sonradan gelir — `simulate.renewal(re
 siparişi başarılı sayar (`subscription.reactivated`), `{fail: true}` yine başarısız.
 `simulate.portalCancel/portalRetryPayment` bilinmeyen ya da süresi geçmiş oturumda fırlatır.
 
-## `@z9cloud/steward-contract`'tan geçiş
+## `@steward/contract`'tan geçiş
 
 | Eski | Yeni |
 | --- | --- |
 | `@z9cloud/steward-contract` | `@stewardhq/sdk` (ya da yalnız şema için `@stewardhq/sdk/contract`) |
-| `@z9cloud/steward-contract/client` | `@stewardhq/sdk` (`createBillingClient` aynen; fırlatan istemci `createSteward`) |
+| `@z9cloud/steward-contract/client` | `@stewardhq/sdk` `createSteward` (fırlatan; fırlatmayan `createBillingClient` dışa açılmaz) |
 | `@z9cloud/steward-contract/webhook` | `@stewardhq/sdk/webhook` |
 | `@z9cloud/steward-contract/fixtures/events/*.json` | `@stewardhq/sdk/testing/fixtures/events/*.json` |
+| `getEntitlements(ref)` / `accounts.entitlements(ref)` | `accounts.state(ref)` ya da `stateCache` (tek okuma modeli `AccountState`; uç 2026-09-16'da kaldırıldı) |
+| `listEvents` / `redeliverEvent` / `events.*` | Yok (2026-09-16): kaçırılan durum için `accounts.resync(ref)`; dead teslimatı operatör pod CLI `redeliver-event` ile yeniden gönderir (testte `fake.simulate.redeliver`) |
 
 GitHub Packages `.npmrc` satırı ve Docker `--secret` bağlaması artık gerekmez.
 
@@ -434,4 +428,4 @@ GitHub Packages `.npmrc` satırı ve Docker `--secret` bağlaması artık gerekm
 
 Semver. Alan kaldırma/yeniden adlandırma kırıcıdır (major; 1.0 öncesi minor).
 Yayın: `sdk/package.json` sürümü artırılır, `sdk-v<sürüm>` etiketi push edilir
-(`.github/workflows/sdk-publish.yml`, npm provenance ile).
+(`.github/workflows/sdk-publish.yml`).

package/dist/_chunks/errors.js

@@ -1,4 +1,4 @@
-import { R as errorCodeSpec } from "./src.js";
+import { B as errorCodeSpec } from "./src.js";
 //#region src/errors.ts
 var StewardError = class extends Error {
 	code;

package/dist/_chunks/events.d.ts

@@ -1,8 +1,17 @@
 import { z } from "zod";
 //#region ../contract/src/accounts.d.ts
+declare const AccountLocaleSchema: z.ZodEnum<{
+  tr: "tr";
+  en: "en";
+}>;
 declare const AccountUpsertInputSchema: z.ZodObject<{
   displayName: z.ZodString;
   metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+  notificationEmails: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodEmail>, z.ZodTransform<string[], string[]>>>;
+  locale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+    tr: "tr";
+    en: "en";
+  }>>>;
 }, z.core.$strip>;
 type AccountUpsertInput = z.input<typeof AccountUpsertInputSchema>;
 declare const BillingProfileKindSchema: z.ZodEnum<{
@@ -263,6 +272,11 @@ declare const AccountSchema: z.ZodObject<{
       cancelAt: z.ZodNullable<z.ZodISODateTime>;
     }, z.core.$strip>>;
   }, z.core.$strip>;
+  notificationEmails: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  locale: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+    tr: "tr";
+    en: "en";
+  }>>>;
 }, z.core.$strip>;
 type Account = z.infer<typeof AccountSchema>;
 declare const AccountDeleteResponseSchema: z.ZodObject<{
@@ -534,4 +548,4 @@ declare const PingSchema: z.ZodObject<{
 }, z.core.$strip>;
 type Ping = z.infer<typeof PingSchema>;
 //#endregion
-export { AccountProfileState as A, AccountUpsertInputSchema as B, AccountDeleteResponse as C, AccountInclude as D, AccountDunningStateSchema as E, AccountState as F, EntitlementSnapshot as G, BillingProfileInput as H, AccountStateSchema as I, SubscriptionStatusSchema as J, EntitlementSnapshotSchema as K, AccountSubscriptionState as L, AccountScheduledChange as M, AccountScheduledChangeSchema as N, AccountOpenCheckout as O, AccountSchema as P, AccountSubscriptionStateSchema as R, Account as S, AccountDunningState as T, BillingProfileKindSchema as U, BillingProfile as V, BillingProfileSchema as W, SubscriptionSummarySchema as X, SubscriptionSummary as Y, PingSchema as _, BillingEvent as a, AccessState as b, EVENT_DETAIL_SCHEMAS as c, EventIdSchema as d, EventType as f, Ping as g, PING_EVENT_TYPE as h, ApiVersionSchema as i, AccountProfileStateSchema as j, AccountOpenCheckoutSchema as k, EVENT_TYPES as l, LegacyEventType as m, AnyBillingEvent as n, BillingEventOf as o, LEGACY_EVENT_TYPES as p, SubscriptionStatus as q, AnyBillingEventSchema as r, BillingEventSchema as s, AccountStateChangeCause as t, EventDetail as u, isEventType as v, AccountDeleteResponseSchema as w, AccessStateSchema as x, ACCOUNT_INCLUDES as y, AccountUpsertInput as z };
+export { AccountOpenCheckoutSchema as A, AccountUpsertInput as B, AccountDeleteResponse as C, AccountInclude as D, AccountDunningStateSchema as E, AccountSchema as F, BillingProfileSchema as G, BillingProfile as H, AccountState as I, SubscriptionStatus as J, EntitlementSnapshot as K, AccountStateSchema as L, AccountProfileStateSchema as M, AccountScheduledChange as N, AccountLocaleSchema as O, AccountScheduledChangeSchema as P, AccountSubscriptionState as R, Account as S, AccountDunningState as T, BillingProfileInput as U, AccountUpsertInputSchema as V, BillingProfileKindSchema as W, SubscriptionSummary as X, SubscriptionStatusSchema as Y, SubscriptionSummarySchema as Z, PingSchema as _, BillingEvent as a, AccessState as b, EVENT_DETAIL_SCHEMAS as c, EventIdSchema as d, EventType as f, Ping as g, PING_EVENT_TYPE as h, ApiVersionSchema as i, AccountProfileState as j, AccountOpenCheckout as k, EVENT_TYPES as l, LegacyEventType as m, AnyBillingEvent as n, BillingEventOf as o, LEGACY_EVENT_TYPES as p, EntitlementSnapshotSchema as q, AnyBillingEventSchema as r, BillingEventSchema as s, AccountStateChangeCause as t, EventDetail as u, isEventType as v, AccountDeleteResponseSchema as w, AccessStateSchema as x, ACCOUNT_INCLUDES as y, AccountSubscriptionStateSchema as z };

package/dist/_chunks/events.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 //#region ../contract/src/common.ts
 const API_VERSION = "2026-10-01";
 const CodeSchema = z.string().regex(/^[a-z][a-z0-9_]{0,62}$/, "küçük harf, rakam ve _ (harfle başlar)");
-/** Ürün tarafındaki değişmez kimlik (ör. nixscale'de ağın shortId'si). */
+/** Immutable product-side identity (e.g. the id of an org in the product). */
 const ExternalRefSchema = z.string().min(1).max(200).regex(/^[A-Za-z0-9_.:-]+$/, "yalnızca harf, rakam ve _ . : -");
 const IdSchema = z.uuid();
 const CurrencySchema = z.string().regex(/^[A-Z]{3}$/, "ISO-4217 kodu");
@@ -46,10 +46,174 @@ const ErrorResponseSchema = z.object({
 	requestId: z.string().optional().catch(void 0)
 });
 //#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"
+];
+const EmailTemplateSchema = z.enum(EMAIL_TEMPLATES);
+/** Which event triggers which template. Events not listed send no email. */
+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;
+	}
+}
+/**
+* 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.
+*/
+function isEmailRelevant(template, facts) {
+	const live = facts.state.subscription;
+	const same = live !== null && live.id === facts.subscriptionId;
+	switch (template) {
+		case "subscription_started":
+		case "payment_receipt":
+		case "subscription_terminated": return true;
+		case "payment_failed": return same && live.status === "past_due";
+		case "cancel_scheduled": return same && live.cancelAtPeriodEnd;
+		case "subscription_ended": return live === null;
+		case "access_suspended": return same && live.status === "suspended";
+		case "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({
@@ -162,7 +326,11 @@ const AccountSchema = z.object({
 	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,
@@ -347,4 +515,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 { CurrencySchema as $, EMAIL_LOCALES as A, NotificationEmailsSchema as B, BillingProfileKindSchema as C, SubscriptionSummarySchema as D, SubscriptionStatusSchema as E, EmailSettingsPatchSchema as F, emailTemplateOf as G, billingPageUrl as H, EmailSettingsSchema as I, uniqueEmails as J, emailTemplateSettings as K, EmailTemplateSchema as L, EMAIL_TEMPLATE_BY_EVENT as M, EmailExtraTextSchema as N, BILLING_PATH_PLACEHOLDERS as O, EmailSenderSchema as P, CodeSchema as Q, EmailTemplateSettingsSchema as R, AccountUpsertInputSchema as S, EntitlementSnapshotSchema as T, emailLocaleOf as U, applyEmailSettingsPatch as V, emailRecipients as W, ActorRefSchema as X, API_VERSION as Y, AmountMinorSchema as Z, AccountProfileStateSchema as _, EVENT_TYPES as a, ErrorResponseSchema as at, AccountStateSchema as b, PING_EVENT_TYPE as c, IntervalSchema as ct, ACCOUNT_INCLUDES as d, DateTimeSchema as et, AccessStateSchema as f, AccountOpenCheckoutSchema as g, AccountLocaleSchema as h, EVENT_DETAIL_SCHEMAS as i, ErrorCategorySchema as it, EMAIL_TEMPLATES as j, BillingPathSchema as k, PingSchema as l, MetadataSchema as lt, AccountDunningStateSchema as m, ApiVersionSchema as n, EntitlementValueSchema as nt, EventIdSchema as o, ExternalRefSchema as ot, AccountDeleteResponseSchema as p, isEmailRelevant as q, BillingEventSchema as r, EntitlementsSchema as rt, LEGACY_EVENT_TYPES as s, IdSchema as st, AnyBillingEventSchema as t, ERROR_CATEGORIES as tt, isEventType as u, AccountScheduledChangeSchema as v, BillingProfileSchema as w, AccountSubscriptionStateSchema as x, AccountSchema as y, MAX_NOTIFICATION_EMAILS as z };