@sygnl/event-schema 1.0.0

package/dist/index.cjs

@@ -0,0 +1,573 @@
+'use strict';
+
+var zod = require('zod');
+
+// src/base.ts
+var BaseEventMetadataSchema = zod.z.object({
+  /** Unique event identifier */
+  event_id: zod.z.string(),
+  /** ISO timestamp when event occurred */
+  timestamp: zod.z.number().int().positive(),
+  /** Event source */
+  source: zod.z.enum(["pixel", "server", "webhook", "api"]),
+  /** User's anonymous identifier */
+  anonymous_id: zod.z.string().optional(),
+  /** User's authenticated identifier */
+  user_id: zod.z.string().optional(),
+  /** Session identifier */
+  session_id: zod.z.string().optional()
+});
+var MoneySchema = zod.z.object({
+  /** Amount in the specified currency */
+  amount: zod.z.number(),
+  /** ISO 4217 currency code */
+  currency: zod.z.string().length(3).toUpperCase()
+});
+var ProductSchema = zod.z.object({
+  /** Unique product identifier */
+  product_id: zod.z.string(),
+  /** Product name */
+  name: zod.z.string(),
+  /** Product SKU */
+  sku: zod.z.string().optional(),
+  /** Product category */
+  category: zod.z.string().optional(),
+  /** Product brand */
+  brand: zod.z.string().optional(),
+  /** Product variant (size, color, etc.) */
+  variant: zod.z.string().optional(),
+  /** Unit price */
+  price: zod.z.number(),
+  /** Quantity */
+  quantity: zod.z.number().int().positive().default(1),
+  /** Currency code */
+  currency: zod.z.string().length(3).toUpperCase().default("USD"),
+  /** Product image URL */
+  image_url: zod.z.string().url().optional(),
+  /** Product URL */
+  url: zod.z.string().url().optional()
+});
+var CartSchema = zod.z.object({
+  /** Cart identifier */
+  cart_id: zod.z.string().optional(),
+  /** Products in cart */
+  products: zod.z.array(ProductSchema).min(1),
+  /** Cart total */
+  total: MoneySchema,
+  /** Subtotal (before tax/shipping) */
+  subtotal: MoneySchema.optional(),
+  /** Tax amount */
+  tax: MoneySchema.optional(),
+  /** Shipping amount */
+  shipping: MoneySchema.optional(),
+  /** Discount amount */
+  discount: MoneySchema.optional(),
+  /** Coupon code used */
+  coupon: zod.z.string().optional()
+});
+var PageContextSchema = zod.z.object({
+  /** Current page URL */
+  url: zod.z.string().url().optional(),
+  /** Page path */
+  path: zod.z.string().optional(),
+  /** Page title */
+  title: zod.z.string().optional(),
+  /** Referrer URL */
+  referrer: zod.z.string().url().optional(),
+  /** Search query (if applicable) */
+  search: zod.z.string().optional()
+});
+var UserTraitsSchema = zod.z.object({
+  /** Email address */
+  email: zod.z.string().email().optional(),
+  /** Phone number */
+  phone: zod.z.string().optional(),
+  /** First name */
+  first_name: zod.z.string().optional(),
+  /** Last name */
+  last_name: zod.z.string().optional(),
+  /** Company name */
+  company: zod.z.string().optional(),
+  /** Job title */
+  title: zod.z.string().optional(),
+  /** Address city */
+  city: zod.z.string().optional(),
+  /** Address state/region */
+  state: zod.z.string().optional(),
+  /** Address country */
+  country: zod.z.string().optional(),
+  /** Postal code */
+  postal_code: zod.z.string().optional(),
+  /** Avatar/profile image URL */
+  avatar: zod.z.string().url().optional()
+});
+var ProductViewedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("product_viewed"),
+  product: ProductSchema,
+  page: PageContextSchema.optional()
+});
+var ProductListViewedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("product_list_viewed"),
+  list_id: zod.z.string().optional(),
+  list_name: zod.z.string().optional(),
+  category: zod.z.string().optional(),
+  products: zod.z.array(ProductSchema),
+  page: PageContextSchema.optional()
+});
+var ProductAddedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("product_added"),
+  product: ProductSchema,
+  cart: CartSchema.optional()
+});
+var ProductRemovedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("product_removed"),
+  product: ProductSchema,
+  cart: CartSchema.optional()
+});
+var CartViewedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("cart_viewed"),
+  cart: CartSchema
+});
+var CheckoutStartedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("checkout_started"),
+  cart: CartSchema,
+  checkout_id: zod.z.string().optional()
+});
+var CheckoutStepCompletedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("checkout_step_completed"),
+  checkout_id: zod.z.string(),
+  step: zod.z.number().int().positive(),
+  step_name: zod.z.string().optional(),
+  shipping_method: zod.z.string().optional(),
+  payment_method: zod.z.string().optional()
+});
+var PaymentInfoEnteredEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("payment_info_entered"),
+  checkout_id: zod.z.string(),
+  payment_method: zod.z.string(),
+  cart: CartSchema.optional()
+});
+var OrderCompletedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("order_completed"),
+  order_id: zod.z.string(),
+  checkout_id: zod.z.string().optional(),
+  total: MoneySchema,
+  subtotal: MoneySchema.optional(),
+  revenue: MoneySchema,
+  tax: MoneySchema.optional(),
+  shipping: MoneySchema.optional(),
+  discount: MoneySchema.optional(),
+  coupon: zod.z.string().optional(),
+  products: zod.z.array(ProductSchema),
+  payment_method: zod.z.string().optional(),
+  shipping_method: zod.z.string().optional()
+});
+var OrderUpdatedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("order_updated"),
+  order_id: zod.z.string(),
+  total: MoneySchema.optional(),
+  status: zod.z.string().optional(),
+  products: zod.z.array(ProductSchema).optional()
+});
+var OrderRefundedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("order_refunded"),
+  order_id: zod.z.string(),
+  refund_amount: MoneySchema,
+  refund_reason: zod.z.string().optional(),
+  products: zod.z.array(ProductSchema).optional()
+});
+var OrderCancelledEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("order_cancelled"),
+  order_id: zod.z.string(),
+  cancel_reason: zod.z.string().optional()
+});
+var EcommerceEventSchema = zod.z.discriminatedUnion("event_type", [
+  ProductViewedEventSchema,
+  ProductListViewedEventSchema,
+  ProductAddedEventSchema,
+  ProductRemovedEventSchema,
+  CartViewedEventSchema,
+  CheckoutStartedEventSchema,
+  CheckoutStepCompletedEventSchema,
+  PaymentInfoEnteredEventSchema,
+  OrderCompletedEventSchema,
+  OrderUpdatedEventSchema,
+  OrderRefundedEventSchema,
+  OrderCancelledEventSchema
+]);
+var SubscriptionPlanSchema = zod.z.object({
+  plan_id: zod.z.string(),
+  plan_name: zod.z.string(),
+  plan_type: zod.z.enum(["free", "trial", "paid"]).optional(),
+  billing_period: zod.z.enum(["monthly", "yearly", "quarterly", "lifetime"]).optional(),
+  price: MoneySchema.optional()
+});
+var UserSignedUpEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("user_signed_up"),
+  user_traits: UserTraitsSchema.optional(),
+  signup_method: zod.z.enum(["email", "google", "github", "sso", "other"]).optional(),
+  referral_code: zod.z.string().optional()
+});
+var UserInvitedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("user_invited"),
+  invited_email: zod.z.string().email(),
+  inviter_id: zod.z.string(),
+  role: zod.z.string().optional(),
+  team_id: zod.z.string().optional()
+});
+var UserLoggedInEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("user_logged_in"),
+  login_method: zod.z.enum(["email", "google", "github", "sso", "other"]).optional()
+});
+var UserLoggedOutEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("user_logged_out")
+});
+var AccountCreatedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("account_created"),
+  account_id: zod.z.string(),
+  account_name: zod.z.string(),
+  plan: SubscriptionPlanSchema.optional()
+});
+var AccountDeletedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("account_deleted"),
+  account_id: zod.z.string(),
+  delete_reason: zod.z.string().optional()
+});
+var TrialStartedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("trial_started"),
+  plan: SubscriptionPlanSchema,
+  trial_days: zod.z.number().int().positive(),
+  trial_end_date: zod.z.number().int().positive()
+});
+var TrialConvertedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("trial_converted"),
+  from_plan: SubscriptionPlanSchema,
+  to_plan: SubscriptionPlanSchema
+});
+var TrialEndedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("trial_ended"),
+  plan: SubscriptionPlanSchema,
+  converted: zod.z.boolean()
+});
+var SubscriptionStartedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("subscription_started"),
+  subscription_id: zod.z.string(),
+  plan: SubscriptionPlanSchema,
+  billing_period_start: zod.z.number().int().positive(),
+  billing_period_end: zod.z.number().int().positive()
+});
+var SubscriptionUpgradedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("subscription_upgraded"),
+  subscription_id: zod.z.string(),
+  from_plan: SubscriptionPlanSchema,
+  to_plan: SubscriptionPlanSchema,
+  prorated_amount: MoneySchema.optional()
+});
+var SubscriptionDowngradedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("subscription_downgraded"),
+  subscription_id: zod.z.string(),
+  from_plan: SubscriptionPlanSchema,
+  to_plan: SubscriptionPlanSchema,
+  effective_date: zod.z.number().int().positive().optional()
+});
+var SubscriptionCancelledEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("subscription_cancelled"),
+  subscription_id: zod.z.string(),
+  plan: SubscriptionPlanSchema,
+  cancel_reason: zod.z.string().optional(),
+  cancel_at_period_end: zod.z.boolean().default(true),
+  effective_date: zod.z.number().int().positive().optional()
+});
+var SubscriptionRenewedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("subscription_renewed"),
+  subscription_id: zod.z.string(),
+  plan: SubscriptionPlanSchema,
+  billing_period_start: zod.z.number().int().positive(),
+  billing_period_end: zod.z.number().int().positive()
+});
+var SubscriptionPausedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("subscription_paused"),
+  subscription_id: zod.z.string(),
+  pause_reason: zod.z.string().optional()
+});
+var SubscriptionResumedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("subscription_resumed"),
+  subscription_id: zod.z.string()
+});
+var PaymentSucceededEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("payment_succeeded"),
+  payment_id: zod.z.string(),
+  subscription_id: zod.z.string().optional(),
+  invoice_id: zod.z.string().optional(),
+  amount: MoneySchema,
+  payment_method: zod.z.string().optional()
+});
+var PaymentFailedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("payment_failed"),
+  payment_id: zod.z.string().optional(),
+  subscription_id: zod.z.string().optional(),
+  invoice_id: zod.z.string().optional(),
+  amount: MoneySchema,
+  failure_reason: zod.z.string().optional(),
+  retry_attempt: zod.z.number().int().nonnegative().optional()
+});
+var InvoiceCreatedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("invoice_created"),
+  invoice_id: zod.z.string(),
+  subscription_id: zod.z.string().optional(),
+  amount: MoneySchema,
+  due_date: zod.z.number().int().positive().optional()
+});
+var InvoicePaidEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("invoice_paid"),
+  invoice_id: zod.z.string(),
+  subscription_id: zod.z.string().optional(),
+  amount: MoneySchema,
+  paid_at: zod.z.number().int().positive()
+});
+var FeatureUsedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("feature_used"),
+  feature_name: zod.z.string(),
+  feature_id: zod.z.string().optional(),
+  usage_count: zod.z.number().int().nonnegative().optional(),
+  metadata: zod.z.record(zod.z.unknown()).optional()
+});
+var LimitReachedEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("limit_reached"),
+  limit_type: zod.z.string(),
+  current_usage: zod.z.number(),
+  limit_value: zod.z.number(),
+  plan: SubscriptionPlanSchema.optional()
+});
+var QuotaExceededEventSchema = BaseEventMetadataSchema.extend({
+  event_type: zod.z.literal("quota_exceeded"),
+  quota_type: zod.z.string(),
+  current_usage: zod.z.number(),
+  quota_limit: zod.z.number(),
+  plan: SubscriptionPlanSchema.optional()
+});
+var SaasEventSchema = zod.z.discriminatedUnion("event_type", [
+  UserSignedUpEventSchema,
+  UserInvitedEventSchema,
+  UserLoggedInEventSchema,
+  UserLoggedOutEventSchema,
+  AccountCreatedEventSchema,
+  AccountDeletedEventSchema,
+  TrialStartedEventSchema,
+  TrialConvertedEventSchema,
+  TrialEndedEventSchema,
+  SubscriptionStartedEventSchema,
+  SubscriptionUpgradedEventSchema,
+  SubscriptionDowngradedEventSchema,
+  SubscriptionCancelledEventSchema,
+  SubscriptionRenewedEventSchema,
+  SubscriptionPausedEventSchema,
+  SubscriptionResumedEventSchema,
+  PaymentSucceededEventSchema,
+  PaymentFailedEventSchema,
+  InvoiceCreatedEventSchema,
+  InvoicePaidEventSchema,
+  FeatureUsedEventSchema,
+  LimitReachedEventSchema,
+  QuotaExceededEventSchema
+]);
+var CustomEventSchema = BaseEventMetadataSchema.extend({
+  /** Custom event type (user-defined) */
+  event_type: zod.z.string(),
+  /** Custom event properties (user-defined) */
+  properties: zod.z.record(zod.z.unknown()).optional()
+});
+function createCustomEventSchema(eventType, propertiesSchema) {
+  return BaseEventMetadataSchema.extend({
+    event_type: zod.z.literal(eventType),
+    properties: propertiesSchema
+  });
+}
+var CoreEventSchema = zod.z.union([EcommerceEventSchema, SaasEventSchema]);
+var AnyEventSchema = zod.z.union([
+  EcommerceEventSchema,
+  SaasEventSchema,
+  CustomEventSchema
+]);
+function validateEvent(data) {
+  try {
+    const parsed = AnyEventSchema.parse(data);
+    return {
+      success: true,
+      data: parsed,
+      error: null
+    };
+  } catch (error) {
+    if (error instanceof zod.z.ZodError) {
+      return {
+        success: false,
+        data: null,
+        error
+      };
+    }
+    throw error;
+  }
+}
+function validateEcommerceEvent(data) {
+  try {
+    const parsed = EcommerceEventSchema.parse(data);
+    return {
+      success: true,
+      data: parsed,
+      error: null
+    };
+  } catch (error) {
+    if (error instanceof zod.z.ZodError) {
+      return {
+        success: false,
+        data: null,
+        error
+      };
+    }
+    throw error;
+  }
+}
+function validateSaasEvent(data) {
+  try {
+    const parsed = SaasEventSchema.parse(data);
+    return {
+      success: true,
+      data: parsed,
+      error: null
+    };
+  } catch (error) {
+    if (error instanceof zod.z.ZodError) {
+      return {
+        success: false,
+        data: null,
+        error
+      };
+    }
+    throw error;
+  }
+}
+function validateCustomEvent(data) {
+  try {
+    const parsed = CustomEventSchema.parse(data);
+    return {
+      success: true,
+      data: parsed,
+      error: null
+    };
+  } catch (error) {
+    if (error instanceof zod.z.ZodError) {
+      return {
+        success: false,
+        data: null,
+        error
+      };
+    }
+    throw error;
+  }
+}
+function isEcommerceEvent(event) {
+  const ecommerceTypes = [
+    "product_viewed",
+    "product_list_viewed",
+    "product_added",
+    "product_removed",
+    "cart_viewed",
+    "checkout_started",
+    "checkout_step_completed",
+    "payment_info_entered",
+    "order_completed",
+    "order_updated",
+    "order_refunded",
+    "order_cancelled"
+  ];
+  return ecommerceTypes.includes(event.event_type);
+}
+function isSaasEvent(event) {
+  const saasTypes = [
+    "user_signed_up",
+    "user_invited",
+    "user_logged_in",
+    "user_logged_out",
+    "account_created",
+    "account_deleted",
+    "trial_started",
+    "trial_converted",
+    "trial_ended",
+    "subscription_started",
+    "subscription_upgraded",
+    "subscription_downgraded",
+    "subscription_cancelled",
+    "subscription_renewed",
+    "subscription_paused",
+    "subscription_resumed",
+    "payment_succeeded",
+    "payment_failed",
+    "invoice_created",
+    "invoice_paid",
+    "feature_used",
+    "limit_reached",
+    "quota_exceeded"
+  ];
+  return saasTypes.includes(event.event_type);
+}
+function isCustomEvent(event) {
+  return !isEcommerceEvent(event) && !isSaasEvent(event);
+}
+
+exports.AccountCreatedEventSchema = AccountCreatedEventSchema;
+exports.AccountDeletedEventSchema = AccountDeletedEventSchema;
+exports.AnyEventSchema = AnyEventSchema;
+exports.BaseEventMetadataSchema = BaseEventMetadataSchema;
+exports.CartSchema = CartSchema;
+exports.CartViewedEventSchema = CartViewedEventSchema;
+exports.CheckoutStartedEventSchema = CheckoutStartedEventSchema;
+exports.CheckoutStepCompletedEventSchema = CheckoutStepCompletedEventSchema;
+exports.CoreEventSchema = CoreEventSchema;
+exports.CustomEventSchema = CustomEventSchema;
+exports.EcommerceEventSchema = EcommerceEventSchema;
+exports.FeatureUsedEventSchema = FeatureUsedEventSchema;
+exports.InvoiceCreatedEventSchema = InvoiceCreatedEventSchema;
+exports.InvoicePaidEventSchema = InvoicePaidEventSchema;
+exports.LimitReachedEventSchema = LimitReachedEventSchema;
+exports.MoneySchema = MoneySchema;
+exports.OrderCancelledEventSchema = OrderCancelledEventSchema;
+exports.OrderCompletedEventSchema = OrderCompletedEventSchema;
+exports.OrderRefundedEventSchema = OrderRefundedEventSchema;
+exports.OrderUpdatedEventSchema = OrderUpdatedEventSchema;
+exports.PageContextSchema = PageContextSchema;
+exports.PaymentFailedEventSchema = PaymentFailedEventSchema;
+exports.PaymentInfoEnteredEventSchema = PaymentInfoEnteredEventSchema;
+exports.PaymentSucceededEventSchema = PaymentSucceededEventSchema;
+exports.ProductAddedEventSchema = ProductAddedEventSchema;
+exports.ProductListViewedEventSchema = ProductListViewedEventSchema;
+exports.ProductRemovedEventSchema = ProductRemovedEventSchema;
+exports.ProductSchema = ProductSchema;
+exports.ProductViewedEventSchema = ProductViewedEventSchema;
+exports.QuotaExceededEventSchema = QuotaExceededEventSchema;
+exports.SaasEventSchema = SaasEventSchema;
+exports.SubscriptionCancelledEventSchema = SubscriptionCancelledEventSchema;
+exports.SubscriptionDowngradedEventSchema = SubscriptionDowngradedEventSchema;
+exports.SubscriptionPausedEventSchema = SubscriptionPausedEventSchema;
+exports.SubscriptionPlanSchema = SubscriptionPlanSchema;
+exports.SubscriptionRenewedEventSchema = SubscriptionRenewedEventSchema;
+exports.SubscriptionResumedEventSchema = SubscriptionResumedEventSchema;
+exports.SubscriptionStartedEventSchema = SubscriptionStartedEventSchema;
+exports.SubscriptionUpgradedEventSchema = SubscriptionUpgradedEventSchema;
+exports.TrialConvertedEventSchema = TrialConvertedEventSchema;
+exports.TrialEndedEventSchema = TrialEndedEventSchema;
+exports.TrialStartedEventSchema = TrialStartedEventSchema;
+exports.UserInvitedEventSchema = UserInvitedEventSchema;
+exports.UserLoggedInEventSchema = UserLoggedInEventSchema;
+exports.UserLoggedOutEventSchema = UserLoggedOutEventSchema;
+exports.UserSignedUpEventSchema = UserSignedUpEventSchema;
+exports.UserTraitsSchema = UserTraitsSchema;
+exports.createCustomEventSchema = createCustomEventSchema;
+exports.isCustomEvent = isCustomEvent;
+exports.isEcommerceEvent = isEcommerceEvent;
+exports.isSaasEvent = isSaasEvent;
+exports.validateCustomEvent = validateCustomEvent;
+exports.validateEcommerceEvent = validateEcommerceEvent;
+exports.validateEvent = validateEvent;
+exports.validateSaasEvent = validateSaasEvent;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map