@buildspacestudio/sdk 0.3.0 → 0.4.0

package/dist/next/index.js

@@ -0,0 +1,172 @@
+// src/errors.ts
+var BuildspaceError = class extends Error {
+  /** Machine-readable error code, e.g. `"auth/invalid-token"`. */
+  code;
+  /** Which service produced the error. */
+  service;
+  /** HTTP status code from the API. */
+  status;
+  constructor({
+    code,
+    message,
+    service,
+    status
+  }) {
+    super(message);
+    this.name = "BuildspaceError";
+    this.code = code;
+    this.service = service;
+    this.status = status;
+  }
+};
+
+// src/next/index.ts
+var SESSION_COOKIE_NAME = "bs_session";
+function isSecureDefault() {
+  return globalThis.process?.env?.NODE_ENV !== "development";
+}
+function serializeSessionCookie(value, maxAge, opts) {
+  const parts = [
+    `${SESSION_COOKIE_NAME}=${value}`,
+    `Path=${opts?.path ?? "/"}`,
+    "HttpOnly",
+    `SameSite=${opts?.sameSite === "strict" ? "Strict" : opts?.sameSite === "none" ? "None" : "Lax"}`
+  ];
+  if (maxAge !== null) {
+    parts.push(`Max-Age=${Math.max(0, Math.floor(maxAge))}`);
+  }
+  if (opts?.secure ?? isSecureDefault()) {
+    parts.push("Secure");
+  }
+  if (opts?.domain) {
+    parts.push(`Domain=${opts.domain}`);
+  }
+  return parts.join("; ");
+}
+function buildSessionCookie(token, maxAgeSeconds, opts) {
+  return serializeSessionCookie(token, maxAgeSeconds, opts);
+}
+function buildClearSessionCookie(opts) {
+  return serializeSessionCookie("", 0, opts);
+}
+function parseCookieHeader(header, name) {
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) {
+      continue;
+    }
+    if (part.slice(0, eq).trim() === name) {
+      return part.slice(eq + 1).trim();
+    }
+  }
+  return null;
+}
+function getSessionToken(source) {
+  if (source instanceof Request) {
+    const header = source.headers.get("cookie");
+    return header ? parseCookieHeader(header, SESSION_COOKIE_NAME) : null;
+  }
+  const cookie = source.get(SESSION_COOKIE_NAME);
+  if (!cookie) {
+    return null;
+  }
+  const value = typeof cookie === "string" ? cookie : cookie.value;
+  return value || null;
+}
+async function getSession(client, source) {
+  const token = getSessionToken(source);
+  if (!token) {
+    return null;
+  }
+  try {
+    const session = await client.auth.getSession(token);
+    return session ? { ...session, token } : null;
+  } catch {
+    return null;
+  }
+}
+async function requireSession(client, source) {
+  const session = await getSession(client, source);
+  if (!session) {
+    throw new BuildspaceError({
+      service: "auth",
+      status: 401,
+      code: "auth/session-required",
+      message: "No valid session. The bs_session cookie is missing, expired, or revoked."
+    });
+  }
+  return session;
+}
+function createAuthCallback(client, options) {
+  return async (request) => {
+    let tokens;
+    try {
+      tokens = await client.auth.handleCallback(request);
+    } catch (error) {
+      if (options?.onError) {
+        return await options.onError(error, request);
+      }
+      throw error;
+    }
+    if (options?.onSignIn) {
+      try {
+        await options.onSignIn({
+          accessToken: tokens.access_token,
+          request,
+          user: tokens.user
+        });
+      } catch (error) {
+        console.error("[buildspace] onSignIn hook failed", error);
+      }
+    }
+    return new Response(null, {
+      status: 303,
+      headers: {
+        Location: options?.redirectTo ?? "/",
+        "Set-Cookie": buildSessionCookie(tokens.access_token, tokens.expires_in, options?.cookie)
+      }
+    });
+  };
+}
+function createLogoutRoute(client, options) {
+  return async (request) => {
+    const token = getSessionToken(request);
+    if (token) {
+      try {
+        await client.auth.signOut(token);
+      } catch (error) {
+        console.error("[buildspace] session revoke failed during logout", error);
+      }
+    }
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json",
+        "Set-Cookie": buildClearSessionCookie(options?.cookie)
+      }
+    });
+  };
+}
+function createSessionRoute(client) {
+  return async (request) => {
+    const session = await getSession(client, request);
+    const publicSession = session ? { appId: session.appId, user: session.user } : null;
+    return new Response(JSON.stringify({ session: publicSession }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" }
+    });
+  };
+}
+function createSessionCookieGuard(options) {
+  return (request) => {
+    if (getSessionToken(request)) {
+      return;
+    }
+    const target = new URL(options?.redirectTo ?? "/", new URL(request.url).origin);
+    return Response.redirect(target.toString(), 307);
+  };
+}
+
+export { SESSION_COOKIE_NAME, buildClearSessionCookie, buildSessionCookie, createAuthCallback, createLogoutRoute, createSessionCookieGuard, createSessionRoute, getSession, getSessionToken, requireSession };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/next/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/next/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** Services available in the Buildspace platform. */\nexport type BuildspaceService = \"auth\" | \"billing\" | \"events\" | \"notifications\" | \"storage\";\n\n/**\n * Error thrown by all Buildspace SDK methods on failure.\n *\n * @example\n * ```ts\n * try {\n *   await buildspace.auth.getSession(token);\n * } catch (err) {\n *   if (err instanceof BuildspaceError) {\n *     console.error(err.service, err.code, err.status, err.message);\n *   }\n * }\n * ```\n */\nexport class BuildspaceError extends Error {\n  /** Machine-readable error code, e.g. `\"auth/invalid-token\"`. */\n  readonly code: string;\n  /** Which service produced the error. */\n  readonly service: BuildspaceService;\n  /** HTTP status code from the API. */\n  readonly status: number;\n\n  constructor({\n    code,\n    message,\n    service,\n    status,\n  }: {\n    code: string;\n    message: string;\n    service: BuildspaceService;\n    status: number;\n  }) {\n    super(message);\n    this.name = \"BuildspaceError\";\n    this.code = code;\n    this.service = service;\n    this.status = status;\n  }\n}\n","import type { AuthSession, AuthUser, TokenResponse } from \"../auth\";\nimport { BuildspaceError } from \"../errors\";\n\n/**\n * Framework adapter for Next.js (and any framework using web-standard\n * `Request`/`Response` route handlers).\n *\n * Replaces the auth glue every creator app used to hand-roll: the OAuth\n * callback route, logout + session routes, a cookie-aware `getSession()`,\n * and a middleware cookie guard — all standardized on the `bs_session`\n * cookie.\n *\n * @example\n * ```ts\n * // app/api/auth/callback/route.ts\n * import { createAuthCallback } from \"@buildspacestudio/sdk/next\";\n * import { getServerClient } from \"@/lib/buildspace\";\n *\n * export const GET = createAuthCallback(getServerClient(), { redirectTo: \"/dashboard\" });\n * ```\n */\n\n/** The session cookie name shared by every Buildspace app. */\nexport const SESSION_COOKIE_NAME = \"bs_session\";\n\n/** The minimal server-client surface the adapter needs (a `Buildspace` instance). */\nexport interface AuthServerClient {\n  auth: {\n    getSession(sessionToken: string): Promise<AuthSession | null>;\n    handleCallback(\n      request: Request | URL | string,\n      opts?: { redirectUri?: string }\n    ): Promise<TokenResponse>;\n    signOut(sessionToken?: string): Promise<void>;\n  };\n}\n\n/** Options controlling the `bs_session` cookie attributes. */\nexport interface SessionCookieOptions {\n  /** Cookie domain. Omitted by default (host-only cookie). */\n  domain?: string;\n  /** Cookie path. Defaults to `/`. */\n  path?: string;\n  /** SameSite attribute. Defaults to `Lax`. */\n  sameSite?: \"lax\" | \"strict\" | \"none\";\n  /** Set the `Secure` attribute. Defaults to `true` outside development. */\n  secure?: boolean;\n}\n\nfunction isSecureDefault(): boolean {\n  return (\n    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env\n      ?.NODE_ENV !== \"development\"\n  );\n}\n\nfunction serializeSessionCookie(\n  value: string,\n  maxAge: number | null,\n  opts?: SessionCookieOptions\n): string {\n  const parts = [\n    `${SESSION_COOKIE_NAME}=${value}`,\n    `Path=${opts?.path ?? \"/\"}`,\n    \"HttpOnly\",\n    `SameSite=${opts?.sameSite === \"strict\" ? \"Strict\" : opts?.sameSite === \"none\" ? \"None\" : \"Lax\"}`,\n  ];\n\n  if (maxAge !== null) {\n    parts.push(`Max-Age=${Math.max(0, Math.floor(maxAge))}`);\n  }\n\n  if (opts?.secure ?? isSecureDefault()) {\n    parts.push(\"Secure\");\n  }\n\n  if (opts?.domain) {\n    parts.push(`Domain=${opts.domain}`);\n  }\n\n  return parts.join(\"; \");\n}\n\n/** Build a `Set-Cookie` header value that stores the session token. */\nexport function buildSessionCookie(\n  token: string,\n  maxAgeSeconds: number,\n  opts?: SessionCookieOptions\n): string {\n  return serializeSessionCookie(token, maxAgeSeconds, opts);\n}\n\n/** Build a `Set-Cookie` header value that clears the session cookie. */\nexport function buildClearSessionCookie(opts?: SessionCookieOptions): string {\n  return serializeSessionCookie(\"\", 0, opts);\n}\n\n/**\n * Anything the adapter can read the session cookie from: a web `Request`,\n * or a cookie store with a `get(name)` method (e.g. the object returned by\n * Next.js `cookies()` in Server Components and Route Handlers).\n */\nexport type SessionCookieSource =\n  | Request\n  | {\n      get(name: string): { value: string } | string | null | undefined;\n    };\n\nfunction parseCookieHeader(header: string, name: string): string | null {\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq === -1) {\n      continue;\n    }\n\n    if (part.slice(0, eq).trim() === name) {\n      return part.slice(eq + 1).trim();\n    }\n  }\n\n  return null;\n}\n\n/** Read the raw session token from a request or cookie store, or `null`. */\nexport function getSessionToken(source: SessionCookieSource): string | null {\n  if (source instanceof Request) {\n    const header = source.headers.get(\"cookie\");\n    return header ? parseCookieHeader(header, SESSION_COOKIE_NAME) : null;\n  }\n\n  const cookie = source.get(SESSION_COOKIE_NAME);\n  if (!cookie) {\n    return null;\n  }\n\n  const value = typeof cookie === \"string\" ? cookie : cookie.value;\n  return value || null;\n}\n\n/** An {@link AuthSession} plus the raw token it was resolved from. */\nexport type SessionWithToken = AuthSession & { token: string };\n\n/**\n * Cookie-aware session lookup.\n *\n * Reads the `bs_session` cookie from the given source and verifies it with\n * the Buildspace API. Returns `null` when there is no cookie or the token\n * is expired/revoked. Network/5xx errors also resolve to `null` so a blip\n * never crashes rendering — sign-in state degrades to \"signed out\".\n *\n * @example\n * ```ts\n * // Server Component\n * import { cookies } from \"next/headers\";\n * const session = await getSession(getServerClient(), await cookies());\n * ```\n */\nexport async function getSession(\n  client: AuthServerClient,\n  source: SessionCookieSource\n): Promise<SessionWithToken | null> {\n  const token = getSessionToken(source);\n  if (!token) {\n    return null;\n  }\n\n  try {\n    const session = await client.auth.getSession(token);\n    return session ? { ...session, token } : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Like {@link getSession} but throws a `BuildspaceError` (401) when there is\n * no valid session. Use in route handlers and server actions that must only\n * run for signed-in users.\n */\nexport async function requireSession(\n  client: AuthServerClient,\n  source: SessionCookieSource\n): Promise<SessionWithToken> {\n  const session = await getSession(client, source);\n  if (!session) {\n    throw new BuildspaceError({\n      service: \"auth\",\n      status: 401,\n      code: \"auth/session-required\",\n      message: \"No valid session. The bs_session cookie is missing, expired, or revoked.\",\n    });\n  }\n\n  return session;\n}\n\n/** Options for {@link createAuthCallback}. */\nexport interface CreateAuthCallbackOptions {\n  /** Cookie attribute overrides. */\n  cookie?: SessionCookieOptions;\n  /**\n   * Called when the code exchange fails. Return a `Response` to control the\n   * error page; by default the error is rethrown (surfacing your framework's\n   * error handling).\n   */\n  onError?: (error: unknown, request: Request) => Response | Promise<Response>;\n  /**\n   * Signup/sign-in side effects (mirror the user into your DB, send a\n   * welcome email, track an event). Failures are logged and never break\n   * login.\n   */\n  onSignIn?: (ctx: {\n    accessToken: string;\n    request: Request;\n    user: AuthUser;\n  }) => void | Promise<void>;\n  /** Where to send the user after login. Defaults to `/`. */\n  redirectTo?: string;\n}\n\n/**\n * Create the OAuth callback route handler.\n *\n * Exchanges the `?code=` for tokens, runs your `onSignIn` hook, stores the\n * access token in the `bs_session` cookie (with `expires_in` as `Max-Age`),\n * and redirects to `redirectTo`.\n *\n * @example\n * ```ts\n * // app/api/auth/callback/route.ts\n * export const GET = createAuthCallback(getServerClient(), {\n *   redirectTo: \"/dashboard\",\n *   onSignIn: async ({ user }) => upsertUser(user),\n * });\n * ```\n */\nexport function createAuthCallback(\n  client: AuthServerClient,\n  options?: CreateAuthCallbackOptions\n): (request: Request) => Promise<Response> {\n  return async (request: Request): Promise<Response> => {\n    let tokens: TokenResponse;\n    try {\n      tokens = await client.auth.handleCallback(request);\n    } catch (error) {\n      if (options?.onError) {\n        return await options.onError(error, request);\n      }\n      throw error;\n    }\n\n    if (options?.onSignIn) {\n      try {\n        await options.onSignIn({\n          accessToken: tokens.access_token,\n          request,\n          user: tokens.user,\n        });\n      } catch (error) {\n        console.error(\"[buildspace] onSignIn hook failed\", error);\n      }\n    }\n\n    return new Response(null, {\n      status: 303,\n      headers: {\n        Location: options?.redirectTo ?? \"/\",\n        \"Set-Cookie\": buildSessionCookie(tokens.access_token, tokens.expires_in, options?.cookie),\n      },\n    });\n  };\n}\n\n/**\n * Create the logout route handler (`POST /api/auth/logout`).\n *\n * Revokes the session with the Buildspace API (already-expired sessions are\n * ignored) and clears the `bs_session` cookie.\n */\nexport function createLogoutRoute(\n  client: AuthServerClient,\n  options?: { cookie?: SessionCookieOptions }\n): (request: Request) => Promise<Response> {\n  return async (request: Request): Promise<Response> => {\n    const token = getSessionToken(request);\n\n    if (token) {\n      try {\n        await client.auth.signOut(token);\n      } catch (error) {\n        console.error(\"[buildspace] session revoke failed during logout\", error);\n      }\n    }\n\n    return new Response(JSON.stringify({ ok: true }), {\n      status: 200,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        \"Set-Cookie\": buildClearSessionCookie(options?.cookie),\n      },\n    });\n  };\n}\n\n/**\n * Create the session route handler (`GET /api/auth/session`).\n *\n * Returns `{ session }` for the current cookie, with the raw token omitted —\n * this response is safe to expose to the browser.\n */\nexport function createSessionRoute(\n  client: AuthServerClient\n): (request: Request) => Promise<Response> {\n  return async (request: Request): Promise<Response> => {\n    const session = await getSession(client, request);\n    const publicSession = session ? { appId: session.appId, user: session.user } : null;\n\n    return new Response(JSON.stringify({ session: publicSession }), {\n      status: 200,\n      headers: { \"Content-Type\": \"application/json\" },\n    });\n  };\n}\n\n/**\n * Middleware helper: redirect requests that don't carry a session cookie.\n *\n * This is a fast presence check (no API call — middleware runs on every\n * matched request); route handlers and pages must still verify the session\n * with {@link getSession}.\n *\n * @example\n * ```ts\n * // middleware.ts / proxy.ts\n * import { createSessionCookieGuard } from \"@buildspacestudio/sdk/next\";\n *\n * export const proxy = createSessionCookieGuard({ redirectTo: \"/\" });\n * export const config = { matcher: [\"/dashboard/:path*\"] };\n * ```\n */\nexport function createSessionCookieGuard(options?: {\n  /** Where to send signed-out users. Defaults to `/`. */\n  redirectTo?: string;\n}): (request: Request) => Response | undefined {\n  return (request: Request): Response | undefined => {\n    if (getSessionToken(request)) {\n      return;\n    }\n\n    const target = new URL(options?.redirectTo ?? \"/\", new URL(request.url).origin);\n    return Response.redirect(target.toString(), 307);\n  };\n}\n"]}

