flowgrid-sdk 1.7.3 → 1.7.8

package/dist/lib/server/index.d.ts

@@ -0,0 +1,531 @@
+/**
+ * @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;
+ * }
+ * ```
+ */
+import type { CartItem, MoneyValue, Order, ShippingInfo } from "../types";
+export interface FlowGridServerConfig {
+    /** Public web/site identifier (e.g. `"wx_abc123"`). Required. */
+    webId: string;
+    /**
+     * Private API key, sent as a Bearer token. Required on the server — there
+     * is no `data-site` body-auth fallback for server ingestion.
+     */
+    apiKey: string;
+    /** API base URL. Defaults to `"https://core.flow-grid.xyz"`. */
+    endpoint?: string;
+    /**
+     * Deployment environment stamped on every event as `_environment`
+     * (defaults to `process.env.NODE_ENV`). Lets the dashboard separate
+     * production traffic from staging/preview.
+     */
+    environment?: string;
+    /** Request timeout in ms (default 10 000). */
+    timeoutMs?: number;
+    /** Max retries for network failures / 5xx responses (default 2). */
+    maxRetries?: number;
+}
+/** Per-call options shared by every server tracking method. */
+export interface ServerCallOptions {
+    /**
+     * The browser visitor id for the request (read it from the `visitor_id`
+     * cookie — see {@link visitorIdFromCookies}; in payment webhooks, from
+     * checkout metadata via {@link attributionFromMetadata}). Passing it
+     * links server events to the visitor's web session. When omitted, a
+     * stable synthetic visitor id is derived from the `userId` so events
+     * still attribute to the user; fully anonymous events share one
+     * per-process visitor.
+     */
+    visitorId?: string;
+    /**
+     * The browser session id — same sources as `visitorId`
+     * ({@link sessionIdFromCookies} / {@link attributionFromMetadata}).
+     * Carried on ecommerce/revenue events so a purchase joins the exact
+     * session (and therefore the campaign/landing page) that produced it.
+     */
+    sessionId?: string;
+}
+/** Every server tracking method resolves to this — it never rejects. */
+export interface ServerTrackResult {
+    ok: boolean;
+    /** HTTP status when a response was received. */
+    status?: number;
+    /** Why the event was not delivered (validation failure, network, …). */
+    reason?: string;
+}
+export interface ServerAuthInput {
+    event: "login" | "signup";
+    userId: string;
+    email?: string;
+    name?: string;
+    method?: string;
+    source?: string;
+    traits?: Record<string, unknown>;
+}
+export interface ServerFeatureUsageInput {
+    featureId: string;
+    featureName: string;
+    /** Lifecycle action — defaults to `"used"` (Adopted). */
+    action?: "viewed" | "used" | "completed" | "abandoned" | string;
+    userId?: string;
+    category?: string;
+    duration?: number;
+    success?: boolean;
+    properties?: Record<string, unknown>;
+}
+/** Input for {@link FlowGridServer.trackPurchase}. */
+export interface ServerPurchaseInput {
+    /** Full order — same {@link Order} shape the browser SDK sends. */
+    order: Order;
+    /** The purchasing user — required by the ingestion contract. */
+    userId: string;
+    /**
+     * Campaign attribution for the purchase. Server webhooks have no UTM
+     * context of their own, so pass what you stored at checkout if you
+     * want revenue attributed to a campaign.
+     */
+    attribution?: {
+        source?: string;
+        medium?: string;
+        campaign?: string;
+        affiliate?: string;
+    };
+    properties?: Record<string, unknown>;
+}
+/** Input for {@link FlowGridServer.trackRefund}. */
+export interface ServerRefundInput {
+    /** Original order id. */
+    orderId: string;
+    /** Refund id (e.g. the Stripe refund id). */
+    refundId: string;
+    /** Refunded amount (same unit you report order totals in). */
+    amount: number;
+    /** ISO 4217 currency code. */
+    currency: string;
+    userId?: string;
+    /** Items being refunded (partial refunds). */
+    items?: CartItem[];
+    reason?: string;
+    isFullRefund?: boolean;
+    initiatedBy?: "customer" | "merchant" | "system" | string;
+    properties?: Record<string, unknown>;
+}
+/**
+ * Input for {@link FlowGridServer.trackSubscription} — discriminated on
+ * `event`, mirroring the browser `subscriptions.*` methods one-to-one.
+ */
+export type ServerSubscriptionInput = {
+    event: "start";
+    subscriptionId: string;
+    userId: string;
+    plan: string;
+    /** New MRR (amount in the smallest currency unit, e.g. cents). */
+    mrr: MoneyValue;
+    billingCycle?: "monthly" | "yearly" | string;
+    trialDays?: number;
+    coupon?: string;
+    properties?: Record<string, unknown>;
+} | {
+    event: "change";
+    subscriptionId: string;
+    userId: string;
+    previousPlan: string;
+    newPlan: string;
+    previousMrr?: MoneyValue;
+    newMrr?: MoneyValue;
+    changeType?: "upgrade" | "downgrade" | string;
+    properties?: Record<string, unknown>;
+} | {
+    event: "cancel";
+    subscriptionId: string;
+    userId: string;
+    /** Cancellation reason — required by the ingestion contract. */
+    reason: string;
+    plan?: string;
+    /** Churned MRR. */
+    lostMrr?: MoneyValue;
+    feedback?: string;
+    immediate?: boolean;
+    properties?: Record<string, unknown>;
+} | {
+    event: "renew";
+    subscriptionId: string;
+    userId: string;
+    mrr: MoneyValue;
+    properties?: Record<string, unknown>;
+} | {
+    event: "trial_converted";
+    subscriptionId: string;
+    userId: string;
+    plan: string;
+    mrr: MoneyValue;
+    properties?: Record<string, unknown>;
+} | {
+    event: "trial_expired";
+    subscriptionId: string;
+    userId: string;
+    properties?: Record<string, unknown>;
+};
+export interface ServerErrorOptions extends ServerCallOptions {
+    userId?: string;
+    /** Free-form origin label, e.g. `"stripe-webhook"` or a job name. */
+    context?: string;
+    /** API route the error occurred in, e.g. `"/api/teams/edit/[teamId]"`. */
+    route?: string;
+    /** HTTP method of the failing request. */
+    method?: string;
+    /** HTTP status the route responded with (or would have). */
+    statusCode?: number;
+    /** Marks process-fatal errors (uncaught exceptions). */
+    fatal?: boolean;
+    properties?: Record<string, unknown>;
+}
+/**
+ * A feature bound to its id/name via {@link FlowGridServer.defineFeature}.
+ * Server twin of the browser `FeatureHandle` — verbs accept per-call
+ * `userId`/`visitorId` since one server process serves many users.
+ */
+export interface ServerFeatureHandle {
+    readonly featureId: string;
+    readonly featureName: string;
+    viewed(properties?: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    used(properties?: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    completed(properties?: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    abandoned(properties?: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    track(action: string, properties?: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+}
+/**
+ * Minimal cookie reader — compatible with Next.js `cookies()` and Nuxt
+ * `useCookie()`. Mirrors `ServerCookieReader` in `utils/identity` (kept
+ * local so this module stays free of browser-leaning imports).
+ */
+export interface ServerCookieSource {
+    get(name: string): {
+        value: string;
+    } | string | undefined | null;
+}
+/**
+ * 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 });
+ * ```
+ */
+export declare function visitorIdFromCookies(source: ServerCookieSource): string | undefined;
+/**
+ * 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.
+ */
+export declare function sessionIdFromCookies(source: ServerCookieSource): string | undefined;
+/**
+ * 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()) },
+ * });
+ * ```
+ */
+export declare function checkoutAttributionFromCookies(source: ServerCookieSource): {
+    flowgrid_visitor_id?: string;
+    flowgrid_session_id?: string;
+};
+/**
+ * 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);
+ * ```
+ */
+export declare function attributionFromMetadata(metadata: unknown): {
+    visitorId?: string;
+    sessionId?: string;
+};
+export declare class FlowGridServer {
+    /** Singleton created by {@link FlowGridServer.init}. */
+    private static _instance;
+    private readonly webId;
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly environment?;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    /** Per-process visitor for events with no user and no explicit visitorId. */
+    private anonymousVisitorId;
+    /** One quiet debug note per failure signature — mirrors the browser transport. */
+    private static failureNoted;
+    /**
+     * One-line init. Idempotent — calling twice returns the same instance
+     * (matching the browser `FlowGrid.init` contract).
+     */
+    static init(config: FlowGridServerConfig): FlowGridServer;
+    /** Returns the singleton created by {@link FlowGridServer.init}, if any. */
+    static instance(): FlowGridServer | null;
+    /** Reset the singleton — primarily for tests / hot-reload. */
+    static reset(): void;
+    /** Explicit constructor for multi-tenant setups; most apps use {@link init}. */
+    constructor(config: FlowGridServerConfig);
+    /**
+     * Identify a user server-side (e.g. inside an auth callback). Writes the
+     * visitor identity store exactly like the browser `fg.identifyUser`.
+     */
+    identifyUser(userId: string, traits?: Record<string, unknown>, opts?: ServerCallOptions & {
+        anonymousId?: string;
+    }): Promise<ServerTrackResult>;
+    /** Update traits on an already-identified user. */
+    updateTraits(userId: string, traits: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /** Alias a previous user id to a new one (e.g. after an ID migration). */
+    aliasUser(previousId: string, userId: string, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /** Reset a user's identity on logout (server twin of `fg.logout`). */
+    logout(userId: string, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /**
+     * Record a completed signup (populates the Acquisition Funnel's
+     * "Signed up" stage, same as the browser `fg.signup`).
+     */
+    signup(userId: string, method: string, source?: string, properties?: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /** Record a returning-user login (retention signal, not a funnel conversion). */
+    login(userId: string, method?: string, properties?: Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /**
+     * Emit an "active user" signal for DAU/WAU/MAU by identity — server twin
+     * of `fg.pingActiveUser` (rides the same `custom_event` pipe).
+     */
+    pingActiveUser(userId: string, traits?: {
+        email?: string;
+        name?: string;
+    } & Record<string, unknown>, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /**
+     * 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()) },
+     * );
+     * ```
+     */
+    trackAuth(input: ServerAuthInput, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /**
+     * 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: ServerFeatureUsageInput, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /**
+     * 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: string, featureName: string, defOpts?: {
+        category?: string;
+    }): ServerFeatureHandle;
+    /**
+     * 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: ServerPurchaseInput, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /** Track an order status change from fulfilment systems / order webhooks. */
+    trackOrderStatus(orderId: string, newStatus: NonNullable<Order["status"]> | string, previousStatus?: string, opts?: ServerCallOptions & {
+        userId?: string;
+    }): Promise<ServerTrackResult>;
+    /** Track an order shipped event (carrier/fulfilment webhook). */
+    trackOrderShipped(orderId: string, shipping: ShippingInfo, opts?: ServerCallOptions & {
+        userId?: string;
+    }): Promise<ServerTrackResult>;
+    /** Track an order delivered event. */
+    trackOrderDelivered(orderId: string, deliveredAt?: string, opts?: ServerCallOptions & {
+        userId?: string;
+    }): Promise<ServerTrackResult>;
+    /**
+     * Track a processed refund — fire from your payment provider's refund
+     * webhook (e.g. Stripe `charge.refunded`) so net revenue stays accurate.
+     */
+    trackRefund(input: ServerRefundInput, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /**
+     * 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: ServerSubscriptionInput, opts?: ServerCallOptions): Promise<ServerTrackResult>;
+    /**
+     * 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: unknown, opts?: ServerErrorOptions): Promise<ServerTrackResult>;
+    /**
+     * 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<A extends unknown[], R>(fn: (...args: A) => Promise<R> | R, opts?: Omit<ServerErrorOptions, "fatal">): (...args: A) => Promise<R>;
+    /**
+     * 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?: Omit<ServerErrorOptions, "fatal">): () => void;
+    /**
+     * 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).
+     */
+    private resolveVisitorId;
+    /** Context stamped on every server event — parallel to the browser device context. */
+    private serverContext;
+    /**
+     * POST one event to the gateway (`?call=<type>`), with timeout, jittered
+     * retry on 5xx/network failure, and the never-throw guarantee.
+     */
+    private send;
+    /**
+     * 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.
+     */
+    private noteFailure;
+}
+export default FlowGridServer;