@hellyeah/x-ray 0.1.0-beta.5

package/dist/server/index.d.cts

@@ -0,0 +1,234 @@
+declare const cv: {
+	readonly purchase: "cv_purchase";
+	readonly subscribe: "cv_subscribe";
+	readonly startTrial: "cv_start_trial";
+	readonly leadSubmit: "cv_lead_submit";
+	readonly registrationComplete: "cv_registration_complete";
+	readonly bookAppointment: "cv_book_appointment";
+	readonly contact: "cv_contact";
+	readonly submitApplication: "cv_submit_application";
+	readonly addToCart: "cv_add_to_cart";
+	readonly beginCheckout: "cv_begin_checkout";
+	readonly addPaymentInfo: "cv_add_payment_info";
+	readonly viewContent: "cv_view_content";
+	readonly search: "cv_search";
+};
+type ConversionEvent = (typeof cv)[keyof typeof cv];
+type XRayLogEntry = {
+	/** Which SDK operation produced this log. */
+	action: "track" | "track_immediate" | "identify" | "flush" | "shutdown" | "enqueue" | "send_batch" | "serverless_detect";
+	/** What happened. */
+	outcome: "success" | "error" | "drop" | "retry" | "overflow" | "warning";
+	/** Human-readable description. */
+	message: string;
+	/** Event name when relevant. */
+	event?: string;
+	/** Number of items involved (batch size, queue length). */
+	count?: number;
+	/** Retry attempt number (1-indexed). */
+	attempt?: number;
+	/** Total retry attempts configured. */
+	maxAttempts?: number;
+	/** HTTP status code from server. */
+	statusCode?: number;
+	/** Error object when outcome is "error". */
+	error?: unknown;
+};
+type Attribution = {
+	utm_source?: string;
+	utm_medium?: string;
+	utm_campaign?: string;
+	utm_content?: string;
+	utm_term?: string;
+	gclid?: string;
+	fbclid?: string;
+	msclkid?: string;
+	ttclid?: string;
+	li_fat_id?: string;
+	twclid?: string;
+};
+type TrackData = {
+	/** User identifier. Falls back to the value set via `identify()`. */
+	distinctId?: string;
+	/** Revenue amount (e.g. `49.99`). Converted to string on the wire. */
+	revenue?: number;
+	/** ISO 4217 currency code (e.g. `"USD"`). */
+	currency?: string;
+	/** Arbitrary key-value metadata attached to the event. */
+	metadata?: Record<string, string | number | boolean | null>;
+	/** Grouping tag for filtering in the dashboard. */
+	tag?: string;
+	/** Page URL where the event occurred. */
+	url?: string;
+	/** Hostname of the tracked page (e.g. `"example.com"`). Used for session context. */
+	hostname?: string;
+};
+type XRayOptions = {
+	/** Base URL of the analytics server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	host?: string;
+	/** Events to batch before flushing. @defaultValue 20 */
+	flushAt?: number;
+	/** Milliseconds between automatic flushes. @defaultValue 10000 */
+	flushInterval?: number;
+	/** Maximum events held in memory. Oldest events are dropped when exceeded. @defaultValue 1000 */
+	maxQueueSize?: number;
+	/** Milliseconds before an HTTP request is aborted. @defaultValue 10000 */
+	requestTimeout?: number;
+	/** When `true`, all tracking methods become no-ops. @defaultValue false */
+	disabled?: boolean;
+	/** Custom `fetch` implementation. Useful for proxying or testing. @defaultValue globalThis.fetch */
+	fetch?: typeof fetch;
+	/** Custom logger callback. Receives structured log entries. */
+	logger?: (entry: XRayLogEntry) => void;
+	/** Session-scoped attribution fields (UTM params, click IDs) applied to every event. */
+	context?: Attribution;
+	/** Serverless lifecycle hook — pass your platform's `waitUntil` to ensure flushes complete after the response. */
+	waitUntil?: (promise: Promise<unknown>) => void;
+	/** @internal */
+	retryDelay?: number;
+};
+type IdentifyParams = {
+	/** Unique user identifier used as the default for subsequent `track()` calls. */
+	distinctId: string;
+	/** User traits to associate with this identifier. */
+	properties?: Record<string, string | number | boolean | null>;
+};
+/**
+* Wire-format payload for a single queued event.
+* @internal
+*/
+type QueueItem = {
+	website: string;
+	name: string;
+	id: string;
+	hy_event_id: string;
+	revenue?: string;
+	currency?: string;
+	tag?: string;
+	url?: string;
+	hostname?: string;
+	utm_source?: string;
+	utm_medium?: string;
+	utm_campaign?: string;
+	utm_content?: string;
+	utm_term?: string;
+	gclid?: string;
+	fbclid?: string;
+	msclkid?: string;
+	ttclid?: string;
+	li_fat_id?: string;
+	twclid?: string;
+	data?: Record<string, string | number | boolean | null>;
+};
+/** @internal Resolved internal configuration. */
+type XRayConfig = {
+	websiteId: string;
+	host: string;
+	flushAt: number;
+	flushInterval: number;
+	maxQueueSize: number;
+	requestTimeout: number;
+	disabled: boolean;
+	retryDelay: number;
+	context: Attribution;
+	waitUntil: ((promise: Promise<unknown>) => void) | null;
+};
+/**
+* Server-side tracking SDK for x-ray analytics.
+*
+* Buffers events in memory and flushes them in batches to the analytics server.
+* A background timer flushes automatically at the configured interval, making
+* this suitable for long-running Node/Bun processes.
+*
+* @example
+* ```ts
+* const xray = new XRay("site_abc123");
+*
+* xray.identify({ distinctId: "user_42" });
+* xray.track("signup");
+*
+* // On process exit
+* await xray.shutdown();
+* ```
+*
+* @remarks
+* The flush timer is unref'd so it won't keep a Node process alive. In
+* serverless/edge runtimes where the process may exit after a single request,
+* use {@link trackImmediate} or call {@link shutdown} before returning.
+*/
+declare class XRay {
+	private readonly queue;
+	private timer;
+	private defaultDistinctId?;
+	private logFn;
+	private flushing;
+	private readonly fetchFn;
+	private shutdownCalled;
+	private readonly cfg;
+	/**
+	* @param websiteId - Your site identifier. Falls back to `XRAY_WEBSITE_ID` env var.
+	* @param options - SDK configuration. See {@link XRayOptions}.
+	*/
+	constructor(websiteId?: string, options?: XRayOptions);
+	/**
+	* Queue a custom event for batched delivery.
+	*
+	* @param event - Name of the event (e.g. `"signup"`, `"purchase"`).
+	* @param data - Optional event data including distinctId, revenue, metadata, etc.
+	*
+	* @remarks
+	* Events are buffered in memory and flushed automatically when the queue
+	* reaches `flushAt` or on the next `flushInterval` tick.
+	*/
+	track(event: string, data?: TrackData): void;
+	/**
+	* Send a single event immediately, bypassing the queue.
+	*
+	* @param event - Name of the event (e.g. `"signup"`, `"purchase"`).
+	* @param data - Optional event data including distinctId, revenue, metadata, etc.
+	*
+	* @remarks
+	* Use this in serverless/edge runtimes where the process may exit before the
+	* next flush tick. For long-running servers, prefer {@link track} for better
+	* batching efficiency.
+	*/
+	trackImmediate(event: string, data?: TrackData): Promise<void>;
+	/** Set the default distinctId for subsequent track() calls. */
+	identify(params: IdentifyParams): void;
+	/**
+	* Drain all queued events immediately.
+	*
+	* @remarks
+	* On network failure the failed batch is re-queued at the front so no events
+	* are lost. Concurrent calls are deduplicated — only one flush runs at a time.
+	*/
+	flush(): Promise<void>;
+	/**
+	* Stop the flush timer and send all remaining events.
+	*
+	* @param timeoutMs - Maximum time to wait for the final flush. @defaultValue 5000
+	* @remarks
+	* Safe to call multiple times — subsequent calls are no-ops.
+	*/
+	shutdown(timeoutMs?: number): Promise<void>;
+	/** Toggle debug logging to console. When enabled, logs structured entries as JSON to console.log. */
+	debug(enabled: boolean): void;
+	private enqueue;
+	private sendBatch;
+	private buildItem;
+	private sanitizeProperties;
+	private resolveWaitUntil;
+	private log;
+}
+/**
+* Get or create a shared XRay singleton.
+*
+* @param websiteId - Falls back to `XRAY_WEBSITE_ID` env var.
+* @param options - Ignored when an instance already exists.
+*
+* @remarks
+* Uses a `Symbol.for` key on `globalThis` so the instance survives HMR
+* reloads and multiple import paths.
+*/
+declare const createXRay: (websiteId?: string, options?: XRayOptions) => XRay;
+export { cv, createXRay, XRayOptions, XRayLogEntry, XRayConfig, XRay, TrackData, QueueItem, IdentifyParams, ConversionEvent, Attribution };