package/dist/notifications/index.d.cts

@@ -1,4 +1,4 @@
-import { H as HttpTransport } from '../http-U-zzKmFF.cjs';
+import { H as HttpTransport } from '../http-D2gXpNpr.cjs';
 
 /** Options for sending a custom email. */
 interface SendOptions {

package/dist/notifications/index.d.ts

@@ -1,4 +1,4 @@
-import { H as HttpTransport } from '../http-U-zzKmFF.js';
+import { H as HttpTransport } from '../http-D2gXpNpr.js';
 
 /** Options for sending a custom email. */
 interface SendOptions {

package/dist/react/index.cjs

@@ -0,0 +1,120 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  BuildspaceProvider: () => BuildspaceProvider,
+  useAuth: () => useAuth,
+  useBuildspaceClient: () => useBuildspaceClient,
+  useSession: () => useSession,
+  useTrack: () => useTrack
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+var BuildspaceContext = (0, import_react.createContext)({
+  client: null,
+  loading: false,
+  signIn: () => void 0,
+  signOut: () => Promise.resolve(),
+  signUp: () => void 0,
+  user: null
+});
+function browserLocation() {
+  const location = globalThis.location;
+  return location ?? null;
+}
+function BuildspaceProvider({
+  callbackPath = "/api/auth/callback",
+  children,
+  client,
+  initialUser = null,
+  logoutPath = "/api/auth/logout",
+  signedOutRedirect = "/"
+}) {
+  const [user, setUser] = (0, import_react.useState)(initialUser);
+  const signIn = (0, import_react.useCallback)(() => {
+    const location = browserLocation();
+    if (!location) {
+      return;
+    }
+    location.href = client.auth.getSignInUrl({
+      redirectUri: `${location.origin}${callbackPath}`
+    });
+  }, [client, callbackPath]);
+  const signUp = (0, import_react.useCallback)(() => {
+    const location = browserLocation();
+    if (!location) {
+      return;
+    }
+    location.href = client.auth.getSignUpUrl({
+      redirectUri: `${location.origin}${callbackPath}`
+    });
+  }, [client, callbackPath]);
+  const signOut = (0, import_react.useCallback)(async () => {
+    await fetch(logoutPath, { method: "POST" });
+    setUser(null);
+    const location = browserLocation();
+    if (location) {
+      location.href = signedOutRedirect;
+    }
+  }, [logoutPath, signedOutRedirect]);
+  const value = (0, import_react.useMemo)(
+    () => ({ client, loading: false, signIn, signOut, signUp, user }),
+    [client, signIn, signOut, signUp, user]
+  );
+  return (0, import_react.createElement)(BuildspaceContext, { value }, children);
+}
+function useAuth() {
+  const { client: _client, ...auth } = (0, import_react.useContext)(BuildspaceContext);
+  return auth;
+}
+function useSession() {
+  const { loading, user } = (0, import_react.useContext)(BuildspaceContext);
+  return { loading, user };
+}
+function useBuildspaceClient() {
+  const { client } = (0, import_react.useContext)(BuildspaceContext);
+  if (!client) {
+    throw new Error("useBuildspaceClient must be used inside <BuildspaceProvider>.");
+  }
+  return client;
+}
+function useTrack() {
+  const { client, user } = (0, import_react.useContext)(BuildspaceContext);
+  return (0, import_react.useCallback)(
+    (event, properties) => {
+      try {
+        client?.events.track(event, properties, user?.id);
+      } catch {
+      }
+    },
+    [client, user?.id]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BuildspaceProvider,
+  useAuth,
+  useBuildspaceClient,
+  useSession,
+  useTrack
+});
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { createContext, createElement, useCallback, useContext, useMemo, useState } from \"react\";\nimport type { AuthUser } from \"../auth\";\nimport type { BuildspaceClient } from \"../client\";\n\n/**\n * React bindings for the Buildspace client SDK.\n *\n * Wrap your app in {@link BuildspaceProvider} (pass a client created with\n * `createClient()` from `@buildspacestudio/sdk/client` and, optionally, the\n * server-resolved user for a flash-free first paint), then read auth state\n * with {@link useAuth}/{@link useSession} and track events with\n * {@link useTrack}.\n *\n * @example\n * ```tsx\n * // app/layout.tsx (Server Component)\n * const session = await getSession(getServerClient(), await cookies());\n * <Providers initialUser={session?.user ?? null}>{children}</Providers>\n *\n * // components/providers.tsx (\"use client\")\n * <BuildspaceProvider client={getBrowserClient()} initialUser={initialUser}>\n *   {children}\n * </BuildspaceProvider>\n * ```\n */\n\n/** Auth state and actions exposed by {@link useAuth}. */\nexport interface BuildspaceAuthState {\n  /** True while the session is being resolved client-side. */\n  loading: boolean;\n  /** Redirect the browser to the Buildspace sign-in page. */\n  signIn: () => void;\n  /** Log out: POST the logout route, clear local state, and go home. */\n  signOut: () => Promise<void>;\n  /** Redirect the browser to the Buildspace sign-up page. */\n  signUp: () => void;\n  /** The signed-in user, or `null`. */\n  user: AuthUser | null;\n}\n\ninterface BuildspaceContextValue extends BuildspaceAuthState {\n  client: BuildspaceClient | null;\n}\n\nconst BuildspaceContext = createContext<BuildspaceContextValue>({\n  client: null,\n  loading: false,\n  signIn: () => undefined,\n  signOut: () => Promise.resolve(),\n  signUp: () => undefined,\n  user: null,\n});\n\nfunction browserLocation(): { href: string; origin: string } | null {\n  const location = (globalThis as { location?: { href: string; origin: string } }).location;\n  return location ?? null;\n}\n\n/** Options for {@link BuildspaceProvider}. */\nexport interface BuildspaceProviderProps {\n  /** Path of your OAuth callback route. Defaults to `/api/auth/callback`. */\n  callbackPath?: string;\n  children: ReactNode;\n  /** A client SDK instance (`createClient(\"bs_pub_...\")`). */\n  client: BuildspaceClient;\n  /**\n   * The server-resolved user (from `getSession()` in a Server Component).\n   * Pass it so the first client render already knows who is signed in.\n   */\n  initialUser?: AuthUser | null;\n  /** Path of your logout route. Defaults to `/api/auth/logout`. */\n  logoutPath?: string;\n  /** Where to send the user after sign-out. Defaults to `/`. */\n  signedOutRedirect?: string;\n}\n\n/**\n * Provides Buildspace auth state and the client SDK to the React tree.\n *\n * Must render inside a client boundary (`\"use client\"`).\n */\nexport function BuildspaceProvider({\n  callbackPath = \"/api/auth/callback\",\n  children,\n  client,\n  initialUser = null,\n  logoutPath = \"/api/auth/logout\",\n  signedOutRedirect = \"/\",\n}: BuildspaceProviderProps) {\n  const [user, setUser] = useState<AuthUser | null>(initialUser);\n\n  const signIn = useCallback(() => {\n    const location = browserLocation();\n    if (!location) {\n      return;\n    }\n\n    location.href = client.auth.getSignInUrl({\n      redirectUri: `${location.origin}${callbackPath}`,\n    });\n  }, [client, callbackPath]);\n\n  const signUp = useCallback(() => {\n    const location = browserLocation();\n    if (!location) {\n      return;\n    }\n\n    location.href = client.auth.getSignUpUrl({\n      redirectUri: `${location.origin}${callbackPath}`,\n    });\n  }, [client, callbackPath]);\n\n  const signOut = useCallback(async () => {\n    await fetch(logoutPath, { method: \"POST\" });\n    setUser(null);\n    const location = browserLocation();\n    if (location) {\n      location.href = signedOutRedirect;\n    }\n  }, [logoutPath, signedOutRedirect]);\n\n  const value = useMemo<BuildspaceContextValue>(\n    () => ({ client, loading: false, signIn, signOut, signUp, user }),\n    [client, signIn, signOut, signUp, user]\n  );\n\n  return createElement(BuildspaceContext, { value }, children);\n}\n\n/** Auth state and actions: `{ user, loading, signIn, signUp, signOut }`. */\nexport function useAuth(): BuildspaceAuthState {\n  const { client: _client, ...auth } = useContext(BuildspaceContext);\n  return auth;\n}\n\n/** The current session's user: `{ user, loading }`. */\nexport function useSession(): { loading: boolean; user: AuthUser | null } {\n  const { loading, user } = useContext(BuildspaceContext);\n  return { loading, user };\n}\n\n/** The client SDK instance passed to {@link BuildspaceProvider}. */\nexport function useBuildspaceClient(): BuildspaceClient {\n  const { client } = useContext(BuildspaceContext);\n  if (!client) {\n    throw new Error(\"useBuildspaceClient must be used inside <BuildspaceProvider>.\");\n  }\n\n  return client;\n}\n\n/**\n * Fire-and-forget analytics tracking bound to the signed-in user.\n *\n * Wraps the batched client events namespace; analytics never throw and never\n * block the UI.\n *\n * @example\n * ```tsx\n * const track = useTrack();\n * <button onClick={() => track(\"upgrade.clicked\", { plan: \"pro\" })} />\n * ```\n */\nexport function useTrack(): (event: string, properties?: Record<string, unknown>) => void {\n  const { client, user } = useContext(BuildspaceContext);\n\n  return useCallback(\n    (event: string, properties?: Record<string, unknown>) => {\n      try {\n        client?.events.track(event, properties, user?.id);\n      } catch {\n        // Analytics must never break the app.\n      }\n    },\n    [client, user?.id]\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,mBAAyF;AA4CzF,IAAM,wBAAoB,4BAAsC;AAAA,EAC9D,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ,MAAM;AAAA,EACd,SAAS,MAAM,QAAQ,QAAQ;AAAA,EAC/B,QAAQ,MAAM;AAAA,EACd,MAAM;AACR,CAAC;AAED,SAAS,kBAA2D;AAClE,QAAM,WAAY,WAA+D;AACjF,SAAO,YAAY;AACrB;AAyBO,SAAS,mBAAmB;AAAA,EACjC,eAAe;AAAA,EACf;AAAA,EACA;AAAA,EACA,cAAc;AAAA,EACd,aAAa;AAAA,EACb,oBAAoB;AACtB,GAA4B;AAC1B,QAAM,CAAC,MAAM,OAAO,QAAI,uBAA0B,WAAW;AAE7D,QAAM,aAAS,0BAAY,MAAM;AAC/B,UAAM,WAAW,gBAAgB;AACjC,QAAI,CAAC,UAAU;AACb;AAAA,IACF;AAEA,aAAS,OAAO,OAAO,KAAK,aAAa;AAAA,MACvC,aAAa,GAAG,SAAS,MAAM,GAAG,YAAY;AAAA,IAChD,CAAC;AAAA,EACH,GAAG,CAAC,QAAQ,YAAY,CAAC;AAEzB,QAAM,aAAS,0BAAY,MAAM;AAC/B,UAAM,WAAW,gBAAgB;AACjC,QAAI,CAAC,UAAU;AACb;AAAA,IACF;AAEA,aAAS,OAAO,OAAO,KAAK,aAAa;AAAA,MACvC,aAAa,GAAG,SAAS,MAAM,GAAG,YAAY;AAAA,IAChD,CAAC;AAAA,EACH,GAAG,CAAC,QAAQ,YAAY,CAAC;AAEzB,QAAM,cAAU,0BAAY,YAAY;AACtC,UAAM,MAAM,YAAY,EAAE,QAAQ,OAAO,CAAC;AAC1C,YAAQ,IAAI;AACZ,UAAM,WAAW,gBAAgB;AACjC,QAAI,UAAU;AACZ,eAAS,OAAO;AAAA,IAClB;AAAA,EACF,GAAG,CAAC,YAAY,iBAAiB,CAAC;AAElC,QAAM,YAAQ;AAAA,IACZ,OAAO,EAAE,QAAQ,SAAS,OAAO,QAAQ,SAAS,QAAQ,KAAK;AAAA,IAC/D,CAAC,QAAQ,QAAQ,SAAS,QAAQ,IAAI;AAAA,EACxC;AAEA,aAAO,4BAAc,mBAAmB,EAAE,MAAM,GAAG,QAAQ;AAC7D;AAGO,SAAS,UAA+B;AAC7C,QAAM,EAAE,QAAQ,SAAS,GAAG,KAAK,QAAI,yBAAW,iBAAiB;AACjE,SAAO;AACT;AAGO,SAAS,aAA0D;AACxE,QAAM,EAAE,SAAS,KAAK,QAAI,yBAAW,iBAAiB;AACtD,SAAO,EAAE,SAAS,KAAK;AACzB;AAGO,SAAS,sBAAwC;AACtD,QAAM,EAAE,OAAO,QAAI,yBAAW,iBAAiB;AAC/C,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,+DAA+D;AAAA,EACjF;AAEA,SAAO;AACT;AAcO,SAAS,WAA0E;AACxF,QAAM,EAAE,QAAQ,KAAK,QAAI,yBAAW,iBAAiB;AAErD,aAAO;AAAA,IACL,CAAC,OAAe,eAAyC;AACvD,UAAI;AACF,gBAAQ,OAAO,MAAM,OAAO,YAAY,MAAM,EAAE;AAAA,MAClD,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,IACA,CAAC,QAAQ,MAAM,EAAE;AAAA,EACnB;AACF;","names":[]}