flowgrid-sdk 1.7.7 → 1.7.10

package/dist/lib/server/index.js

@@ -0,0 +1,812 @@
+"use strict";
+/**
+ * @fileoverview FlowGrid Server SDK — Node/edge-safe tracking client.
+ * @module server
+ *
+ * @description
+ * Server-side counterpart to the browser `FlowGrid` facade, deliberately
+ * scoped to the operations that make sense off-browser:
+ *
+ * - **Identity** — identify/alias/reset users and auth-level events
+ *   (signup/login/active-user) from server auth flows.
+ * - **Feature usage** — `feature_usage` events from API routes and jobs.
+ * - **Ecommerce / revenue** — purchases, refunds, order lifecycle and
+ *   subscription MRR events from payment webhooks, where money is actually
+ *   confirmed (immune to ad blockers and closed checkout tabs).
+ * - **Error tracking** — API and server-side exceptions as `error_event`s.
+ *
+ * It speaks the exact same wire contract as the browser SDK (per-op
+ * `?call=<type>` routing, suffixed event names like `identify_user`,
+ * camelCase properties), so flowgrid-core ingests both identically.
+ *
+ * Never touches `window`/`document`/`localStorage` and imports no Node
+ * built-ins — only global `fetch` (Node ≥ 18) — so it is safe in Next.js
+ * API routes and middleware, Express services, workers, and edge runtimes.
+ * Like the browser transport, it **never throws** for delivery problems:
+ * failures resolve `{ ok: false }` and are debug-noted once per signature.
+ *
+ * @example
+ * ```ts
+ * import { FlowGridServer } from "flowgrid-sdk/server";
+ *
+ * const fg = FlowGridServer.init({
+ *   webId: process.env.NEXT_PUBLIC_WEB_ID!,
+ *   apiKey: process.env.FLOWGRID_API_KEY!,
+ * });
+ *
+ * // Identity (auth-level, server-side)
+ * await fg.trackAuth({ event: "login", userId: user.id, email: user.email });
+ *
+ * // Feature usage
+ * await fg.trackFeature({ featureId: "team_update", featureName: "Team update", userId: user.id });
+ *
+ * // Revenue — from a payment webhook (e.g. Stripe checkout.session.completed)
+ * await fg.trackPurchase({ order, userId: session.client_reference_id });
+ *
+ * // API / server error tracking
+ * try { … } catch (err) {
+ *   await fg.trackError(err, { route: "/api/teams/edit", method: "PATCH", statusCode: 500 });
+ *   throw err;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowGridServer = void 0;
+exports.visitorIdFromCookies = visitorIdFromCookies;
+exports.sessionIdFromCookies = sessionIdFromCookies;
+exports.checkoutAttributionFromCookies = checkoutAttributionFromCookies;
+exports.attributionFromMetadata = attributionFromMetadata;
+/** Maps {@link ServerSubscriptionInput}'s `event` to the ingest subtype. */
+const SUBSCRIPTION_SUBTYPES = {
+    start: "subscription_start",
+    change: "subscription_change",
+    cancel: "subscription_cancel",
+    renew: "subscription_renew",
+    trial_converted: "trial_converted",
+    trial_expired: "trial_expired",
+};
+/**
+ * Read the FlowGrid visitor id from a request's cookies so server events
+ * link to the visitor's web session. Checks the tracking-script cookie
+ * (`visitor_id`) first, then the SDK's own `fg_visitor_id`.
+ *
+ * @example
+ * ```ts
+ * import { cookies } from "next/headers";
+ * const visitorId = visitorIdFromCookies(await cookies());
+ * await fg.identifyUser(user.id, { email: user.email }, { visitorId });
+ * ```
+ */
+function visitorIdFromCookies(source) {
+    return readFirstCookie(source, ["visitor_id", "fg_visitor_id"]);
+}
+/**
+ * Read the FlowGrid session id from a request's cookies. Both trackers
+ * mirror it to a cookie (`session_id` for the no-code script,
+ * `fg_session_id` for the npm SDK) precisely so checkout-creation routes
+ * can read it for revenue attribution.
+ */
+function sessionIdFromCookies(source) {
+    return readFirstCookie(source, ["session_id", "fg_session_id"]);
+}
+/**
+ * The **checkout leg** of the revenue-attribution cycle. Returns
+ * `{ flowgrid_visitor_id, flowgrid_session_id }` read from the request
+ * cookies, ready to drop into Stripe's `metadata` or Lemon Squeezy's
+ * `checkoutData.custom` when you create the checkout. Your payment
+ * webhook reads them back with {@link attributionFromMetadata} — that
+ * round-trip is what ties the payment to the visitor's session, campaign
+ * and journey, since the webhook itself arrives with no cookies.
+ *
+ * @example
+ * ```ts
+ * // app/api/checkout/route.ts
+ * import { cookies } from "next/headers";
+ * import { checkoutAttributionFromCookies } from "flowgrid-sdk/server";
+ *
+ * const session = await stripe.checkout.sessions.create({
+ *   // …
+ *   metadata: { ...checkoutAttributionFromCookies(await cookies()) },
+ * });
+ * ```
+ */
+function checkoutAttributionFromCookies(source) {
+    const visitorId = visitorIdFromCookies(source);
+    const sessionId = sessionIdFromCookies(source);
+    return {
+        ...(visitorId ? { flowgrid_visitor_id: visitorId } : {}),
+        ...(sessionId ? { flowgrid_session_id: sessionId } : {}),
+    };
+}
+/**
+ * The **webhook leg** of the revenue-attribution cycle: extract the
+ * visitor/session ids your checkout route embedded via
+ * {@link checkoutAttributionFromCookies} (or the browser's
+ * `fg.checkoutAttribution()`). Accepts the metadata map itself, or a
+ * provider object containing it — Stripe objects (`.metadata`) and
+ * Lemon Squeezy webhook payloads (`.meta.custom_data`) are unwrapped
+ * automatically. Recognises `flowgrid_*`, `fg_*` and bare key spellings.
+ * Never throws; missing ids come back `undefined`.
+ *
+ * @example
+ * ```ts
+ * // Stripe: checkout.session.completed
+ * const { visitorId, sessionId } = attributionFromMetadata(event.data.object);
+ * await fg.trackPurchase({ order, userId }, { visitorId, sessionId });
+ *
+ * // Lemon Squeezy: order_created
+ * const { visitorId, sessionId } = attributionFromMetadata(payload);
+ * ```
+ */
+function attributionFromMetadata(metadata) {
+    const map = unwrapMetadata(metadata);
+    if (!map)
+        return {};
+    return {
+        visitorId: readFirstKey(map, ["flowgrid_visitor_id", "fg_visitor_id", "visitor_id"]),
+        sessionId: readFirstKey(map, ["flowgrid_session_id", "fg_session_id", "session_id"]),
+    };
+}
+function readFirstCookie(source, names) {
+    for (const name of names) {
+        try {
+            const raw = source.get(name);
+            if (!raw)
+                continue;
+            const value = typeof raw === "object" && "value" in raw ? raw.value : raw;
+            if (typeof value === "string" && value)
+                return value;
+        }
+        catch { /* reader threw — try the next cookie */ }
+    }
+    return undefined;
+}
+/** Dig the flat metadata map out of a provider object, if wrapped. */
+function unwrapMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object")
+        return undefined;
+    const obj = metadata;
+    // Lemon Squeezy webhook payload: { meta: { custom_data: {…} } }
+    if (obj.meta?.custom_data && typeof obj.meta.custom_data === "object") {
+        return obj.meta.custom_data;
+    }
+    // Stripe object carrying its metadata: { metadata: {…} }
+    if (obj.metadata && typeof obj.metadata === "object")
+        return obj.metadata;
+    return obj;
+}
+function readFirstKey(map, keys) {
+    for (const key of keys) {
+        const value = map[key];
+        if (typeof value === "string" && value)
+            return value;
+    }
+    return undefined;
+}
+// ============================================================================
+// SERVER CLIENT
+// ============================================================================
+const DEFAULT_ENDPOINT = "https://core.flow-grid.xyz";
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_RETRIES = 2;
+const MAX_PAYLOAD_SIZE = 10000; // 10KB — same cap as the browser transport
+class FlowGridServer {
+    /**
+     * One-line init. Idempotent — calling twice returns the same instance
+     * (matching the browser `FlowGrid.init` contract).
+     */
+    static init(config) {
+        if (FlowGridServer._instance)
+            return FlowGridServer._instance;
+        FlowGridServer._instance = new FlowGridServer(config);
+        return FlowGridServer._instance;
+    }
+    /** Returns the singleton created by {@link FlowGridServer.init}, if any. */
+    static instance() {
+        return FlowGridServer._instance;
+    }
+    /** Reset the singleton — primarily for tests / hot-reload. */
+    static reset() {
+        FlowGridServer._instance = null;
+    }
+    /** Explicit constructor for multi-tenant setups; most apps use {@link init}. */
+    constructor(config) {
+        /** Per-process visitor for events with no user and no explicit visitorId. */
+        this.anonymousVisitorId = null;
+        if (!config?.webId?.trim()) {
+            throw new Error("FlowGridServer.init: `webId` is required.");
+        }
+        if (!config?.apiKey?.trim()) {
+            throw new Error("FlowGridServer.init: `apiKey` is required for server-side tracking.");
+        }
+        this.webId = config.webId.trim();
+        this.apiKey = config.apiKey.trim();
+        this.endpoint = normalizeEndpoint(config.endpoint ?? DEFAULT_ENDPOINT);
+        this.environment = config.environment
+            ?? (typeof process !== "undefined" ? process.env?.NODE_ENV : undefined);
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    }
+    // ==========================================================================
+    // IDENTITY — auth-level events
+    // ==========================================================================
+    /**
+     * Identify a user server-side (e.g. inside an auth callback). Writes the
+     * visitor identity store exactly like the browser `fg.identifyUser`.
+     */
+    identifyUser(userId, traits, opts) {
+        return this.send("identify", "identify_user", {
+            type: "identify",
+            userId,
+            anonymousId: opts?.anonymousId,
+            traits: traits ?? {},
+        }, this.resolveVisitorId(opts, userId));
+    }
+    /** Update traits on an already-identified user. */
+    updateTraits(userId, traits, opts) {
+        return this.send("update_traits", "update_traits", {
+            type: "update_traits",
+            userId,
+            traits,
+        }, this.resolveVisitorId(opts, userId));
+    }
+    /** Alias a previous user id to a new one (e.g. after an ID migration). */
+    aliasUser(previousId, userId, opts) {
+        return this.send("alias", "alias_user", {
+            type: "alias",
+            previousId,
+            userId,
+        }, this.resolveVisitorId(opts, userId));
+    }
+    /** Reset a user's identity on logout (server twin of `fg.logout`). */
+    logout(userId, opts) {
+        return this.send("reset", "reset_identity", {
+            type: "reset",
+            userId,
+        }, this.resolveVisitorId(opts, userId));
+    }
+    /**
+     * Record a completed signup (populates the Acquisition Funnel's
+     * "Signed up" stage, same as the browser `fg.signup`).
+     */
+    signup(userId, method, source, properties, opts) {
+        return this.send("activation", "signup_completed", {
+            type: "activation",
+            subtype: "signup",
+            userId,
+            method,
+            source,
+            ...properties,
+        }, this.resolveVisitorId(opts, userId));
+    }
+    /** Record a returning-user login (retention signal, not a funnel conversion). */
+    login(userId, method, properties, opts) {
+        return this.send("activation", "login_completed", {
+            type: "activation",
+            subtype: "login",
+            userId,
+            method,
+            ...properties,
+        }, this.resolveVisitorId(opts, userId));
+    }
+    /**
+     * Emit an "active user" signal for DAU/WAU/MAU by identity — server twin
+     * of `fg.pingActiveUser`. Rides the activation pipe (subtype `active_user`)
+     * so the wire `event_name` is `active_user`, the shape the active-users
+     * pipes read (the old `custom_event` pipe stored the name out of reach).
+     */
+    pingActiveUser(userId, traits, opts) {
+        const now = new Date();
+        return this.send("activation", "active_user", {
+            type: "activation",
+            subtype: "active_user",
+            userId,
+            ...(traits?.email ? { email: traits.email } : {}),
+            ...(traits?.name ? { name: traits.name } : {}),
+            date: now.toISOString().slice(0, 10),
+        }, this.resolveVisitorId(opts, userId));
+    }
+    /**
+     * One-call server-side auth tracking: identify + signup/login event +
+     * active-user ping — exact parity with the browser `fg.trackAuth`, for
+     * auth flows that resolve on the server (OAuth callbacks, session
+     * endpoints, credential logins).
+     *
+     * @example
+     * ```ts
+     * // In an auth callback / route handler:
+     * await fg.trackAuth(
+     *   { event: "signup", userId: user.id, email: user.email, method: "google" },
+     *   { visitorId: visitorIdFromCookies(await cookies()) },
+     * );
+     * ```
+     */
+    async trackAuth(input, opts) {
+        const traits = {
+            ...(input.email ? { email: input.email } : {}),
+            ...(input.name ? { name: input.name } : {}),
+            ...(input.traits ?? {}),
+        };
+        const method = input.method ?? "email";
+        const [identified, event] = await Promise.all([
+            this.identifyUser(input.userId, traits, opts),
+            input.event === "signup"
+                ? this.signup(input.userId, method, input.source, traits, opts)
+                : this.login(input.userId, method, traits, opts),
+            this.pingActiveUser(input.userId, traits, opts),
+        ]);
+        return identified.ok && event.ok ? identified : (identified.ok ? event : identified);
+    }
+    // ==========================================================================
+    // FEATURE USAGE
+    // ==========================================================================
+    /**
+     * Track a feature-usage event from the server (API-triggered features,
+     * background jobs, webhooks). Same `feature_usage` contract as the
+     * browser `fg.track("feature_usage", …)`.
+     */
+    trackFeature(input, opts) {
+        const action = input.action ?? "used";
+        return this.send("feature_usage", "feature_usage", {
+            type: "feature_usage",
+            subtype: action,
+            featureId: input.featureId,
+            featureName: input.featureName,
+            userId: input.userId,
+            action,
+            duration: input.duration,
+            success: input.success,
+            category: input.category,
+            ...input.properties,
+        }, this.resolveVisitorId(opts, input.userId));
+    }
+    /**
+     * Bind a feature's id + name once and get semantic verbs back — server
+     * twin of the browser `fg.defineFeature`. Verbs accept per-call
+     * `{ userId, visitorId }` since a server process serves many users.
+     *
+     * @example
+     * ```ts
+     * const teamUpdate = fg.defineFeature("team_update", "Team update", { category: "teams" });
+     * await teamUpdate.used({ userId: user.id });
+     * ```
+     */
+    defineFeature(featureId, featureName, defOpts = {}) {
+        const emit = (action, properties, opts) => {
+            const { userId, ...rest } = properties ?? {};
+            return this.trackFeature({
+                featureId,
+                featureName,
+                action,
+                userId: typeof userId === "string" ? userId : undefined,
+                category: defOpts.category,
+                properties: rest,
+            }, opts);
+        };
+        return {
+            featureId,
+            featureName,
+            viewed: (properties, opts) => emit("viewed", properties, opts),
+            used: (properties, opts) => emit("used", properties, opts),
+            completed: (properties, opts) => emit("completed", properties, opts),
+            abandoned: (properties, opts) => emit("abandoned", properties, opts),
+            track: (action, properties, opts) => emit(action, properties, opts),
+        };
+    }
+    // ==========================================================================
+    // ECOMMERCE — revenue events from payment webhooks
+    // ==========================================================================
+    /**
+     * Track a confirmed purchase from the server. Fire this from your payment
+     * webhook (Stripe `checkout.session.completed`, PayPal capture, order
+     * service) — the place where money is actually confirmed — instead of the
+     * browser thank-you page, which loses orders to ad blockers, closed tabs
+     * and interrupted redirects. Same `ecommerce`/`purchase` wire contract as
+     * the browser `purchases.track()`, so revenue dashboards see one stream.
+     *
+     * @example
+     * ```ts
+     * // Stripe webhook route
+     * await fg.trackPurchase({
+     *   order: {
+     *     orderId: session.id,
+     *     items, subtotal, discountTotal: 0, shippingTotal: 0,
+     *     taxTotal, total: session.amount_total / 100, currency: "USD",
+     *     payment: { method: "credit_card", provider: "stripe" },
+     *   },
+     *   userId: session.client_reference_id,
+     * });
+     * ```
+     */
+    trackPurchase(input, opts) {
+        const order = input.order;
+        return this.send("ecommerce", "purchase", {
+            type: "ecommerce",
+            subtype: "purchase",
+            order: {
+                orderId: order.orderId,
+                items: order.items,
+                subtotal: order.subtotal,
+                discountTotal: order.discountTotal,
+                shippingTotal: order.shippingTotal,
+                taxTotal: order.taxTotal,
+                total: order.total,
+                currency: order.currency,
+                shipping: order.shipping,
+                payment: order.payment,
+                coupons: order.coupons,
+                affiliation: order.affiliation,
+            },
+            revenue: order.total,
+            itemCount: order.items.reduce((sum, item) => sum + item.quantity, 0),
+            userId: input.userId,
+            sessionId: opts?.sessionId,
+            attribution: input.attribution,
+            ...input.properties,
+        }, this.resolveVisitorId(opts, input.userId));
+    }
+    /** Track an order status change from fulfilment systems / order webhooks. */
+    trackOrderStatus(orderId, newStatus, previousStatus, opts) {
+        return this.send("ecommerce", "order_status_change", {
+            type: "ecommerce",
+            subtype: "order_status_change",
+            orderId,
+            newStatus,
+            previousStatus,
+            userId: opts?.userId,
+            sessionId: opts?.sessionId,
+        }, this.resolveVisitorId(opts, opts?.userId));
+    }
+    /** Track an order shipped event (carrier/fulfilment webhook). */
+    trackOrderShipped(orderId, shipping, opts) {
+        return this.send("ecommerce", "order_shipped", {
+            type: "ecommerce",
+            subtype: "order_shipped",
+            orderId,
+            shipping,
+            userId: opts?.userId,
+            sessionId: opts?.sessionId,
+        }, this.resolveVisitorId(opts, opts?.userId));
+    }
+    /** Track an order delivered event. */
+    trackOrderDelivered(orderId, deliveredAt, opts) {
+        return this.send("ecommerce", "order_delivered", {
+            type: "ecommerce",
+            subtype: "order_delivered",
+            orderId,
+            deliveredAt: deliveredAt ?? new Date().toISOString(),
+            userId: opts?.userId,
+            sessionId: opts?.sessionId,
+        }, this.resolveVisitorId(opts, opts?.userId));
+    }
+    /**
+     * Track a processed refund — fire from your payment provider's refund
+     * webhook (e.g. Stripe `charge.refunded`) so net revenue stays accurate.
+     */
+    trackRefund(input, opts) {
+        return this.send("ecommerce", "refund", {
+            type: "ecommerce",
+            subtype: "refund",
+            orderId: input.orderId,
+            refundId: input.refundId,
+            items: input.items,
+            amount: input.amount,
+            currency: input.currency,
+            reason: input.reason,
+            isFullRefund: input.isFullRefund,
+            userId: input.userId,
+            sessionId: opts?.sessionId,
+            initiatedBy: input.initiatedBy,
+            ...input.properties,
+        }, this.resolveVisitorId(opts, input.userId));
+    }
+    /**
+     * Track subscription lifecycle / MRR events — start, plan change, cancel,
+     * renew, trial conversion and trial expiry — from your billing webhooks.
+     * These power the MRR/churn dashboards; billing state lives on your
+     * server, so this is the authoritative place to emit them.
+     *
+     * @example
+     * ```ts
+     * // customer.subscription.created
+     * await fg.trackSubscription({
+     *   event: "start",
+     *   subscriptionId: sub.id,
+     *   userId: customer.metadata.userId,
+     *   plan: "professional",
+     *   mrr: { amount: 9900, currency: "USD" },
+     *   billingCycle: "monthly",
+     * });
+     *
+     * // customer.subscription.deleted
+     * await fg.trackSubscription({
+     *   event: "cancel",
+     *   subscriptionId: sub.id,
+     *   userId,
+     *   reason: sub.cancellation_details?.reason ?? "unknown",
+     *   lostMrr: { amount: 9900, currency: "USD" },
+     * });
+     * ```
+     */
+    trackSubscription(input, opts) {
+        const subtype = SUBSCRIPTION_SUBTYPES[input.event];
+        const { event: _event, properties, ...fields } = input;
+        const payload = {
+            type: "ecommerce",
+            subtype,
+            sessionId: opts?.sessionId,
+            ...fields,
+            ...properties,
+        };
+        if (input.event === "start") {
+            payload.isTrialing = (input.trialDays ?? 0) > 0;
+        }
+        if (input.event === "change" && input.previousMrr && input.newMrr) {
+            payload.mrrChange = input.newMrr.amount - input.previousMrr.amount;
+        }
+        return this.send("ecommerce", subtype, payload, this.resolveVisitorId(opts, input.userId));
+    }
+    // ==========================================================================
+    // ERROR TRACKING — API routes + server exceptions
+    // ==========================================================================
+    /**
+     * Track a server-side error or exception as an `error_event`. Accepts a
+     * thrown value of any shape; pass `route`/`method`/`statusCode` for API
+     * errors so the dashboard can break failures down per endpoint.
+     *
+     * FlowGrid-internal notes (messages starting with `[FlowGrid]`) are
+     * filtered out, matching the browser SDK's own error filtering.
+     */
+    trackError(error, opts = {}) {
+        const normalized = normalizeError(error);
+        if (normalized.message.startsWith("[FlowGrid]") || normalized.message.startsWith("[Flowgrid]")) {
+            return Promise.resolve({ ok: false, reason: "flowgrid-internal" });
+        }
+        return this.send("error_event", "error_event", {
+            type: "error_event",
+            message: normalized.message,
+            stack: normalized.stack,
+            errorType: normalized.type,
+            fatal: opts.fatal ?? false,
+            context: opts.context ?? opts.route,
+            userId: opts.userId,
+            ...(opts.route ? { _api_route: opts.route } : {}),
+            ...(opts.method ? { _http_method: opts.method } : {}),
+            ...(opts.statusCode !== undefined ? { _status_code: opts.statusCode } : {}),
+            ...opts.properties,
+        }, this.resolveVisitorId(opts, opts.userId));
+    }
+    /**
+     * Wrap an async function (API route handler, job, webhook) so any thrown
+     * error is tracked before being rethrown — the failure still surfaces to
+     * the caller/framework exactly as before.
+     *
+     * @example
+     * ```ts
+     * export const PATCH = fg.withErrorTracking(
+     *   async (req: NextRequest) => { … },
+     *   { route: "/api/teams/edit/[teamId]", method: "PATCH" },
+     * );
+     * ```
+     */
+    withErrorTracking(fn, opts = {}) {
+        return async (...args) => {
+            try {
+                return await fn(...args);
+            }
+            catch (error) {
+                // Fire-and-forget: error delivery must never delay the rethrow.
+                void this.trackError(error, { ...opts, statusCode: opts.statusCode ?? 500 });
+                throw error;
+            }
+        };
+    }
+    /**
+     * Opt-in process-level capture: reports `uncaughtException` and
+     * `unhandledRejection` as fatal `error_event`s. Observes only — never
+     * swallows; Node's default crash behaviour is unchanged. Returns a
+     * detach function. No-op outside Node (edge runtimes have no `process.on`).
+     */
+    captureUncaught(opts = {}) {
+        if (typeof process === "undefined" || typeof process.on !== "function") {
+            return () => { };
+        }
+        const onException = (error) => {
+            void this.trackError(error, { ...opts, context: opts.context ?? "uncaughtException", fatal: true });
+        };
+        const onRejection = (reason) => {
+            void this.trackError(reason, { ...opts, context: opts.context ?? "unhandledRejection", fatal: true });
+        };
+        process.on("uncaughtException", onException);
+        process.on("unhandledRejection", onRejection);
+        return () => {
+            process.removeListener("uncaughtException", onException);
+            process.removeListener("unhandledRejection", onRejection);
+        };
+    }
+    // ==========================================================================
+    // TRANSPORT
+    // ==========================================================================
+    /**
+     * Visitor resolution, in preference order:
+     * 1. explicit per-call `visitorId` (the real browser visitor — best),
+     * 2. stable synthetic id derived from the userId (`fg_srv_<hash>`), so a
+     *    user's server events always land on one visitor,
+     * 3. one per-process anonymous visitor (events with no identity at all).
+     */
+    resolveVisitorId(opts, userId) {
+        if (opts?.visitorId)
+            return opts.visitorId;
+        if (userId)
+            return `fg_srv_${fnv1a64(userId)}`;
+        if (!this.anonymousVisitorId) {
+            this.anonymousVisitorId = `fg_srv_anon_${randomHex(16)}`;
+        }
+        return this.anonymousVisitorId;
+    }
+    /** Context stamped on every server event — parallel to the browser device context. */
+    serverContext() {
+        const proc = typeof process !== "undefined" ? process : undefined;
+        return {
+            _server: true,
+            _runtime: proc?.release?.name ?? "node",
+            ...(proc?.version ? { _runtime_version: proc.version } : {}),
+            ...(this.environment ? { _environment: this.environment } : {}),
+        };
+    }
+    /**
+     * POST one event to the gateway (`?call=<type>`), with timeout, jittered
+     * retry on 5xx/network failure, and the never-throw guarantee.
+     */
+    async send(callType, eventName, properties, visitorId) {
+        let body;
+        try {
+            // Drop undefined values so payloads stay clean (JSON.stringify would
+            // drop them anyway, but this keeps the size check honest).
+            const cleaned = {};
+            for (const [key, value] of Object.entries(properties)) {
+                if (value !== undefined)
+                    cleaned[key] = value;
+            }
+            body = JSON.stringify({
+                web_id: this.webId,
+                visitor_id: visitorId,
+                event_name: eventName,
+                properties: {
+                    ...this.serverContext(),
+                    ...cleaned,
+                    timestamp: new Date().toISOString(),
+                },
+            });
+        }
+        catch {
+            this.noteFailure(`${eventName}: properties not JSON-serializable`);
+            return { ok: false, reason: "not-serializable" };
+        }
+        if (byteLength(body) > MAX_PAYLOAD_SIZE) {
+            this.noteFailure(`${eventName}: payload too large (max 10KB)`);
+            return { ok: false, reason: "payload-too-large" };
+        }
+        const url = `${this.endpoint}/api/v1/sdk/functions?call=${encodeURIComponent(callType)}`;
+        for (let attempt = 0;; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Authorization": `Bearer ${this.apiKey}`,
+                    },
+                    body,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (res.status >= 500 && attempt < this.maxRetries) {
+                    await backoff(attempt + 1);
+                    continue;
+                }
+                if (!res.ok) {
+                    this.noteFailure(`${eventName}: ${res.status} ${res.statusText}`);
+                    return { ok: false, status: res.status, reason: `http-${res.status}` };
+                }
+                return { ok: true, status: res.status };
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                if (attempt < this.maxRetries) {
+                    await backoff(attempt + 1);
+                    continue;
+                }
+                const reason = error instanceof Error && error.name === "AbortError"
+                    ? "timed out"
+                    : error instanceof Error ? error.message : String(error);
+                this.noteFailure(`${eventName}: ${reason}`);
+                return { ok: false, reason };
+            }
+        }
+    }
+    /**
+     * One quiet, non-throwing note per failure signature (same policy as the
+     * browser transport): a failed tracking request is FlowGrid's problem,
+     * not the host app's — it must never reach the customer's error tracking.
+     */
+    noteFailure(detail) {
+        if (FlowGridServer.failureNoted.has(detail))
+            return;
+        FlowGridServer.failureNoted.add(detail);
+        if (typeof console !== "undefined") {
+            console.debug(`[FlowGrid] Server event not delivered (${detail}) — FlowGrid never throws; this note is debug-only.`);
+        }
+    }
+}
+exports.FlowGridServer = FlowGridServer;
+/** Singleton created by {@link FlowGridServer.init}. */
+FlowGridServer._instance = null;
+/** One quiet debug note per failure signature — mirrors the browser transport. */
+FlowGridServer.failureNoted = new Set();
+// ============================================================================
+// INTERNALS
+// ============================================================================
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return { message: error.message || String(error), stack: error.stack, type: error.name };
+    }
+    if (typeof error === "string")
+        return { message: error, type: "Error" };
+    if (error && typeof error === "object") {
+        const obj = error;
+        return {
+            message: typeof obj.message === "string" && obj.message ? obj.message : safeStringify(error),
+            stack: typeof obj.stack === "string" ? obj.stack : undefined,
+            type: typeof obj.name === "string" ? obj.name : "Error",
+        };
+    }
+    return { message: String(error), type: "Error" };
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function normalizeEndpoint(endpoint) {
+    let clean = endpoint.trim();
+    if (!clean.startsWith("http://") && !clean.startsWith("https://")) {
+        clean = `https://${clean}`;
+    }
+    return clean.replace(/\/+$/, "");
+}
+function byteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+/** Jittered exponential backoff (~1s, ~2s windows) — matches the browser transport. */
+function backoff(attempt) {
+    const ceiling = Math.min(Math.pow(2, attempt - 1) * 1000, 30000);
+    return new Promise((resolve) => setTimeout(resolve, Math.random() * ceiling));
+}
+/** FNV-1a 64-bit — dependency-free stable hash for synthetic visitor ids. */
+function fnv1a64(input) {
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= BigInt(input.charCodeAt(i));
+        hash = (hash * prime) & 0xffffffffffffffffn;
+    }
+    return hash.toString(16).padStart(16, "0");
+}
+function randomHex(length) {
+    const bytes = new Uint8Array(length);
+    if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+        crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+exports.default = FlowGridServer;
+//# sourceMappingURL=index.js.map