@trakoo/openpanel 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 trakoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @trakoo/openpanel
+
+OpenPanel providers for [trakoo](https://www.npmjs.com/package/trakoo), the typed, provider-agnostic analytics library.
+
+## Installation
+
+Install the package with only the OpenPanel SDK for the side you use:
+
+```bash
+# Browser
+pnpm add trakoo @trakoo/openpanel @openpanel/web
+
+# Server
+pnpm add trakoo @trakoo/openpanel @openpanel/sdk
+```
+
+## Usage
+
+`appEvents` is your event registry, created with `defineEvents()` from `trakoo`.
+
+```typescript title="lib/analytics.ts"
+import { createClientAnalytics } from 'trakoo/client';
+import { OpenPanelClientProvider } from '@trakoo/openpanel/client';
+import { appEvents } from './events';
+
+export const analytics = createClientAnalytics({
+  events: appEvents,
+  providers: [
+    new OpenPanelClientProvider({
+      clientId: import.meta.env.VITE_OPENPANEL_CLIENT_ID
+    })
+  ]
+});
+```
+
+```typescript title="lib/server-analytics.ts"
+import { createServerAnalytics } from 'trakoo/server';
+import { OpenPanelServerProvider } from '@trakoo/openpanel/server';
+import { appEvents } from './events';
+
+export const serverAnalytics = createServerAnalytics({
+  events: appEvents,
+  providers: [
+    new OpenPanelServerProvider({
+      clientId: process.env.OPENPANEL_CLIENT_ID!,
+      clientSecret: process.env.OPENPANEL_CLIENT_SECRET!
+    })
+  ]
+});
+```
+
+Never put the client secret in browser code; `OpenPanelClientProvider` does not accept one.
+
+## Documentation
+
+https://trakoo.co/docs/providers/openpanel

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import { BaseAnalyticsProvider, type BaseEvent, type EventContext } from "trakoo";
+import type { OpenPanelDeliveryFailureHandler } from "./transport.js";
+import type { OpenPanelOptions as OpenPanelWebOptions } from "@openpanel/web";
+export type OpenPanelClientConfig = Omit<OpenPanelWebOptions, "clientSecret" | "debug" | "disabled" | "sdk" | "sdkVersion" | "waitForProfile"> & {
+    clientId: string;
+    debug?: boolean;
+    enabled?: boolean;
+    /**
+     * Called when OpenPanel rejects an event. Without a handler the failure is
+     * logged, because the OpenPanel SDK drops rejected requests silently.
+     */
+    onDeliveryFailure?: OpenPanelDeliveryFailureHandler;
+};
+export type { OpenPanelDeliveryFailure, OpenPanelDeliveryFailureHandler, OpenPanelDeliveryFailureReason, } from "./transport.js";
+export declare class OpenPanelClientProvider extends BaseAnalyticsProvider {
+    name: string;
+    private client?;
+    private trackEvent?;
+    private config;
+    private initialized;
+    private initPromise?;
+    private pendingActions;
+    constructor(config: OpenPanelClientConfig);
+    initialize(): Promise<void>;
+    private doInitialize;
+    private runWhenInitialized;
+    private flushPendingActions;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(event: BaseEvent, context?: EventContext): Promise<void>;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): void;
+    pageLeave(_properties?: Record<string, unknown>, _context?: EventContext): void;
+    reset(): void;
+}

package/dist/client.js

