@outlit/core 1.5.2 → 3.0.0

package/README.md

@@ -0,0 +1,16 @@
+# @outlit/core
+
+Shared types and utilities for the Outlit browser and Node.js tracking SDKs.
+
+Most applications should install `@outlit/browser` or `@outlit/node` directly. Use this package when building lower-level integrations on top of Outlit's shared tracking types and client utilities.
+
+Outlit is the real-time understanding of every customer, the infrastructure agents use to automate customer operations.
+
+## Canonical Docs
+
+- Quick start: <https://docs.outlit.ai/tracking/quickstart>
+- Tracking overview: <https://docs.outlit.ai/tracking/how-it-works>
+- Browser SDK docs: <https://docs.outlit.ai/tracking/browser/npm>
+- Node.js SDK docs: <https://docs.outlit.ai/tracking/server/nodejs>
+- OpenAPI spec: <https://docs.outlit.ai/openapi.json>
+- Agent-facing docs index: <https://docs.outlit.ai/llms.txt>

package/dist/index.d.mts

@@ -1,14 +1,187 @@
-type EventType = "pageview" | "form" | "identify" | "custom" | "calendar" | "engagement" | "stage" | "billing";
-type ExplicitJourneyStage = "activated" | "engaged" | "inactive";
-type BillingStatus = "trialing" | "paid" | "churned";
-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;
@@ -63,173 +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;
-}
-/**
- * Customer identity for SDK billing methods.
- * Public billing calls should use `customerId`.
- */
-interface CustomerIdentifier extends CustomerAttribution {
-    /**
-     * @deprecated Stripe customer identifier.
-     * Billing attribution should use `customerId` publicly.
-     */
-    stripeCustomerId?: string;
-}
-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;
-}
-interface StageEvent extends BaseEvent {
-    type: "stage";
-    /** Stage event value. New SDK callers should only send "activated". */
-    stage: ExplicitJourneyStage;
-    /** Optional properties for context */
-    properties?: Record<string, string | number | boolean | null>;
-}
-interface BillingEvent extends BaseEvent {
-    type: "billing";
-    /** The billing status to set for a customer */
-    status: BillingStatus;
-    /** Optional customer identifiers */
-    customerId?: string;
-    stripeCustomerId?: string;
-    /** Optional properties for context */
-    properties?: Record<string, string | number | boolean | null>;
-}
-type TrackerEvent = PageviewEvent | FormEvent | IdentifyEvent | CustomEvent | CalendarEvent | EngagementEvent | StageEvent | BillingEvent;
 /**
- * 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";
 
@@ -297,27 +327,6 @@ declare function buildEngagementEvent(params: BaseEventParams & {
     totalTimeMs: number;
     sessionId: string;
 }): EngagementEvent;
-/**
- * Build a stage event.
- * Used to explicitly send customer journey stage events.
- * New SDK callers should only send activated; engaged and inactive are derived
- * by Outlit from tracked activity but remain accepted for wire compatibility.
- * discovered/signed_up stages are inferred from identify calls.
- */
-declare function buildStageEvent(params: BaseEventParams & {
-    stage: ExplicitJourneyStage;
-    properties?: Record<string, string | number | boolean | null>;
-}): StageEvent;
-/**
- * Build a billing event.
- * Used to set customer billing status (trialing, paid, churned).
- */
-declare function buildBillingEvent(params: BaseEventParams & {
-    status: BillingStatus;
-    customerId?: string;
-    stripeCustomerId?: string;
-    properties?: Record<string, string | number | boolean | null>;
-}): BillingEvent;
 /**
  * Build an ingest payload from events.
  *
@@ -331,16 +340,20 @@ declare function buildBillingEvent(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.
  */
@@ -369,10 +382,6 @@ declare function sanitizeFormFields(fields: Record<string, string> | undefined,
  * - customerId: Your system-owned customer/account/workspace ID
  */
 declare function validateServerIdentity(fingerprint?: string, email?: string, userId?: string, customerId?: string): void;
-/**
- * Validate that at least one customer identifier is provided for billing calls.
- */
-declare function validateCustomerIdentity(customerId?: string, stripeCustomerId?: string): void;
 /**
  * Validate that a string looks like a valid email address.
  */
@@ -428,4 +437,4 @@ interface ExtractedIdentity {
  */
 declare function extractIdentityFromForm(fields: Record<string, string>, inputTypes?: Map<string, string>): ExtractedIdentity | undefined;
 
-export { type BillingEvent, type BillingStatus, type BrowserIdentifyOptions, type BrowserTrackOptions, type CalendarEvent, type CalendarProvider, type CustomEvent, type CustomerAttribution, type CustomerIdentifier, type CustomerTraits, DEFAULT_API_HOST, DEFAULT_DENIED_FORM_FIELDS, type EngagementEvent, type EventType, type ExplicitJourneyStage, 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 StageEvent, type TrackerConfig, type TrackerEvent, type UtmParams, batchEvents, buildBillingEvent, buildCalendarEvent, buildCustomEvent, buildEngagementEvent, buildFormEvent, buildIdentifyEvent, buildIngestPayload, buildPageviewEvent, buildStageEvent, extractIdentityFromForm, extractPathFromUrl, extractUtmParams, findEmailField, findNameFields, isFieldDenied, isValidEmail, sanitizeFormFields, validateCustomerIdentity, 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 };