package/dist/server/index.d.ts

@@ -0,0 +1,234 @@
+declare const cv: {
+	readonly purchase: "cv_purchase";
+	readonly subscribe: "cv_subscribe";
+	readonly startTrial: "cv_start_trial";
+	readonly leadSubmit: "cv_lead_submit";
+	readonly registrationComplete: "cv_registration_complete";
+	readonly bookAppointment: "cv_book_appointment";
+	readonly contact: "cv_contact";
+	readonly submitApplication: "cv_submit_application";
+	readonly addToCart: "cv_add_to_cart";
+	readonly beginCheckout: "cv_begin_checkout";
+	readonly addPaymentInfo: "cv_add_payment_info";
+	readonly viewContent: "cv_view_content";
+	readonly search: "cv_search";
+};
+type ConversionEvent = (typeof cv)[keyof typeof cv];
+type XRayLogEntry = {
+	/** Which SDK operation produced this log. */
+	action: "track" | "track_immediate" | "identify" | "flush" | "shutdown" | "enqueue" | "send_batch" | "serverless_detect";
+	/** What happened. */
+	outcome: "success" | "error" | "drop" | "retry" | "overflow" | "warning";
+	/** Human-readable description. */
+	message: string;
+	/** Event name when relevant. */
+	event?: string;
+	/** Number of items involved (batch size, queue length). */
+	count?: number;
+	/** Retry attempt number (1-indexed). */
+	attempt?: number;
+	/** Total retry attempts configured. */
+	maxAttempts?: number;
+	/** HTTP status code from server. */
+	statusCode?: number;
+	/** Error object when outcome is "error". */
+	error?: unknown;
+};
+type Attribution = {
+	utm_source?: string;
+	utm_medium?: string;
+	utm_campaign?: string;
+	utm_content?: string;
+	utm_term?: string;
+	gclid?: string;
+	fbclid?: string;
+	msclkid?: string;
+	ttclid?: string;
+	li_fat_id?: string;
+	twclid?: string;
+};
+type TrackData = {
+	/** User identifier. Falls back to the value set via `identify()`. */
+	distinctId?: string;
+	/** Revenue amount (e.g. `49.99`). Converted to string on the wire. */
+	revenue?: number;
+	/** ISO 4217 currency code (e.g. `"USD"`). */
+	currency?: string;
+	/** Arbitrary key-value metadata attached to the event. */
+	metadata?: Record<string, string | number | boolean | null>;
+	/** Grouping tag for filtering in the dashboard. */
+	tag?: string;
+	/** Page URL where the event occurred. */
+	url?: string;
+	/** Hostname of the tracked page (e.g. `"example.com"`). Used for session context. */
+	hostname?: string;
+};
+type XRayOptions = {
+	/** Base URL of the analytics server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	host?: string;
+	/** Events to batch before flushing. @defaultValue 20 */
+	flushAt?: number;
+	/** Milliseconds between automatic flushes. @defaultValue 10000 */
+	flushInterval?: number;
+	/** Maximum events held in memory. Oldest events are dropped when exceeded. @defaultValue 1000 */
+	maxQueueSize?: number;
+	/** Milliseconds before an HTTP request is aborted. @defaultValue 10000 */
+	requestTimeout?: number;
+	/** When `true`, all tracking methods become no-ops. @defaultValue false */
+	disabled?: boolean;
+	/** Custom `fetch` implementation. Useful for proxying or testing. @defaultValue globalThis.fetch */
+	fetch?: typeof fetch;
+	/** Custom logger callback. Receives structured log entries. */
+	logger?: (entry: XRayLogEntry) => void;
+	/** Session-scoped attribution fields (UTM params, click IDs) applied to every event. */
+	context?: Attribution;
+	/** Serverless lifecycle hook — pass your platform's `waitUntil` to ensure flushes complete after the response. */
+	waitUntil?: (promise: Promise<unknown>) => void;
+	/** @internal */
+	retryDelay?: number;
+};
+type IdentifyParams = {
+	/** Unique user identifier used as the default for subsequent `track()` calls. */
+	distinctId: string;
+	/** User traits to associate with this identifier. */
+	properties?: Record<string, string | number | boolean | null>;
+};
+/**
+* Wire-format payload for a single queued event.
+* @internal
+*/
+type QueueItem = {
+	website: string;
+	name: string;
+	id: string;
+	hy_event_id: string;
+	revenue?: string;
+	currency?: string;
+	tag?: string;
+	url?: string;
+	hostname?: string;
+	utm_source?: string;
+	utm_medium?: string;
+	utm_campaign?: string;
+	utm_content?: string;
+	utm_term?: string;
+	gclid?: string;
+	fbclid?: string;
+	msclkid?: string;
+	ttclid?: string;
+	li_fat_id?: string;
+	twclid?: string;
+	data?: Record<string, string | number | boolean | null>;
+};
+/** @internal Resolved internal configuration. */
+type XRayConfig = {
+	websiteId: string;
+	host: string;
+	flushAt: number;
+	flushInterval: number;
+	maxQueueSize: number;
+	requestTimeout: number;
+	disabled: boolean;
+	retryDelay: number;
+	context: Attribution;
+	waitUntil: ((promise: Promise<unknown>) => void) | null;
+};
+/**
+* Server-side tracking SDK for x-ray analytics.
+*
+* Buffers events in memory and flushes them in batches to the analytics server.
+* A background timer flushes automatically at the configured interval, making
+* this suitable for long-running Node/Bun processes.
+*
+* @example
+* ```ts
+* const xray = new XRay("site_abc123");
+*
+* xray.identify({ distinctId: "user_42" });
+* xray.track("signup");
+*
+* // On process exit
+* await xray.shutdown();
+* ```
+*
+* @remarks
+* The flush timer is unref'd so it won't keep a Node process alive. In
+* serverless/edge runtimes where the process may exit after a single request,
+* use {@link trackImmediate} or call {@link shutdown} before returning.
+*/
+declare class XRay {
+	private readonly queue;
+	private timer;
+	private defaultDistinctId?;
+	private logFn;
+	private flushing;
+	private readonly fetchFn;
+	private shutdownCalled;
+	private readonly cfg;
+	/**
+	* @param websiteId - Your site identifier. Falls back to `XRAY_WEBSITE_ID` env var.
+	* @param options - SDK configuration. See {@link XRayOptions}.
+	*/
+	constructor(websiteId?: string, options?: XRayOptions);
+	/**
+	* Queue a custom event for batched delivery.
+	*
+	* @param event - Name of the event (e.g. `"signup"`, `"purchase"`).
+	* @param data - Optional event data including distinctId, revenue, metadata, etc.
+	*
+	* @remarks
+	* Events are buffered in memory and flushed automatically when the queue
+	* reaches `flushAt` or on the next `flushInterval` tick.
+	*/
+	track(event: string, data?: TrackData): void;
+	/**
+	* Send a single event immediately, bypassing the queue.
+	*
+	* @param event - Name of the event (e.g. `"signup"`, `"purchase"`).
+	* @param data - Optional event data including distinctId, revenue, metadata, etc.
+	*
+	* @remarks
+	* Use this in serverless/edge runtimes where the process may exit before the
+	* next flush tick. For long-running servers, prefer {@link track} for better
+	* batching efficiency.
+	*/
+	trackImmediate(event: string, data?: TrackData): Promise<void>;
+	/** Set the default distinctId for subsequent track() calls. */
+	identify(params: IdentifyParams): void;
+	/**
+	* Drain all queued events immediately.
+	*
+	* @remarks
+	* On network failure the failed batch is re-queued at the front so no events
+	* are lost. Concurrent calls are deduplicated — only one flush runs at a time.
+	*/
+	flush(): Promise<void>;
+	/**
+	* Stop the flush timer and send all remaining events.
+	*
+	* @param timeoutMs - Maximum time to wait for the final flush. @defaultValue 5000
+	* @remarks
+	* Safe to call multiple times — subsequent calls are no-ops.
+	*/
+	shutdown(timeoutMs?: number): Promise<void>;
+	/** Toggle debug logging to console. When enabled, logs structured entries as JSON to console.log. */
+	debug(enabled: boolean): void;
+	private enqueue;
+	private sendBatch;
+	private buildItem;
+	private sanitizeProperties;
+	private resolveWaitUntil;
+	private log;
+}
+/**
+* Get or create a shared XRay singleton.
+*
+* @param websiteId - Falls back to `XRAY_WEBSITE_ID` env var.
+* @param options - Ignored when an instance already exists.
+*
+* @remarks
+* Uses a `Symbol.for` key on `globalThis` so the instance survives HMR
+* reloads and multiple import paths.
+*/
+declare const createXRay: (websiteId?: string, options?: XRayOptions) => XRay;
+export { cv, createXRay, XRayOptions, XRayLogEntry, XRayConfig, XRay, TrackData, QueueItem, IdentifyParams, ConversionEvent, Attribution };