@@ -0,0 +1,135 @@
+import { BaseAnalyticsProvider, } from "trakoo";
+import { buildEventProperties, buildIdentifyPayload, buildTrackedEventProperties, } from "./shared.js";
+import { createDeliveryFailureReporter, instrumentOpenPanelDelivery, } from "./transport.js";
+import { isBrowser } from "./environment.js";
+export class OpenPanelClientProvider extends BaseAnalyticsProvider {
+    name = "OpenPanel-Client";
+    client;
+    trackEvent;
+    config;
+    initialized = false;
+    initPromise;
+    pendingActions = [];
+    constructor(config) {
+        super({ debug: config.debug, enabled: config.enabled });
+        this.config = config;
+    }
+    initialize() {
+        if (!this.isEnabled() || this.initialized)
+            return Promise.resolve();
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.doInitialize();
+        return this.initPromise;
+    }
+    async doInitialize() {
+        if (!isBrowser()) {
+            this.log("Skipping initialization - not in browser environment");
+            return;
+        }
+        if (!this.config.clientId || typeof this.config.clientId !== "string") {
+            this.initPromise = undefined;
+            throw new Error("OpenPanel requires a clientId");
+        }
+        try {
+            const { OpenPanel, OpenPanelBase } = await import("@openpanel/web");
+            const runtimeConfig = this.config;
+            const { enabled, clientSecret, disabled, onDeliveryFailure, sdk, sdkVersion, waitForProfile, ...options } = runtimeConfig;
+            void enabled;
+            void clientSecret;
+            void disabled;
+            void sdk;
+            void sdkVersion;
+            void waitForProfile;
+            this.client = new OpenPanel({
+                trackAttributes: false,
+                trackOutgoingLinks: false,
+                trackScreenViews: false,
+                ...options,
+                debug: this.config.debug ?? false,
+            });
+            const instrumented = instrumentOpenPanelDelivery(this.client, createDeliveryFailureReporter(this.name, onDeliveryFailure));
+            if (!instrumented) {
+                console.warn("[OpenPanel-Client] Unrecognized @openpanel/web transport - delivery failure reporting is unavailable");
+            }
+            // The web override replaces a caller-supplied __path with its last screen view.
+            this.trackEvent = OpenPanelBase.prototype.track.bind(this.client);
+            this.initialized = true;
+            this.flushPendingActions();
+            this.log("Initialized successfully");
+        }
+        catch (error) {
+            this.initPromise = undefined;
+            this.pendingActions = [];
+            console.error(`[OpenPanel-Client] Failed to initialize (${this.getErrorClass(error)})`);
+            throw error;
+        }
+    }
+    runWhenInitialized(action) {
+        if (!this.isEnabled())
+            return;
+        if (this.initialized && this.client) {
+            action();
+            return;
+        }
+        if (this.initPromise) {
+            this.pendingActions.push(action);
+        }
+    }
+    flushPendingActions() {
+        const actions = this.pendingActions;
+        this.pendingActions = [];
+        for (const action of actions) {
+            try {
+                action();
+            }
+            catch (error) {
+                console.error(`[OpenPanel-Client] Pending action failed (${this.getErrorClass(error)})`);
+            }
+        }
+    }
+    identify(userId, traits) {
+        this.runWhenInitialized(() => {
+            const pending = this.client?.identify(buildIdentifyPayload(userId, traits));
+            if (pending) {
+                void pending.catch((error) => {
+                    console.error(`[OpenPanel-Client] Failed to identify user (${this.getErrorClass(error)})`);
+                });
+            }
+            this.log("Identified user");
+        });
+    }
+    async track(event, context) {
+        if (!this.isEnabled())
+            return;
+        if (!this.initialized && this.initPromise)
+            await this.initPromise;
+        if (!this.initialized || !this.trackEvent)
+            return;
+        await this.trackEvent(event.action, buildTrackedEventProperties(event, context));
+        this.log("Tracked event");
+    }
+    pageView(properties, context) {
+        this.runWhenInitialized(() => {
+            const pageProperties = buildEventProperties(properties, context, {});
+            const path = context?.page?.url ?? context?.page?.path;
+            if (path) {
+                this.client?.screenView(path, pageProperties);
+            }
+            else {
+                this.client?.screenView(pageProperties);
+            }
+            this.log("Tracked page view");
+        });
+    }
+    pageLeave(_properties, _context) {
+        this.log("Page leave is not supported by OpenPanel");
+    }
+    reset() {
+        this.pendingActions = [];
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        this.client.clear();
+        this.log("Cleared user identity");
+    }
+}

package/dist/environment.d.ts

@@ -0,0 +1 @@
+export declare function isBrowser(): boolean;

package/dist/environment.js

