@stewardhq/sdk 0.1.0-rc.0

package/dist/_chunks/events.js

@@ -0,0 +1,350 @@
+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). */
+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");
+const AmountMinorSchema = z.number().int().nonnegative();
+const IntervalSchema = z.enum(["month", "year"]);
+const DateTimeSchema = z.iso.datetime({ offset: true });
+/** Denetim izinde "kim yaptı": ör. `user:42`, `staff:7`, `system`. */
+const ActorRefSchema = z.string().min(1).max(200).regex(/^[a-z]+(:[A-Za-z0-9_.@-]+)?$/, "tür[:kimlik]");
+/**
+* Entitlement değeri. `null` = sınırsız (limit türünde); boolean = özellik
+* açık/kapalı; string = serbest ayar.
+*/
+const EntitlementValueSchema = z.union([
+	z.number().int().nonnegative(),
+	z.boolean(),
+	z.string(),
+	z.null()
+]);
+const EntitlementsSchema = z.record(CodeSchema, EntitlementValueSchema);
+const MetadataSchema = z.record(z.string().max(64), z.string().max(500));
+const ERROR_CATEGORIES = [
+	"validation",
+	"not_found",
+	"conflict",
+	"config",
+	"provider",
+	"unavailable"
+];
+const ErrorCategorySchema = z.enum(ERROR_CATEGORIES);
+/**
+* Hata gövdesi. `error` makine kodu (açık küme; bilinenler `ERROR_CODES`),
+* `message` insan için. `category`, `retryable` ve `requestId` 0.2'de eklendi;
+* eski steward göndermez. Bilinmeyen (gelecekteki) bir kategori hatayı
+* düşürmesin diye yok sayılır: kod her durumda okunur.
+*/
+const ErrorResponseSchema = z.object({
+	error: z.string(),
+	message: z.string().optional(),
+	category: ErrorCategorySchema.optional().catch(void 0),
+	retryable: z.boolean().optional().catch(void 0),
+	requestId: z.string().optional().catch(void 0)
+});
+//#endregion
+//#region ../contract/src/accounts.ts
+const AccountUpsertInputSchema = z.object({
+	displayName: z.string().min(1).max(200),
+	metadata: MetadataSchema.default({})
+});
+const BillingProfileKindSchema = z.enum(["individual", "company"]);
+const BillingProfileSchema = z.object({
+	kind: BillingProfileKindSchema,
+	contactName: z.string().min(2).max(200),
+	companyName: z.string().min(2).max(200).optional(),
+	taxOffice: z.string().min(2).max(100).optional(),
+	/** Kurumsal vergi kimliği (ör. VKN). Bireysel kimlik numarası profilde SAKLANMAZ. */
+	taxId: z.string().min(1).max(32).optional(),
+	email: z.email().max(200),
+	phone: z.string().regex(/^\+[1-9]\d{7,14}$/, "E.164 (+90…)"),
+	address: z.string().min(5).max(500),
+	city: z.string().min(2).max(100),
+	/** ISO-3166 alpha-2 */
+	country: z.string().regex(/^[A-Z]{2}$/).default("TR")
+}).superRefine((p, ctx) => {
+	if (p.kind === "company") {
+		for (const key of [
+			"companyName",
+			"taxOffice",
+			"taxId"
+		]) if (!p[key]) ctx.addIssue({
+			code: "custom",
+			path: [key],
+			message: "kurumsal profilde zorunlu"
+		});
+	}
+});
+const AccessStateSchema = z.enum(["active", "suspended"]);
+const SubscriptionStatusSchema = z.enum([
+	"active",
+	"past_due",
+	"suspended",
+	"canceled",
+	"expired"
+]);
+/** Snapshot içindeki canlı abonelik özeti (yoksa null). */
+const SubscriptionSummarySchema = z.object({
+	id: IdSchema,
+	status: SubscriptionStatusSchema,
+	planCode: CodeSchema,
+	interval: IntervalSchema,
+	amountMinor: AmountMinorSchema,
+	currency: CurrencySchema,
+	currentPeriodEnd: DateTimeSchema.nullable(),
+	/** Dönem sonunda iptal planlandıysa iptal anı. */
+	cancelAt: DateTimeSchema.nullable()
+});
+const EntitlementSnapshotSchema = z.object({
+	version: z.number().int().nonnegative(),
+	planCode: CodeSchema,
+	accessState: AccessStateSchema,
+	entitlements: EntitlementsSchema,
+	subscription: SubscriptionSummarySchema.nullable()
+});
+/** Dunning'deki aboneliğin adımı. `step` tamamlanan politika adımı sayısı (başlangıçta 0). */
+const AccountDunningStateSchema = z.object({
+	step: z.number().int().nonnegative(),
+	/** Sıradaki dunning aksiyonunun zamanı; kalmadıysa null. */
+	nextActionAt: DateTimeSchema.nullable()
+});
+/** Dönem sonunda uygulanacak plan değişikliği. F4b'ye kadar her zaman null. */
+const AccountScheduledChangeSchema = z.object({
+	planCode: CodeSchema,
+	interval: IntervalSchema,
+	effectiveAt: DateTimeSchema
+});
+const AccountSubscriptionStateSchema = SubscriptionSummarySchema.extend({
+	cancelAtPeriodEnd: z.boolean(),
+	/** `past_due`'ya düştüğü an (dunning başlangıcı); ödeme sorunu yoksa null. */
+	pastDueSince: DateTimeSchema.nullable(),
+	currentPeriodStart: DateTimeSchema.nullable(),
+	/** Abonelik dunning'de değilse null. */
+	dunning: AccountDunningStateSchema.nullable(),
+	/** F4b (`POST /v1/subscriptions/:id/change`) gelene kadar her zaman null. */
+	scheduledChange: AccountScheduledChangeSchema.nullable()
+});
+/** Hesabın açık (tamamlanmamış, süresi dolmamış) checkout oturumu. */
+const AccountOpenCheckoutSchema = z.object({
+	id: IdSchema,
+	planCode: CodeSchema,
+	interval: IntervalSchema,
+	intervalCount: z.number().int().min(1),
+	currency: CurrencySchema,
+	amountMinor: AmountMinorSchema,
+	expiresAt: DateTimeSchema
+});
+/** Fatura profili özeti: yalnızca var mı ve türü (alanlar PII, burada yok). */
+const AccountProfileStateSchema = z.object({
+	present: z.boolean(),
+	kind: BillingProfileKindSchema.nullable()
+});
+const AccountStateSchema = EntitlementSnapshotSchema.extend({
+	ref: ExternalRefSchema,
+	displayName: z.string(),
+	/** Durumun hesaplandığı an. Değişiklik algılamaya katılmaz. */
+	updatedAt: DateTimeSchema,
+	/**
+	* Durumun hesaplandığı katalog sürümü — opak metin (steward `GET /v1/catalog`
+	* ETag değerini tırnaksız koyar); katalog yoksa null. Değişiklik algılamaya
+	* katılmaz; katalog önbelleğinin bayat olup olmadığını anlamak için.
+	*/
+	catalogVersion: z.string().nullable(),
+	subscription: AccountSubscriptionStateSchema.nullable(),
+	openCheckout: AccountOpenCheckoutSchema.nullable(),
+	profile: AccountProfileStateSchema
+});
+const AccountSchema = z.object({
+	ref: ExternalRefSchema,
+	displayName: z.string(),
+	metadata: MetadataSchema,
+	createdAt: DateTimeSchema,
+	snapshot: EntitlementSnapshotSchema
+});
+const AccountDeleteResponseSchema = z.object({
+	ref: ExternalRefSchema,
+	deletedAt: DateTimeSchema
+});
+const ACCOUNT_INCLUDES = [
+	"profile",
+	"subscriptions",
+	"checkouts",
+	"payments",
+	"invoices",
+	"grants"
+];
+//#endregion
+//#region ../contract/src/events.ts
+const EventIdSchema = z.string().regex(/^evt_[0-9a-f-]{36}$/);
+const ApiVersionSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+const sub = { subscriptionId: IdSchema };
+const EVENT_DETAIL_SCHEMAS = {
+	"account.updated": z.object({ 
+	/** Snapshot'ın hangi alanları değişti (planCode, accessState, entitlements, subscription). */
+changed: z.array(z.string()) }),
+	"checkout.completed": z.object({
+		checkoutSessionId: IdSchema,
+		...sub
+	}),
+	"checkout.failed": z.object({
+		checkoutSessionId: IdSchema,
+		reason: z.string()
+	}),
+	"checkout.expired": z.object({ checkoutSessionId: IdSchema }),
+	"subscription.activated": z.object({
+		...sub,
+		planCode: CodeSchema,
+		interval: IntervalSchema,
+		amountMinor: AmountMinorSchema,
+		currency: CurrencySchema,
+		actorRef: z.string().nullable()
+	}),
+	"subscription.renewed": z.object({
+		...sub,
+		paymentId: IdSchema,
+		periodStart: DateTimeSchema.nullable(),
+		periodEnd: DateTimeSchema.nullable(),
+		invoiceId: IdSchema.nullable()
+	}),
+	"subscription.payment_failed": z.object({
+		...sub,
+		paymentId: IdSchema.nullable(),
+		/** Dunning'in kaçıncı başarısız denemesi (1'den başlar). */
+		attempt: z.number().int().positive(),
+		nextRetryAt: DateTimeSchema.nullable()
+	}),
+	"subscription.suspended": z.object({
+		...sub,
+		dunningDay: z.number().int().nonnegative()
+	}),
+	"subscription.reactivated": z.object({
+		...sub,
+		paymentId: IdSchema.nullable()
+	}),
+	"subscription.cancel_scheduled": z.object({
+		...sub,
+		cancelAt: DateTimeSchema,
+		reason: z.string(),
+		actorRef: z.string().nullable()
+	}),
+	"subscription.canceled": z.object({
+		...sub,
+		reason: z.string(),
+		effectiveAt: DateTimeSchema,
+		actorRef: z.string().nullable()
+	}),
+	"subscription.expired": z.object({
+		...sub,
+		effectiveAt: DateTimeSchema
+	}),
+	"subscription.terminated": z.object({
+		...sub,
+		reason: z.enum(["nonpayment"]),
+		dunningDay: z.number().int().nonnegative()
+	}),
+	"invoice.created": z.object({
+		invoiceId: IdSchema,
+		totalMinor: AmountMinorSchema,
+		currency: CurrencySchema
+	}),
+	"invoice.issued": z.object({
+		invoiceId: IdSchema,
+		number: z.string(),
+		totalMinor: AmountMinorSchema,
+		currency: CurrencySchema
+	}),
+	"invoice.voided": z.object({
+		invoiceId: IdSchema,
+		number: z.string().nullable(),
+		totalMinor: AmountMinorSchema,
+		currency: CurrencySchema,
+		reason: z.string()
+	}),
+	"account.state_changed": z.object({
+		cause: z.string().min(1).max(100),
+		/** Nedeni bir event ise onun id'si (aynı işlemde yayınlanan eski tip); iç nedende null. */
+		causeEventId: EventIdSchema.nullable()
+	}),
+	"account.deleted": z.object({
+		deletedAt: DateTimeSchema,
+		actorRef: z.string().nullable()
+	})
+};
+/** Tüm event tipleri (yenileri dahil). */
+const EVENT_TYPES = Object.keys(EVENT_DETAIL_SCHEMAS);
+/**
+* 0.1 sözleşmesinin 15 tipi: `event_types` filtresi olmayan (NULL) endpoint'in
+* aldığı küme. Değişmez; yeni tip buraya EKLENMEZ.
+*/
+const LEGACY_EVENT_TYPES = Object.freeze([
+	"account.updated",
+	"checkout.completed",
+	"checkout.failed",
+	"checkout.expired",
+	"subscription.activated",
+	"subscription.renewed",
+	"subscription.payment_failed",
+	"subscription.suspended",
+	"subscription.reactivated",
+	"subscription.cancel_scheduled",
+	"subscription.canceled",
+	"subscription.expired",
+	"subscription.terminated",
+	"invoice.created",
+	"invoice.issued"
+]);
+const FULL_STATE_EVENT_TYPES = /* @__PURE__ */ new Set(["account.state_changed", "account.deleted"]);
+function accountSchemaOf(type) {
+	return FULL_STATE_EVENT_TYPES.has(type) ? AccountStateSchema : EntitlementSnapshotSchema;
+}
+function envelope(type) {
+	return z.object({
+		id: EventIdSchema,
+		type: z.literal(type),
+		apiVersion: ApiVersionSchema,
+		createdAt: DateTimeSchema,
+		product: CodeSchema,
+		accountRef: ExternalRefSchema,
+		data: z.object({
+			account: accountSchemaOf(type),
+			detail: EVENT_DETAIL_SCHEMAS[type]
+		})
+	});
+}
+const ENVELOPES = Object.fromEntries(EVENT_TYPES.map((t) => [t, envelope(t)]));
+const BillingEventSchema = z.discriminatedUnion("type", Object.values(ENVELOPES));
+function isEventType(event, type) {
+	return event.type === type;
+}
+/**
+* Gevşek zarf: bu sürümün tanımadığı (gelecekteki) event tipini de kabul eder.
+* Alıcı önce `BillingEventSchema` dener; tutmazsa bununla id/version/hesap
+* alanlarını okuyup tekrarı ayıklar ve bilinmeyen tipi 2xx ile geçer (400
+* dönmek teslimat sırasını tıkar). `data.account` ve `data.detail` doğrulanmaz.
+*/
+const AnyBillingEventSchema = z.looseObject({
+	id: EventIdSchema,
+	type: z.string().min(1),
+	apiVersion: ApiVersionSchema,
+	createdAt: DateTimeSchema,
+	product: CodeSchema,
+	accountRef: ExternalRefSchema,
+	data: z.looseObject({
+		account: z.unknown(),
+		detail: z.unknown()
+	})
+});
+const PING_EVENT_TYPE = "endpoint.ping";
+const PingSchema = z.object({
+	id: EventIdSchema,
+	type: z.literal(PING_EVENT_TYPE),
+	apiVersion: ApiVersionSchema,
+	createdAt: DateTimeSchema,
+	product: CodeSchema,
+	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 };