@outlit/core 2.0.0 → 3.0.0

package/dist/index.d.ts

@@ -1,12 +1,187 @@
-type EventType = "pageview" | "form" | "identify" | "custom" | "calendar" | "engagement";
-type CalendarProvider = "cal.com" | "calendly" | "unknown";
-type SourceType = "client" | "server" | "integration";
+type GeneratedIngestPayload = {
+    visitorId?: string;
+    fingerprint?: string;
+    source?: "client" | "server" | "integration";
+    events: Array<{
+        uuid?: string;
+        type: "pageview";
+        timestamp: number;
+        url: string;
+        path: string;
+        referrer?: string;
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+            ref?: string;
+        };
+        customerId?: string;
+        customerTraits?: Record<string, string | number | boolean | null>;
+        title?: string;
+    } | {
+        uuid?: string;
+        type: "form";
+        timestamp: number;
+        url: string;
+        path: string;
+        referrer?: string;
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+            ref?: string;
+        };
+        customerId?: string;
+        customerTraits?: Record<string, string | number | boolean | null>;
+        formId?: string;
+        formFields?: Record<string, string>;
+    } | {
+        uuid?: string;
+        type: "identify";
+        timestamp: number;
+        url: string;
+        path: string;
+        referrer?: string;
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+            ref?: string;
+        };
+        email?: string;
+        userId?: string;
+        fingerprint?: string;
+        customerId?: string;
+        customerTraits?: Record<string, string | number | boolean | null>;
+        traits?: Record<string, string | number | boolean | null>;
+    } | {
+        uuid?: string;
+        type: "custom";
+        timestamp: number;
+        url: string;
+        path: string;
+        referrer?: string;
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+            ref?: string;
+        };
+        customerId?: string;
+        customerTraits?: Record<string, string | number | boolean | null>;
+        email?: string;
+        userId?: string;
+        fingerprint?: string;
+        eventName: string;
+        properties?: Record<string, unknown>;
+    } | {
+        uuid?: string;
+        type: "calendar";
+        timestamp: number;
+        url: string;
+        path: string;
+        referrer?: string;
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+            ref?: string;
+        };
+        customerId?: string;
+        customerTraits?: Record<string, string | number | boolean | null>;
+        provider: "cal.com" | "calendly" | "unknown";
+        eventType?: string;
+        startTime?: string;
+        endTime?: string;
+        duration?: number;
+        isRecurring?: boolean;
+        inviteeEmail?: string;
+        inviteeName?: string;
+    } | {
+        uuid?: string;
+        type: "engagement";
+        timestamp: number;
+        url: string;
+        path: string;
+        referrer?: string;
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+            ref?: string;
+        };
+        customerId?: string;
+        customerTraits?: Record<string, string | number | boolean | null>;
+        activeTimeMs: number;
+        totalTimeMs: number;
+        sessionId: string;
+    }>;
+    sessionId?: string;
+    userIdentity?: {
+        email?: string;
+        userId?: string;
+        fingerprint?: string;
+        traits?: Record<string, string | number | boolean | null>;
+    };
+    customerIdentity?: {
+        customerId?: string;
+        customerTraits?: Record<string, string | number | boolean | null>;
+    };
+};
+type GeneratedIngestResponse = {
+    success: boolean;
+    processed: number;
+    errors?: Array<{
+        index: number;
+        message: string;
+    }>;
+};
+
+type IngestPayload = GeneratedIngestPayload;
+type IngestResponse = GeneratedIngestResponse;
+type TrackerEvent = IngestPayload["events"][number];
+type EventType = TrackerEvent["type"];
+type SourceType = NonNullable<IngestPayload["source"]>;
+type PageviewEvent = Extract<TrackerEvent, {
+    type: "pageview";
+}>;
+type FormEvent = Extract<TrackerEvent, {
+    type: "form";
+}>;
+type IdentifyEvent = Extract<TrackerEvent, {
+    type: "identify";
+}>;
+type CustomEvent = Extract<TrackerEvent, {
+    type: "custom";
+}>;
+type CalendarEvent = Extract<TrackerEvent, {
+    type: "calendar";
+}>;
+type EngagementEvent = Extract<TrackerEvent, {
+    type: "engagement";
+}>;
+type CalendarProvider = CalendarEvent["provider"];
+type PayloadUserIdentity = NonNullable<IngestPayload["userIdentity"]>;
+type PayloadCustomerIdentity = NonNullable<IngestPayload["customerIdentity"]>;
 interface UtmParams {
     source?: string;
     medium?: string;
     campaign?: string;
     term?: string;
     content?: string;
+    ref?: string;
 }
 interface TrackerConfig {
     publicKey: string;
@@ -61,145 +236,30 @@ interface IdentifyTraits {
     /** User-level traits */
     [key: string]: string | number | boolean | null | undefined;
 }
-interface ServerTrackOptions extends ServerIdentity, CustomerAttribution {
-    eventName: string;
-    properties?: Record<string, string | number | boolean | null>;
-    timestamp?: number;
-}
-interface ServerIdentifyOptions extends ServerIdentity, CustomerAttribution {
-    traits?: IdentifyTraits;
-    customerTraits?: CustomerTraits;
-}
-interface BaseEvent {
-    uuid?: string;
-    type: EventType;
-    timestamp: number;
-    url: string;
-    path: string;
-    referrer?: string;
-    utm?: UtmParams;
-}
-interface PageviewEvent extends BaseEvent {
-    type: "pageview";
-    title?: string;
-}
-interface FormEvent extends BaseEvent {
-    type: "form";
-    formId?: string;
-    formFields?: Record<string, string>;
-}
-interface IdentifyEvent extends BaseEvent {
-    type: "identify";
-    email?: string;
-    userId?: string;
-    fingerprint?: string;
-    customerId?: string;
-    customerTraits?: CustomerTraits;
-    traits?: IdentifyTraits;
-}
-interface CustomEvent extends BaseEvent {
-    type: "custom";
-    eventName: string;
-    email?: string;
-    userId?: string;
-    fingerprint?: string;
-    customerId?: string;
-    properties?: Record<string, string | number | boolean | null>;
-}
-interface CalendarEvent extends BaseEvent {
-    type: "calendar";
-    provider: CalendarProvider;
-    eventType?: string;
-    startTime?: string;
-    endTime?: string;
-    duration?: number;
-    isRecurring?: boolean;
-    /** Available when identity is passed via webhooks or manual integration */
-    inviteeEmail?: string;
-    inviteeName?: string;
-}
-interface EngagementEvent extends BaseEvent {
-    type: "engagement";
-    /** Time in milliseconds the user was actively engaged (visible tab + user interactions) */
-    activeTimeMs: number;
-    /** Total wall-clock time in milliseconds on the page */
-    totalTimeMs: number;
-    /** Session ID for grouping engagement events. Resets after 30 min of inactivity or tab close. */
-    sessionId: string;
-}
-type TrackerEvent = PageviewEvent | FormEvent | IdentifyEvent | CustomEvent | CalendarEvent | EngagementEvent;
 /**
- * User identity for payload-level resolution.
- * Used by browser SDK when user is logged in (via setUser).
- * Customer attribution is carried separately in `customerIdentity`.
+ * Input accepted by the payload builder. Deprecated customer fields are lifted
+ * into the wire-level `customerIdentity` object and are never sent in `userIdentity`.
  */
-interface PayloadUserIdentity {
-    email?: string;
-    /** Your system-owned user/contact ID. */
-    userId?: string;
+type PayloadUserIdentityInput = Omit<PayloadUserIdentity, "traits"> & {
     /** User/contact traits. */
     traits?: IdentifyTraits;
-    /**
-     * @deprecated Use payload-level `customerIdentity.customerId` instead.
-     * Kept for one compatibility window while callers migrate.
-     */
+    /** @deprecated Pass `customerIdentity.customerId` to the payload builder instead. */
     customerId?: string;
-    /**
-     * @deprecated Use payload-level `customerIdentity.customerTraits` instead.
-     * Kept for one compatibility window while callers migrate.
-     */
+    /** @deprecated Pass `customerIdentity.customerTraits` to the payload builder instead. */
     customerTraits?: CustomerTraits;
-}
-/**
- * Customer identity for payload-level attribution.
- * Used by browser SDK to attach account/workspace context to a batch.
- * `customerId`-only attribution is valid and remains provisional until a later
- * identify(email, customerId) call links that external account/workspace to a resolved customer.
- */
-interface PayloadCustomerIdentity extends CustomerAttribution {
+};
+interface PayloadCustomerIdentityInput extends CustomerAttribution {
     /** Customer/account traits. */
     customerTraits?: CustomerTraits;
 }
-interface IngestPayload {
-    visitorId?: string;
-    source: SourceType;
-    events: TrackerEvent[];
-    /**
-     * Device identifier for anonymous tracking.
-     * Events with fingerprint can be linked to users later via identify.
-     * Only present for server-side events.
-     */
-    fingerprint?: string;
-    /**
-     * Session ID for grouping all events in this batch.
-     * Only present for browser (client) source events.
-     * Used to correlate pageviews, forms, custom events, and engagement
-     * within the same browsing session.
-     */
-    sessionId?: string;
-    /**
-     * User identity for this batch of events.
-     * When present, the server can resolve directly to CustomerContact
-     * instead of relying on anonymous visitor flow.
-     *
-     * This is set by the browser SDK when setUser() has been called,
-     * allowing immediate identity resolution for SPA/React apps.
-     */
-    userIdentity?: PayloadUserIdentity;
-    /**
-     * Customer/account identity for this batch of events.
-     * Used to attribute browser batches to a customer/workspace even when
-     * the customer fields are not present on every event.
-     */
-    customerIdentity?: PayloadCustomerIdentity;
+interface ServerTrackOptions extends ServerIdentity, CustomerAttribution {
+    eventName: string;
+    properties?: Record<string, string | number | boolean | null>;
+    timestamp?: number;
 }
-interface IngestResponse {
-    success: boolean;
-    processed: number;
-    errors?: Array<{
-        index: number;
-        message: string;
-    }>;
+interface ServerIdentifyOptions extends ServerIdentity, CustomerAttribution {
+    traits?: IdentifyTraits;
+    customerTraits?: CustomerTraits;
 }
 declare const DEFAULT_API_HOST = "https://app.outlit.ai";
 
@@ -280,16 +340,20 @@ declare function buildEngagementEvent(params: BaseEventParams & {
  * batches are valid and remain provisional until a later identify(email, customerId) call
  * links that external account/workspace to a resolved customer.
  */
-declare function buildIngestPayload(visitorId: string, source: SourceType, events: TrackerEvent[], userIdentity?: PayloadUserIdentity, sessionId?: string, fingerprint?: string, customerIdentity?: PayloadCustomerIdentity): IngestPayload;
+declare function buildIngestPayload(visitorId: string, source: SourceType, events: TrackerEvent[], userIdentity?: PayloadUserIdentityInput, sessionId?: string, fingerprint?: string, customerIdentity?: PayloadCustomerIdentityInput): IngestPayload;
 /**
  * Maximum number of events in a single batch.
  */
-declare const MAX_BATCH_SIZE = 100;
+declare const MAX_BATCH_SIZE: 100;
 /**
  * Split events into batches of MAX_BATCH_SIZE.
  */
 declare function batchEvents(events: TrackerEvent[]): TrackerEvent[][];
 
+declare const INGEST_METHOD: "POST";
+declare const INGEST_EVENT_TYPES: readonly ["pageview", "form", "identify", "custom", "calendar", "engagement"];
+declare function buildIngestUrl(apiHost: string, publicKey: string): string;
+
 /**
  * Extract UTM parameters from a URL.
  */
@@ -373,4 +437,4 @@ interface ExtractedIdentity {
  */
 declare function extractIdentityFromForm(fields: Record<string, string>, inputTypes?: Map<string, string>): ExtractedIdentity | undefined;
 
-export { type BrowserIdentifyOptions, type BrowserTrackOptions, type CalendarEvent, type CalendarProvider, type CustomEvent, type CustomerAttribution, type CustomerTraits, DEFAULT_API_HOST, DEFAULT_DENIED_FORM_FIELDS, type EngagementEvent, type EventType, type ExtractedIdentity, type FormEvent, type IdentifyEvent, type IdentifyTraits, type IngestPayload, type IngestResponse, MAX_BATCH_SIZE, type PageviewEvent, type PayloadCustomerIdentity, type PayloadUserIdentity, type ServerIdentifyOptions, type ServerIdentity, type ServerTrackOptions, type SourceType, type TrackerConfig, type TrackerEvent, type UtmParams, batchEvents, buildCalendarEvent, buildCustomEvent, buildEngagementEvent, buildFormEvent, buildIdentifyEvent, buildIngestPayload, buildPageviewEvent, extractIdentityFromForm, extractPathFromUrl, extractUtmParams, findEmailField, findNameFields, isFieldDenied, isValidEmail, sanitizeFormFields, validateServerIdentity };
+export { type BrowserIdentifyOptions, type BrowserTrackOptions, type CalendarEvent, type CalendarProvider, type CustomEvent, type CustomerAttribution, type CustomerTraits, DEFAULT_API_HOST, DEFAULT_DENIED_FORM_FIELDS, type EngagementEvent, type EventType, type ExtractedIdentity, type FormEvent, INGEST_EVENT_TYPES, INGEST_METHOD, type IdentifyEvent, type IdentifyTraits, type IngestPayload, type IngestResponse, MAX_BATCH_SIZE, type PageviewEvent, type PayloadCustomerIdentity, type PayloadCustomerIdentityInput, type PayloadUserIdentity, type PayloadUserIdentityInput, type ServerIdentifyOptions, type ServerIdentity, type ServerTrackOptions, type SourceType, type TrackerConfig, type TrackerEvent, type UtmParams, batchEvents, buildCalendarEvent, buildCustomEvent, buildEngagementEvent, buildFormEvent, buildIdentifyEvent, buildIngestPayload, buildIngestUrl, buildPageviewEvent, extractIdentityFromForm, extractPathFromUrl, extractUtmParams, findEmailField, findNameFields, isFieldDenied, isValidEmail, sanitizeFormFields, validateServerIdentity };

package/dist/index.js

@@ -22,6 +22,8 @@ var src_exports = {};
 __export(src_exports, {
   DEFAULT_API_HOST: () => DEFAULT_API_HOST,
   DEFAULT_DENIED_FORM_FIELDS: () => DEFAULT_DENIED_FORM_FIELDS,
+  INGEST_EVENT_TYPES: () => INGEST_EVENT_TYPES,
+  INGEST_METHOD: () => INGEST_METHOD,
   MAX_BATCH_SIZE: () => MAX_BATCH_SIZE,
   batchEvents: () => batchEvents,
   buildCalendarEvent: () => buildCalendarEvent,
@@ -30,6 +32,7 @@ __export(src_exports, {
   buildFormEvent: () => buildFormEvent,
   buildIdentifyEvent: () => buildIdentifyEvent,
   buildIngestPayload: () => buildIngestPayload,
+  buildIngestUrl: () => buildIngestUrl,
   buildPageviewEvent: () => buildPageviewEvent,
   extractIdentityFromForm: () => extractIdentityFromForm,
   extractPathFromUrl: () => extractPathFromUrl,
@@ -46,6 +49,14 @@ module.exports = __toCommonJS(src_exports);
 // src/payload.ts
 var import_uuid = require("uuid");
 
+// src/generated/ingest-contract.ts
+var ingestTransport = {
+  method: "POST",
+  pathTemplate: "/api/i/v1/{publicKey}/events",
+  maxBatchSize: 100,
+  eventTypes: ["pageview", "form", "identify", "custom", "calendar", "engagement"]
+};
+
 // src/types.ts
 var DEFAULT_API_HOST = "https://app.outlit.ai";
 var DEFAULT_DENIED_FORM_FIELDS = [
@@ -264,6 +275,14 @@ function extractIdentityFromForm(fields, inputTypes) {
 }
 
 // src/payload.ts
+function normalizeTraits(traits) {
+  if (!traits) return void 0;
+  const normalized = {};
+  for (const [key, value] of Object.entries(traits)) {
+    if (value !== void 0) normalized[key] = value;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
 function buildPageviewEvent(params) {
   const { url, referrer, timestamp, title } = params;
   return {
@@ -315,8 +334,8 @@ function buildIdentifyEvent(params) {
     userId,
     fingerprint,
     customerId,
-    customerTraits,
-    traits
+    customerTraits: normalizeTraits(customerTraits),
+    traits: normalizeTraits(traits)
   };
 }
 function buildCustomEvent(params) {
@@ -405,32 +424,33 @@ function buildIngestPayload(visitorId, source, events, userIdentity, sessionId,
     ...userIdentity.customerTraits && { customerTraits: userIdentity.customerTraits }
   } : void 0;
   const resolvedCustomerIdentity = customerIdentity ?? legacyCustomerIdentity;
+  const userTraits = normalizeTraits(userIdentity?.traits);
+  const customerTraits = normalizeTraits(resolvedCustomerIdentity?.customerTraits);
   if (fingerprint) {
     payload.fingerprint = fingerprint;
   }
   if (sessionId) {
     payload.sessionId = sessionId;
   }
-  if (userIdentity && (userIdentity.email || userIdentity.userId || userIdentity.traits)) {
+  if (userIdentity && (userIdentity.email || userIdentity.userId || userIdentity.fingerprint || userTraits)) {
     payload.userIdentity = {
       ...userIdentity.email && { email: userIdentity.email },
       ...userIdentity.userId && { userId: userIdentity.userId },
-      ...userIdentity.traits && { traits: userIdentity.traits }
+      ...userIdentity.fingerprint && { fingerprint: userIdentity.fingerprint },
+      ...userTraits && { traits: userTraits }
     };
   }
-  if (resolvedCustomerIdentity && (resolvedCustomerIdentity.customerId || resolvedCustomerIdentity.customerTraits)) {
+  if (resolvedCustomerIdentity && (resolvedCustomerIdentity.customerId || customerTraits)) {
     payload.customerIdentity = {
       ...resolvedCustomerIdentity.customerId && {
         customerId: resolvedCustomerIdentity.customerId
       },
-      ...resolvedCustomerIdentity.customerTraits && {
-        customerTraits: resolvedCustomerIdentity.customerTraits
-      }
+      ...customerTraits && { customerTraits }
     };
   }
   return payload;
 }
-var MAX_BATCH_SIZE = 100;
+var MAX_BATCH_SIZE = ingestTransport.maxBatchSize;
 function batchEvents(events) {
   const batches = [];
   for (let i = 0; i < events.length; i += MAX_BATCH_SIZE) {
@@ -438,10 +458,20 @@ function batchEvents(events) {
   }
   return batches;
 }
+
+// src/transport.ts
+var INGEST_METHOD = ingestTransport.method;
+var INGEST_EVENT_TYPES = ingestTransport.eventTypes;
+function buildIngestUrl(apiHost, publicKey) {
+  const path = ingestTransport.pathTemplate.replace("{publicKey}", encodeURIComponent(publicKey));
+  return `${apiHost.replace(/\/$/, "")}${path}`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_API_HOST,
   DEFAULT_DENIED_FORM_FIELDS,
+  INGEST_EVENT_TYPES,
+  INGEST_METHOD,
   MAX_BATCH_SIZE,
   batchEvents,
   buildCalendarEvent,
@@ -450,6 +480,7 @@ function batchEvents(events) {
   buildFormEvent,
   buildIdentifyEvent,
   buildIngestPayload,
+  buildIngestUrl,
   buildPageviewEvent,
   extractIdentityFromForm,
   extractPathFromUrl,