@elvix.is/sdk 0.3.2 → 0.5.0

package/README.md

@@ -126,7 +126,7 @@ elvix ships first-class agent support. Three surfaces:
      "mcpServers": {
        "elvix": {
          "command": "npx",
-         "args": ["-y", "-p", "@elvix.is/sdk", "elvix-mcp"],
+         "args": ["-y", "-p", "@elvix.is/sdk", "elvix", "mcp"],
          "env": { "ELVIX_API_KEY": "eak_..." }
        }
      }
@@ -135,6 +135,20 @@ elvix ships first-class agent support. Three surfaces:
 
    Read-only by default. `--admin` opts in to mutation tools. Never logs the bearer token.
 
+## CLI
+
+The package ships an `elvix` command:
+
+```bash
+# Diagnose an integration — base URL, clientId, verify endpoint, API key.
+ELVIX_CLIENT_ID=client_… npx -p @elvix.is/sdk elvix doctor
+
+# Launch the MCP server on stdio.
+ELVIX_API_KEY=eak_… npx -p @elvix.is/sdk elvix mcp
+```
+
+`elvix doctor` prints a green/red checklist so "why isn't elvix working" is a two-second answer. (`elvix-mcp` is kept as an alias for `elvix mcp`.)
+
 Full agent guide: <https://elvix.is/docs/agents>
 
 ## Components

package/dist/cli/doctor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `elvix doctor` — diagnose an elvix integration from the terminal.
+ *
+ * Runs a green/red checklist so a developer (or their agent) can
+ * answer "why isn't elvix working" in two seconds instead of a support
+ * email. Read-only; never mutates anything.
+ *
+ * Checks:
+ *   - base URL reachable (GET /llms.txt)
+ *   - clientId resolves (GET /api/v1/bootstrap/<clientId> → 200)
+ *   - verify endpoint live (POST /api/v1/verify with a dummy token → 401)
+ *   - ELVIX_API_KEY present (informational)
+ *
+ * Inputs (env or flags):
+ *   ELVIX_BASE_URL    default https://elvix.is        (--base-url=)
+ *   ELVIX_CLIENT_ID   the app's public clientId       (--client-id=)
+ *   ELVIX_API_KEY     server API key (presence only)
+ */
+declare function runDoctor(): Promise<number>;
+
+export { runDoctor };

package/dist/cli/doctor.js