@@ -0,0 +1,3 @@
+export function isBrowser() {
+    return (typeof window !== "undefined" && typeof window.document !== "undefined");
+}

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+import { BaseAnalyticsProvider, type BaseEvent, type EventContext } from "trakoo";
+import type { OpenPanelDeliveryFailureHandler } from "./transport.js";
+import type { OpenPanelOptions } from "@openpanel/sdk";
+export interface OpenPanelServerConfig {
+    clientId: string;
+    clientSecret: string;
+    apiUrl?: string;
+    filter?: OpenPanelOptions["filter"];
+    debug?: boolean;
+    enabled?: boolean;
+    /**
+     * Called when OpenPanel rejects an event. Without a handler the failure is
+     * logged, because the OpenPanel SDK drops rejected requests silently.
+     */
+    onDeliveryFailure?: OpenPanelDeliveryFailureHandler;
+}
+export type { OpenPanelDeliveryFailure, OpenPanelDeliveryFailureHandler, OpenPanelDeliveryFailureReason, } from "./transport.js";
+export declare class OpenPanelServerProvider extends BaseAnalyticsProvider {
+    name: string;
+    private client?;
+    private config;
+    private initialized;
+    private initializePromise?;
+    constructor(config: OpenPanelServerConfig);
+    initialize(): Promise<void>;
+    private initializeOpenPanel;
+    private reportDeliveryFailures;
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    track(event: BaseEvent, context?: EventContext): Promise<void>;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): Promise<void>;
+    pageLeave(_properties?: Record<string, unknown>, _context?: EventContext): void;
+    reset(): void;
+    shutdown(): void;
+}

package/dist/server.js

