@elvix.is/sdk 0.4.0 → 0.5.0

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.4.0",
+  "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",
@@ -46,7 +46,11 @@
       "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 src/cli/index.ts src/cli/doctor.ts --format esm --dts --clean --external react --external next",
     "typecheck": "tsc --noEmit",