@stewardhq/sdk 0.2.0 → 0.3.0

package/README.md

@@ -338,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
 
@@ -366,11 +366,16 @@ fake.simulate.outage(true, { mode: "503" });           // ya da "network": fetch
 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.
@@ -423,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

@@ -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 };