@@ -0,0 +1,78 @@
+// src/cli/doctor.ts
+var DEFAULT_BASE_URL = "https://elvix.is";
+function flag(name) {
+  const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+  return hit?.split("=").slice(1).join("=");
+}
+async function timed(fn, timeoutMs = 8e3) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    return await fn();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+async function runDoctor() {
+  const baseUrl = flag("base-url") ?? process.env.ELVIX_BASE_URL ?? DEFAULT_BASE_URL;
+  const clientId = flag("client-id") ?? process.env.ELVIX_CLIENT_ID;
+  const apiKey = process.env.ELVIX_API_KEY;
+  const checks = [];
+  const llms = await timed(() => fetch(`${baseUrl}/llms.txt`));
+  checks.push({
+    label: `Base URL reachable (${baseUrl})`,
+    ok: Boolean(llms?.ok),
+    detail: llms ? `HTTP ${llms.status}` : "no response / timeout"
+  });
+  if (clientId) {
+    const boot = await timed(
+      () => fetch(`${baseUrl}/api/v1/bootstrap/${encodeURIComponent(clientId)}`)
+    );
+    checks.push({
+      label: `clientId resolves (${clientId})`,
+      ok: Boolean(boot?.ok),
+      detail: boot ? boot.ok ? `HTTP ${boot.status}` : `HTTP ${boot.status} \u2014 wrong clientId, or app is draft/deleted` : "no response / timeout"
+    });
+  } else {
+    checks.push({
+      label: "clientId resolves",
+      ok: false,
+      detail: "skipped \u2014 pass --client-id=<id> or set ELVIX_CLIENT_ID"
+    });
+  }
+  const verify = await timed(
+    () => fetch(`${baseUrl}/api/v1/verify`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ token: "doctor-probe" })
+    })
+  );
+  checks.push({
+    label: "Verify endpoint live (POST /api/v1/verify)",
+    ok: verify?.status === 401,
+    detail: verify ? `HTTP ${verify.status} (401 expected)` : "no response / timeout"
+  });
+  checks.push({
+    label: "ELVIX_API_KEY present",
+    ok: Boolean(apiKey),
+    detail: apiKey ? `set (${apiKey.slice(0, 8)}\u2026)` : "not set \u2014 server-side verify will fail"
+  });
+  let criticalFail = false;
+  process.stdout.write("\nelvix doctor\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+  for (const c of checks) {
+    const mark = c.ok ? "\u2713" : "\u2717";
+    process.stdout.write(`  ${mark}  ${c.label}
+       ${c.detail}
+`);
+  }
+  if (!checks[0]?.ok || !checks[2]?.ok) criticalFail = true;
+  process.stdout.write(
+    criticalFail ? "\nResult: elvix is NOT reachable from here. Check network / base URL.\n" : "\nResult: elvix is reachable. Warnings above (if any) are config hints.\n"
+  );
+  return criticalFail ? 1 : 0;
+}
+export {
+  runDoctor
+};

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+var HELP = `elvix \u2014 @elvix.is/sdk CLI
+
+Usage:
+  elvix mcp [--admin] [--base-url=<url>]
+      Launch the elvix MCP server on stdio. Reads ELVIX_API_KEY from
+      the environment. Read-only by default; --admin enables mutation
+      tools (the server still enforces the admin scope on the key).
+
+  elvix doctor [--client-id=<id>] [--base-url=<url>]
+      Diagnose an integration: base URL reachability, clientId
+      resolution, verify-endpoint liveness, API-key presence.
+      Reads ELVIX_CLIENT_ID / ELVIX_API_KEY / ELVIX_BASE_URL.
+
+  elvix help
+      Show this message.
+
+Docs: https://elvix.is/docs/agents`;
+async function main() {
+  const sub = process.argv[2];
+  switch (sub) {
+    case "mcp": {
+      const { createElvixMcpServer } = await import("../mcp/index.js");
+      const apiKey = process.env.ELVIX_API_KEY;
+      if (!apiKey) {
+        process.stderr.write("ELVIX_API_KEY environment variable is required.\n");
+        process.exit(1);
+      }
+      const admin = process.argv.includes("--admin");
+      const baseUrl = process.argv.find((a) => a.startsWith("--base-url="))?.split("=")[1];
+      const { connectStdio } = await createElvixMcpServer({ apiKey, readonly: !admin, baseUrl });
+      await connectStdio();
+      return;
+    }
+    case "doctor": {
+      const { runDoctor } = await import("./doctor.js");
+      process.exit(await runDoctor());
+      break;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+    case void 0:
+      process.stdout.write(`${HELP}
+`);
+      return;
+    default:
+      process.stderr.write(`Unknown command: ${sub}
+
+${HELP}
+`);
+      process.exit(1);
+  }
+}
+main().catch((e) => {
+  process.stderr.write(`elvix: ${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(1);
+});

package/dist/react.d.ts

@@ -67,6 +67,12 @@ type ElvixSignInResultOk = {
     redirect?: string;
     /** Sign-in factor that succeeded. */
     method: ElvixSignInMethod;
+    /**
+     * Cross-origin only: the session token. Pass it to your backend and verify
+     * it with `verifyElvixToken` from `@elvix.is/sdk/server`. Undefined for
+     * same-origin sign-in (the session rides a cookie instead).
+     */
+    token?: string;
 };
 type ElvixSignInResultErr = {
     ok: false;
@@ -120,6 +126,48 @@ declare function ElvixSignIn({ onResult, redirectAfterSignIn, className, }: {
     className?: string;
 }): react.JSX.Element;
 
+/**
+ * Session token store for cross-origin SDK use.
+ *
+ * When the SDK runs on a customer app's own origin it can't use elvix's
+ * session cookie (third-party cookies are blocked), so sign-in returns a
+ * token that every subsequent call carries as `Authorization: Bearer`.
+ * `<ElvixSignIn>` stores it here; `appPost/appPatch/appDelete` and the live
+ * hooks attach it. Same-origin hosts never store a token, so these are no-ops
+ * and the cookie path is used unchanged.
+ */
+/** Current session token (memory first, then localStorage), or null. */
+declare function getElvixToken(): string | null;
+/** Store (or clear with null) the session token. Persists to localStorage. */
+declare function setElvixToken(token: string | null): void;
+
+type UseUserListResult = {
+    slugs: string[];
+    loading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+};
+type Opts = {
+    applicationId: string;
+    userId: string;
+    /** elvix origin. Defaults to "" (same-origin). */
+    baseUrl?: string;
+    /** Poll interval in ms. Default 7000. */
+    pollMs?: number;
+};
+declare const useUserRoles: (opts: Opts) => UseUserListResult;
+declare const useUserScopes: (opts: Opts) => UseUserListResult;
+declare const useUserMemberships: (opts: Opts) => UseUserListResult;
+
+declare function ElvixLifecycleWatcher({ baseUrl, pollMs, onSignedOut, }: {
+    /** elvix origin. Defaults to "" (same-origin). */
+    baseUrl?: string;
+    /** Poll interval in ms. Default 7000. */
+    pollMs?: number;
+    /** Called once with the reason when the session ends. Defaults to a reload. */
+    onSignedOut?: (reason: string) => void;
+}): null;
+
 /**
  * `<ElvixUsername>` — claim or change the end-user's username for the
  * current Application. PATCH /api/account/apps/<appId>/username.
@@ -232,4 +280,4 @@ declare function ElvixLegalEntities({ onResult, }: {
     onResult?: (r: ElvixActionResult) => void;
 }): react.JSX.Element;
 
-export { ElvixActionResult, ElvixAddressBook, ElvixAvatar, ElvixBanner, type ElvixBootstrapEnvelope, type ElvixBrand, ElvixCard, ElvixDeactivate, ElvixExport, ElvixIdentityForm, ElvixLanguages, ElvixLeave, ElvixLegalEntities, ElvixProvider, ElvixRegion, ElvixSessions, ElvixSignIn, type ElvixSignInMethod, type ElvixSignInResult, type ElvixSignInResultErr, type ElvixSignInResultOk, type ElvixTheme, ElvixUsername, useElvixApp, useElvixContext };
+export { ElvixActionResult, ElvixAddressBook, ElvixAvatar, ElvixBanner, type ElvixBootstrapEnvelope, type ElvixBrand, ElvixCard, ElvixDeactivate, ElvixExport, ElvixIdentityForm, ElvixLanguages, ElvixLeave, ElvixLegalEntities, ElvixLifecycleWatcher, ElvixProvider, ElvixRegion, ElvixSessions, ElvixSignIn, type ElvixSignInMethod, type ElvixSignInResult, type ElvixSignInResultErr, type ElvixSignInResultOk, type ElvixTheme, ElvixUsername, type UseUserListResult, getElvixToken, setElvixToken, useElvixApp, useElvixContext, useUserMemberships, useUserRoles, useUserScopes };

package/dist/react.js

@@ -166,6 +166,35 @@ function withAlpha(hex, a) {
 
 // src/react/elvix-sign-in.tsx
 import { useState as useState2 } from "react";
+
+// src/react/session.ts
+var STORAGE_KEY = "elvix.session.token";
+var memToken = null;
+function getElvixToken() {
+  if (memToken) return memToken;
+  if (typeof window !== "undefined") {
+    try {
+      memToken = window.localStorage.getItem(STORAGE_KEY);
+    } catch {
+    }
+  }
+  return memToken;
+}
+function setElvixToken(token) {
+  memToken = token;
+  if (typeof window === "undefined") return;
+  try {
+    if (token) window.localStorage.setItem(STORAGE_KEY, token);
+    else window.localStorage.removeItem(STORAGE_KEY);
+  } catch {
+  }
+}
+function authInit() {
+  const token = getElvixToken();
+  return token ? { headers: { authorization: `Bearer ${token}` }, credentials: "omit" } : { headers: {}, credentials: "include" };
+}
+
+// src/react/elvix-sign-in.tsx
 function ElvixSignIn({
   onResult,
   redirectAfterSignIn,
@@ -235,11 +264,13 @@ function ElvixSignIn({
       if (!res.ok || !body.success) {
         return fail(body.errorMessage ?? "otp_verify_failed");
       }
+      if (body.data?.token) setElvixToken(body.data.token);
       setStep("done");
       onResult?.({
         ok: true,
         method: "email_otp",
-        redirect: body.data?.redirect ?? redirectAfterSignIn
+        redirect: body.data?.redirect ?? redirectAfterSignIn,
+        token: body.data?.token
       });
     } catch (e2) {
       fail("network", e2 instanceof Error ? e2.message : void 0);
@@ -289,16 +320,90 @@ function ElvixSignIn({
   ), /* @__PURE__ */ React.createElement("button", { type: "submit", disabled: busy, className: "elvix-btn elvix-btn-primary" }, busy ? "Verifying\u2026" : verb)), error && /* @__PURE__ */ React.createElement("p", { role: "alert", className: "elvix-error" }, error));
 }
 
+// src/react/hooks.ts
+import { useCallback, useEffect as useEffect2, useState as useState3 } from "react";
+var POLL_MS = 7e3;
+function useUserList(kind, opts) {
+  const { applicationId, baseUrl = "", pollMs = POLL_MS } = opts;
+  const [slugs, setSlugs] = useState3([]);
+  const [loading, setLoading] = useState3(true);
+  const [error, setError] = useState3(null);
+  const refresh = useCallback(async () => {
+    setError(null);
+    try {
+      const res = await fetch(
+        `${baseUrl}/api/me/${kind}?applicationId=${encodeURIComponent(applicationId)}`,
+        authInit()
+      );
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok || json.success === false) {
+        setError(json.errorMessage ?? `http_${res.status}`);
+        return;
+      }
+      setSlugs(json.data?.slugs ?? []);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "network");
+    } finally {
+      setLoading(false);
+    }
+  }, [applicationId, baseUrl, kind]);
+  useEffect2(() => {
+    refresh();
+    const id = setInterval(refresh, pollMs);
+    return () => clearInterval(id);
+  }, [refresh, pollMs]);
+  return { slugs, loading, error, refresh };
+}
+var useUserRoles = (opts) => useUserList("roles", opts);
+var useUserScopes = (opts) => useUserList("scopes", opts);
+var useUserMemberships = (opts) => useUserList("memberships", opts);
+
+// src/react/lifecycle-watcher.tsx
+import { useEffect as useEffect3 } from "react";
+function ElvixLifecycleWatcher({
+  baseUrl = "",
+  pollMs = 7e3,
+  onSignedOut
+}) {
+  useEffect3(() => {
+    let cancelled = false;
+    let fired = false;
+    const poll = async () => {
+      try {
+        const res = await fetch(`${baseUrl}/api/v1/session`, { method: "POST", ...authInit() });
+        const body = await res.json().catch(() => ({}));
+        if (cancelled || fired) return;
+        if (!body.ok) {
+          fired = true;
+          setElvixToken(null);
+          const reason = body.error ?? "signed_out";
+          if (onSignedOut) onSignedOut(reason);
+          else if (typeof window !== "undefined") window.location.reload();
+        }
+      } catch {
+      }
+    };
+    void poll();
+    const id = setInterval(poll, pollMs);
+    return () => {
+      cancelled = true;
+      clearInterval(id);
+    };
+  }, [baseUrl, pollMs, onSignedOut]);
+  return null;
+}
+
 // src/react/elvix-username.tsx
-import { useState as useState3 } from "react";
+import { useState as useState4 } from "react";
 
 // src/react/lib.ts
 async function appPost(opts, path, body) {
   try {
+    const auth = authInit();
     const res = await fetch(`${opts.baseUrl}/api/account/apps/${opts.applicationId}${path}`, {
       method: "POST",
-      headers: { "content-type": "application/json" },
-      credentials: "include",
+      headers: { "content-type": "application/json", ...auth.headers },
+      credentials: auth.credentials,
       body: JSON.stringify(body)
     });
     const json = await res.json();
@@ -312,10 +417,11 @@ async function appPost(opts, path, body) {
 }
 async function appPatch(opts, path, body) {
   try {
+    const auth = authInit();
     const res = await fetch(`${opts.baseUrl}/api/account/apps/${opts.applicationId}${path}`, {
       method: "PATCH",
-      headers: { "content-type": "application/json" },
-      credentials: "include",
+      headers: { "content-type": "application/json", ...auth.headers },
+      credentials: auth.credentials,
       body: JSON.stringify(body)
     });
     const json = await res.json();
@@ -329,9 +435,11 @@ async function appPatch(opts, path, body) {
 }
 async function appDelete(opts, path) {
   try {
+    const auth = authInit();
     const res = await fetch(`${opts.baseUrl}/api/account/apps/${opts.applicationId}${path}`, {
       method: "DELETE",
-      credentials: "include"
+      headers: { ...auth.headers },
+      credentials: auth.credentials
     });
     const json = await res.json().catch(() => ({}));
     if (!res.ok || json.success !== void 0 && !json.success) {
@@ -348,10 +456,10 @@ function ElvixUsername({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [value, setValue] = useState3("");
-  const [busy, setBusy] = useState3(false);
-  const [error, setError] = useState3(null);
-  const [done, setDone] = useState3(null);
+  const [value, setValue] = useState4("");
+  const [busy, setBusy] = useState4(false);
+  const [error, setError] = useState4(null);
+  const [done, setDone] = useState4(null);
   async function submit(e) {
     e.preventDefault();
     if (!ctx.app) return;
@@ -389,14 +497,14 @@ function ElvixUsername({
 }
 
 // src/react/elvix-avatar.tsx
-import { useState as useState4 } from "react";
+import { useState as useState5 } from "react";
 function ElvixAvatar({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [busy, setBusy] = useState4(false);
-  const [error, setError] = useState4(null);
-  const [preview, setPreview] = useState4(null);
+  const [busy, setBusy] = useState5(false);
+  const [error, setError] = useState5(null);
+  const [preview, setPreview] = useState5(null);
   async function onFile(e) {
     const file = e.target.files?.[0];
     if (!file || !ctx.app) return;
@@ -430,14 +538,14 @@ function ElvixAvatar({
 }
 
 // src/react/elvix-banner.tsx
-import { useState as useState5 } from "react";
+import { useState as useState6 } from "react";
 function ElvixBanner({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [busy, setBusy] = useState5(false);
-  const [error, setError] = useState5(null);
-  const [preview, setPreview] = useState5(null);
+  const [busy, setBusy] = useState6(false);
+  const [error, setError] = useState6(null);
+  const [preview, setPreview] = useState6(null);
   async function onFile(e) {
     const file = e.target.files?.[0];
     if (!file || !ctx.app) return;
@@ -471,18 +579,18 @@ function ElvixBanner({
 }
 
 // src/react/elvix-identity-form.tsx
-import { useState as useState6 } from "react";
+import { useState as useState7 } from "react";
 function ElvixIdentityForm({
   initialName = "",
   initialBio = "",
   onResult
 }) {
   const ctx = useElvixContext();
-  const [name, setName] = useState6(initialName);
-  const [bio, setBio] = useState6(initialBio);
-  const [busy, setBusy] = useState6(false);
-  const [error, setError] = useState6(null);
-  const [saved, setSaved] = useState6(false);
+  const [name, setName] = useState7(initialName);
+  const [bio, setBio] = useState7(initialBio);
+  const [busy, setBusy] = useState7(false);
+  const [error, setError] = useState7(null);
+  const [saved, setSaved] = useState7(false);
   async function submit(e) {
     e.preventDefault();
     if (!ctx.app) return;
@@ -502,18 +610,18 @@ function ElvixIdentityForm({
 }
 
 // src/react/elvix-region.tsx
-import { useState as useState7 } from "react";
+import { useState as useState8 } from "react";
 function ElvixRegion({
   initialCountry = "",
   initialTimezone = "",
   onResult
 }) {
   const ctx = useElvixContext();
-  const [country, setCountry] = useState7(initialCountry);
-  const [timezone, setTimezone] = useState7(initialTimezone);
-  const [busy, setBusy] = useState7(false);
-  const [error, setError] = useState7(null);
-  const [saved, setSaved] = useState7(false);
+  const [country, setCountry] = useState8(initialCountry);
+  const [timezone, setTimezone] = useState8(initialTimezone);
+  const [busy, setBusy] = useState8(false);
+  const [error, setError] = useState8(null);
+  const [saved, setSaved] = useState8(false);
   async function submit(e) {
     e.preventDefault();
     if (!ctx.app) return;
@@ -533,16 +641,16 @@ function ElvixRegion({
 }
 
 // src/react/elvix-languages.tsx
-import { useState as useState8 } from "react";
+import { useState as useState9 } from "react";
 function ElvixLanguages({
   initial = [],
   onResult
 }) {
   const ctx = useElvixContext();
-  const [raw, setRaw] = useState8(initial.join(", "));
-  const [busy, setBusy] = useState8(false);
-  const [error, setError] = useState8(null);
-  const [saved, setSaved] = useState8(false);
+  const [raw, setRaw] = useState9(initial.join(", "));
+  const [busy, setBusy] = useState9(false);
+  const [error, setError] = useState9(null);
+  const [saved, setSaved] = useState9(false);
   async function submit(e) {
     e.preventDefault();
     if (!ctx.app) return;
@@ -563,15 +671,15 @@ function ElvixLanguages({
 }
 
 // src/react/elvix-sessions.tsx
-import { useEffect as useEffect2, useState as useState9 } from "react";
+import { useEffect as useEffect4, useState as useState10 } from "react";
 function ElvixSessions({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [rows, setRows] = useState9(null);
-  const [error, setError] = useState9(null);
-  const [busy, setBusy] = useState9(false);
-  useEffect2(() => {
+  const [rows, setRows] = useState10(null);
+  const [error, setError] = useState10(null);
+  const [busy, setBusy] = useState10(false);
+  useEffect4(() => {
     if (!ctx.app) return;
     fetch(`${ctx.baseUrl}/api/account/apps/${ctx.app.applicationId}/sessions`, {
       credentials: "include"
@@ -595,14 +703,14 @@ function ElvixSessions({
 }
 
 // src/react/elvix-export.tsx
-import { useState as useState10 } from "react";
+import { useState as useState11 } from "react";
 function ElvixExport({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [busy, setBusy] = useState10(false);
-  const [done, setDone] = useState10(false);
-  const [error, setError] = useState10(null);
+  const [busy, setBusy] = useState11(false);
+  const [done, setDone] = useState11(false);
+  const [error, setError] = useState11(null);
   async function start() {
     if (!ctx.app) return;
     setBusy(true);
@@ -621,16 +729,16 @@ function ElvixExport({
 }
 
 // src/react/elvix-deactivate.tsx
-import { useState as useState11 } from "react";
+import { useState as useState12 } from "react";
 function ElvixDeactivate({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [pane, setPane] = useState11("warn");
-  const [challengeId, setChallengeId] = useState11(null);
-  const [code, setCode] = useState11("");
-  const [busy, setBusy] = useState11(false);
-  const [error, setError] = useState11(null);
+  const [pane, setPane] = useState12("warn");
+  const [challengeId, setChallengeId] = useState12(null);
+  const [code, setCode] = useState12("");
+  const [busy, setBusy] = useState12(false);
+  const [error, setError] = useState12(null);
   async function startChallenge() {
     if (!ctx.app) return;
     setBusy(true);
@@ -687,16 +795,16 @@ function ElvixDeactivate({
 }
 
 // src/react/elvix-leave.tsx
-import { useState as useState12 } from "react";
+import { useState as useState13 } from "react";
 function ElvixLeave({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [pane, setPane] = useState12("warn");
-  const [challengeId, setChallengeId] = useState12(null);
-  const [code, setCode] = useState12("");
-  const [busy, setBusy] = useState12(false);
-  const [error, setError] = useState12(null);
+  const [pane, setPane] = useState13("warn");
+  const [challengeId, setChallengeId] = useState13(null);
+  const [code, setCode] = useState13("");
+  const [busy, setBusy] = useState13(false);
+  const [error, setError] = useState13(null);
   async function startChallenge() {
     if (!ctx.app) return;
     setBusy(true);
@@ -753,16 +861,16 @@ function ElvixLeave({
 }
 
 // src/react/elvix-address-book.tsx
-import { useEffect as useEffect3, useState as useState13 } from "react";
+import { useEffect as useEffect5, useState as useState14 } from "react";
 function ElvixAddressBook({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [rows, setRows] = useState13(null);
-  const [error, setError] = useState13(null);
-  const [busy, setBusy] = useState13(false);
-  const [adding, setAdding] = useState13(false);
-  const [form, setForm] = useState13({
+  const [rows, setRows] = useState14(null);
+  const [error, setError] = useState14(null);
+  const [busy, setBusy] = useState14(false);
+  const [adding, setAdding] = useState14(false);
+  const [form, setForm] = useState14({
     label: "Home",
     line1: "",
     postalCode: "",
@@ -778,7 +886,7 @@ function ElvixAddressBook({
       else setError("load_failed");
     }).catch(() => setError("network"));
   }
-  useEffect3(() => {
+  useEffect5(() => {
     reload();
   }, [ctx.app, ctx.baseUrl]);
   async function add(e) {
@@ -815,16 +923,16 @@ function ElvixAddressBook({
 }
 
 // src/react/elvix-legal-entities.tsx
-import { useEffect as useEffect4, useState as useState14 } from "react";
+import { useEffect as useEffect6, useState as useState15 } from "react";
 function ElvixLegalEntities({
   onResult
 }) {
   const ctx = useElvixContext();
-  const [rows, setRows] = useState14(null);
-  const [error, setError] = useState14(null);
-  const [busy, setBusy] = useState14(false);
-  const [adding, setAdding] = useState14(false);
-  const [form, setForm] = useState14({
+  const [rows, setRows] = useState15(null);
+  const [error, setError] = useState15(null);
+  const [busy, setBusy] = useState15(false);
+  const [adding, setAdding] = useState15(false);
+  const [form, setForm] = useState15({
     legalName: "",
     taxId: "",
     country: ""
@@ -838,7 +946,7 @@ function ElvixLegalEntities({
       else setError("load_failed");
     }).catch(() => setError("network"));
   }
-  useEffect4(() => {
+  useEffect6(() => {
     reload();
   }, [ctx.app, ctx.baseUrl]);
   async function add(e) {
@@ -884,11 +992,17 @@ export {
   ElvixLanguages,
   ElvixLeave,
   ElvixLegalEntities,
+  ElvixLifecycleWatcher,
   ElvixProvider,
   ElvixRegion,
   ElvixSessions,
   ElvixSignIn,
   ElvixUsername,
+  getElvixToken,
+  setElvixToken,
   useElvixApp,
-  useElvixContext
+  useElvixContext,
+  useUserMemberships,
+  useUserRoles,
+  useUserScopes
 };

package/dist/server.d.ts

@@ -7,21 +7,25 @@ import { ElvixVerifyResult } from './index.js';
  */
 
 type VerifyOptions = {
-    /** Application API key (Console → Credentials). */
-    apiKey: string;
     /** Override the elvix origin for testing / proxy setups. */
     baseUrl?: string;
     /** Per-request timeout in ms. Default 5000. */
     timeoutMs?: number;
 };
 /**
- * Exchange an end-user session token for the verified user envelope
- * (roles + scopes + memberships). Hit the `/api/v1/verify` endpoint
- * with the customer's Application API key.
+ * Verify an end-user session token (the value the SDK handed you via
+ * `onSuccess({ token })`) and get back the live user envelope — roles,
+ * scopes, memberships — for the token's application.
  *
- * Returns a discriminated union — never throws on auth failure.
- * Throws only on infra failure (network, timeout, malformed JSON).
+ * The token is self-authenticating: POST it as a Bearer to
+ * `/api/v1/session`. elvix re-checks the session and the user/membership
+ * status on every call, so a banned, paused, or signed-out user verifies as
+ * `ok:false` here within one request — call this on each protected request
+ * (or cache for a few seconds) and you enforce bans server-side too.
+ *
+ * Returns a discriminated union — never throws on auth failure. Throws only
+ * on infra failure (network, timeout, malformed JSON).
  */
-declare function verifyElvixToken(token: string, opts: VerifyOptions): Promise<ElvixVerifyResult>;
+declare function verifyElvixToken(token: string, opts?: VerifyOptions): Promise<ElvixVerifyResult>;
 
 export { type VerifyOptions, verifyElvixToken };

package/dist/server.js

@@ -1,33 +1,34 @@
 // src/server.ts
 var DEFAULT_BASE_URL = "https://elvix.is";
-async function verifyElvixToken(token, opts) {
-  const url = `${opts.baseUrl ?? DEFAULT_BASE_URL}/api/v1/verify`;
+async function verifyElvixToken(token, opts = {}) {
+  const url = `${opts.baseUrl ?? DEFAULT_BASE_URL}/api/v1/session`;
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 5e3);
   try {
     const res = await fetch(url, {
       method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${opts.apiKey}`
-      },
-      body: JSON.stringify({ token }),
+      headers: { authorization: `Bearer ${token}` },
       signal: ctrl.signal
     });
     const body = await res.json();
-    if (!res.ok || !body.success || !body.data) {
+    if (!res.ok || !body.ok || !body.userId) {
       return {
         ok: false,
-        error: pickError(body.errorMessage, res.status),
-        message: body.errorMessage
+        error: pickError(body.error, res.status),
+        message: body.error
       };
     }
     return {
       ok: true,
-      user: body.data.user,
-      roles: body.data.roles,
-      scopes: body.data.scopes,
-      memberships: body.data.memberships
+      user: {
+        id: body.userId,
+        email: body.email ?? "",
+        name: body.name ?? void 0,
+        avatarUrl: body.avatarUrl ?? void 0
+      },
+      roles: body.roles ?? [],
+      scopes: body.scopes ?? [],
+      memberships: body.memberships ?? []
     };
   } finally {
     clearTimeout(timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvix.is/sdk",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Official elvix SDK. Drop-in React components, server helpers, and an MCP server so AI coding agents integrate elvix on the first try.",
   "license": "MIT",
   "homepage": "https://elvix.is",
@@ -21,6 +21,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
+    "elvix": "./dist/cli/index.js",
     "elvix-mcp": "./dist/mcp/bin.js"
   },
   "exports": {
@@ -45,9 +46,13 @@
       "import": "./dist/mcp/index.js"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "build": "tsup src/index.ts src/react.ts src/server.ts src/types.ts src/mcp/index.ts src/mcp/bin.ts --format esm --dts --clean --external react --external next",
+    "build": "tsup src/index.ts src/react.ts src/server.ts src/types.ts src/mcp/index.ts src/mcp/bin.ts src/cli/index.ts src/cli/doctor.ts --format esm --dts --clean --external react --external next",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },