@snowplow/signals-browser-plugin 0.0.1

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025 Snowplow Analytics Ltd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,131 @@
+# Snowplow Signals Interventions Plugin
+
+[![npm version][npm-image]][npm-url]
+[![License][license-image]](LICENSE)
+
+Browser Plugin to be used with [`@snowplow/browser-tracker`](https://github.com/snowplow/snowplow-javascript-tracker).
+
+This plugin allows receiving and reacting to [Snowplow Signals](https://docs.snowplow.io/docs/signals/) interventions.
+
+## Maintainer quick start
+
+Build with [Node.js](https://nodejs.org/).
+
+### Setup repository
+
+```bash
+git clone https://github.com/snowplow-incubator/signals-browser-plugin.git
+npm install
+```
+
+## Package Installation
+
+With npm:
+
+```bash
+npm install @snowplow/signals-browser-plugin
+```
+
+## Usage
+
+Initialize your tracker with the `SignalsInterventionsPlugin`, add a handler, and request interventions:
+
+```js
+import { newTracker } from '@snowplow/browser-tracker';
+import {
+  SignalsInterventionsPlugin,
+  addInterventionHandlers,
+  subscribeToInterventions,
+} from '@snowplow/signals-browser-plugin';
+
+newTracker('sp1', '{{collector_url}}', {
+  appId: 'my-app-id',
+  plugins: [SignalsInterventionsPlugin()],
+});
+
+addInterventionHandlers({
+  myHandler(intervention) {
+    console.log('intervention received!', intervention);
+  },
+});
+
+subscribeToInterventions({
+  endpoint: '00000000-0000-0000-0000-000000000000.svc.snplow.net',
+});
+```
+
+### Configuration
+
+#### Plugin Configuration
+
+The plugin can be configured with the following options:
+
+- `handlers`: Object containing handler functions to be called when interventions are received
+- `measurement`: Configure defaults for the built-in events the plugin generates when interventions are received
+  - `delivery`, `dispatch_accept`, `dispatch_error`: Set to `false` or a boolean-returning function to disable tracking events when interventions are received or handled
+  - `context`: Set to an array of entities or entity-generating callbacks to add custom context to events generated by the plugin
+
+#### Handlers
+
+Handlers can be provided in the initial configuration via the `handlers` setting, or added dynamically after configuration using `addInterventionHandlers()`.
+
+Each handler function will receive the intervention instance payload and the associated `BrowserTracker` instance.
+
+Handlers can also be removed via `removeInterventionHandlers()`, which takes an array of handler IDs.
+
+#### Subscribing
+
+Call `subscribeToInterventions()` to configure the fetcher and make a request for interventions.
+
+It will automatically adjust its subscription to account for updated entity IDs; by default it extracts the standard `domain_userid` and `domain_sessionid` entities.
+
+It takes the following options:
+
+- `endpoint` (required): your Signals API URI to connect to; until this option is provided no connection will be made and no interventions will be received
+- `apiPath`: The path to request from `endpoint` when fetching interventions. Defaults to `/api/v1/interventions`
+- `entityTargets`: Configures how to extract entity IDs from Snowplow events that get observed (see below)
+- `entityIds`: Object mapping explicit entity ID configurations to request, as an object
+- `connectionTimeoutMs`: How long to wait for the initial network request to be accepted before aborting (default 2500 milliseconds)
+
+You can call this function multiple times to update these settings, previous connections will be closed if necessary.
+
+#### Entity Targets
+
+The `entityTargets` setting lets you declare rules for entity IDs to extract from events that the Snowplow tracker generates.
+
+You specify a map of entity name to a string (or array of strings) containing [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901) that configure how to find the value to use as an ID.
+For arrays, if a JSON Pointer does not return a result, the next pointer in the array is tried until a value is found.
+
+The JSON pointers are evaluated against `Payload` instances, so the fields use their [Tracker Protocol](https://docs.snowplow.io/docs/events/going-deeper/event-parameters/) names.
+
+For convenience, the plugin will map enriched field-names to their Tracker Protocol equivalents so either work.
+The fields available are only those present in the actual event however, so values added during enrichment like `geo_country` will not work, beyond basic examples like `event_name` or `page_urlpath` which will be computed and work.
+
+Entities and self-describing event payloads are mapped in a version independent manner, accessible under their tracker protocol fields, followed by vendor and name.
+Single-element arrays will be treated as scalars for convenience.
+
+For example, the default entity IDs could alternatively be explicitly configured via:
+
+```json
+{
+  "domain_userid": ["duid", "domain_userid", "/context/com.snowplowanalytics.snowplow/client_session/userId"],
+  "domain_sessionid": ["sid", "domain_sessionid", "/cx/com.snowplowanalytics.snowplow/client_session/sessionId"]
+}
+```
+
+`duid` and `domain_userid` would both lookup the `duid` field so are redundant, but if not found the `client_session` entity will be examined.
+If the found value is `null` or `undefined`, the entity will be ignored until a later event supplies a matching value to use as ID.
+
+## Copyright and license
+
+Licensed and distributed under the [BSD 3-Clause License](LICENSE) ([An OSI Approved License][osi]).
+
+Copyright (c) 2025 Snowplow Analytics Ltd.
+
+All rights reserved.
+
+[npm-url]: https://www.npmjs.com/package/@snowplow/browser-plugin-signals-interventions
+[npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-signals-interventions
+[docs]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-tracker/
+[osi]: https://opensource.org/licenses/BSD-3-Clause
+[license-image]: https://img.shields.io/npm/l/@snowplow/browser-plugin-signals-interventions

package/dist/index.module.d.ts

@@ -0,0 +1,187 @@
+import { Payload, BrowserTracker, BrowserPlugin } from '@snowplow/browser-tracker-core';
+import { DynamicContext } from '@snowplow/tracker-core';
+
+declare const MEASUREMENT_EVENTS: {
+    readonly delivery: "iglu:com.snowplowanalytics.signals/intervention_receive/jsonschema/1-0-0";
+    readonly dispatch_accept: "iglu:com.snowplowanalytics.signals/intervention_handle/jsonschema/1-0-0";
+    readonly dispatch_error: "iglu:com.snowplowanalytics.signals/intervention_handle_error/jsonschema/1-0-0";
+};
+type MeasurementEvents = keyof typeof MEASUREMENT_EVENTS;
+
+/**
+ * An Intervention payload received from the Signals API.
+ */
+type Intervention = {
+    /**
+     * Unique identifier for this triggered Intervention instance. Interventions triggered against different Entities should be deduped by this ID.
+     */
+    intervention_id: string;
+    /**
+     * The unique name/identifier for the Intervention (or its definition).
+     */
+    name: string;
+    /**
+     * Version number for this intervention's definition if applicable.
+     */
+    version: number;
+    /**
+     * The complete or requested set of attributes for the Entity this intervention was triggered against an their values when it was triggered.
+     */
+    attributes: Record<string, OneOrMore<string | number | boolean>>;
+    /**
+     * Information about the Entity that triggered this intervention or is intended to receive it.
+     */
+    target_entity?: {
+        /**
+         * The name/type of Entity that is the target/triggerer of this intervention.
+         */
+        name: EntityName;
+        /**
+         * The specific identifier for the instance of type `entityName` that is the target/triggerer of this intervention.
+         */
+        id?: EntityId;
+    };
+};
+/**
+ * Convenience utility, allowing a single scalar or array of multiple scalar values of type T.
+ */
+type OneOrMore<T> = T | T[];
+/**
+ * A JSON Pointer is a slash-separated path of key segments for identifying a single JSON value within a complex JSON document. (see RFC 6901)
+ */
+type JSONPointer = '' | `/${string}`;
+/**
+ * A single or array of JSON Pointers. The first to return a non-undefined result is the value used.
+ */
+type JSONPointerList = OneOrMore<JSONPointer>;
+/**
+ * Handle for an entity type to request Interventions for. The name is paired with an EntityId as URL parameters in the request for Interventions.
+ */
+type EntityName = string;
+/**
+ * An identifier for a specific Entity instance.
+ */
+type EntityId = string;
+/**
+ * Unique name/identifier for an Intervention handler.
+ */
+type HandlerId = string;
+/**
+ * Unique ID/namespace for a Snowplow tracker instance.
+ */
+type TrackerId = string;
+/**
+ * Configuration the API to request interventions from.
+ */
+type SignalsInterventionConfiguration = {
+    /**
+     * The Signals API endpoint to request from. Should be a hostname, with optional scheme or path prefix.
+     */
+    endpoint: string;
+    /**
+     * The API call path to append to `endpoint`, if required. Defaults to `/api/v1/interventions`.
+     */
+    apiPath?: string;
+    /**
+     * A definition of entity types and JSON Pointers to extract the ID values from. These will be extracted from events as they are tracked to update the Intervention request as values are updated.
+     */
+    entityTargets?: Record<EntityName, JSONPointerList>;
+    /**
+     * An explicit set of entity types and corresponding IDs to request interventions for.
+     */
+    entityIds?: Record<EntityName, EntityId>;
+    /**
+     * Timeout duration to wait for the initial API to accept the Intervention request.
+     */
+    connectionTimeoutMs?: number;
+};
+/**
+ * Configuration for the events generated by the plugin when interventions are received/handled.
+ * Each type of event can be enabled/disabled, or decided dynamically via a callback.
+ */
+type MeasurementSettings = Record<MeasurementEvents, boolean | ((_: Intervention) => boolean)>;
+/**
+ * Initial plugin configuration for receiving Interventions.
+ * Controls initial handlers, measurement settings, and optionally a custom fetcher may be provided.
+ */
+type SignalsHandlerConfiguration = {
+    /**
+     * Custom function to build a `Fetcher` given a `BrowserTracker` instance and `dispatch` callback to deliver any received interventions to registered handlers.
+     * @private
+     */
+    fetcher?: FetcherFactory;
+    /**
+     * Map of custom handlers to call with custom Interventions received. If not provided here, they can be added later via `addInterventionHandlers`.
+     */
+    handlers?: Record<HandlerId, Handler>;
+    /**
+     * Settings for changing the events automatically tracked by this plugin when interventions are delivered, successfully processed by a handler, or unsuccessfully processed by a handler.
+     */
+    measurement?: Partial<MeasurementSettings> & {
+        /**
+         * Custom entities to attach to the events generated by the plugin.
+         * Callbacks will receive a label for the type of event, the intervention itself, and the event payload.
+         */
+        context?: DynamicContext;
+    };
+};
+/**
+ * A `FetcherFactory` function is called when the plugin is activated and should construct and return a `Fetcher` instance that calls the provided `dispatch` callback when Interventions are received.
+ * The plugin provides its own `DefaultFetcher` if not provided.
+ */
+interface FetcherFactory {
+    (tracker: BrowserTracker, dispatch: (intervention: Intervention, tracker: BrowserTracker) => void): Fetcher;
+}
+/**
+ * A `Fetcher` is expected to react to calls to `configure()` and use the provided information to subscribe to Interventions.
+ * When interventions are received, a `Fetcher` is expected to call the `dispatch` callback that was provided to the `FetchFactory` that constructed the `Fetcher` and provide the `BrowserTracker` to measure events with.
+ * `update()` will be called when new Snowplow events are observed, or explicit entity IDs are provided. It should update the connection so Interventions may be received for new entities described in the event.
+ */
+interface Fetcher {
+    /**
+     * Accept a configuration for an interventions endpoint, and set up a connection to subscribe for Interventions on any configured entities.
+     * @param config Endpoint/entity configuration information.
+     */
+    configure(config: SignalsInterventionConfiguration): void;
+    /**
+     * Called when a new Snowplow event has been observed or entity IDs provided. Entity IDs should be extracted and intervention subscription updated to accommodate new IDs if found.
+     * @param payload A Snowplow event payload observed.
+     * @param explicitEntities An explicit set of entity names/IDs to subscribe for.
+     */
+    update(payload?: Payload, explicitEntities?: Record<EntityName, EntityId>): void;
+}
+/**
+ * `Handler`s are delivered Intervention instanced as they are received.
+ * They receive the Intervention payload and the tracker instance if needed to pull other state if required.
+ * The function may `return` to be considered successfully handled, or `throw` to be considered a failure, which the plugin will track as an event.
+ * Async functions or functions that return Promises will be awaited and resolve/reject are treated as success/failure.
+ */
+type Handler = (intervention: Intervention, tracker: BrowserTracker) => Promise<unknown> | unknown;
+
+/**
+ * Create an instance of the Signals Interventions plugin.
+ * @param configuration Configuration for the plugin
+ * @returns Configured plugin instance
+ */
+declare function SignalsInterventionsPlugin({ fetcher, measurement, handlers }?: SignalsHandlerConfiguration): BrowserPlugin;
+/**
+ * Configure the endpoint information for the plugin's `Fetcher` to subscribe to events from
+ * @param config Configuration about the endpoint and entity IDs/definitions to configure
+ * @param trackers List of tracker IDs that have activated the plugin to configure a `Fetcher` for
+ */
+declare function subscribeToInterventions(config: SignalsInterventionConfiguration, trackers?: TrackerId[]): void;
+/**
+ * Start calling the given handlers when new interventions are received
+ * @param handlers Map of handler IDs to handler functions to call with new interventions
+ * @param trackers List of tracker IDs that have activated the plugin to add these handlers to
+ */
+declare function addInterventionHandlers(handlers: Record<HandlerId, Handler>, trackers?: TrackerId[]): void;
+/**
+ * Stop calling handlers with the given IDs with new interventions
+ * @param handlerIds One or more handler IDs to remove
+ * @param trackers List of trackers to remove the handlers for; defaults to all trackers that have activated the plugin.
+ */
+declare function removeInterventionHandlers(handlerIds: OneOrMore<HandlerId>, trackers?: TrackerId[]): void;
+
+export { SignalsInterventionsPlugin, addInterventionHandlers, removeInterventionHandlers, subscribeToInterventions };
+export type { EntityId, EntityName, Fetcher, FetcherFactory, Handler, HandlerId, Intervention, JSONPointer, JSONPointerList, MeasurementEvents, MeasurementSettings, OneOrMore, SignalsHandlerConfiguration, SignalsInterventionConfiguration, TrackerId };