@caravela-studio/glancy-next 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# @caravela-studio/glancy-next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Send product analytics from a Next.js app straight to Glancy — no Segment in between.
+
+- **Browser:** `<GlancyProvider>` sends a page view on every route change, `useGlancy()` gives you
+  `track` / `identify` / `group` / `alias` / `reset`. Messages are batched (20 messages or 2 s) and flushed with
+  `fetch(keepalive)` when the tab is hidden or closed. Works with the App Router and the Pages Router.
+- **Middleware:** `withGlancy()` from `@caravela-studio/glancy-next/middleware` sends page views for page loads
+  (shared with the browser, so each is stored once) and `API Request` events from the server — see
+  [below](#middleware).
+- **Server:** `glancy()` from `@caravela-studio/glancy-next/server` for route handlers, server actions and middleware.
+- **Session replay & heatmaps (opt-in):** record sessions to watch them back, and collect clicks and scroll depth
+  per page — see [below](#session-replay-and-heatmaps).
+- **One visitor across both:** the browser's anonymous id lives in the `glancy_anon_id` cookie, so server events
+  can be tied to it with `getAnonymousId()`. `identify` merges the anonymous history into the user.
+
+Messages follow the Segment spec, so they look exactly like the events Glancy already receives from Segment.
+
+> Not on Next.js? See [all the SDKs](../README.md): `@caravela-studio/glancy-web` for any web app, `glancy.js` for any site,
+> React Native, Swift and Kotlin. This package is built on [`@caravela-studio/glancy-web`](../web).
+
+## Install
+
+Public on npm, no token needed:
+
+```bash
+npm install @caravela-studio/glancy-next     # brings @caravela-studio/glancy-web with it
+```
+
+`.env.local` of your app (the write key is on the bucket's **Setup** page):
+
+```bash
+NEXT_PUBLIC_GLANCY_HOST=https://analytics.example.com
+NEXT_PUBLIC_GLANCY_WRITE_KEY=glc_prod_…
+```
+
+The write key can only add events to one bucket, never read them, so it's fine to ship it to the browser.
+
+## Browser
+
+```tsx
+// app/layout.tsx
+import { GlancyProvider } from "@caravela-studio/glancy-next";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <GlancyProvider>{children}</GlancyProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+"use client";
+import { useGlancy } from "@caravela-studio/glancy-next";
+
+export function BuyButton() {
+  const analytics = useGlancy();
+  return <button onClick={() => analytics.track("Order Completed", { revenue: 42, currency: "EUR" })}>Buy</button>;
+}
+```
+
+| Method | What it sends |
+|---|---|
+| `track(event, properties?)` | A named event |
+| `page(name?, properties?)` | `Page Viewed` with `path`, `url`, `title`, `referrer`, `search` (automatic with the provider) |
+| `identify(userId, traits?)` | Links this browser to a user and stores traits on the profile (call after sign in) |
+| `group(groupId, traits?)` | Associates the user with a company / team |
+| `alias(userId, previousId?)` | Merges a previous id into `userId` |
+| `reset()` | Forgets the user, starts a new anonymous id and a new session (call on sign out) |
+| `flush()` | Sends the queue now |
+| `stopRecording()` | Stops session replay and heatmaps (e.g. consent withdrawn); events keep working |
+| `getSessionId()` | The current session id (also sent as `context.sessionId` on every event) |
+
+Provider props: `writeKey`, `host` (default to the env vars above), `trackPageViews` (default `true`),
+`flushAt` (20), `flushInterval` (2000 ms), `debug` (logs every message), `sessionReplay`, `heatmaps`.
+
+Every message carries `context.page`, `userAgent`, `os.name`, `locale`, `timezone` and `screen`, so breakdowns
+like *by OS* work out of the box.
+
+## Session replay and heatmaps
+
+Both are off by default and turned on with a prop:
+
+```tsx
+<GlancyProvider sessionReplay heatmaps>{children}</GlancyProvider>
+
+// or with options
+<GlancyProvider sessionReplay={{ sampleRate: 0.25, maskAllText: false }} heatmaps>
+```
+
+**Session replay** records the DOM with [rrweb](https://github.com/rrweb-io/rrweb) and sends it in compressed
+chunks every few seconds. Watch sessions under **Replays** in Glancy (with the session's events on a
+timeline), or from a person's profile. The recorder is loaded on demand, so it isn't in your bundle when replay is
+off.
+
+- A session is one browser tab; it ends after 30 minutes of inactivity or on `reset()`.
+- Privacy defaults: everything typed in inputs is masked (passwords always are). Add `data-glancy-mask` (or class
+  `glancy-mask`) to mask an element's text, `data-glancy-block` (or `glancy-block`) to leave it out entirely.
+
+| `sessionReplay` option | Default | |
+|---|---|---|
+| `sampleRate` | `1` | Share of sessions recorded (decided once per session) |
+| `maskAllInputs` | `true` | Mask what people type |
+| `maskAllText` | `false` | Mask every piece of text on the page |
+| `maskTextSelector` | — | More elements to mask |
+| `blockSelector` | — | More elements to leave out |
+
+**Heatmaps** collect every click (where on the page, and which element) and the deepest scroll of each page view.
+Glancy draws them over your live page in a frame, per page and device class (desktop / tablet / mobile), and
+lists the most clicked elements. Give important elements a `data-testid` or `data-glancy-name` to get stable names.
+For the page to show, your site must allow being framed by the dashboard's origin (no `X-Frame-Options: DENY` /
+restrictive `frame-ancestors`); the SDK doesn't track inside that frame.
+
+## Middleware
+
+```ts
+// middleware.ts
+import { withGlancy } from "@caravela-studio/glancy-next/middleware";
+
+export default withGlancy({ exclude: ["/api/health"], userId: (req) => req.cookies.get("uid")?.value });
+export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
+```
+
+- A page view for every page load (`Sec-Fetch-Dest: document`), with a fresh `messageId` that it hands to the
+  browser in the short-lived `glancy_pv` cookie. The browser SDK's first page view of that page reuses it, and
+  ingestion stores one row, filling in what the server's copy lacked (title, screen, the browser session).
+  Client-side navigations stay with `<GlancyProvider>`: Next.js strips the RSC / prefetch headers before middleware,
+  so a navigation can't be told from a prefetch there.
+- An `API Request` event (method, path) for paths matching `api` (default `["/api/"]`).
+- Sets `glancy_anon_id` on the first request (readable by the browser SDK), so both sides share the visitor.
+- Skips static files, prefetches, redirects and `exclude`; sends with `event.waitUntil`.
+- `withGlancy(options, yourMiddleware)` runs yours first and keeps its response.
+
+## Server
+
+Set `GLANCY_HOST` and `GLANCY_WRITE_KEY` (the `NEXT_PUBLIC_` ones are used as a fallback).
+
+```ts
+// app/api/checkout/route.ts
+import { glancy, getAnonymousId } from "@caravela-studio/glancy-next/server";
+import { cookies } from "next/headers";
+import { after } from "next/server";
+
+export async function POST() {
+  const anonymousId = getAnonymousId(await cookies());
+  after(() => glancy().track({ userId: user.id, anonymousId, event: "Order Completed", properties: { revenue: 42 } }));
+  return Response.json({ ok: true });
+}
+```
+
+Server calls (`track`, `identify`, `page`, `group`, `alias`, `batch`) need a `userId` or an `anonymousId`. Each
+one is sent right away and resolves once it's stored, so serverless functions don't drop events; `after()` keeps
+it off the response time. Sending never throws — failures go to `onError` (default `console.error`).
+`new ServerClient({ writeKey, host })` creates a client with explicit config.
+
+## Example
+
+`examples/nextjs` is a small app using both sides: `npm install && npm run dev` (port 3048).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { GlancyProvider, useGlancy, type GlancyProviderProps } from "./react.js";
+export { BrowserClient, ANONYMOUS_ID_COOKIE, type BrowserOptions, type SessionReplayOptions, type Message, type Properties, type Traits } from "@caravela-studio/glancy-web";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { GlancyProvider, useGlancy } from "./react.js";
+// The browser client and its types come from @caravela-studio/glancy-web.
+export { BrowserClient, ANONYMOUS_ID_COOKIE } from "@caravela-studio/glancy-web";

package/dist/middleware.d.ts

@@ -0,0 +1,36 @@
+import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
+import { type ServerOptions } from "./server.js";
+/** A path prefix ("/api/"), a regular expression, or a test of the whole request. */
+export type PathMatcher = string | RegExp | ((req: NextRequest) => boolean);
+export interface GlancyMiddlewareOptions extends ServerOptions {
+    /**
+     * Send a page view from the server for every page load. The browser SDK (`<GlancyProvider>`) reuses
+     * its id, so each page view is stored once, and it still counts when the browser script is blocked.
+     * Client-side navigations are tracked by the browser. Default true.
+     */
+    pageViews?: boolean;
+    /** Requests sent as an "API Request" event (method, path). Default ["/api/"]; false for none. */
+    api?: PathMatcher[] | false;
+    /** Requests never tracked, e.g. health checks. */
+    exclude?: PathMatcher[];
+    /** The signed-in user, e.g. from your session cookie, so events land on their profile. */
+    userId?: (req: NextRequest) => string | number | null | undefined | Promise<string | number | null | undefined>;
+}
+type Middleware = (req: NextRequest, event: NextFetchEvent) => Response | NextResponse | null | undefined | void | Promise<Response | NextResponse | null | undefined | void>;
+/**
+ * A page load: a document request. Client-side navigations aren't counted here: Next.js hides the
+ * headers that tell a navigation from a prefetch from middleware, so the browser SDK tracks those.
+ */
+export declare function isPageRequest(req: NextRequest): boolean;
+/**
+ * Next.js middleware that tracks server-side: page views (shared with the browser SDK, so nothing is
+ * counted twice) and API requests. It also sets the anonymous id cookie on the first request, so
+ * server and browser events belong to the same visitor from the start.
+ *
+ *   // middleware.ts
+ *   export default withGlancy({ userId: (req) => req.cookies.get("uid")?.value });
+ *
+ * Pass your own middleware as the second argument to run it first.
+ */
+export declare function withGlancy(options?: GlancyMiddlewareOptions, middleware?: Middleware): (req: NextRequest, event: NextFetchEvent) => Promise<Response>;
+export {};

package/dist/middleware.js

@@ -0,0 +1,116 @@
+import { NextResponse } from "next/server";
+import { ANONYMOUS_ID_COOKIE, DEFAULT_REDACTED_PARAMS, PAGE_VIEW_COOKIE, encodePageView, redactUrl, uuid } from "@caravela-studio/glancy-web/core";
+import { ServerClient } from "./server.js";
+const YEAR = 365 * 24 * 3600;
+/** Static files and Next.js internals: never page views or API requests. */
+const ASSET = /^\/(_next|__nextjs)|\.[a-z0-9]{2,5}$/i;
+const matches = (req, list) => list.some((m) => (typeof m === "string" ? req.nextUrl.pathname.startsWith(m) : m instanceof RegExp ? m.test(req.nextUrl.pathname) : m(req)));
+/** A browser prefetch (speculation rules, <link rel=prefetch>): nobody has seen the page yet. */
+const isPrefetch = (h) => h.get("purpose") === "prefetch" || /prefetch|prerender/.test(h.get("sec-purpose") ?? "");
+/**
+ * A page load: a document request. Client-side navigations aren't counted here: Next.js hides the
+ * headers that tell a navigation from a prefetch from middleware, so the browser SDK tracks those.
+ */
+export function isPageRequest(req) {
+    const h = req.headers;
+    if (req.method !== "GET" || isPrefetch(h) || ASSET.test(req.nextUrl.pathname))
+        return false;
+    const dest = h.get("sec-fetch-dest");
+    if (dest)
+        return dest === "document";
+    return !h.has("next-url") && (h.get("accept") ?? "").includes("text/html");
+}
+/** Country, region and city from Vercel's geolocation headers, when the app runs on Vercel. */
+function location(h) {
+    const country = h.get("x-vercel-ip-country");
+    if (!country)
+        return undefined;
+    const decode = (v) => (v ? decodeURIComponent(v) : undefined);
+    const lat = Number(h.get("x-vercel-ip-latitude"));
+    const lon = Number(h.get("x-vercel-ip-longitude"));
+    return {
+        country,
+        region: decode(h.get("x-vercel-ip-country-region")),
+        city: decode(h.get("x-vercel-ip-city")),
+        ...(Number.isFinite(lat) && Number.isFinite(lon) && h.get("x-vercel-ip-latitude") ? { latitude: lat, longitude: lon } : {}),
+    };
+}
+function cookie(name, value, maxAge, secure) {
+    return `${name}=${encodeURIComponent(value)}; Path=/; Max-Age=${maxAge}; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+/**
+ * Next.js middleware that tracks server-side: page views (shared with the browser SDK, so nothing is
+ * counted twice) and API requests. It also sets the anonymous id cookie on the first request, so
+ * server and browser events belong to the same visitor from the start.
+ *
+ *   // middleware.ts
+ *   export default withGlancy({ userId: (req) => req.cookies.get("uid")?.value });
+ *
+ * Pass your own middleware as the second argument to run it first.
+ */
+export function withGlancy(options = {}, middleware) {
+    const { pageViews = true, api = ["/api/"], exclude = [], userId, ...serverOptions } = options;
+    let client = null;
+    return async function glancyMiddleware(req, event) {
+        const response = (await middleware?.(req, event)) ?? NextResponse.next();
+        if (ASSET.test(req.nextUrl.pathname) || matches(req, exclude))
+            return response;
+        const page = pageViews && isPageRequest(req) && !(response.status >= 300 && response.status < 400);
+        const apiRequest = !!api && !page && matches(req, api) && !isPrefetch(req.headers);
+        if (!page && !apiRequest)
+            return response;
+        const secure = req.nextUrl.protocol === "https:";
+        const cookies = [];
+        let anonymousId = req.cookies.get(ANONYMOUS_ID_COOKIE)?.value;
+        anonymousId = anonymousId ? decodeURIComponent(anonymousId) : undefined;
+        if (!anonymousId) {
+            anonymousId = uuid();
+            cookies.push(cookie(ANONYMOUS_ID_COOKIE, anonymousId, YEAR, secure));
+        }
+        // Secret query parameters (tokens, codes) never leave the server, like in the browser SDK.
+        const url = req.nextUrl;
+        const redact = (u) => redactUrl(u, DEFAULT_REDACTED_PARAMS);
+        const h = req.headers;
+        const info = {
+            path: url.pathname,
+            url: redact(url.href),
+            search: redact(url.search ? `/${url.search}` : "").slice(1),
+            referrer: redact(h.get("referer") ?? ""),
+        };
+        const context = {
+            userAgent: h.get("user-agent") ?? undefined,
+            locale: h.get("accept-language")?.split(",")[0] || undefined,
+            location: location(h),
+            page: info,
+        };
+        const properties = page ? info : { method: req.method, path: url.pathname };
+        const messageId = uuid();
+        if (page)
+            cookies.push(cookie(PAGE_VIEW_COOKIE, encodePageView(messageId, redact(url.pathname + url.search)), 60, secure));
+        const send = async () => {
+            try {
+                client ?? (client = new ServerClient(serverOptions));
+                const identity = { anonymousId: anonymousId, userId: (userId ? await userId(req) : null) ?? null };
+                await (page
+                    ? client.page({ ...identity, messageId, context, properties })
+                    : client.track({ ...identity, messageId, event: "API Request", context, properties }));
+            }
+            catch (err) {
+                (serverOptions.onError ?? console.error)(err);
+            }
+        };
+        // Off the response's critical path: Next.js keeps the function alive until it's stored.
+        const sending = send();
+        if (typeof event?.waitUntil === "function")
+            event.waitUntil(sending);
+        for (const c of cookies) {
+            try {
+                response.headers.append("Set-Cookie", c);
+            }
+            catch {
+                // Immutable headers (e.g. Response.redirect): no cookies, the browser SDK makes its own ids.
+            }
+        }
+        return response;
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import { BrowserClient, type BrowserOptions } from "@caravela-studio/glancy-web";
+export interface GlancyProviderProps extends Partial<BrowserOptions> {
+    children: ReactNode;
+    /** Send a page view on every route change (pathname or search params). Default true. */
+    trackPageViews?: boolean;
+}
+/**
+ * Put this in the root layout. `writeKey` and `host` default to NEXT_PUBLIC_GLANCY_WRITE_KEY and
+ * NEXT_PUBLIC_GLANCY_HOST. Add `sessionReplay` and / or `heatmaps` to turn those on.
+ */
+export declare function GlancyProvider({ children, trackPageViews, ...options }: GlancyProviderProps): import("react").JSX.Element;
+/** The client, for `track` / `identify` / `reset` in client components. */
+export declare function useGlancy(): BrowserClient;

package/dist/react.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePathname, useSearchParams } from "next/navigation";
+import { createContext, Suspense, useContext, useEffect, useRef, useState } from "react";
+import { BrowserClient, LIBRARY } from "@caravela-studio/glancy-web";
+const Context = createContext(null);
+/**
+ * Put this in the root layout. `writeKey` and `host` default to NEXT_PUBLIC_GLANCY_WRITE_KEY and
+ * NEXT_PUBLIC_GLANCY_HOST. Add `sessionReplay` and / or `heatmaps` to turn those on.
+ */
+export function GlancyProvider({ children, trackPageViews = true, ...options }) {
+    const [client] = useState(() => new BrowserClient({
+        ...options,
+        writeKey: options.writeKey ?? process.env.NEXT_PUBLIC_GLANCY_WRITE_KEY ?? "",
+        host: options.host ?? process.env.NEXT_PUBLIC_GLANCY_HOST ?? "",
+        manualStart: true,
+        library: { name: "@glancy/next", version: LIBRARY.version },
+    }));
+    // In an effect (with cleanup) so React strict mode's double render doesn't record twice.
+    useEffect(() => {
+        client.startRecording();
+        return () => client.stopRecording();
+    }, [client]);
+    return (_jsxs(Context.Provider, { value: client, children: [trackPageViews && (
+            // useSearchParams needs a Suspense boundary, otherwise it opts the whole page out of static rendering.
+            _jsx(Suspense, { fallback: null, children: _jsx(PageViews, { client: client }) })), children] }));
+}
+function PageViews({ client }) {
+    const pathname = usePathname();
+    const search = useSearchParams()?.toString() ?? "";
+    const last = useRef(null);
+    useEffect(() => {
+        const key = `${pathname}?${search}`;
+        // Strict mode runs effects twice in development; one page view per URL.
+        if (last.current === key)
+            return;
+        last.current = key;
+        client.page();
+    }, [client, pathname, search]);
+    return null;
+}
+/** The client, for `track` / `identify` / `reset` in client components. */
+export function useGlancy() {
+    const client = useContext(Context);
+    if (!client)
+        throw new Error("[glancy] useGlancy() must be used inside <GlancyProvider>");
+    return client;
+}

package/dist/server.d.ts

@@ -0,0 +1,70 @@
+import { ANONYMOUS_ID_COOKIE, type Message, type Properties, type Traits } from "@caravela-studio/glancy-web/core";
+export { ANONYMOUS_ID_COOKIE };
+export type { Message, Properties, Traits };
+export interface ServerOptions {
+    /** Defaults to GLANCY_WRITE_KEY (or NEXT_PUBLIC_GLANCY_WRITE_KEY). */
+    writeKey?: string;
+    /** Defaults to GLANCY_HOST (or NEXT_PUBLIC_GLANCY_HOST). */
+    host?: string;
+    /** Called when a send fails. Default: console.error. Sending never throws. */
+    onError?: (err: unknown) => void;
+}
+/** Who the event is about: a signed-in user, the browser's anonymous id, or both (links them). */
+export type Identity = {
+    userId: string | number;
+    anonymousId?: string | null;
+} | {
+    userId?: string | number | null;
+    anonymousId: string;
+};
+type Common = Identity & {
+    context?: Record<string, unknown>;
+    timestamp?: Date | string;
+    /** A unique id per message; Glancy stores one message per id (default: a new uuid). */
+    messageId?: string;
+};
+/**
+ * Server client for route handlers, server actions and middleware. Each call is sent right away and the
+ * returned promise resolves when it's stored, so nothing is lost when a serverless function ends. Wrap
+ * calls in `after()` (next/server) to keep them off the response's critical path.
+ */
+export declare class ServerClient {
+    private readonly options;
+    private readonly writeKey;
+    private readonly url;
+    constructor(options?: ServerOptions);
+    track(input: Common & {
+        event: string;
+        properties?: Properties;
+    }): Promise<void>;
+    identify(input: Common & {
+        traits?: Traits;
+    }): Promise<void>;
+    page(input: Common & {
+        name?: string;
+        properties?: Properties;
+    }): Promise<void>;
+    group(input: Common & {
+        groupId: string | number;
+        traits?: Traits;
+    }): Promise<void>;
+    alias(input: {
+        userId: string | number;
+        previousId: string;
+        context?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Send several messages in one request (e.g. a backfill). */
+    batch(messages: Message[]): Promise<void>;
+    private message;
+    private send;
+}
+export declare function glancy(options?: ServerOptions): ServerClient;
+/**
+ * The anonymous id the browser SDK stored in a cookie, so server events land on the same visitor:
+ * `getAnonymousId(await cookies())` or `getAnonymousId(request.cookies)`.
+ */
+export declare function getAnonymousId(cookies: {
+    get(name: string): {
+        value: string;
+    } | undefined;
+}): string | undefined;

package/dist/server.js

@@ -0,0 +1,77 @@
+import { ANONYMOUS_ID_COOKIE, LIBRARY, ingestUrl, stamp } from "@caravela-studio/glancy-web/core";
+const library = { name: "@glancy/next", version: LIBRARY.version };
+export { ANONYMOUS_ID_COOKIE };
+/**
+ * Server client for route handlers, server actions and middleware. Each call is sent right away and the
+ * returned promise resolves when it's stored, so nothing is lost when a serverless function ends. Wrap
+ * calls in `after()` (next/server) to keep them off the response's critical path.
+ */
+export class ServerClient {
+    constructor(options = {}) {
+        this.options = options;
+        const env = typeof process !== "undefined" ? process.env : {};
+        this.writeKey = options.writeKey ?? env.GLANCY_WRITE_KEY ?? env.NEXT_PUBLIC_GLANCY_WRITE_KEY ?? "";
+        if (!this.writeKey)
+            throw new Error("[glancy] `writeKey` is required (or set GLANCY_WRITE_KEY)");
+        this.url = ingestUrl(options.host ?? env.GLANCY_HOST ?? env.NEXT_PUBLIC_GLANCY_HOST ?? "");
+    }
+    track(input) {
+        return this.send([this.message({ ...input, type: "track" })]);
+    }
+    identify(input) {
+        return this.send([this.message({ ...input, type: "identify" })]);
+    }
+    page(input) {
+        return this.send([this.message({ ...input, type: "page" })]);
+    }
+    group(input) {
+        return this.send([this.message({ ...input, type: "group", groupId: String(input.groupId) })]);
+    }
+    alias(input) {
+        return this.send([this.message({ ...input, type: "alias" })]);
+    }
+    /** Send several messages in one request (e.g. a backfill). */
+    async batch(messages) {
+        if (messages.length)
+            await this.send(messages.map((m) => stamp({ ...m, context: { source: "server", ...m.context } }, library)));
+    }
+    message(input) {
+        const { timestamp, userId, context, ...rest } = input;
+        return stamp({
+            ...rest,
+            context: { source: "server", ...context },
+            userId: userId === undefined || userId === null ? null : String(userId),
+            ...(timestamp ? { timestamp: new Date(timestamp).toISOString() } : {}),
+        }, library);
+    }
+    async send(batch) {
+        try {
+            const res = await fetch(this.url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.writeKey}` },
+                body: JSON.stringify({ batch, sentAt: new Date().toISOString() }),
+                cache: "no-store",
+            });
+            if (!res.ok)
+                throw new Error(`[glancy] HTTP ${res.status}: ${await res.text()}`);
+        }
+        catch (err) {
+            (this.options.onError ?? console.error)(err);
+        }
+    }
+}
+/** One client per server process; reads its config from the environment. */
+let shared = null;
+export function glancy(options) {
+    if (options)
+        return new ServerClient(options);
+    return (shared ?? (shared = new ServerClient()));
+}
+/**
+ * The anonymous id the browser SDK stored in a cookie, so server events land on the same visitor:
+ * `getAnonymousId(await cookies())` or `getAnonymousId(request.cookies)`.
+ */
+export function getAnonymousId(cookies) {
+    const v = cookies.get(ANONYMOUS_ID_COOKIE)?.value;
+    return v ? decodeURIComponent(v) : undefined;
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@caravela-studio/glancy-next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Send product analytics from Next.js straight to Glancy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caravela-labs/glancy.git",
+    "directory": "sdks/next"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "default": "./dist/middleware.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "next": ">=13.4",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "next": "^15.5.0",
+    "react": "^19.0.0",
+    "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "@caravela-studio/glancy-web": "^0.1.1"
+  }
+}