@githat/nextjs 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -22,6 +22,17 @@ interface GitHatConfig {
     signUpUrl?: string;
     afterSignInUrl?: string;
     afterSignOutUrl?: string;
+    /**
+     * Token storage mode:
+     * - 'localStorage' (default): Tokens stored in browser localStorage
+     * - 'cookie': Tokens stored in httpOnly cookies (more secure, XSS-resistant)
+     *
+     * When using 'cookie' mode:
+     * - Login/refresh automatically set httpOnly cookies
+     * - SDK reads auth state from cookies (server-side)
+     * - Better for apps with server-side rendering
+     */
+    tokenStorage?: 'localStorage' | 'cookie';
 }
 interface AuthState {
     user: GitHatUser | null;
@@ -56,9 +67,12 @@ interface GitHatProviderProps {
 }
 declare function GitHatProvider({ config: rawConfig, children }: GitHatProviderProps): react_jsx_runtime.JSX.Element;
 
+interface OrgMetadata$1 {
+    [key: string]: unknown;
+}
 declare function useAuth(): GitHatContextValue;
 declare function useGitHat(): {
-    fetch: <T = any>(endpoint: string, options?: RequestInit) => Promise<T>;
+    fetch: <T = unknown>(endpoint: string, fetchOptions?: RequestInit) => Promise<T>;
     getUserOrgs: () => Promise<{
         orgs: GitHatOrg[];
     }>;
@@ -68,6 +82,8 @@ declare function useGitHat(): {
     verifyAgent: (wallet: string) => Promise<{
         verified: boolean;
     }>;
+    getOrgMetadata: () => Promise<OrgMetadata$1>;
+    updateOrgMetadata: (updates: OrgMetadata$1) => Promise<OrgMetadata$1>;
 };
 
 interface DataItem {
@@ -210,4 +226,34 @@ interface ProtectedRouteProps {
 }
 declare function ProtectedRoute({ children, fallback }: ProtectedRouteProps): react_jsx_runtime.JSX.Element | null;
 
-export { type AuthActions, type AuthState, type BatchOperation, type BatchResult, type DataItem, type DeleteResult, type GitHatConfig, type GitHatContextValue, type GitHatOrg, GitHatProvider, type GitHatUser, OrgSwitcher, ProtectedRoute, type PutResult, type QueryOptions, type QueryResult, SignInButton, SignInForm, SignUpButton, type SignUpData, SignUpForm, type SignUpResult, UserButton, VerifiedBadge, useAuth, useData, useGitHat };
+/**
+ * @githat/nextjs/server
+ *
+ * Server-side utilities for token verification in Next.js API routes and middleware.
+ * This module runs on the server only — do not import in client components.
+ */
+interface AuthPayload {
+    userId: string;
+    email: string;
+    orgId: string | null;
+    orgSlug: string | null;
+    role: 'owner' | 'admin' | 'member' | null;
+    tier: 'free' | 'basic' | 'pro' | 'enterprise' | null;
+}
+interface VerifyOptions {
+    /**
+     * Secret key for local JWT verification. If provided, tokens are verified
+     * locally without making an API call (~1ms vs ~50-100ms).
+     * Must match the JWT_SECRET used by the GitHat backend.
+     */
+    secretKey?: string;
+    /**
+     * API URL for remote token verification. Defaults to https://api.githat.io
+     */
+    apiUrl?: string;
+}
+interface OrgMetadata {
+    [key: string]: unknown;
+}
+
+export { type AuthActions, type AuthPayload, type AuthState, type BatchOperation, type BatchResult, type DataItem, type DeleteResult, type GitHatConfig, type GitHatContextValue, type GitHatOrg, GitHatProvider, type GitHatUser, type OrgMetadata, OrgSwitcher, ProtectedRoute, type PutResult, type QueryOptions, type QueryResult, SignInButton, SignInForm, SignUpButton, type SignUpData, SignUpForm, type SignUpResult, UserButton, VerifiedBadge, type VerifyOptions, useAuth, useData, useGitHat };

package/dist/index.d.ts

@@ -22,6 +22,17 @@ interface GitHatConfig {
     signUpUrl?: string;
     afterSignInUrl?: string;
     afterSignOutUrl?: string;
+    /**
+     * Token storage mode:
+     * - 'localStorage' (default): Tokens stored in browser localStorage
+     * - 'cookie': Tokens stored in httpOnly cookies (more secure, XSS-resistant)
+     *
+     * When using 'cookie' mode:
+     * - Login/refresh automatically set httpOnly cookies
+     * - SDK reads auth state from cookies (server-side)
+     * - Better for apps with server-side rendering
+     */
+    tokenStorage?: 'localStorage' | 'cookie';
 }
 interface AuthState {
     user: GitHatUser | null;
@@ -56,9 +67,12 @@ interface GitHatProviderProps {
 }
 declare function GitHatProvider({ config: rawConfig, children }: GitHatProviderProps): react_jsx_runtime.JSX.Element;
 
+interface OrgMetadata$1 {
+    [key: string]: unknown;
+}
 declare function useAuth(): GitHatContextValue;
 declare function useGitHat(): {
-    fetch: <T = any>(endpoint: string, options?: RequestInit) => Promise<T>;
+    fetch: <T = unknown>(endpoint: string, fetchOptions?: RequestInit) => Promise<T>;
     getUserOrgs: () => Promise<{
         orgs: GitHatOrg[];
     }>;
@@ -68,6 +82,8 @@ declare function useGitHat(): {
     verifyAgent: (wallet: string) => Promise<{
         verified: boolean;
     }>;
+    getOrgMetadata: () => Promise<OrgMetadata$1>;
+    updateOrgMetadata: (updates: OrgMetadata$1) => Promise<OrgMetadata$1>;
 };
 
 interface DataItem {
@@ -210,4 +226,34 @@ interface ProtectedRouteProps {
 }
 declare function ProtectedRoute({ children, fallback }: ProtectedRouteProps): react_jsx_runtime.JSX.Element | null;
 
-export { type AuthActions, type AuthState, type BatchOperation, type BatchResult, type DataItem, type DeleteResult, type GitHatConfig, type GitHatContextValue, type GitHatOrg, GitHatProvider, type GitHatUser, OrgSwitcher, ProtectedRoute, type PutResult, type QueryOptions, type QueryResult, SignInButton, SignInForm, SignUpButton, type SignUpData, SignUpForm, type SignUpResult, UserButton, VerifiedBadge, useAuth, useData, useGitHat };
+/**
+ * @githat/nextjs/server
+ *
+ * Server-side utilities for token verification in Next.js API routes and middleware.
+ * This module runs on the server only — do not import in client components.
+ */
+interface AuthPayload {
+    userId: string;
+    email: string;
+    orgId: string | null;
+    orgSlug: string | null;
+    role: 'owner' | 'admin' | 'member' | null;
+    tier: 'free' | 'basic' | 'pro' | 'enterprise' | null;
+}
+interface VerifyOptions {
+    /**
+     * Secret key for local JWT verification. If provided, tokens are verified
+     * locally without making an API call (~1ms vs ~50-100ms).
+     * Must match the JWT_SECRET used by the GitHat backend.
+     */
+    secretKey?: string;
+    /**
+     * API URL for remote token verification. Defaults to https://api.githat.io
+     */
+    apiUrl?: string;
+}
+interface OrgMetadata {
+    [key: string]: unknown;
+}
+
+export { type AuthActions, type AuthPayload, type AuthState, type BatchOperation, type BatchResult, type DataItem, type DeleteResult, type GitHatConfig, type GitHatContextValue, type GitHatOrg, GitHatProvider, type GitHatUser, type OrgMetadata, OrgSwitcher, ProtectedRoute, type PutResult, type QueryOptions, type QueryResult, SignInButton, SignInForm, SignUpButton, type SignUpData, SignUpForm, type SignUpResult, UserButton, VerifiedBadge, type VerifyOptions, useAuth, useData, useGitHat };

package/dist/index.js

@@ -54,15 +54,16 @@ function resolveConfig(config) {
     signInUrl: config.signInUrl || "/sign-in",
     signUpUrl: config.signUpUrl || "/sign-up",
     afterSignInUrl: config.afterSignInUrl || "/dashboard",
-    afterSignOutUrl: config.afterSignOutUrl || "/"
+    afterSignOutUrl: config.afterSignOutUrl || "/",
+    tokenStorage: config.tokenStorage || "localStorage"
   };
 }
 
 // src/client.ts
 var _refreshPromise = null;
-async function refreshTokens(apiUrl, appKey) {
-  const refreshToken = typeof window !== "undefined" ? localStorage.getItem(TOKEN_KEYS.refreshToken) : null;
-  if (!refreshToken) return false;
+async function refreshTokens(apiUrl, appKey, useCookies) {
+  const refreshToken = typeof window !== "undefined" && !useCookies ? localStorage.getItem(TOKEN_KEYS.refreshToken) : null;
+  if (!useCookies && !refreshToken) return false;
   let orgId = null;
   try {
     const orgStr = localStorage.getItem(TOKEN_KEYS.org);
@@ -70,18 +71,22 @@ async function refreshTokens(apiUrl, appKey) {
   } catch {
   }
   try {
-    const res = await fetch(`${apiUrl}/auth/refresh`, {
+    const refreshUrl = useCookies ? `${apiUrl}/auth/refresh?setCookie=true` : `${apiUrl}/auth/refresh`;
+    const res = await fetch(refreshUrl, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         "X-GitHat-App-Key": appKey
       },
-      body: JSON.stringify({ refreshToken, orgId })
+      credentials: useCookies ? "include" : "same-origin",
+      body: JSON.stringify(useCookies ? { orgId } : { refreshToken, orgId })
     });
     if (!res.ok) return false;
     const data = await res.json();
-    if (data.accessToken) localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
-    if (data.refreshToken) localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
+    if (!useCookies) {
+      if (data.accessToken) localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
+      if (data.refreshToken) localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
+    }
     if (data.org) localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(data.org));
     return true;
   } catch {
@@ -91,23 +96,30 @@ async function refreshTokens(apiUrl, appKey) {
 function clearAuth() {
   if (typeof window === "undefined") return;
   Object.values(TOKEN_KEYS).forEach((key) => localStorage.removeItem(key));
-  window.dispatchEvent(new CustomEvent("githat:auth-changed", {
-    detail: { user: null, org: null, signedIn: false }
-  }));
+  window.dispatchEvent(
+    new CustomEvent("githat:auth-changed", {
+      detail: { user: null, org: null, signedIn: false }
+    })
+  );
 }
-function createClient(apiUrl, appKey) {
-  async function fetchApi(endpoint, options = {}) {
+function createClient(apiUrl, appKey, options = {}) {
+  const { useCookies = false } = options;
+  async function fetchApi(endpoint, fetchOptions = {}) {
     const url = `${apiUrl}${endpoint}`;
-    const token = typeof window !== "undefined" ? localStorage.getItem(TOKEN_KEYS.accessToken) : null;
+    const token = typeof window !== "undefined" && !useCookies ? localStorage.getItem(TOKEN_KEYS.accessToken) : null;
     const headers = {
       "Content-Type": "application/json",
       "X-GitHat-App-Key": appKey,
       ...token && { Authorization: `Bearer ${token}` },
-      ...options.headers
+      ...fetchOptions.headers
     };
     let response;
     try {
-      response = await fetch(url, { ...options, headers });
+      response = await fetch(url, {
+        ...fetchOptions,
+        headers,
+        credentials: useCookies ? "include" : "same-origin"
+      });
     } catch (networkError) {
       if (networkError instanceof TypeError) {
         const isMissingKey = !appKey || !appKey.startsWith("pk_live_");
@@ -117,27 +129,26 @@ function createClient(apiUrl, appKey) {
             "Missing GitHat API key. Add NEXT_PUBLIC_GITHAT_PUBLISHABLE_KEY to .env.local"
           );
         }
-        throw new Error(
-          "Unable to connect to GitHat API. Check your network connection."
-        );
+        throw new Error("Unable to connect to GitHat API. Check your network connection.");
       }
       throw networkError;
     }
     if (response.status === 401) {
       if (!_refreshPromise) {
-        _refreshPromise = refreshTokens(apiUrl, appKey).finally(() => {
+        _refreshPromise = refreshTokens(apiUrl, appKey, useCookies).finally(() => {
           _refreshPromise = null;
         });
       }
       const refreshed = await _refreshPromise;
       if (refreshed) {
-        const newToken = localStorage.getItem(TOKEN_KEYS.accessToken);
+        const newToken = !useCookies && typeof window !== "undefined" ? localStorage.getItem(TOKEN_KEYS.accessToken) : null;
         const retryResponse = await fetch(url, {
-          ...options,
+          ...fetchOptions,
           headers: {
             ...headers,
             ...newToken && { Authorization: `Bearer ${newToken}` }
-          }
+          },
+          credentials: useCookies ? "include" : "same-origin"
         });
         const retryData = await retryResponse.json();
         if (!retryResponse.ok) throw new Error(retryData.error || "Request failed");
@@ -158,38 +169,57 @@ var import_jsx_runtime = require("react/jsx-runtime");
 var GitHatContext = (0, import_react.createContext)(null);
 function GitHatProvider({ config: rawConfig, children }) {
   const config = (0, import_react.useMemo)(() => resolveConfig(rawConfig), [rawConfig]);
-  const clientRef = (0, import_react.useRef)(createClient(config.apiUrl, config.publishableKey));
+  const useCookies = config.tokenStorage === "cookie";
+  const clientRef = (0, import_react.useRef)(createClient(config.apiUrl, config.publishableKey, { useCookies }));
   const [user, setUser] = (0, import_react.useState)(null);
   const [org, setOrg] = (0, import_react.useState)(null);
   const [isSignedIn, setIsSignedIn] = (0, import_react.useState)(false);
   const [isLoading, setIsLoading] = (0, import_react.useState)(true);
   const [authError, setAuthError] = (0, import_react.useState)(null);
   (0, import_react.useEffect)(() => {
-    const token = localStorage.getItem(TOKEN_KEYS.accessToken);
-    const storedUser = localStorage.getItem(TOKEN_KEYS.user);
-    if (token && storedUser) {
-      clientRef.current.fetchApi("/auth/me").then((data) => {
-        const u = data.user || JSON.parse(storedUser);
-        setUser(u);
-        const storedOrg = localStorage.getItem(TOKEN_KEYS.org);
-        setOrg(data.currentOrg || (storedOrg ? JSON.parse(storedOrg) : null));
-        setIsSignedIn(true);
-        setAuthError(null);
-      }).catch((err) => {
-        if (err.message === "Session expired") {
+    const validateSession = async () => {
+      try {
+        if (!useCookies) {
+          const token = localStorage.getItem(TOKEN_KEYS.accessToken);
+          const storedUser = localStorage.getItem(TOKEN_KEYS.user);
+          if (!token || !storedUser) {
+            setIsLoading(false);
+            return;
+          }
+        }
+        const data = await clientRef.current.fetchApi("/auth/me");
+        if (data.user) {
+          setUser(data.user);
+          setOrg(data.currentOrg || null);
+          setIsSignedIn(true);
+          setAuthError(null);
+          if (!useCookies) {
+            localStorage.setItem(TOKEN_KEYS.user, JSON.stringify(data.user));
+            if (data.currentOrg) {
+              localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(data.currentOrg));
+            }
+          }
+        }
+      } catch (err) {
+        const error = err;
+        if (error.message === "Session expired") {
           clientRef.current.clearAuth();
-        } else {
-          try {
-            setUser(JSON.parse(storedUser));
-          } catch {
+        } else if (!useCookies) {
+          const storedUser = localStorage.getItem(TOKEN_KEYS.user);
+          if (storedUser) {
+            try {
+              setUser(JSON.parse(storedUser));
+              setIsSignedIn(true);
+            } catch {
+            }
           }
-          setAuthError(err.message || "Failed to verify session");
+          setAuthError(error.message || "Failed to verify session");
         }
-      }).finally(() => setIsLoading(false));
-    } else {
+      }
       setIsLoading(false);
-    }
-  }, []);
+    };
+    validateSession();
+  }, [useCookies]);
   (0, import_react.useEffect)(() => {
     const handleAuthChanged = (e) => {
       const detail = e.detail;
@@ -207,30 +237,36 @@ function GitHatProvider({ config: rawConfig, children }) {
     return () => window.removeEventListener("githat:auth-changed", handleAuthChanged);
   }, []);
   const signIn = (0, import_react.useCallback)(async (email, password) => {
-    const data = await clientRef.current.fetchApi("/auth/login", {
+    const loginUrl = useCookies ? "/auth/login?setCookie=true" : "/auth/login";
+    const data = await clientRef.current.fetchApi(loginUrl, {
       method: "POST",
       body: JSON.stringify({ email, password })
     });
-    localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
-    localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
-    localStorage.setItem(TOKEN_KEYS.user, JSON.stringify(data.user));
-    if (data.org) localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(data.org));
+    if (!useCookies && data.accessToken && data.refreshToken) {
+      localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
+      localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
+      localStorage.setItem(TOKEN_KEYS.user, JSON.stringify(data.user));
+      if (data.org) localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(data.org));
+    }
     setUser(data.user);
     setOrg(data.org || null);
     setIsSignedIn(true);
     window.dispatchEvent(new CustomEvent("githat:auth-changed", {
       detail: { user: data.user, org: data.org, signedIn: true }
     }));
-  }, []);
+  }, [useCookies]);
   const signUp = (0, import_react.useCallback)(async (signUpData) => {
-    const data = await clientRef.current.fetchApi("/auth/register", {
+    const registerUrl = useCookies ? "/auth/register?setCookie=true" : "/auth/register";
+    const data = await clientRef.current.fetchApi(registerUrl, {
       method: "POST",
       body: JSON.stringify(signUpData)
     });
-    localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
-    localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
-    localStorage.setItem(TOKEN_KEYS.user, JSON.stringify(data.user));
-    if (data.org) localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(data.org));
+    if (!useCookies && data.accessToken && data.refreshToken) {
+      localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
+      localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
+      localStorage.setItem(TOKEN_KEYS.user, JSON.stringify(data.user));
+      if (data.org) localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(data.org));
+    }
     setUser(data.user);
     setOrg(data.org || null);
     setIsSignedIn(true);
@@ -238,10 +274,11 @@ function GitHatProvider({ config: rawConfig, children }) {
       detail: { user: data.user, org: data.org, signedIn: true }
     }));
     return { requiresVerification: !data.user.emailVerified, email: signUpData.email };
-  }, []);
+  }, [useCookies]);
   const signOut = (0, import_react.useCallback)(async () => {
     try {
-      await clientRef.current.fetchApi("/auth/logout", { method: "POST" });
+      const logoutUrl = useCookies ? "/auth/logout?setCookie=true" : "/auth/logout";
+      await clientRef.current.fetchApi(logoutUrl, { method: "POST" });
     } catch {
     }
     clientRef.current.clearAuth();
@@ -251,22 +288,24 @@ function GitHatProvider({ config: rawConfig, children }) {
     if (typeof window !== "undefined" && config.afterSignOutUrl) {
       window.location.href = config.afterSignOutUrl;
     }
-  }, [config.afterSignOutUrl]);
+  }, [config.afterSignOutUrl, useCookies]);
   const switchOrg = (0, import_react.useCallback)(async (orgId) => {
     try {
-      const data = await clientRef.current.fetchApi(`/user/orgs/${orgId}/switch`, { method: "POST" });
-      if (data.accessToken) localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
-      if (data.refreshToken) localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
-      const orgData = data.org;
-      localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(orgData));
-      setOrg(orgData);
+      const switchUrl = useCookies ? `/user/orgs/${orgId}/switch?setCookie=true` : `/user/orgs/${orgId}/switch`;
+      const data = await clientRef.current.fetchApi(switchUrl, { method: "POST" });
+      if (!useCookies) {
+        if (data.accessToken) localStorage.setItem(TOKEN_KEYS.accessToken, data.accessToken);
+        if (data.refreshToken) localStorage.setItem(TOKEN_KEYS.refreshToken, data.refreshToken);
+        localStorage.setItem(TOKEN_KEYS.org, JSON.stringify(data.org));
+      }
+      setOrg(data.org);
       window.dispatchEvent(new CustomEvent("githat:auth-changed", {
-        detail: { user, org: orgData, signedIn: true }
+        detail: { user, org: data.org, signedIn: true }
       }));
     } catch (e) {
       console.error("Org switch failed:", e);
     }
-  }, [user]);
+  }, [user, useCookies]);
   const value = (0, import_react.useMemo)(() => ({
     user,
     org,
@@ -295,11 +334,38 @@ function useGitHat() {
     () => createClient(ctx.config.apiUrl, ctx.config.publishableKey),
     [ctx.config.apiUrl, ctx.config.publishableKey]
   );
+  const getOrgMetadata = (0, import_react2.useCallback)(async () => {
+    if (!ctx.org?.id) {
+      throw new Error("No active organization");
+    }
+    const response = await client.fetchApi(
+      `/orgs/${ctx.org.id}/metadata`
+    );
+    return response.metadata || {};
+  }, [client, ctx.org?.id]);
+  const updateOrgMetadata = (0, import_react2.useCallback)(
+    async (updates) => {
+      if (!ctx.org?.id) {
+        throw new Error("No active organization");
+      }
+      const response = await client.fetchApi(
+        `/orgs/${ctx.org.id}/metadata`,
+        {
+          method: "PATCH",
+          body: JSON.stringify(updates)
+        }
+      );
+      return response.metadata || {};
+    },
+    [client, ctx.org?.id]
+  );
   return {
     fetch: client.fetchApi,
     getUserOrgs: () => client.fetchApi("/user/orgs"),
     verifyMCP: (domain) => client.fetchApi(`/verify/mcp/${domain}`),
-    verifyAgent: (wallet) => client.fetchApi(`/verify/agent/${wallet}`)
+    verifyAgent: (wallet) => client.fetchApi(`/verify/agent/${wallet}`),
+    getOrgMetadata,
+    updateOrgMetadata
   };
 }