@@ -0,0 +1,133 @@
+import { BaseAnalyticsProvider, } from "trakoo";
+import { buildEventProperties, buildIdentifyPayload, buildTrackedEventProperties, withRequestContext, } from "./shared.js";
+import { createDeliveryFailureReporter, instrumentOpenPanelDelivery, } from "./transport.js";
+const isMissingPackageError = (error, packageName) => {
+    try {
+        if (!error || typeof error !== "object")
+            return false;
+        const code = Reflect.get(error, "code");
+        const message = Reflect.get(error, "message");
+        if ((code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") ||
+            typeof message !== "string") {
+            return false;
+        }
+        return (message.includes(`Cannot find package '${packageName}'`) ||
+            message.includes(`Cannot find module '${packageName}'`));
+    }
+    catch {
+        return false;
+    }
+};
+export class OpenPanelServerProvider extends BaseAnalyticsProvider {
+    name = "OpenPanel-Server";
+    client;
+    config;
+    initialized = false;
+    initializePromise;
+    constructor(config) {
+        super({ debug: config.debug, enabled: config.enabled });
+        this.config = config;
+    }
+    initialize() {
+        if (!this.isEnabled() || this.initialized)
+            return Promise.resolve();
+        if (this.initializePromise)
+            return this.initializePromise;
+        this.initializePromise = this.initializeOpenPanel().catch((error) => {
+            this.initializePromise = undefined;
+            console.error(`[OpenPanel-Server] Failed to initialize (${this.getErrorClass(error)})`);
+            throw error;
+        });
+        return this.initializePromise;
+    }
+    async initializeOpenPanel() {
+        if (!this.config.clientId || typeof this.config.clientId !== "string") {
+            throw new Error("OpenPanel requires a clientId");
+        }
+        if (!this.config.clientSecret ||
+            typeof this.config.clientSecret !== "string") {
+            throw new Error("OpenPanel requires a clientSecret on the server");
+        }
+        let OpenPanelClient;
+        try {
+            ({ OpenPanel: OpenPanelClient } = await import("@openpanel/sdk"));
+        }
+        catch (error) {
+            if (isMissingPackageError(error, "@openpanel/sdk")) {
+                throw new Error("OpenPanel server provider requires the optional peer package @openpanel/sdk");
+            }
+            throw error;
+        }
+        // Built from the documented options alone. An untyped `disabled` or
+        // `waitForProfile` makes the shared client queue events and release
+        // them under whichever request identifies next.
+        const { apiUrl, clientId, clientSecret, debug, filter, onDeliveryFailure } = this.config;
+        this.client = new OpenPanelClient({
+            clientId,
+            clientSecret,
+            ...(apiUrl !== undefined && { apiUrl }),
+            ...(debug !== undefined && { debug }),
+            ...(filter !== undefined && { filter }),
+        });
+        this.reportDeliveryFailures(onDeliveryFailure);
+        this.initialized = true;
+        this.log("Initialized successfully");
+    }
+    reportDeliveryFailures(onDeliveryFailure) {
+        const instrumented = instrumentOpenPanelDelivery(this.client, createDeliveryFailureReporter(this.name, onDeliveryFailure));
+        if (!instrumented) {
+            // Attribution rides on this transport, so losing it must not be quiet.
+            console.warn("[OpenPanel-Server] Unrecognized @openpanel/sdk transport - caller IP and user agent attribution and delivery failure reporting are unavailable");
+        }
+    }
+    async identify(userId, traits) {
+        const client = this.isEnabled() && this.initialized ? this.client : undefined;
+        if (!client)
+            return;
+        let pending;
+        try {
+            pending = client.identify(buildIdentifyPayload(userId, traits));
+        }
+        finally {
+            client.clear();
+        }
+        await pending;
+        this.log("Updated user profile");
+    }
+    async track(event, context) {
+        const client = this.isEnabled() && this.initialized ? this.client : undefined;
+        if (!client)
+            return;
+        await client.track(event.action, withRequestContext(buildTrackedEventProperties(event, context), context));
+        this.log("Tracked event");
+    }
+    async pageView(properties, context) {
+        const client = this.isEnabled() && this.initialized ? this.client : undefined;
+        if (!client)
+            return;
+        await client.track("screen_view", withRequestContext(buildEventProperties(properties, context, {
+            category: "navigation",
+            userId: context?.user?.userId,
+        }), context));
+        this.log("Tracked page view");
+    }
+    pageLeave(_properties, _context) {
+        this.log("Page leave is not supported by OpenPanel");
+    }
+    reset() {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        this.client.clear();
+        this.log("Cleared user identity");
+    }
+    shutdown() {
+        const client = this.isEnabled() && this.initialized ? this.client : undefined;
+        if (!client)
+            return;
+        client.clear();
+        this.client = undefined;
+        this.initialized = false;
+        this.initializePromise = undefined;
+        this.log("Shutdown complete");
+    }
+}

package/dist/shared.d.ts

@@ -0,0 +1,28 @@
+import type { BaseEvent, EventContext } from "trakoo";
+import { type OpenPanelRequestContext } from "./transport.js";
+import type { IdentifyPayload } from "@openpanel/sdk";
+export declare function buildIdentifyPayload(userId: string, traits?: Record<string, unknown>): IdentifyPayload;
+export declare function buildEventProperties(properties: Record<string, unknown> | undefined, context: EventContext | undefined, metadata: {
+    category?: string;
+    timestamp?: number;
+    userId?: string;
+    sessionId?: string;
+}): Record<string, unknown>;
+export declare function buildTrackedEventProperties(event: BaseEvent, context?: EventContext): Record<string, unknown>;
+/**
+ * Collects the attributes OpenPanel resolves from request headers rather than
+ * from the event body: the caller's IP for geo, its user agent for the device.
+ * `server` is the request-scoped source a server caller populates; `device` is
+ * the fallback for callers that already put the visitor there.
+ */
+export declare function buildRequestContext(context: EventContext | undefined): OpenPanelRequestContext | undefined;
+/**
+ * Parks the request attributes on the payload for the delivery transport to
+ * move onto this one request's headers, and drops the IP `context.device`
+ * contributed to the `device` property: geo belongs to the request, and a raw
+ * address stored on every event is a liability the header avoids.
+ *
+ * Only the server provider applies this. A browser sends its own headers, and
+ * `user-agent` is forbidden to `fetch()` there.
+ */
+export declare function withRequestContext(properties: Record<string, unknown>, context: EventContext | undefined): Record<string, unknown>;

package/dist/shared.js

@@ -0,0 +1,114 @@
+import { REQUEST_CONTEXT } from "./transport.js";
+const PROFILE_FIELDS = ["firstName", "lastName", "email", "avatar"];
+/**
+ * The bytes Node's `fetch` accepts in a header value. It refuses anything else
+ * before the request leaves, and the transport cannot tell that refusal from a
+ * network failure: one malformed attribute would retry and then lose the
+ * whole event. A value outside this set is skipped instead.
+ */
+const HEADER_VALUE = /^[\t\x20-\x7e\x80-\xff]+$/;
+export function buildIdentifyPayload(userId, traits) {
+    const payload = { profileId: userId };
+    const properties = {};
+    for (const [key, value] of Object.entries(traits ?? {})) {
+        if (PROFILE_FIELDS.includes(key) &&
+            typeof value === "string") {
+            if (key === "firstName")
+                payload.firstName = value;
+            if (key === "lastName")
+                payload.lastName = value;
+            if (key === "email")
+                payload.email = value;
+            if (key === "avatar")
+                payload.avatar = value;
+        }
+        else {
+            properties[key] = value;
+        }
+    }
+    if (Object.keys(properties).length > 0) {
+        payload.properties = properties;
+    }
+    return payload;
+}
+export function buildEventProperties(properties, context, metadata) {
+    const pagePath = context?.page?.url ?? context?.page?.path;
+    return {
+        ...properties,
+        ...(metadata.category && { category: metadata.category }),
+        ...(metadata.timestamp !== undefined && {
+            __timestamp: new Date(metadata.timestamp).toISOString(),
+        }),
+        ...(metadata.userId && { profileId: metadata.userId }),
+        ...(metadata.sessionId && { sessionId: metadata.sessionId }),
+        ...(pagePath && { __path: pagePath }),
+        ...(context?.page?.title && { __title: context.page.title }),
+        ...(context?.page?.referrer && { __referrer: context.page.referrer }),
+        ...(context?.page && { page: context.page }),
+        ...(context?.device && { device: context.device }),
+        ...(context?.utm && { utm: context.utm }),
+        ...(context?.user?.email && { user_email: context.user.email }),
+        ...(context?.user?.traits && { user_traits: context.user.traits }),
+    };
+}
+export function buildTrackedEventProperties(event, context) {
+    return buildEventProperties(event.properties, context, {
+        category: event.category,
+        timestamp: event.timestamp,
+        userId: event.userId ?? context?.user?.userId,
+        sessionId: event.sessionId,
+    });
+}
+/**
+ * Collects the attributes OpenPanel resolves from request headers rather than
+ * from the event body: the caller's IP for geo, its user agent for the device.
+ * `server` is the request-scoped source a server caller populates; `device` is
+ * the fallback for callers that already put the visitor there.
+ */
+export function buildRequestContext(context) {
+    const ip = firstHeaderValue(context?.server?.ip, context?.device?.ip);
+    const userAgent = firstHeaderValue(context?.server?.userAgent, context?.device?.userAgent);
+    if (!ip && !userAgent)
+        return undefined;
+    return { ...(ip && { ip }), ...(userAgent && { userAgent }) };
+}
+/**
+ * Parks the request attributes on the payload for the delivery transport to
+ * move onto this one request's headers, and drops the IP `context.device`
+ * contributed to the `device` property: geo belongs to the request, and a raw
+ * address stored on every event is a liability the header avoids.
+ *
+ * Only the server provider applies this. A browser sends its own headers, and
+ * `user-agent` is forbidden to `fetch()` there.
+ */
+export function withRequestContext(properties, context) {
+    const requestContext = buildRequestContext(context);
+    // Only the address copied out of `context.device` is removed. A `device`
+    // the event declared itself is its own data, and an IP promoted from
+    // `context.server` says nothing about it. The address is removed even when
+    // it could not be promoted, so a malformed one is not stored instead.
+    const stripped = typeof context?.device?.ip === "string"
+        ? withoutContextDeviceIp(properties)
+        : properties;
+    return requestContext
+        ? { ...stripped, [REQUEST_CONTEXT]: requestContext }
+        : stripped;
+}
+function withoutContextDeviceIp(properties) {
+    const { device: _contextDevice, ...rest } = properties;
+    const device = withoutIp(properties.device);
+    return { ...rest, ...(device !== undefined && { device }) };
+}
+function withoutIp(device) {
+    if (!device || typeof device !== "object")
+        return device;
+    const { ip: _promoted, ...rest } = device;
+    return Object.keys(rest).length > 0 ? rest : undefined;
+}
+function firstHeaderValue(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && HEADER_VALUE.test(value))
+            return value;
+    }
+    return undefined;
+}

