@ooky/sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to `@ooky/sdk`. Versions follow [semver](https://semver.org);
 pre-1.0, minor versions may include breaking changes (called out explicitly).
 
+## 0.6.0 — 2026-06-19
+
+### Fixed
+- **Middleware fails safe on missing config (high).** `createOokyHandler` throws
+  when `apiKey`/`domain` are missing, and the adapters built the handler at
+  module load — so an unset or typo'd `OOKY_API_KEY` / `OOKY_DOMAIN` threw on
+  construction and **500'd the customer's entire site** (the middleware runs on
+  every request, e.g. Vercel's `MIDDLEWARE_INVOCATION_FAILED`). The Express,
+  Next, and Edge adapters now wrap construction: on failure they log one loud
+  line and return a pass-through middleware, so a misconfigured integration
+  disables Ooky **without taking down the host app**. Complements the existing
+  per-request pass-through hardening.
+
 ## 0.5.0 — 2026-06-12
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ooky/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Ooky SDK — middleware for serving AI brand intelligence and capturing AI-bot analytics from your Node, Next.js, or Vercel Edge app.",
   "keywords": [
     "ai",

package/src/core.js

@@ -19,7 +19,7 @@ import { detectBot as detectFromList, DEFAULT_BOTS, sanitizeBotRegistry } from "
 import { detectAIReferral } from "./referrals.js";
 import { handleMcpJsonRpc, McpToolError } from "./mcp.js";
 
-export const SDK_VERSION = "0.5.0";
+export const SDK_VERSION = "0.6.0";
 
 // Defensive length caps on untrusted strings copied into the event payload.
 // The load-bearing clamp is server-side (owned by the backend), but capping
@@ -33,6 +33,25 @@ export function clampString(value, max) {
   return value.length > max ? value.slice(0, max) : value;
 }
 
+/**
+ * Log (loudly) that the middleware could not be constructed — almost always a
+ * missing/invalid OOKY_API_KEY or OOKY_DOMAIN. The adapters call this and then
+ * return a pass-through middleware: a misconfigured integration must NEVER take
+ * down the customer's site (the middleware runs on every request). Never throws.
+ */
+export function logMiddlewareDisabled(err) {
+  const msg = err && err.message ? err.message : String(err);
+  try {
+    console.error(
+      `[@ooky/sdk] Middleware disabled — ${msg}. Requests pass through ` +
+        `untouched (your app is unaffected); Ooky features are inactive. ` +
+        `Check that OOKY_API_KEY and OOKY_DOMAIN are set.`
+    );
+  } catch {
+    // console may be unavailable in exotic runtimes — never throw from here.
+  }
+}
+
 /**
  * Hard cap on the MCP request body the adapters will read before answering.
  * The Express adapter enforces this while streaming; the Next/Edge adapter

package/src/express.js

@@ -10,6 +10,7 @@
 
 import {
   createOokyHandler,
+  logMiddlewareDisabled,
   MAX_MCP_BODY_BYTES,
   MAX_UA_LENGTH,
   MAX_PATH_LENGTH,
@@ -17,7 +18,19 @@ import {
 } from "./core.js";
 
 export function ookyMiddleware(options) {
-  const handler = createOokyHandler(options);
+  let handler;
+  try {
+    handler = createOokyHandler(options);
+  } catch (err) {
+    // Construction failed (almost always missing OOKY_API_KEY / OOKY_DOMAIN).
+    // This middleware is mounted on every request, so throwing here would take
+    // down the customer's whole app. Fail safe: log loudly, return a no-op that
+    // simply calls next().
+    logMiddlewareDisabled(err);
+    return function ookyHandlerDisabled(req, res, next) {
+      return next();
+    };
+  }
 
   return async function ookyHandler(req, res, next) {
     const rawUa = req.headers["user-agent"] || "";

package/src/next.js

@@ -13,10 +13,21 @@
  * bot / ai_referral analytics events.
  */
 
-import { createOokyHandler, MAX_MCP_BODY_BYTES, MAX_UA_LENGTH, MAX_PATH_LENGTH, clampString } from "./core.js";
+import { createOokyHandler, logMiddlewareDisabled, MAX_MCP_BODY_BYTES, MAX_UA_LENGTH, MAX_PATH_LENGTH, clampString } from "./core.js";
 
 export function ookyMiddleware(options) {
-  const handler = createOokyHandler(options);
+  let handler;
+  try {
+    handler = createOokyHandler(options);
+  } catch (err) {
+    // Construction failed (almost always missing OOKY_API_KEY / OOKY_DOMAIN).
+    // The middleware runs on every request, so throwing here would 500 the
+    // customer's entire site. Fail safe: log loudly, return a pass-through.
+    logMiddlewareDisabled(err);
+    return function ookyNextMiddlewareDisabled() {
+      return undefined; // Next continues to the route — app unaffected.
+    };
+  }
 
   return async function ookyNextMiddleware(request, event) {
     const url = new URL(request.url);