@xylabs/pixel 7.0.7 → 8.0.0

package/README.md

@@ -1,1419 +1,3 @@
-[![logo][]](https://xylabs.com)
-
 # @xylabs/pixel
 
-[![npm][npm-badge]][npm-link]
-[![license][license-badge]][license-link]
-
-> Event Client for xylabs ESB
-
-## Install
-
-Using npm:
-
-```sh
-npm install {{name}}
-```
-
-Using yarn:
-
-```sh
-yarn add {{name}}
-```
-
-Using pnpm:
-
-```sh
-pnpm add {{name}}
-```
-
-Using bun:
-
-```sh
-bun add {{name}}
-```
-
-
-## License
-
-See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
-
-## Reference
-
-### packages
-
-  ### pixel
-
-    ### .temp-typedoc
-
-      ### classes
-
-        ### <a id="PixelApi"></a>PixelApi
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-HTTP client for sending tracking events to the XY Labs pixel API.
-
-## Constructors
-
-### Constructor
-
-```ts
-new PixelApi(baseUri?): PixelApi;
-```
-
-### Parameters
-
-#### baseUri?
-
-`string` = `'prod'`
-
-### Returns
-
-`PixelApi`
-
-## Methods
-
-### trackEvents()
-
-```ts
-trackEvents(events): Promise<any>;
-```
-
-Sends an array of user events to the tracking API.
-
-### Parameters
-
-#### events
-
-[`UserEvent`][#../interfaces/UserEvent]()
-
-The events to submit
-
-### Returns
-
-`Promise`\<`any`\>
-
-The response data from the API
-
-        ### <a id="Referrer"></a>Referrer
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Tracks and persists the document referrer in both session and local storage.
-
-## Constructors
-
-### Constructor
-
-```ts
-new Referrer(): Referrer;
-```
-
-### Returns
-
-`Referrer`
-
-## Properties
-
-### local
-
-```ts
-local: string;
-```
-
-***
-
-### session
-
-```ts
-session: string;
-```
-
-## Methods
-
-### toJson()
-
-```ts
-toJson(): 
-  | {
-  local: string;
-  session: string;
-}
-  | undefined;
-```
-
-Returns the referrer data as a JSON object, or undefined if both values are empty.
-
-### Returns
-
-  \| \{
-  `local`: `string`;
-  `session`: `string`;
-\}
-  \| `undefined`
-
-An object with local and session referrer strings, or undefined
-
-        ### <a id="UniqueUserId"></a>UniqueUserId
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Generates and persists a unique user identifier in localStorage.
-
-## Constructors
-
-### Constructor
-
-```ts
-new UniqueUserId(): UniqueUserId;
-```
-
-### Returns
-
-`UniqueUserId`
-
-## Properties
-
-### id
-
-```ts
-id: string;
-```
-
-## Methods
-
-### toString()
-
-```ts
-toString(): string;
-```
-
-Returns the unique user ID as a string.
-
-### Returns
-
-`string`
-
-        ### <a id="UserEventHandler"></a>UserEventHandler
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Abstract base class for handling user tracking events.
-
-## Extended by
-
-- [`XyUserEventHandler`](#XyUserEventHandler)
-
-## Type Parameters
-
-### TData
-
-`TData` *extends* `EmptyObject`
-
-## Constructors
-
-### Constructor
-
-```ts
-new UserEventHandler<TData>(): UserEventHandler<TData>;
-```
-
-### Returns
-
-`UserEventHandler`\<`TData`\>
-
-## Methods
-
-### funnelStarted()
-
-```ts
-abstract funnelStarted<T>(fields): Promisable<void>;
-```
-
-Tracks a funnel-started event.
-
-### Type Parameters
-
-#### T
-
-`T` *extends* `object`
-
-### Parameters
-
-#### fields
-
-[`FunnelStartedFields`](#../interfaces/FunnelStartedFields) \| `T`
-
-### Returns
-
-`Promisable`\<`void`\>
-
-***
-
-### testStarted()
-
-```ts
-abstract testStarted<T>(fields): Promisable<void>;
-```
-
-Tracks a test-started event.
-
-### Type Parameters
-
-#### T
-
-`T` *extends* `object`
-
-### Parameters
-
-#### fields
-
-[`TestStartedFields`](#../interfaces/TestStartedFields) \| `T`
-
-### Returns
-
-`Promisable`\<`void`\>
-
-***
-
-### userClick()
-
-```ts
-abstract userClick<T>(fields): Promisable<void>;
-```
-
-Tracks a user click event.
-
-### Type Parameters
-
-#### T
-
-`T` *extends* `object`
-
-### Parameters
-
-#### fields
-
-[`UserClickFields`](#../interfaces/UserClickFields) \| `T`
-
-### Returns
-
-`Promisable`\<`void`\>
-
-***
-
-### viewContent()
-
-```ts
-abstract viewContent<T>(fields): Promisable<void>;
-```
-
-Tracks a view-content event.
-
-### Type Parameters
-
-#### T
-
-`T` *extends* `object`
-
-### Parameters
-
-#### fields
-
-`T` \| [`ViewContentFields`](#../interfaces/ViewContentFields)
-
-### Returns
-
-`Promisable`\<`void`\>
-
-        ### <a id="UtmFields"></a>UtmFields
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Tracks UTM campaign parameters from query strings, persisting history in localStorage.
-
-## Constructors
-
-### Constructor
-
-```ts
-new UtmFields(): UtmFields;
-```
-
-### Returns
-
-`UtmFields`
-
-## Properties
-
-### fields
-
-```ts
-fields: Record<string, string>[] = [];
-```
-
-## Methods
-
-### getUtmRecord()
-
-```ts
-getUtmRecord(): Record<string, string> | null;
-```
-
-Parses UTM parameters from the current URL query string.
-
-### Returns
-
-`Record`\<`string`, `string`\> \| `null`
-
-A record of UTM key-value pairs, or null if none are present
-
-***
-
-### toString()
-
-```ts
-toString(): string;
-```
-
-Returns the UTM fields history as a JSON string.
-
-### Returns
-
-`string`
-
-***
-
-### update()
-
-```ts
-update(): Record<string, string>[];
-```
-
-Checks the query string for new UTM values and appends them to the history if changed.
-
-### Returns
-
-`Record`\<`string`, `string`\>[]
-
-The current UTM fields array, or undefined if empty
-
-        ### <a id="XyPixel"></a>XyPixel
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Singleton pixel tracker that queues and sends user events to the XY Labs tracking API.
-
-## Properties
-
-### api
-
-```ts
-static api: PixelApi;
-```
-
-***
-
-### cid
-
-```ts
-cid: string;
-```
-
-***
-
-### email?
-
-```ts
-optional email?: string;
-```
-
-***
-
-### email\_hash?
-
-```ts
-optional email_hash?: string | null;
-```
-
-***
-
-### exids?
-
-```ts
-optional exids?: ExIds;
-```
-
-***
-
-### pixelId?
-
-```ts
-optional pixelId?: string;
-```
-
-***
-
-### queue
-
-```ts
-queue: UserEvent[] = [];
-```
-
-## Accessors
-
-### instance
-
-### Get Signature
-
-```ts
-get static instance(): XyPixel;
-```
-
-Returns the singleton XyPixel instance, throwing if not yet initialized.
-
-#### Returns
-
-`XyPixel`
-
-## Methods
-
-### init()
-
-```ts
-static init(pixelId): XyPixel;
-```
-
-Initializes the XyPixel singleton with the given pixel ID.
-
-### Parameters
-
-#### pixelId
-
-`string`
-
-The pixel identifier for this tracking instance
-
-### Returns
-
-`XyPixel`
-
-The newly created XyPixel instance
-
-***
-
-### selectApi()
-
-```ts
-static selectApi(api): void;
-```
-
-Replaces the default PixelApi instance used for sending events.
-
-### Parameters
-
-#### api
-
-[`PixelApi`](#PixelApi)
-
-The PixelApi instance to use
-
-### Returns
-
-`void`
-
-***
-
-### identify()
-
-```ts
-identify(email?): void;
-```
-
-Associates an email address with this pixel instance, hashing it for privacy.
-
-### Parameters
-
-#### email?
-
-`string`
-
-The email address to identify the user with
-
-### Returns
-
-`void`
-
-***
-
-### send()
-
-```ts
-send<T>(
-   event, 
-   fields?, 
-eventId?): Promise<void>;
-```
-
-Queues a tracking event and attempts to flush the queue to the API.
-
-### Type Parameters
-
-#### T
-
-`T` *extends* `Record`\<`string`, `unknown`\>
-
-### Parameters
-
-#### event
-
-`string`
-
-The event name
-
-#### fields?
-
-`T`
-
-Optional event-specific fields
-
-#### eventId?
-
-`string`
-
-Optional unique event identifier
-
-### Returns
-
-`Promise`\<`void`\>
-
-        ### <a id="XyUserEventHandler"></a>XyUserEventHandler
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Concrete event handler that sends tracking events through the XyPixel singleton.
-
-## Extends
-
-- [`UserEventHandler`](#UserEventHandler)\<`T`\>
-
-## Type Parameters
-
-### T
-
-`T` *extends* `EmptyObject` = `EmptyObject`
-
-## Constructors
-
-### Constructor
-
-```ts
-new XyUserEventHandler<T>(): XyUserEventHandler<T>;
-```
-
-### Returns
-
-`XyUserEventHandler`\<`T`\>
-
-### Overrides
-
-[`UserEventHandler`](#UserEventHandler).[`constructor`](UserEventHandler.md#constructor)
-
-## Methods
-
-### funnelStarted()
-
-```ts
-funnelStarted(fields): Promise<void>;
-```
-
-Sends a funnel-started event via the pixel API.
-
-### Parameters
-
-#### fields
-
-[`FunnelStartedFields`](#../interfaces/FunnelStartedFields) \| `T`
-
-### Returns
-
-`Promise`\<`void`\>
-
-### Overrides
-
-[`UserEventHandler`](#UserEventHandler).[`funnelStarted`](UserEventHandler.md#funnelstarted)
-
-***
-
-### purchase()
-
-```ts
-purchase(fields): Promise<void>;
-```
-
-Sends a purchase event via the pixel API.
-
-### Parameters
-
-#### fields
-
-[`PurchaseFields`](#../interfaces/PurchaseFields) \| `T`
-
-### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### testStarted()
-
-```ts
-testStarted(fields): Promise<void>;
-```
-
-Sends a test-started event via the pixel API.
-
-### Parameters
-
-#### fields
-
-[`TestStartedFields`](#../interfaces/TestStartedFields) \| `T`
-
-### Returns
-
-`Promise`\<`void`\>
-
-### Overrides
-
-[`UserEventHandler`](#UserEventHandler).[`testStarted`](UserEventHandler.md#teststarted)
-
-***
-
-### userClick()
-
-```ts
-userClick(fields): Promise<void>;
-```
-
-Sends a user click event via the pixel API.
-
-### Parameters
-
-#### fields
-
-[`UserClickFields`](#../interfaces/UserClickFields) \| `T`
-
-### Returns
-
-`Promise`\<`void`\>
-
-### Overrides
-
-[`UserEventHandler`](#UserEventHandler).[`userClick`](UserEventHandler.md#userclick)
-
-***
-
-### viewContent()
-
-```ts
-viewContent(fields): Promise<void>;
-```
-
-Sends a view-content event via the pixel API.
-
-### Parameters
-
-#### fields
-
-[`ViewContentFields`](#../interfaces/ViewContentFields) \| `T`
-
-### Returns
-
-`Promise`\<`void`\>
-
-### Overrides
-
-[`UserEventHandler`](#UserEventHandler).[`viewContent`](UserEventHandler.md#viewcontent)
-
-      ### interfaces
-
-        ### <a id="CommonFields"></a>CommonFields
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Common fields shared across all tracking event types.
-
-## Extended by
-
-- [`FunnelStartedFields`](#FunnelStartedFields)
-- [`PurchaseFields`](#PurchaseFields)
-- [`TestStartedFields`](#TestStartedFields)
-- [`UserClickFields`](#UserClickFields)
-- [`ViewContentFields`](#ViewContentFields)
-
-## Properties
-
-### funnel?
-
-```ts
-optional funnel?: string;
-```
-
-***
-
-### testData?
-
-```ts
-optional testData?: string;
-```
-
-        ### <a id="FunnelStartedFields"></a>FunnelStartedFields
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Fields for a funnel-started tracking event.
-
-## Extends
-
-- [`CommonFields`](#CommonFields)
-
-## Properties
-
-### funnel?
-
-```ts
-optional funnel?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`funnel`](CommonFields.md#funnel)
-
-***
-
-### testData?
-
-```ts
-optional testData?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`testData`](CommonFields.md#testdata)
-
-***
-
-### name
-
-```ts
-name: string;
-```
-
-        ### <a id="PurchaseFields"></a>PurchaseFields
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Fields for a purchase tracking event.
-
-## Extends
-
-- [`CommonFields`](#CommonFields)
-
-## Properties
-
-### funnel?
-
-```ts
-optional funnel?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`funnel`](CommonFields.md#funnel)
-
-***
-
-### testData?
-
-```ts
-optional testData?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`testData`](CommonFields.md#testdata)
-
-***
-
-### id
-
-```ts
-id: string;
-```
-
-***
-
-### name?
-
-```ts
-optional name?: string;
-```
-
-***
-
-### price?
-
-```ts
-optional price?: number;
-```
-
-***
-
-### value?
-
-```ts
-optional value?: number;
-```
-
-        ### <a id="TestStartedFields"></a>TestStartedFields
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Fields for a test-started tracking event (e.g. A/B test).
-
-## Extends
-
-- [`CommonFields`](#CommonFields)
-
-## Properties
-
-### funnel?
-
-```ts
-optional funnel?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`funnel`](CommonFields.md#funnel)
-
-***
-
-### testData?
-
-```ts
-optional testData?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`testData`](CommonFields.md#testdata)
-
-***
-
-### name
-
-```ts
-name: string;
-```
-
-        ### <a id="UserClickFields"></a>UserClickFields
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Fields for a user click tracking event.
-
-## Extends
-
-- [`CommonFields`](#CommonFields)
-
-## Properties
-
-### funnel?
-
-```ts
-optional funnel?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`funnel`](CommonFields.md#funnel)
-
-***
-
-### testData?
-
-```ts
-optional testData?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`testData`](CommonFields.md#testdata)
-
-***
-
-### elementName
-
-```ts
-elementName: string;
-```
-
-***
-
-### elementType
-
-```ts
-elementType: string;
-```
-
-***
-
-### intent?
-
-```ts
-optional intent?: string;
-```
-
-***
-
-### placement?
-
-```ts
-optional placement?: string;
-```
-
-        ### <a id="UserEvent"></a>UserEvent
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Represents a single user tracking event to be sent to the pixel API.
-
-## Properties
-
-### cid
-
-```ts
-cid: string;
-```
-
-***
-
-### create\_time?
-
-```ts
-optional create_time?: number;
-```
-
-***
-
-### email?
-
-```ts
-optional email?: string;
-```
-
-***
-
-### email\_hash?
-
-```ts
-optional email_hash?: string;
-```
-
-***
-
-### event?
-
-```ts
-optional event?: string;
-```
-
-***
-
-### event\_id?
-
-```ts
-optional event_id?: string;
-```
-
-***
-
-### exids?
-
-```ts
-optional exids?: ExIds;
-```
-
-***
-
-### fields?
-
-```ts
-optional fields?: Record<string, unknown>;
-```
-
-***
-
-### host?
-
-```ts
-optional host?: string;
-```
-
-***
-
-### pathname?
-
-```ts
-optional pathname?: string;
-```
-
-***
-
-### pixel?
-
-```ts
-optional pixel?: string;
-```
-
-***
-
-### receive\_time?
-
-```ts
-optional receive_time?: number;
-```
-
-***
-
-### referrer?
-
-```ts
-optional referrer?: object;
-```
-
-### local
-
-```ts
-local: string;
-```
-
-### session
-
-```ts
-session: string;
-```
-
-***
-
-### rid?
-
-```ts
-optional rid?: string;
-```
-
-***
-
-### system?
-
-```ts
-optional system?: ParsedResult;
-```
-
-***
-
-### uid?
-
-```ts
-optional uid?: string;
-```
-
-***
-
-### utm?
-
-```ts
-optional utm?: Record<string, string>[] | Record<string, string[]>;
-```
-
-        ### <a id="ViewContentFields"></a>ViewContentFields
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-Fields for a view-content tracking event.
-
-## Extends
-
-- [`CommonFields`](#CommonFields)
-
-## Properties
-
-### funnel?
-
-```ts
-optional funnel?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`funnel`](CommonFields.md#funnel)
-
-***
-
-### testData?
-
-```ts
-optional testData?: string;
-```
-
-### Inherited from
-
-[`CommonFields`](#CommonFields).[`testData`](CommonFields.md#testdata)
-
-***
-
-### name
-
-```ts
-name: string;
-```
-
-***
-
-### path
-
-```ts
-path: string;
-```
-
-        ### <a id="XyLabsTrackingEventJson"></a>XyLabsTrackingEventJson
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-JSON structure for an XY Labs tracking event as stored or transmitted.
-
-## Properties
-
-### cid
-
-```ts
-cid: string;
-```
-
-***
-
-### create\_time?
-
-```ts
-optional create_time?: number;
-```
-
-***
-
-### email?
-
-```ts
-optional email?: string;
-```
-
-***
-
-### email\_hash?
-
-```ts
-optional email_hash?: string;
-```
-
-***
-
-### event?
-
-```ts
-optional event?: string;
-```
-
-***
-
-### event\_id?
-
-```ts
-optional event_id?: string;
-```
-
-***
-
-### exids?
-
-```ts
-optional exids?: Record<string, string>;
-```
-
-***
-
-### fields?
-
-```ts
-optional fields?: Record<string, unknown>;
-```
-
-***
-
-### host?
-
-```ts
-optional host?: string;
-```
-
-***
-
-### ip?
-
-```ts
-optional ip?: string;
-```
-
-***
-
-### pathname?
-
-```ts
-optional pathname?: string;
-```
-
-***
-
-### pixel?
-
-```ts
-optional pixel?: string;
-```
-
-***
-
-### receive\_time?
-
-```ts
-optional receive_time?: number;
-```
-
-***
-
-### rid?
-
-```ts
-optional rid?: string;
-```
-
-***
-
-### system?
-
-```ts
-optional system?: unknown;
-```
-
-***
-
-### ua?
-
-```ts
-optional ua?: string;
-```
-
-***
-
-### uid?
-
-```ts
-optional uid?: string;
-```
-
-***
-
-### utm?
-
-```ts
-optional utm?: Record<string, string>[] | Record<string, string[]>;
-```
-
-      ### interfaces
-
-        ### <a id="UserEventSystem"></a>UserEventSystem
-
-[**@xylabs/pixel**](#../README)
-
-***
-
-```ts
-interface UserEventSystem
-```
-
-Parsed browser/OS/engine information from the user agent string.
-
-#### Properties
-
-### browser?
-
-```ts
-optional browser: UserEventSystemBrowser;
-```
-
-### engine?
-
-```ts
-optional engine: UserEventSystemEngine;
-```
-
-### os?
-
-```ts
-optional os: UserEventSystemOS;
-```
-
-### platform?
-
-```ts
-optional platform: UserEventSystemPlatform;
-```
-
-## Credits
-
-[Made with 🔥 and ❄️ by XY Labs](https://xylabs.com)
-
-[npm-badge]: https://img.shields.io/npm/v/@xylabs/pixel.svg
-[npm-link]: https://www.npmjs.com/package/@xylabs/pixel
-[license-badge]: https://img.shields.io/npm/l/@xylabs/pixel.svg
-[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE
-[logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg
+DEPRECATED — use `@ariestools/pixel` instead.