@shipeasy/sdk 4.4.0 → 4.5.0

package/dist/next/index.d.mts

@@ -0,0 +1,50 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/** The first-party cookie that carries the stable anonymous bucketing unit. */
+declare const ANON_ID_COOKIE = "__se_anon_id";
+interface AnonIdResult {
+    /** The stable bucketing id for this request (existing cookie, or freshly minted). */
+    anonId: string;
+    /** True when there was no valid cookie and we minted a new id (must be persisted). */
+    minted: boolean;
+}
+/**
+ * Read + validate the `__se_anon_id` cookie, minting one when absent/invalid.
+ * When `requestHeaders` is supplied and we mint, the new id is appended to the
+ * forwarded `cookie` header so THIS request's SSR (and any inner middleware)
+ * already sees it. Pair with {@link commitAnonId} to persist a minted id.
+ */
+declare function readOrMintAnonId(req: NextRequest, requestHeaders?: Headers): AnonIdResult;
+/**
+ * Persist a freshly-minted anon id as a first-party cookie on `res` (no-op when
+ * `minted` is false). Non-httpOnly by contract — the browser SDK reads it via
+ * `document.cookie` to bucket identically to SSR. Returns `res` for chaining.
+ */
+declare function commitAnonId(res: NextResponse, result: AnonIdResult, req: NextRequest): NextResponse;
+type ShipeasyMiddleware = (req: NextRequest, event: NextFetchEvent) => NextResponse | Response | undefined | null | void | Promise<NextResponse | Response | undefined | null | void>;
+/**
+ * Wrap an existing Next middleware so every matched request also mints the
+ * shared `__se_anon_id` cookie. Your middleware runs against a request that
+ * already carries the id (its own logic + SSR see it), and the cookie is set on
+ * whatever response it returns. Called with no argument, returns a standalone
+ * mint-only middleware (what the default {@link middleware} export uses).
+ *
+ * If your middleware forwards custom request headers via
+ * `NextResponse.next({ request: { headers } })`, prefer composing the
+ * {@link readOrMintAnonId} + {@link commitAnonId} primitives inside it — that
+ * preserves your forwarding verbatim; this wrapper rebuilds the pass-through
+ * `next()` and so would drop request-header forwarding the inner handler added.
+ */
+declare function withShipeasy(handler?: ShipeasyMiddleware): ShipeasyMiddleware;
+/** Drop-in middleware: `export { middleware, config } from "@shipeasy/sdk/next";` */
+declare const middleware: ShipeasyMiddleware;
+/**
+ * Matcher for the drop-in middleware: every HTML route (landing + app), skipping
+ * Next internals, API routes, and static files (any path segment with a dot).
+ * Define your own `config` if you need a narrower scope.
+ */
+declare const config: {
+    matcher: string[];
+};
+
+export { ANON_ID_COOKIE, type AnonIdResult, type ShipeasyMiddleware, commitAnonId, config, middleware, readOrMintAnonId, withShipeasy };

package/dist/next/index.d.ts

