@trakoo/bento 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/bento
+
+Bento server provider for [trakoo](https://www.npmjs.com/package/trakoo), the typed, provider-agnostic analytics library.
+
+The browser provider, `BentoClientProvider`, needs no SDK and ships with trakoo in `trakoo/providers/client`. Install this package only for server-side tracking.
+
+## Installation
+
+```bash
+pnpm add trakoo @trakoo/bento @bentonow/bento-node-sdk
+```
+
+## Usage
+
+`appEvents` is your event registry, created with `defineEvents()` from `trakoo`.
+
+```typescript title="lib/server-analytics.ts"
+import { createServerAnalytics } from 'trakoo/server';
+import { BentoServerProvider } from '@trakoo/bento/server';
+import { appEvents } from './events';
+
+export const serverAnalytics = createServerAnalytics({
+  events: appEvents,
+  providers: [
+    {
+      provider: new BentoServerProvider({
+        siteUuid: process.env.BENTO_SITE_UUID!,
+        authentication: {
+          publishableKey: process.env.BENTO_PUBLISHABLE_KEY!,
+          secretKey: process.env.BENTO_SECRET_KEY!
+        }
+      }),
+      exclude: ['pageView']
+    }
+  ]
+});
+```
+
+Bento requires an email for every event. Pass it with each server call, and route anonymous page views to another provider:
+
+```typescript
+await serverAnalytics.track('subscription_renewed', { plan: 'pro' }, {
+  user: { email: 'user@example.com' }
+});
+```
+
+## What reaches Bento
+
+- `identify()` sends `$update_fields`, so traits become subscriber fields. It does not send `$subscribe`. To subscribe someone, call the Bento SDK's `V1.addSubscriber()` directly.
+- `track()` sends `$<event name>`. For example, `subscription_renewed` arrives as `$subscription_renewed`. The event timestamp becomes the Bento event `date`.
+- `pageView()` sends `$view`.
+- Failed requests, and events Bento does not queue, are logged without the event payload and are not thrown. Set `logErrors: true` to have the Bento SDK log the HTTP response of failed requests.
+
+## Documentation
+
+https://trakoo.co/docs/providers/bento

package/dist/server.d.ts

@@ -0,0 +1,58 @@
+import { BaseAnalyticsProvider, type BaseEvent, type EventContext } from "trakoo";
+export interface BentoAnalyticsOptions {
+    /**
+     * Your Bento Site UUID from Team Settings
+     */
+    siteUuid: string;
+    /**
+     * Authentication credentials
+     */
+    authentication: {
+        /**
+         * Your Bento Publishable Key from Team Settings
+         */
+        publishableKey: string;
+        /**
+         * Your Bento Secret Key from Team Settings
+         */
+        secretKey: string;
+    };
+    /**
+     * Optional client configuration
+     */
+    clientOptions?: {
+        /**
+         * Base URL for the Bento API (optional)
+         */
+        baseUrl?: string;
+    };
+    /**
+     * Whether to log errors (optional)
+     */
+    logErrors?: boolean;
+}
+export interface BentoServerConfig extends BentoAnalyticsOptions {
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Enable/disable the provider
+     */
+    enabled?: boolean;
+}
+export declare class BentoServerProvider extends BaseAnalyticsProvider {
+    name: string;
+    private client?;
+    private initialized;
+    private config;
+    constructor(config: BentoServerConfig);
+    initialize(): Promise<void>;
+    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>;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+    /** Logs a failed call without the event, its user, or the SDK's message. */
+    private logFailure;
+}

package/dist/server.js

@@ -0,0 +1,194 @@
+import { BaseAnalyticsProvider, } from "trakoo";
+export class BentoServerProvider extends BaseAnalyticsProvider {
+    name = "Bento-Server";
+    client;
+    initialized = false;
+    config;
+    constructor(config) {
+        super({ debug: config.debug, enabled: config.enabled });
+        this.config = config;
+    }
+    async initialize() {
+        if (!this.isEnabled())
+            return;
+        if (this.initialized)
+            return;
+        // Validate config has required fields
+        if (!this.config.siteUuid || typeof this.config.siteUuid !== "string") {
+            throw new Error("Bento requires a siteUuid");
+        }
+        if (!this.config.authentication?.publishableKey ||
+            typeof this.config.authentication.publishableKey !== "string") {
+            throw new Error("Bento requires authentication.publishableKey");
+        }
+        if (!this.config.authentication?.secretKey ||
+            typeof this.config.authentication.secretKey !== "string") {
+            throw new Error("Bento requires authentication.secretKey");
+        }
+        try {
+            // Dynamically import the Bento SDK
+            // This will be resolved at runtime when the package is installed
+            const { Analytics } = await import("@bentonow/bento-node-sdk");
+            const { debug, enabled, ...bentoConfig } = this.config;
+            this.client = new Analytics(bentoConfig);
+            this.initialized = true;
+            this.log("Initialized successfully");
+        }
+        catch (error) {
+            this.logFailure("initialize", this.getErrorClass(error));
+            throw error;
+        }
+    }
+    async identify(userId, traits) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        // Extract email from userId or traits
+        const email = traits?.email || userId;
+        // Validate that we have a proper email format
+        if (!email || !email.includes("@")) {
+            this.log("Skipping identify - invalid or missing email");
+            return;
+        }
+        // Update the subscriber's fields. Bento creates the subscriber when needed.
+        // V1.addSubscriber is not used: it sends $subscribe, which subscribes the
+        // person to marketing email and re-runs subscribe automations on every call.
+        const { email: _email, ...fields } = traits ?? {};
+        try {
+            const queued = await this.client.V1.updateFields({ email, fields });
+            if (!queued) {
+                this.logFailure("identify user", "not queued by Bento");
+                return;
+            }
+            this.log("Identified user");
+        }
+        catch (error) {
+            this.logFailure("identify user", this.getErrorClass(error));
+        }
+    }
+    async track(event, context) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        // Server providers use only identity supplied on the current call.
+        const email = context?.user?.email ||
+            context?.user?.userId ||
+            event.userId;
+        // Bento SDK does not currently support anonymous events
+        // See: https://github.com/bentonow/bento-node-sdk
+        if (!email || !email.includes("@")) {
+            console.warn("[Bento-Server] Skipping event - Bento requires an email address. " +
+                "Anonymous events are not currently supported by the Bento Node SDK. " +
+                "For now, use the Bento client provider for anonymous tracking. " +
+                "If you're using a proxy, use the hybrid pattern as described in the docs. " +
+                "For identified events, provide a valid email in the current call's user context or event userId; calling identify() earlier does not set event identity.");
+            return;
+        }
+        const details = {
+            ...event.properties,
+            category: event.category,
+            timestamp: event.timestamp || Date.now(),
+            ...(event.sessionId && { sessionId: event.sessionId }),
+            ...(context?.page && {
+                page: {
+                    url: context.page.url,
+                    host: context.page.host,
+                    path: context.page.path,
+                    title: context.page.title,
+                    protocol: context.page.protocol,
+                    referrer: context.page.referrer,
+                    ...(context.page.search && { search: context.page.search }),
+                },
+            }),
+            ...(context?.device && { device: context.device }),
+            ...(context?.utm && { utm: context.utm }),
+            site: this.config.siteUuid,
+            ...(context?.user?.userId && { visitor: context.user.userId }),
+        };
+        // Add user traits as fields if available
+        const fields = context?.user?.traits || {};
+        try {
+            const queued = await this.client.V1.track({
+                email,
+                type: `$${event.action}`,
+                details,
+                fields,
+                ...(event.timestamp !== undefined && {
+                    date: new Date(event.timestamp),
+                }),
+            });
+            if (!queued) {
+                this.logFailure("track event", "not queued by Bento");
+                return;
+            }
+            this.log("Tracked event");
+        }
+        catch (error) {
+            this.logFailure("track event", this.getErrorClass(error));
+        }
+    }
+    async pageView(properties, context) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        // Page views may only use identity supplied in the current context.
+        const email = context?.user?.email || context?.user?.userId;
+        // Bento SDK does not currently support anonymous events
+        // See: https://github.com/bentonow/bento-node-sdk
+        if (!email || !email.includes("@")) {
+            console.warn("[Bento-Server] Skipping pageView - Bento requires an email address. " +
+                "Anonymous events are not currently supported by the Bento Node SDK. " +
+                "For now, use the Bento client provider for anonymous tracking. " +
+                "If you're using a proxy, use the hybrid pattern as described in the docs. " +
+                "For identified page views, provide a valid email in the current call's user context; calling identify() earlier does not set page identity.");
+            return;
+        }
+        const details = {
+            ...properties,
+            date: new Date().toISOString(),
+            ...(context?.page && {
+                page: {
+                    url: context.page.url,
+                    host: context.page.host,
+                    path: context.page.path,
+                    title: context.page.title,
+                    protocol: context.page.protocol,
+                    referrer: context.page.referrer,
+                    ...(context.page.search && { search: context.page.search }),
+                },
+            }),
+            site: this.config.siteUuid,
+            ...(context?.user?.userId && { visitor: context.user.userId }),
+        };
+        const fields = context?.user?.traits || {};
+        try {
+            const queued = await this.client.V1.track({
+                email,
+                type: "$view",
+                details,
+                fields,
+            });
+            if (!queued) {
+                this.logFailure("track page view", "not queued by Bento");
+                return;
+            }
+            this.log("Tracked page view");
+        }
+        catch (error) {
+            this.logFailure("track page view", this.getErrorClass(error));
+        }
+    }
+    async reset() {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        this.log("Reset called; server provider has no retained identity");
+    }
+    async shutdown() {
+        // Bento Node SDK doesn't require explicit shutdown
+        // Just clear the reference
+        this.client = undefined;
+        this.initialized = false;
+        this.log("Shutdown complete");
+    }
+    /** Logs a failed call without the event, its user, or the SDK's message. */
+    logFailure(action, reason) {
+        console.error(`[${this.name}] Failed to ${action} (${reason})`);
+    }
+}

package/package.json

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