package/dist/transport.d.ts

@@ -0,0 +1,64 @@
+/**
+ * OpenPanel's SDKs treat HTTP 401 as a non-error: their shared `Api.post`
+ * returns `null` without throwing, retrying or logging, so a wrong, rotated or
+ * origin-rejected key stops analytics silently. Both the browser and the server
+ * SDK send through the `api` instance they expose publicly, so trakoo replaces
+ * that instance's `fetch` with an equivalent implementation that reports the
+ * response status before returning the value the SDK expects.
+ *
+ * The replacement mirrors the SDK transport: 200 and 202 are the only success
+ * statuses, 401 is never retried, every other failure backs off exponentially,
+ * and headers, body and request options are built the same way. Delivery still
+ * resolves rather than throwing, so reporting a failure can never turn a
+ * tracked event into an application error.
+ */
+export type OpenPanelDeliveryFailureReason = "network_error" | "server_error" | "unauthorized";
+export interface OpenPanelDeliveryFailure {
+    /** Requests made for this event, including the one that failed. */
+    readonly attempts: number;
+    /** OpenPanel envelope type such as `track` or `identify`, never a payload. */
+    readonly payloadType?: string;
+    readonly reason: OpenPanelDeliveryFailureReason;
+    /** Absent when the request never produced a response. */
+    readonly status?: number;
+    /** Ingestion endpoint the event was sent to. */
+    readonly url: string;
+}
+export type OpenPanelDeliveryFailureHandler = (failure: OpenPanelDeliveryFailure) => void;
+/**
+ * Request attributes OpenPanel reads from headers rather than from the event
+ * body: the caller's IP resolves geo, and the user agent resolves the device.
+ */
+export interface OpenPanelRequestContext {
+    readonly ip?: string;
+    readonly userAgent?: string;
+}
+/**
+ * Where the server provider parks {@link OpenPanelRequestContext} on the
+ * payload it hands the SDK.
+ *
+ * OpenPanel's own server integrations build a fresh client per request and
+ * call `api.addHeader()` on it. A trakoo provider is long-lived and shared by
+ * every concurrent request, so mutating those headers would attribute one
+ * caller's event to another caller's IP. Carrying the values on the payload
+ * keeps them bound to the single event they describe and survives the SDK's
+ * internal queue, which spreads the properties object.
+ *
+ * The key is a symbol, so no event property can impersonate it and turn
+ * tracked data into request headers. It also cannot be serialized:
+ * `JSON.stringify` drops symbol keys, so the carrier never reaches OpenPanel
+ * as a property even when this transport is not installed.
+ */
+export declare const REQUEST_CONTEXT: unique symbol;
+/**
+ * Replaces the transport of an OpenPanel client so rejected requests are
+ * reported. Returns `false` when the client does not expose the expected
+ * transport, in which case the SDK keeps delivering events unchanged.
+ */
+export declare function instrumentOpenPanelDelivery(client: unknown, report: OpenPanelDeliveryFailureHandler): boolean;
+/**
+ * Wraps a caller-supplied handler so it can never fail an analytics call, and
+ * logs the failure when no handler is configured. OpenPanel drops rejected
+ * requests silently, so a missing handler must not mean missing signal.
+ */
+export declare function createDeliveryFailureReporter(providerName: string, onDeliveryFailure: OpenPanelDeliveryFailureHandler | undefined): OpenPanelDeliveryFailureHandler;