@@ -0,0 +1,50 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/** The first-party cookie that carries the stable anonymous bucketing unit. */
+declare const ANON_ID_COOKIE = "__se_anon_id";
+interface AnonIdResult {
+    /** The stable bucketing id for this request (existing cookie, or freshly minted). */
+    anonId: string;
+    /** True when there was no valid cookie and we minted a new id (must be persisted). */
+    minted: boolean;
+}
+/**
+ * Read + validate the `__se_anon_id` cookie, minting one when absent/invalid.
+ * When `requestHeaders` is supplied and we mint, the new id is appended to the
+ * forwarded `cookie` header so THIS request's SSR (and any inner middleware)
+ * already sees it. Pair with {@link commitAnonId} to persist a minted id.
+ */
+declare function readOrMintAnonId(req: NextRequest, requestHeaders?: Headers): AnonIdResult;
+/**
+ * Persist a freshly-minted anon id as a first-party cookie on `res` (no-op when
+ * `minted` is false). Non-httpOnly by contract — the browser SDK reads it via
+ * `document.cookie` to bucket identically to SSR. Returns `res` for chaining.
+ */
+declare function commitAnonId(res: NextResponse, result: AnonIdResult, req: NextRequest): NextResponse;
+type ShipeasyMiddleware = (req: NextRequest, event: NextFetchEvent) => NextResponse | Response | undefined | null | void | Promise<NextResponse | Response | undefined | null | void>;
+/**
+ * Wrap an existing Next middleware so every matched request also mints the
+ * shared `__se_anon_id` cookie. Your middleware runs against a request that
+ * already carries the id (its own logic + SSR see it), and the cookie is set on
+ * whatever response it returns. Called with no argument, returns a standalone
+ * mint-only middleware (what the default {@link middleware} export uses).
+ *
+ * If your middleware forwards custom request headers via
+ * `NextResponse.next({ request: { headers } })`, prefer composing the
+ * {@link readOrMintAnonId} + {@link commitAnonId} primitives inside it — that
+ * preserves your forwarding verbatim; this wrapper rebuilds the pass-through
+ * `next()` and so would drop request-header forwarding the inner handler added.
+ */
+declare function withShipeasy(handler?: ShipeasyMiddleware): ShipeasyMiddleware;
+/** Drop-in middleware: `export { middleware, config } from "@shipeasy/sdk/next";` */
+declare const middleware: ShipeasyMiddleware;
+/**
+ * Matcher for the drop-in middleware: every HTML route (landing + app), skipping
+ * Next internals, API routes, and static files (any path segment with a dot).
+ * Define your own `config` if you need a narrower scope.
+ */
+declare const config: {
+    matcher: string[];
+};
+
+export { ANON_ID_COOKIE, type AnonIdResult, type ShipeasyMiddleware, commitAnonId, config, middleware, readOrMintAnonId, withShipeasy };

package/dist/next/index.js

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/next/index.ts
+var next_exports = {};
+__export(next_exports, {
+  ANON_ID_COOKIE: () => ANON_ID_COOKIE,
+  commitAnonId: () => commitAnonId,
+  config: () => config,
+  middleware: () => middleware,
+  readOrMintAnonId: () => readOrMintAnonId,
+  withShipeasy: () => withShipeasy
+});
+module.exports = __toCommonJS(next_exports);
+var import_server = require("next/server");
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+var ANON_ID_MAX_AGE = 60 * 60 * 24 * 365;
+function mint() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
+function appendCookie(headers, name, value) {
+  const existing = headers.get("cookie") ?? "";
+  const parts = existing.split(";").map((c) => c.trim()).filter((c) => c && !c.startsWith(`${name}=`));
+  parts.push(`${name}=${value}`);
+  headers.set("cookie", parts.join("; "));
+}
+function readOrMintAnonId(req, requestHeaders) {
+  const raw = req.cookies.get(ANON_ID_COOKIE)?.value;
+  const valid = !!raw && ANON_ID_RX.test(raw);
+  const anonId = valid ? raw : mint();
+  const minted = !valid;
+  if (minted && requestHeaders) appendCookie(requestHeaders, ANON_ID_COOKIE, anonId);
+  return { anonId, minted };
+}
+function commitAnonId(res, result, req) {
+  if (result.minted) {
+    res.cookies.set(ANON_ID_COOKIE, result.anonId, {
+      httpOnly: false,
+      secure: req.nextUrl.protocol === "https:",
+      sameSite: "lax",
+      path: "/",
+      maxAge: ANON_ID_MAX_AGE
+    });
+  }
+  return res;
+}
+function withShipeasy(handler) {
+  return async (req, event) => {
+    const requestHeaders = new Headers(req.headers);
+    const anon = readOrMintAnonId(req, requestHeaders);
+    if (anon.minted) req.cookies.set(ANON_ID_COOKIE, anon.anonId);
+    const userRes = handler ? await handler(req, event) : void 0;
+    const isPassThrough = !userRes || userRes instanceof import_server.NextResponse && userRes.headers.get("x-middleware-next") === "1";
+    if (isPassThrough) {
+      const res2 = import_server.NextResponse.next({ request: { headers: requestHeaders } });
+      if (userRes instanceof import_server.NextResponse) {
+        userRes.cookies.getAll().forEach((c) => res2.cookies.set(c));
+        userRes.headers.forEach((v, k) => {
+          if (k !== "x-middleware-next") res2.headers.set(k, v);
+        });
+      }
+      return commitAnonId(res2, anon, req);
+    }
+    const res = userRes instanceof import_server.NextResponse ? userRes : userRes instanceof Response ? new import_server.NextResponse(userRes.body, userRes) : import_server.NextResponse.next({ request: { headers: requestHeaders } });
+    return commitAnonId(res, anon, req);
+  };
+}
+var middleware = withShipeasy();
+var config = {
+  matcher: ["/((?!api/|_next/|.*\\..*).*)"]
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ANON_ID_COOKIE,
+  commitAnonId,
+  config,
+  middleware,
+  readOrMintAnonId,
+  withShipeasy
+});

