@sylphx/sdk 0.7.0 → 0.8.0-rc.2

package/README.md

@@ -26,21 +26,23 @@ bun add @sylphx/sdk
 
 ### 1. Environment Variables
 
-Two keys from your [Platform Console](https://sylphx.com/console):
+Your server connection URL and environment app ID from your
+[Platform Console](https://sylphx.com/console):
 
 ```bash
 # .env.local
-SYLPHX_SECRET_KEY=sk_dev_xxxxxxxxxxxxxxxxxxxx        # server-only
-NEXT_PUBLIC_SYLPHX_APP_ID=app_dev_xxxxxxxxxxxx        # safe to expose
+SYLPHX_URL=sylphx://sk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@bold-river-a1b2c3.api.sylphx.com
+NEXT_PUBLIC_SYLPHX_APP_ID=app_dev_xxxxxxxxxxxx
 ```
 
 That's it. No other config needed.
 
 > **Key formats**
-> - `sk_dev_*` / `sk_stg_*` / `sk_prod_*` — Secret key (server only, never expose)
+> - `sylphx://sk_*@<tenant-slug>.api.sylphx.com` — Server connection URL (server only, never expose)
 > - `app_dev_*` / `app_stg_*` / `app_prod_*` — App ID (safe for client-side)
 >
-> Get both from **Console → Your App → API Keys**.
+> Get both from **Console → Your App → API Keys**. The hosted BaaS API is always
+> addressed as `<tenant-slug>.api.sylphx.com`.
 
 ---
 
@@ -73,11 +75,16 @@ Fetch config server-side once, pass to the provider:
 // app/layout.tsx
 import { getAppConfig } from '@sylphx/sdk/server'
 import { SylphxProvider } from '@sylphx/sdk/react'
+import { createServerClient } from '@sylphx/sdk'
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const sylphx = createServerClient(process.env.SYLPHX_URL!)
+  const apiUrl = sylphx.baseUrl.replace(/\/v[0-9]+$/, '')
+
   const config = await getAppConfig({
-    secretKey: process.env.SYLPHX_SECRET_KEY!,
+    secretKey: sylphx.secretKey!,
     appId: process.env.NEXT_PUBLIC_SYLPHX_APP_ID!,
+    platformUrl: apiUrl,
   })
 
   return (
@@ -86,6 +93,7 @@ export default async function RootLayout({ children }: { children: React.ReactNo
         <SylphxProvider
           config={config}
           appId={process.env.NEXT_PUBLIC_SYLPHX_APP_ID!}
+          platformUrl={apiUrl}
         >
           {children}
         </SylphxProvider>
@@ -159,19 +167,15 @@ const userId = await currentUserId()
 ### Server API Client
 
 ```ts
-import { createServerClient } from '@sylphx/sdk/server'
+import { createServerClient, getPlans, track } from '@sylphx/sdk'
 
-const client = createServerClient({
-  secretKey: process.env.SYLPHX_SECRET_KEY!,
-})
+const sylphx = createServerClient(process.env.SYLPHX_URL!)
 
-// GET /billing/plans
-const plans = await client.GET('/billing/plans')
+// Billing
+const plans = await getPlans(sylphx)
 
-// POST /analytics/track
-await client.POST('/analytics/track', {
-  body: { events: [{ event: 'purchase', properties: { amount: 99 } }] },
-})
+// Analytics
+await track(sylphx, { event: 'purchase', properties: { amount: 99 } })
 ```
 
 ### Prefetch App Config
@@ -183,10 +187,14 @@ import {
   getFeatureFlags, // Feature flag definitions
   getConsentTypes, // GDPR consent config
 } from '@sylphx/sdk/server'
+import { createServerClient } from '@sylphx/sdk'
+
+const sylphx = createServerClient(process.env.SYLPHX_URL!)
 
 const config = await getAppConfig({
-  secretKey: process.env.SYLPHX_SECRET_KEY!,
+  secretKey: sylphx.secretKey!,
   appId: process.env.NEXT_PUBLIC_SYLPHX_APP_ID!,
+  platformUrl: sylphx.baseUrl.replace(/\/v[0-9]+$/, ''),
 })
 // config.plans, config.featureFlags, config.oauthProviders, config.consentTypes
 ```
@@ -368,9 +376,9 @@ import { Protect } from '@sylphx/sdk/react'
 For non-React environments or maximum control:
 
 ```ts
-import { createConfig, signIn, track, getPlans } from '@sylphx/sdk'
+import { createClient, signIn, track, getPlans } from '@sylphx/sdk'
 
-const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY! })
+const config = createClient(process.env.SYLPHX_URL!)
 
 // Auth
 const tokens = await signIn(config, { email, password })
@@ -393,6 +401,31 @@ const plans = await getPlans(config)
 | `@sylphx/sdk/react` | React hooks, components, `SylphxProvider` |
 | `@sylphx/sdk/server` | JWT verification, webhook verification, server client |
 | `@sylphx/sdk/nextjs` | `createSylphxMiddleware`, `auth()`, `currentUser()` |
+| `@sylphx/sdk/web-analytics` | Standalone web-analytics tracker (rrweb + web-vitals) |
+| `@sylphx/sdk/health` | Multi-signal health score for the `sylphx-health-agent` sidecar (ADR-111 Phase B) |
+
+### `@sylphx/sdk/health` — Phase B health score (ADR-111)
+
+Apps register signals (event-loop lag, queue depth, error rate, memory pressure)
+and the SDK folds them into a continuous score in `[0, 1]`. The
+`sylphx-health-agent` sidecar polls the score and decides liveness /
+readiness / drain via the three-tier gate. See
+[`src/health/README.md`](./src/health/README.md) for the full guide.
+
+```ts
+import { sylphxHealth, eventLoopLagSignal, queueDepthSignal } from '@sylphx/sdk/health'
+
+const health = sylphxHealth({
+  signals: [
+    eventLoopLagSignal({ degradedMs: 5000, deadMs: 30000 }),
+    queueDepthSignal({ getter: () => queue.size, fullThreshold: 1000 }),
+  ],
+})
+
+app.get('/healthz', health.handler())
+// Or — Unix-socket transport for the sidecar:
+health.serveUnixSocket() // → /var/run/sylphx/health.sock
+```
 
 ---
 
@@ -415,18 +448,18 @@ If you're running your own Sylphx Platform deployment, configure the base URL vi
 SYLPHX_API_URL=https://platform.your-domain.com sylphx deploy
 ```
 
-Or in the SDK via `projectRef`:
+Or in the SDK via an explicit custom-domain connection URL:
 
 ```ts
-import { createConfig } from '@sylphx/sdk'
-const config = createConfig({
-  secretKey: process.env.SYLPHX_SECRET_KEY!,
-  projectRef: 'your-project-ref',  // from Platform console
-})
+import { createServerClient } from '@sylphx/sdk'
+
+const config = createServerClient(
+  'sylphx://sk_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@acme.api.example.com',
+)
 ```
 
-> **Note:** `SYLPHX_PLATFORM_URL` has been removed (was deprecated). Use `projectRef` instead.
-> If using hosted Sylphx at [sylphx.com](https://sylphx.com), no additional config is needed.
+> **Note:** hosted Sylphx uses `<tenant-slug>.api.sylphx.com`. Only use a custom
+> host for self-hosted deployments or a documented legacy migration.
 
 ---
 

package/dist/health/index.mjs

@@ -0,0 +1,475 @@
+// src/health/effects.ts
+import { Effect } from "effect";
+
+// src/health/types.ts
+var HealthError = class extends Error {
+  _tag = "HealthError";
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "HealthError";
+    this.cause = cause;
+  }
+};
+
+// src/health/effects.ts
+function evaluateEffect(evaluator) {
+  return Effect.tryPromise({
+    try: () => evaluator(),
+    catch: (err) => new HealthError("health evaluation failed", err)
+  });
+}
+
+// src/health/handler.ts
+function createWebHandler(source) {
+  return async (_req) => {
+    try {
+      const score = await source.evaluate();
+      return new Response(JSON.stringify(score), {
+        status: 200,
+        headers: {
+          "Content-Type": "application/json",
+          // Cache-Control: never cache. Even 1-second cache on a
+          // CDN edge would mask a fast-moving health collapse.
+          "Cache-Control": "no-store, no-cache, must-revalidate"
+        }
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return new Response(
+        JSON.stringify({
+          error: "health_evaluator_failed",
+          message
+        }),
+        {
+          status: 500,
+          headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "no-store, no-cache, must-revalidate"
+          }
+        }
+      );
+    }
+  };
+}
+function createNodeHandler(source) {
+  return async (_req, res) => {
+    try {
+      const score = await source.evaluate();
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "application/json");
+      res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
+      res.end(JSON.stringify(score));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "application/json");
+      res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
+      res.end(JSON.stringify({ error: "health_evaluator_failed", message }));
+    }
+  };
+}
+
+// src/health/scoring.ts
+function clamp01(x) {
+  if (!Number.isFinite(x)) return 0;
+  if (x < 0) return 0;
+  if (x > 1) return 1;
+  return x;
+}
+var weightedProduct = (readings) => {
+  if (readings.length === 0) return 1;
+  const active = [];
+  for (const { signal, reading } of readings) {
+    const w = signal.weight;
+    if (!Number.isFinite(w) || w <= 0) continue;
+    if (reading.unknown === true) continue;
+    active.push({
+      factor: clamp01(reading.healthFactor),
+      weight: w
+    });
+  }
+  if (active.length === 0) return 1;
+  const totalWeight = active.reduce((sum, a) => sum + a.weight, 0);
+  if (totalWeight <= 0 || !Number.isFinite(totalWeight)) return 1;
+  let logSum = 0;
+  for (const { factor, weight } of active) {
+    const normalisedWeight = weight / totalWeight;
+    if (factor <= 0) {
+      return 0;
+    }
+    logSum += normalisedWeight * Math.log(factor);
+  }
+  const score = Math.exp(logSum);
+  return clamp01(score);
+};
+function defaultScoringStrategy() {
+  return weightedProduct;
+}
+
+// src/health/signals/event-loop-lag.ts
+import { monitorEventLoopDelay } from "perf_hooks";
+function eventLoopLagSignal(opts = {}) {
+  const degradedMs = opts.degradedMs ?? 5e3;
+  const deadMs = opts.deadMs ?? 3e4;
+  const resolutionMs = opts.resolutionMs ?? 10;
+  const weight = opts.weight ?? 0.4;
+  if (!Number.isFinite(degradedMs) || degradedMs < 0) {
+    throw new Error(`eventLoopLagSignal: degradedMs must be >= 0, got ${degradedMs}`);
+  }
+  if (!Number.isFinite(deadMs) || deadMs <= degradedMs) {
+    throw new Error(
+      `eventLoopLagSignal: deadMs must be > degradedMs (${degradedMs}), got ${deadMs}`
+    );
+  }
+  if (!Number.isFinite(resolutionMs) || resolutionMs < 1) {
+    throw new Error(`eventLoopLagSignal: resolutionMs must be >= 1, got ${resolutionMs}`);
+  }
+  const monitor = opts.monitor ?? monitorEventLoopDelay({ resolution: resolutionMs });
+  monitor.enable();
+  return {
+    name: "eventLoopLagMs",
+    weight,
+    read() {
+      const maxNs = monitor.max;
+      if (!Number.isFinite(maxNs) || maxNs <= 0 || maxNs >= Number.MAX_SAFE_INTEGER) {
+        monitor.reset();
+        return { value: 0, healthFactor: 1, unknown: true };
+      }
+      const observedMs = maxNs / 1e6;
+      monitor.reset();
+      let factor;
+      if (observedMs <= degradedMs) factor = 1;
+      else if (observedMs >= deadMs) factor = 0;
+      else {
+        const span = deadMs - degradedMs;
+        factor = 1 - (observedMs - degradedMs) / span;
+      }
+      return {
+        value: Math.round(observedMs),
+        healthFactor: factor
+      };
+    },
+    dispose() {
+      monitor.disable();
+    }
+  };
+}
+
+// src/health/unix-socket-server.ts
+import { unlinkSync } from "fs";
+function startUnixSocketServer(source, opts = {}) {
+  const bun = opts.bunRuntime !== void 0 ? opts.bunRuntime : globalThis.Bun;
+  if (bun === null || bun === void 0 || typeof bun.serve !== "function") {
+    throw new Error(
+      "startUnixSocketServer: Bun.serve is unavailable \u2014 Unix-socket transport requires a Bun runtime"
+    );
+  }
+  const path = opts.path ?? "/var/run/sylphx/health.sock";
+  const unlinkOnShutdown = opts.unlinkOnShutdown ?? true;
+  try {
+    unlinkSync(path);
+  } catch {
+  }
+  const handler = createWebHandler(source);
+  const server = bun.serve({
+    unix: path,
+    fetch: async (req) => handler(req)
+  });
+  const handle = {
+    path,
+    server,
+    async shutdown() {
+      try {
+        server.stop(true);
+      } catch {
+      }
+      if (unlinkOnShutdown) {
+        try {
+          unlinkSync(path);
+        } catch {
+        }
+      }
+    }
+  };
+  return handle;
+}
+
+// src/health/signals/error-rate.ts
+function parseWindow(w) {
+  if (typeof w === "number") {
+    if (!Number.isFinite(w) || w <= 0) {
+      throw new Error(`errorRateSignal: window must be > 0, got ${w}`);
+    }
+    return w;
+  }
+  const m = /^(\d+)(s|m)$/.exec(w);
+  if (m === null) {
+    throw new Error(`errorRateSignal: invalid window '${w}', expected '5s' / '1m' / number`);
+  }
+  const n = Number.parseInt(m[1], 10);
+  const unit = m[2];
+  const ms = unit === "s" ? n * 1e3 : n * 6e4;
+  if (ms <= 0) {
+    throw new Error(`errorRateSignal: parsed window ${ms}ms must be > 0`);
+  }
+  return ms;
+}
+function errorRateSignal(opts) {
+  const windowMs = parseWindow(opts.window);
+  const degradedRate = opts.degradedRate ?? 0.05;
+  const deadRate = opts.deadRate ?? 0.5;
+  const minSamples = opts.minSamples ?? 10;
+  const weight = opts.weight ?? 0.2;
+  const now = opts.now ?? Date.now;
+  if (degradedRate < 0 || degradedRate > 1) {
+    throw new Error(`errorRateSignal: degradedRate must be in [0, 1], got ${degradedRate}`);
+  }
+  if (deadRate <= degradedRate || deadRate > 1) {
+    throw new Error(`errorRateSignal: deadRate must be in (degradedRate, 1], got ${deadRate}`);
+  }
+  if (!Number.isFinite(minSamples) || minSamples < 1) {
+    throw new Error(`errorRateSignal: minSamples must be >= 1, got ${minSamples}`);
+  }
+  const samples = [];
+  function pruneExpired(t) {
+    const cutoff = t - windowMs;
+    while (samples.length > 0 && samples[0].t < cutoff) {
+      samples.shift();
+    }
+  }
+  return {
+    name: `recent${Math.round(windowMs / 1e3)}sErrorRate`,
+    weight,
+    recordSuccess() {
+      samples.push({ t: now(), e: false });
+    },
+    recordError() {
+      samples.push({ t: now(), e: true });
+    },
+    reset() {
+      samples.length = 0;
+    },
+    read() {
+      const t = now();
+      pruneExpired(t);
+      if (samples.length === 0 || samples.length < minSamples) {
+        return { value: 0, healthFactor: 1 };
+      }
+      let errors = 0;
+      for (const s of samples) {
+        if (s.e) errors++;
+      }
+      const rate = errors / samples.length;
+      let factor;
+      if (rate <= degradedRate) factor = 1;
+      else if (rate >= deadRate) factor = 0;
+      else {
+        const span = deadRate - degradedRate;
+        factor = 1 - (rate - degradedRate) / span;
+      }
+      const valueRounded = Math.round(rate * 1e4) / 1e4;
+      return {
+        value: valueRounded,
+        healthFactor: factor
+      };
+    }
+  };
+}
+
+// src/health/signals/memory-pressure.ts
+import { readFileSync } from "fs";
+var CGROUP_V1_UNLIMITED_FLOOR = 1e18;
+function tryRead(reader, path) {
+  try {
+    return reader(path);
+  } catch {
+    return null;
+  }
+}
+function readContainerMemoryLimit(reader, v2Path, v1Path) {
+  const v2 = tryRead(reader, v2Path);
+  if (v2 !== null) {
+    const trimmed2 = v2.trim();
+    if (trimmed2 === "max" || trimmed2 === "") return null;
+    const n2 = Number.parseInt(trimmed2, 10);
+    if (!Number.isFinite(n2) || n2 <= 0) return null;
+    if (n2 > CGROUP_V1_UNLIMITED_FLOOR) return null;
+    return n2;
+  }
+  const v1 = tryRead(reader, v1Path);
+  if (v1 === null) return null;
+  const trimmed = v1.trim();
+  const n = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  if (n > CGROUP_V1_UNLIMITED_FLOOR) return null;
+  return n;
+}
+function memoryPressureSignal(opts = {}) {
+  const degradedRatio = opts.degradedRatio ?? 0.85;
+  const deadRatio = opts.deadRatio ?? 0.95;
+  const v2Path = opts.cgroupV2Path ?? "/sys/fs/cgroup/memory.max";
+  const v1Path = opts.cgroupV1Path ?? "/sys/fs/cgroup/memory/memory.limit_in_bytes";
+  const weight = opts.weight ?? 0.2;
+  const memoryUsage = opts.memoryUsage ?? (() => {
+    const m = process.memoryUsage();
+    return { rss: m.rss };
+  });
+  const readFile = opts.readFile ?? ((p) => readFileSync(p, "utf8"));
+  if (degradedRatio <= 0 || degradedRatio >= 1) {
+    throw new Error(`memoryPressureSignal: degradedRatio must be in (0, 1), got ${degradedRatio}`);
+  }
+  if (deadRatio <= degradedRatio || deadRatio > 1) {
+    throw new Error(
+      `memoryPressureSignal: deadRatio must be in (degradedRatio, 1], got ${deadRatio}`
+    );
+  }
+  let cachedLimit;
+  function getLimit() {
+    if (cachedLimit === void 0) {
+      cachedLimit = readContainerMemoryLimit(readFile, v2Path, v1Path);
+    }
+    return cachedLimit;
+  }
+  return {
+    name: "memoryPressure",
+    weight,
+    read() {
+      const limit = getLimit();
+      if (limit === null) {
+        return { value: 0, healthFactor: 1, unknown: true };
+      }
+      let rss;
+      try {
+        rss = memoryUsage().rss;
+      } catch {
+        return { value: 0, healthFactor: 1, unknown: true };
+      }
+      if (!Number.isFinite(rss) || rss < 0) {
+        return { value: 0, healthFactor: 1, unknown: true };
+      }
+      const ratio = rss / limit;
+      let factor;
+      if (ratio <= degradedRatio) factor = 1;
+      else if (ratio >= deadRatio) factor = 0;
+      else {
+        const span = deadRatio - degradedRatio;
+        factor = 1 - (ratio - degradedRatio) / span;
+      }
+      const valueRounded = Math.round(ratio * 1e3) / 1e3;
+      return { value: valueRounded, healthFactor: factor };
+    }
+  };
+}
+
+// src/health/signals/queue-depth.ts
+function queueDepthSignal(opts) {
+  if (typeof opts.getter !== "function") {
+    throw new Error("queueDepthSignal: getter must be a function");
+  }
+  if (!Number.isFinite(opts.fullThreshold) || opts.fullThreshold <= 0) {
+    throw new Error(`queueDepthSignal: fullThreshold must be > 0, got ${opts.fullThreshold}`);
+  }
+  const healthyBelow = opts.healthyBelow ?? 0;
+  if (!Number.isFinite(healthyBelow) || healthyBelow < 0 || healthyBelow >= opts.fullThreshold) {
+    throw new Error(
+      `queueDepthSignal: healthyBelow must be in [0, fullThreshold), got ${healthyBelow}`
+    );
+  }
+  const weight = opts.weight ?? 0.2;
+  return {
+    name: opts.name ?? "queueDepth",
+    weight,
+    async read() {
+      let raw;
+      try {
+        raw = await opts.getter();
+      } catch {
+        return { value: 0, healthFactor: 1, unknown: true };
+      }
+      if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
+        return { value: 0, healthFactor: 1, unknown: true };
+      }
+      const depth = raw;
+      let factor;
+      if (depth <= healthyBelow) factor = 1;
+      else if (depth >= opts.fullThreshold) factor = 0;
+      else {
+        const span = opts.fullThreshold - healthyBelow;
+        factor = 1 - (depth - healthyBelow) / span;
+      }
+      return {
+        value: depth,
+        healthFactor: factor
+      };
+    }
+  };
+}
+
+// src/health/index.ts
+function sylphxHealth(opts = {}) {
+  const signals = opts.signals && opts.signals.length > 0 ? [...opts.signals] : [eventLoopLagSignal({ degradedMs: 5e3, deadMs: 3e4, weight: 1 })];
+  const scoringStrategy = opts.scoringStrategy ?? defaultScoringStrategy();
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  let disposed = false;
+  const evaluate = async () => {
+    if (disposed) {
+      throw new Error("sylphxHealth: instance disposed");
+    }
+    const readings = await Promise.all(
+      signals.map(async (signal) => ({
+        signal,
+        reading: await signal.read()
+      }))
+    );
+    const score = scoringStrategy(readings);
+    const signalsMap = {};
+    for (const { signal, reading } of readings) {
+      signalsMap[signal.name] = reading.value;
+    }
+    return {
+      score,
+      signals: signalsMap,
+      lastTickAt: now().toISOString()
+    };
+  };
+  const evaluator = { evaluate };
+  const evaluateEffect2 = evaluateEffect(evaluate);
+  return {
+    signals,
+    evaluate,
+    evaluateEffect: evaluateEffect2,
+    handler() {
+      return createWebHandler(evaluator);
+    },
+    nodeHandler() {
+      return createNodeHandler(evaluator);
+    },
+    serveUnixSocket(unixOpts) {
+      return startUnixSocketServer(evaluator, unixOpts);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const s of signals) {
+        try {
+          s.dispose?.();
+        } catch {
+        }
+      }
+    }
+  };
+}
+export {
+  HealthError,
+  createNodeHandler,
+  createWebHandler,
+  defaultScoringStrategy,
+  errorRateSignal,
+  eventLoopLagSignal,
+  memoryPressureSignal,
+  queueDepthSignal,
+  sylphxHealth,
+  weightedProduct
+};
+//# sourceMappingURL=index.mjs.map