package/dist/transport.js

@@ -0,0 +1,187 @@
+/**
+ * OpenPanel's SDKs treat HTTP 401 as a non-error: their shared `Api.post`
+ * returns `null` without throwing, retrying or logging, so a wrong, rotated or
+ * origin-rejected key stops analytics silently. Both the browser and the server
+ * SDK send through the `api` instance they expose publicly, so trakoo replaces
+ * that instance's `fetch` with an equivalent implementation that reports the
+ * response status before returning the value the SDK expects.
+ *
+ * The replacement mirrors the SDK transport: 200 and 202 are the only success
+ * statuses, 401 is never retried, every other failure backs off exponentially,
+ * and headers, body and request options are built the same way. Delivery still
+ * resolves rather than throwing, so reporting a failure can never turn a
+ * tracked event into an application error.
+ */
+/**
+ * Where the server provider parks {@link OpenPanelRequestContext} on the
+ * payload it hands the SDK.
+ *
+ * OpenPanel's own server integrations build a fresh client per request and
+ * call `api.addHeader()` on it. A trakoo provider is long-lived and shared by
+ * every concurrent request, so mutating those headers would attribute one
+ * caller's event to another caller's IP. Carrying the values on the payload
+ * keeps them bound to the single event they describe and survives the SDK's
+ * internal queue, which spreads the properties object.
+ *
+ * The key is a symbol, so no event property can impersonate it and turn
+ * tracked data into request headers. It also cannot be serialized:
+ * `JSON.stringify` drops symbol keys, so the carrier never reaches OpenPanel
+ * as a property even when this transport is not installed.
+ */
+export const REQUEST_CONTEXT = Symbol("trakoo.openpanel.requestContext");
+const CLIENT_IP_HEADER = "openpanel-client-ip";
+const USER_AGENT_HEADER = "user-agent";
+const DEFAULT_INITIAL_RETRY_DELAY_MS = 500;
+const DEFAULT_MAX_RETRIES = 3;
+const SUCCESS_STATUSES = new Set([200, 202]);
+const UNAUTHORIZED_STATUS = 401;
+/**
+ * Replaces the transport of an OpenPanel client so rejected requests are
+ * reported. Returns `false` when the client does not expose the expected
+ * transport, in which case the SDK keeps delivering events unchanged.
+ */
+export function instrumentOpenPanelDelivery(client, report) {
+    const api = openPanelApiOf(client);
+    if (!api)
+        return false;
+    api.fetch = (path, data, options) => deliver(api, path, data, options, report);
+    return true;
+}
+/**
+ * Wraps a caller-supplied handler so it can never fail an analytics call, and
+ * logs the failure when no handler is configured. OpenPanel drops rejected
+ * requests silently, so a missing handler must not mean missing signal.
+ */
+export function createDeliveryFailureReporter(providerName, onDeliveryFailure) {
+    return (failure) => {
+        if (!onDeliveryFailure) {
+            logDeliveryFailure(providerName, failure);
+            return;
+        }
+        try {
+            onDeliveryFailure(failure);
+        }
+        catch {
+            // Delivery reporting must not change the outcome of a tracked event.
+        }
+    };
+}
+function openPanelApiOf(client) {
+    // `Api` is not exported by the SDK, so its instance is matched structurally.
+    const api = client?.api;
+    if (!api || typeof api !== "object")
+        return undefined;
+    const candidate = api;
+    if (typeof candidate.fetch !== "function")
+        return undefined;
+    if (typeof candidate.baseUrl !== "string")
+        return undefined;
+    if (!candidate.headers || typeof candidate.headers !== "object") {
+        return undefined;
+    }
+    return candidate;
+}
+async function deliver(api, path, data, options, report) {
+    const url = `${api.baseUrl}${path}`;
+    const payloadType = payloadTypeOf(data);
+    const headers = requestHeadersOf(data);
+    const maxRetries = nonNegativeNumber(api.maxRetries, DEFAULT_MAX_RETRIES);
+    const retryDelay = nonNegativeNumber(api.initialRetryDelay, DEFAULT_INITIAL_RETRY_DELAY_MS);
+    for (let attempt = 0;; attempt += 1) {
+        const outcome = await attemptDelivery(api, url, data, options, headers);
+        if (outcome.ok)
+            return outcome.body;
+        // A rejected key is rejected for every retry, so it is reported at once.
+        if (outcome.reason !== "unauthorized" && attempt < maxRetries) {
+            await wait(retryDelay * 2 ** attempt);
+            continue;
+        }
+        report({
+            attempts: attempt + 1,
+            ...(payloadType && { payloadType }),
+            reason: outcome.reason,
+            ...(outcome.status !== undefined && { status: outcome.status }),
+            url,
+        });
+        return null;
+    }
+}
+async function attemptDelivery(api, url, data, options, requestHeaders) {
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { ...(await resolveHeaders(api.headers)), ...requestHeaders },
+            body: data ? JSON.stringify(data) : undefined,
+            keepalive: true,
+            ...options,
+        });
+        if (response.status === UNAUTHORIZED_STATUS) {
+            return { ok: false, reason: "unauthorized", status: UNAUTHORIZED_STATUS };
+        }
+        if (!SUCCESS_STATUSES.has(response.status)) {
+            return { ok: false, reason: "server_error", status: response.status };
+        }
+        const text = await response.text();
+        return { body: text ? JSON.parse(text) : null, ok: true };
+    }
+    catch {
+        return { ok: false, reason: "network_error" };
+    }
+}
+async function resolveHeaders(headers) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(headers)) {
+        const header = await value;
+        if (header !== null)
+            resolved[key] = header;
+    }
+    return resolved;
+}
+/**
+ * Turns any {@link OpenPanelRequestContext} carried by the payload into this
+ * one request's headers. The payload itself is left untouched — the carrier is
+ * symbol-keyed, so it is already invisible to `JSON.stringify`.
+ */
+function requestHeadersOf(data) {
+    const requestContext = propertiesOf(data)?.[REQUEST_CONTEXT];
+    if (!requestContext || typeof requestContext !== "object")
+        return {};
+    const { ip, userAgent } = requestContext;
+    return {
+        ...(typeof ip === "string" && ip && { [CLIENT_IP_HEADER]: ip }),
+        ...(typeof userAgent === "string" &&
+            userAgent && { [USER_AGENT_HEADER]: userAgent }),
+    };
+}
+function propertiesOf(data) {
+    if (!data || typeof data !== "object")
+        return undefined;
+    const payload = data.payload;
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const properties = payload.properties;
+    if (!properties || typeof properties !== "object")
+        return undefined;
+    return properties;
+}
+function payloadTypeOf(data) {
+    if (!data || typeof data !== "object")
+        return undefined;
+    const type = data.type;
+    return typeof type === "string" ? type : undefined;
+}
+function nonNegativeNumber(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : fallback;
+}
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function logDeliveryFailure(providerName, failure) {
+    const status = failure.status === undefined ? "" : ` (HTTP ${failure.status})`;
+    const hint = failure.reason === "unauthorized"
+        ? " - check the OpenPanel credentials and the project's allowed origins"
+        : "";
+    console.error(`[${providerName}] Delivery failed: ${failure.reason}${status} after ${failure.attempts} attempt(s) to ${failure.url}${hint}`);
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@trakoo/openpanel",
+  "version": "0.0.0",
+  "description": "OpenPanel provider for trakoo",
+  "type": "module",
+  "exports": {
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "analytics",
+    "trakoo",
+    "openpanel",
+    "typescript"
+  ],
+  "author": "Chris Jayden <https://github.com/multiplehats>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/multiplehats/trakoo.git",
+    "directory": "packages/openpanel"
+  },
+  "bugs": {
+    "url": "https://github.com/multiplehats/trakoo/issues"
+  },
+  "homepage": "https://trakoo.co/docs/providers/openpanel",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@openpanel/sdk": "^1.3.1",
+    "@openpanel/web": "^1.4.1",
+    "trakoo": "^1.2.1"
+  },
+  "peerDependenciesMeta": {
+    "@openpanel/sdk": {
+      "optional": true
+    },
+    "@openpanel/web": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@openpanel/sdk": "^1.3.1",
+    "@openpanel/web": "^1.4.1",
+    "trakoo": "1.2.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}