package/dist/next/index.mjs

@@ -0,0 +1,67 @@
+// src/next/index.ts
+import { NextResponse } from "next/server";
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+var ANON_ID_MAX_AGE = 60 * 60 * 24 * 365;
+function mint() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
+function appendCookie(headers, name, value) {
+  const existing = headers.get("cookie") ?? "";
+  const parts = existing.split(";").map((c) => c.trim()).filter((c) => c && !c.startsWith(`${name}=`));
+  parts.push(`${name}=${value}`);
+  headers.set("cookie", parts.join("; "));
+}
+function readOrMintAnonId(req, requestHeaders) {
+  const raw = req.cookies.get(ANON_ID_COOKIE)?.value;
+  const valid = !!raw && ANON_ID_RX.test(raw);
+  const anonId = valid ? raw : mint();
+  const minted = !valid;
+  if (minted && requestHeaders) appendCookie(requestHeaders, ANON_ID_COOKIE, anonId);
+  return { anonId, minted };
+}
+function commitAnonId(res, result, req) {
+  if (result.minted) {
+    res.cookies.set(ANON_ID_COOKIE, result.anonId, {
+      httpOnly: false,
+      secure: req.nextUrl.protocol === "https:",
+      sameSite: "lax",
+      path: "/",
+      maxAge: ANON_ID_MAX_AGE
+    });
+  }
+  return res;
+}
+function withShipeasy(handler) {
+  return async (req, event) => {
+    const requestHeaders = new Headers(req.headers);
+    const anon = readOrMintAnonId(req, requestHeaders);
+    if (anon.minted) req.cookies.set(ANON_ID_COOKIE, anon.anonId);
+    const userRes = handler ? await handler(req, event) : void 0;
+    const isPassThrough = !userRes || userRes instanceof NextResponse && userRes.headers.get("x-middleware-next") === "1";
+    if (isPassThrough) {
+      const res2 = NextResponse.next({ request: { headers: requestHeaders } });
+      if (userRes instanceof NextResponse) {
+        userRes.cookies.getAll().forEach((c) => res2.cookies.set(c));
+        userRes.headers.forEach((v, k) => {
+          if (k !== "x-middleware-next") res2.headers.set(k, v);
+        });
+      }
+      return commitAnonId(res2, anon, req);
+    }
+    const res = userRes instanceof NextResponse ? userRes : userRes instanceof Response ? new NextResponse(userRes.body, userRes) : NextResponse.next({ request: { headers: requestHeaders } });
+    return commitAnonId(res, anon, req);
+  };
+}
+var middleware = withShipeasy();
+var config = {
+  matcher: ["/((?!api/|_next/|.*\\..*).*)"]
+};
+export {
+  ANON_ID_COOKIE,
+  commitAnonId,
+  config,
+  middleware,
+  readOrMintAnonId,
+  withShipeasy
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",
@@ -21,6 +21,9 @@
       ],
       "server": [
         "./dist/server/index.d.ts"
+      ],
+      "next": [
+        "./dist/next/index.d.ts"
       ]
     }
   },
@@ -39,11 +42,17 @@
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.mjs",
+      "default": "./dist/next/index.js"
+    },
     "./templates/*": "./templates/*.js"
   },
   "files": [
     "dist/server/",
     "dist/client/",
+    "dist/next/",
     "templates/",
     "LICENSE",
     "README.md"
@@ -58,9 +67,18 @@
   "dependencies": {
     "murmurhash-js": "^1.0.0"
   },
+  "peerDependencies": {
+    "next": ">=13"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/murmurhash-js": "^1.0.6",
     "@types/node": "^20.0.0",
+    "next": "^16.2.3",
     "tsup": "^8.3.0",
     "typescript": "^5.7.4",
     "vitest": "^2.1.0",