@buildspacestudio/sdk 0.2.2 → 0.4.0

package/dist/react/index.d.ts

@@ -0,0 +1,567 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type ClientMode = "server" | "client";
+/** Configuration options for the server SDK (`new Buildspace()`). */
+interface BuildspaceConfig {
+    /** Base URL of the Buildspace API. Defaults to `"https://api.buildspace.studio"`. */
+    baseUrl?: string;
+    /** Custom `fetch` implementation (useful for testing or edge runtimes). */
+    fetch?: typeof fetch;
+    /** Base URL of the Buildspace login service. Defaults to `"https://login.buildspace.studio"`. */
+    loginUrl?: string;
+    /** API version string sent via the `X-Buildspace-Version` header. Defaults to `"2025-06-01"`. */
+    version?: string;
+}
+/** Configuration for client-side event batching behavior. */
+interface EventsBatchingConfig {
+    /** How often queued events are flushed to the API, in milliseconds. Defaults to `5000`. */
+    flushInterval?: number;
+    /** Maximum number of events to queue before an automatic flush. Defaults to `20`. */
+    maxBatchSize?: number;
+}
+/** Configuration options for the client SDK (`createClient()`). */
+interface BuildspaceClientConfig extends BuildspaceConfig {
+    /** Options for client-side event batching. */
+    events?: EventsBatchingConfig;
+}
+interface ResolvedConfig {
+    baseUrl: string;
+    fetch: typeof fetch;
+    loginUrl: string;
+    mode: ClientMode;
+    version: string;
+}
+
+/** Services available in the Buildspace platform. */
+type BuildspaceService = "auth" | "billing" | "events" | "notifications" | "storage";
+
+interface RequestOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+    keepalive?: boolean;
+    method?: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    service: BuildspaceService;
+}
+/**
+ * Low-level HTTP transport used internally by all SDK namespaces.
+ *
+ * Handles authentication headers, API versioning, session tokens,
+ * and consistent error mapping to {@link BuildspaceError}.
+ */
+declare class HttpTransport {
+    readonly baseUrl: string;
+    readonly fetcher: typeof fetch;
+    readonly key: string;
+    readonly loginUrl: string;
+    readonly mode: ClientMode;
+    readonly version: string;
+    private sessionToken;
+    constructor({ key, resolvedConfig }: {
+        key: string;
+        resolvedConfig: ResolvedConfig;
+    });
+    /** Remove the stored session token. */
+    clearSession(): void;
+    /** Return the current session token, or `null` if none is set. */
+    getSessionToken(): string | null;
+    /** Store a session token that will be sent as `X-Session-Token` on subsequent requests. */
+    setSession(sessionToken: string): void;
+    request<T>({ service, path, method, query, body, headers, keepalive, }: RequestOptions): Promise<T>;
+}
+
+/** Options for generating a sign-in URL. */
+interface SignInUrlOptions {
+    /** App slug to scope the login to a specific creator app. */
+    appSlug?: string;
+    /** Environment to authenticate against. */
+    env?: "dev" | "prod";
+    /** URL to redirect the user to after authentication completes. */
+    redirectUri: string;
+}
+/** Options for generating a sign-up URL. */
+interface SignUpUrlOptions {
+    /** App slug to scope the registration to a specific creator app. */
+    appSlug?: string;
+    /** Environment to authenticate against. */
+    env?: "dev" | "prod";
+    /** URL to redirect the user to after registration completes. */
+    redirectUri: string;
+}
+/**
+ * Client-side authentication methods for generating login URLs.
+ *
+ * Access via `buildspace.auth` on the client SDK, or `buildspace.authClient`
+ * on the server SDK when you need to generate URLs from server-side code.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@buildspacestudio/sdk/client";
+ *
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
+ *
+ * const signInUrl = buildspace.auth.getSignInUrl({
+ *   redirectUri: "https://yourapp.com/auth/callback",
+ * });
+ *
+ * // Use in a link or redirect
+ * window.location.href = signInUrl;
+ * ```
+ */
+declare class AuthClientNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Build a URL that redirects the user to the Buildspace sign-in page.
+     *
+     * After the user authenticates, they are redirected back to `redirectUri`
+     * with a `?code=` parameter that can be exchanged for tokens via
+     * `buildspace.auth.handleCallback()` on the server.
+     *
+     * @param opts - Sign-in URL options.
+     * @returns The full sign-in URL as a string.
+     */
+    getSignInUrl(opts: SignInUrlOptions): string;
+    /**
+     * Build a URL that redirects the user to the Buildspace sign-up page.
+     *
+     * Works identically to {@link getSignInUrl} but directs the user to the
+     * registration flow instead.
+     *
+     * @param opts - Sign-up URL options.
+     * @returns The full sign-up URL as a string.
+     */
+    getSignUpUrl(opts: SignUpUrlOptions): string;
+}
+
+/** A Buildspace user returned from auth endpoints. */
+interface AuthUser {
+    /** The user's email address. */
+    email: string;
+    /** Unique user identifier. */
+    id: string;
+    /** The user's display name, or `null` if not set. */
+    name: string | null;
+}
+
+interface BillingProduct {
+    active: boolean;
+    createdAt: string;
+    description: string | null;
+    id: string;
+    name: string;
+}
+interface BillingPrice {
+    active: boolean;
+    amountCents: number | null;
+    createdAt: string;
+    currency: string;
+    id: string;
+    interval: string | null;
+    lookupKey: string | null;
+    productId: string;
+    productName: string;
+    type: "one_time" | "recurring" | "metered";
+}
+interface CreateClientCheckoutOptions {
+    cancelUrl: string;
+    checkoutRequestId?: string;
+    lookupKey?: string;
+    metadata?: Record<string, string>;
+    priceId?: string;
+    quantity?: number;
+    successUrl: string;
+}
+interface BillingSubscriptionResponse {
+    subscription: {
+        cancelAtPeriodEnd: boolean;
+        currentPeriodEnd: string | null;
+        id: string;
+        status: string;
+    } | null;
+}
+interface BillingEntitlementsResponse {
+    active: boolean;
+    subscription: {
+        currentPeriodEnd: string | null;
+        id: string;
+        status: string;
+    } | null;
+}
+type BillingMode = "test" | "live";
+type BillingConfigStatus = "disabled" | "setup_required" | "active" | "paused";
+interface BillingStatusResponse {
+    enabled: boolean;
+    mode: BillingMode | null;
+    status: BillingConfigStatus | null;
+    testMode: boolean;
+}
+interface CreateClientPortalSessionOptions {
+    returnUrl: string;
+}
+
+declare class BillingClientNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Read whether billing is enabled for the app environment tied to this
+     * publishable key, and whether the connected Stripe account is in test or
+     * live mode.
+     *
+     * Render a "Test mode" banner in your app whenever `testMode` is true.
+     */
+    getStatus(): Promise<BillingStatusResponse>;
+    /**
+     * List the active billing products for the app environment tied to this
+     * publishable key.
+     */
+    listProducts(): Promise<{
+        products: BillingProduct[];
+    }>;
+    /**
+     * List the active billing prices for the app environment tied to this
+     * publishable key.
+     */
+    listPrices(): Promise<{
+        prices: BillingPrice[];
+    }>;
+    /**
+     * Create a Checkout Session for the signed-in browser user and redirect to
+     * the Stripe-hosted Checkout page.
+     *
+     * This method depends on a Buildspace session being available through
+     * `setSession()` or your app's authenticated request context.
+     */
+    redirectToCheckout(opts: CreateClientCheckoutOptions): Promise<void>;
+    /**
+     * Open the Stripe-hosted customer portal for the signed-in browser user.
+     */
+    redirectToPortal(opts: CreateClientPortalSessionOptions): Promise<void>;
+    /**
+     * Discoverable alias for redirectToPortal — opens the Stripe-hosted customer
+     * portal so the signed-in user can manage their subscription, payment method,
+     * and invoices.
+     */
+    manageSubscription(opts: CreateClientPortalSessionOptions): Promise<void>;
+    /**
+     * Read the current subscription state for the signed-in browser user.
+     */
+    getSubscription(): Promise<BillingSubscriptionResponse>;
+    /**
+     * Read the current paid entitlement state for the signed-in browser user.
+     */
+    getEntitlements(): Promise<BillingEntitlementsResponse>;
+}
+
+/**
+ * Client-side event tracking with automatic batching.
+ *
+ * Events are queued in memory and flushed to the API in batches,
+ * either on a timer or when the batch size limit is reached.
+ *
+ * Access via `buildspace.events` on the client SDK.
+ *
+ * @example
+ * ```ts
+ * // Fire and forget — events are queued automatically
+ * buildspace.events.track("button.clicked", { label: "upgrade" });
+ *
+ * // Flush before page unload
+ * await buildspace.events.flush();
+ *
+ * // Graceful shutdown (clears timer, flushes remaining)
+ * await buildspace.events.shutdown();
+ * ```
+ */
+declare class EventsClientNamespace {
+    private readonly queue;
+    private readonly transport;
+    private timer;
+    constructor(transport: HttpTransport, config?: {
+        flushInterval?: number;
+        maxBatchSize?: number;
+    });
+    private readonly maxBatchSize;
+    /**
+     * Queue an event for batched delivery.
+     *
+     * This method is synchronous and returns immediately. Events are
+     * automatically flushed when the batch size is reached or on the
+     * configured interval.
+     *
+     * @param event - Event name, e.g. `"button.clicked"`.
+     * @param properties - Arbitrary key-value data to attach.
+     * @param actorId - Identifier of the user or entity that triggered the event.
+     */
+    track(event: string, properties?: Record<string, unknown>, actorId?: string): void;
+    /**
+     * Send all queued events to the API immediately.
+     *
+     * If the flush fails, events are re-queued for the next attempt.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the automatic flush timer and send any remaining events.
+     *
+     * Call this during app shutdown or cleanup to ensure no events are lost.
+     */
+    shutdown(): Promise<void>;
+}
+
+/** Metadata for a stored object. */
+interface StorageObject {
+    /** MIME type of the stored file. */
+    contentType: string;
+    /** ISO 8601 timestamp of when the object was created. */
+    createdAt: string;
+    /** Unique object identifier. */
+    id: string;
+    /** Storage key/path of the object. */
+    key: string;
+    /** File size in bytes. */
+    size: number;
+    /** ID of the user who uploaded the object, or `null` if uploaded via server key. */
+    uploadedBy: string | null;
+}
+
+/** Options for uploading a file from the client. */
+interface UploadOptions {
+    /** MIME type override. If omitted, inferred from the `File` object or defaults to `"application/octet-stream"`. */
+    contentType?: string;
+    /** Storage path/key for the file, e.g. `"avatars/user-123.png"`. */
+    path: string;
+}
+/** Result of a successful client-side file upload. */
+interface UploadResponse {
+    /** The resolved storage key. */
+    key: string;
+    /** File size in bytes. */
+    size: number;
+    /** Signed download URL for the uploaded file. */
+    url: string;
+}
+/** Result of requesting a signed download URL. */
+interface GetUrlResponse {
+    /** URL lifetime in seconds, if applicable. */
+    expiresIn?: number;
+    /** The storage key of the object. */
+    key: string;
+    /** The signed download URL. */
+    url: string;
+}
+/**
+ * Client-side storage methods for uploading and managing files.
+ *
+ * Access via `buildspace.storage` on the client SDK.
+ *
+ * @example
+ * ```ts
+ * // Upload a file (handles signed URL + PUT automatically)
+ * const { key, url } = await buildspace.storage.upload(file, {
+ *   path: "avatars/user-123.png",
+ * });
+ *
+ * // Get a download URL for an existing file
+ * const { url } = await buildspace.storage.getUrl(key);
+ * ```
+ */
+declare class StorageClientNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Upload a `File` or `Blob` to Buildspace storage.
+     *
+     * This method handles the full upload flow:
+     * 1. Requests a pre-signed upload URL from the API
+     * 2. Uploads the file directly to the storage provider
+     * 3. Returns a signed download URL for the uploaded file
+     *
+     * @param file - The file or blob to upload.
+     * @param opts - Upload options including the storage path.
+     * @returns The storage key, file size, and a signed download URL.
+     *
+     * @throws {BuildspaceError} If the upload URL request or the direct upload fails.
+     */
+    upload(file: File | Blob, opts: UploadOptions): Promise<UploadResponse>;
+    /**
+     * Get a time-limited signed URL for downloading a stored file.
+     *
+     * @param key - The storage key of the object.
+     * @param opts - Optional settings.
+     * @param opts.expiresIn - URL lifetime in seconds.
+     */
+    getUrl(key: string, opts?: {
+        expiresIn?: number;
+    }): Promise<GetUrlResponse>;
+    /**
+     * List stored objects, optionally filtered by key prefix.
+     *
+     * @param prefix - Only return objects whose key starts with this prefix.
+     * @param opts - Pagination options.
+     */
+    list(prefix?: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        objects: StorageObject[];
+    }>;
+    /**
+     * Delete a stored object by key.
+     *
+     * @param key - The storage key of the object to delete.
+     */
+    delete(key: string): Promise<void>;
+}
+
+/**
+ * Buildspace client SDK — use with a publishable key (`bs_pub_*`).
+ *
+ * Provides client-safe access to auth URL generation, event tracking
+ * (with automatic batching), and file uploads. For server-side usage
+ * with full API access, use `new Buildspace()` from `@buildspacestudio/sdk`.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@buildspacestudio/sdk/client";
+ *
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
+ *
+ * // Generate a sign-in URL
+ * const url = buildspace.auth.getSignInUrl({
+ *   redirectUri: "https://yourapp.com/auth/callback",
+ * });
+ *
+ * // Track an event (fire and forget)
+ * buildspace.events.track("button.clicked", { label: "upgrade" });
+ *
+ * // Upload a file
+ * const { key, url } = await buildspace.storage.upload(file, {
+ *   path: "avatars/user-123.png",
+ * });
+ * ```
+ */
+declare class BuildspaceClient {
+    private readonly transport;
+    private readonly config;
+    private _auth;
+    private _billing;
+    private _events;
+    private _storage;
+    /**
+     * Create a new client SDK instance.
+     *
+     * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).
+     * @param config - Optional configuration overrides.
+     */
+    constructor(publishableKey: string, config?: BuildspaceClientConfig);
+    /** Client-side auth: sign-in and sign-up URL generation. */
+    get auth(): AuthClientNamespace;
+    /** Client-side event tracking with automatic batching. */
+    get events(): EventsClientNamespace;
+    /** Client-side billing: list prices and redirect to Checkout or Portal. */
+    get billing(): BillingClientNamespace;
+    /** Client-side file storage: uploads, downloads, listing, deletion. */
+    get storage(): StorageClientNamespace;
+    /**
+     * Notifications are server-only and not available on the client SDK.
+     *
+     * @throws {BuildspaceError} Always throws — use the server SDK for notifications.
+     */
+    get notifications(): never;
+    /** Clear the stored session token. */
+    clearSession(): void;
+    /**
+     * Set a session token that will be sent as `X-Session-Token` on all
+     * subsequent API requests.
+     *
+     * @param sessionToken - The session token to attach to requests.
+     */
+    setSession(sessionToken: string): void;
+}
+
+/**
+ * React bindings for the Buildspace client SDK.
+ *
+ * Wrap your app in {@link BuildspaceProvider} (pass a client created with
+ * `createClient()` from `@buildspacestudio/sdk/client` and, optionally, the
+ * server-resolved user for a flash-free first paint), then read auth state
+ * with {@link useAuth}/{@link useSession} and track events with
+ * {@link useTrack}.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx (Server Component)
+ * const session = await getSession(getServerClient(), await cookies());
+ * <Providers initialUser={session?.user ?? null}>{children}</Providers>
+ *
+ * // components/providers.tsx ("use client")
+ * <BuildspaceProvider client={getBrowserClient()} initialUser={initialUser}>
+ *   {children}
+ * </BuildspaceProvider>
+ * ```
+ */
+/** Auth state and actions exposed by {@link useAuth}. */
+interface BuildspaceAuthState {
+    /** True while the session is being resolved client-side. */
+    loading: boolean;
+    /** Redirect the browser to the Buildspace sign-in page. */
+    signIn: () => void;
+    /** Log out: POST the logout route, clear local state, and go home. */
+    signOut: () => Promise<void>;
+    /** Redirect the browser to the Buildspace sign-up page. */
+    signUp: () => void;
+    /** The signed-in user, or `null`. */
+    user: AuthUser | null;
+}
+interface BuildspaceContextValue extends BuildspaceAuthState {
+    client: BuildspaceClient | null;
+}
+/** Options for {@link BuildspaceProvider}. */
+interface BuildspaceProviderProps {
+    /** Path of your OAuth callback route. Defaults to `/api/auth/callback`. */
+    callbackPath?: string;
+    children: ReactNode;
+    /** A client SDK instance (`createClient("bs_pub_...")`). */
+    client: BuildspaceClient;
+    /**
+     * The server-resolved user (from `getSession()` in a Server Component).
+     * Pass it so the first client render already knows who is signed in.
+     */
+    initialUser?: AuthUser | null;
+    /** Path of your logout route. Defaults to `/api/auth/logout`. */
+    logoutPath?: string;
+    /** Where to send the user after sign-out. Defaults to `/`. */
+    signedOutRedirect?: string;
+}
+/**
+ * Provides Buildspace auth state and the client SDK to the React tree.
+ *
+ * Must render inside a client boundary (`"use client"`).
+ */
+declare function BuildspaceProvider({ callbackPath, children, client, initialUser, logoutPath, signedOutRedirect, }: BuildspaceProviderProps): react.FunctionComponentElement<react.ProviderProps<BuildspaceContextValue>>;
+/** Auth state and actions: `{ user, loading, signIn, signUp, signOut }`. */
+declare function useAuth(): BuildspaceAuthState;
+/** The current session's user: `{ user, loading }`. */
+declare function useSession(): {
+    loading: boolean;
+    user: AuthUser | null;
+};
+/** The client SDK instance passed to {@link BuildspaceProvider}. */
+declare function useBuildspaceClient(): BuildspaceClient;
+/**
+ * Fire-and-forget analytics tracking bound to the signed-in user.
+ *
+ * Wraps the batched client events namespace; analytics never throw and never
+ * block the UI.
+ *
+ * @example
+ * ```tsx
+ * const track = useTrack();
+ * <button onClick={() => track("upgrade.clicked", { plan: "pro" })} />
+ * ```
+ */
+declare function useTrack(): (event: string, properties?: Record<string, unknown>) => void;
+
+export { type BuildspaceAuthState, BuildspaceProvider, type BuildspaceProviderProps, useAuth, useBuildspaceClient, useSession, useTrack };

package/dist/react/index.js

@@ -0,0 +1,92 @@
+"use client";
+
+// src/react/index.ts
+import { createContext, createElement, useCallback, useContext, useMemo, useState } from "react";
+var BuildspaceContext = 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] = useState(initialUser);
+  const signIn = useCallback(() => {
+    const location = browserLocation();
+    if (!location) {
+      return;
+    }
+    location.href = client.auth.getSignInUrl({
+      redirectUri: `${location.origin}${callbackPath}`
+    });
+  }, [client, callbackPath]);
+  const signUp = useCallback(() => {
+    const location = browserLocation();
+    if (!location) {
+      return;
+    }
+    location.href = client.auth.getSignUpUrl({
+      redirectUri: `${location.origin}${callbackPath}`
+    });
+  }, [client, callbackPath]);
+  const signOut = useCallback(async () => {
+    await fetch(logoutPath, { method: "POST" });
+    setUser(null);
+    const location = browserLocation();
+    if (location) {
+      location.href = signedOutRedirect;
+    }
+  }, [logoutPath, signedOutRedirect]);
+  const value = useMemo(
+    () => ({ client, loading: false, signIn, signOut, signUp, user }),
+    [client, signIn, signOut, signUp, user]
+  );
+  return createElement(BuildspaceContext, { value }, children);
+}
+function useAuth() {
+  const { client: _client, ...auth } = useContext(BuildspaceContext);
+  return auth;
+}
+function useSession() {
+  const { loading, user } = useContext(BuildspaceContext);
+  return { loading, user };
+}
+function useBuildspaceClient() {
+  const { client } = useContext(BuildspaceContext);
+  if (!client) {
+    throw new Error("useBuildspaceClient must be used inside <BuildspaceProvider>.");
+  }
+  return client;
+}
+function useTrack() {
+  const { client, user } = useContext(BuildspaceContext);
+  return useCallback(
+    (event, properties) => {
+      try {
+        client?.events.track(event, properties, user?.id);
+      } catch {
+      }
+    },
+    [client, user?.id]
+  );
+}
+export {
+  BuildspaceProvider,
+  useAuth,
+  useBuildspaceClient,
+  useSession,
+  useTrack
+};
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.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":";;;AACA,SAAS,eAAe,eAAe,aAAa,YAAY,SAAS,gBAAgB;AA4CzF,IAAM,oBAAoB,cAAsC;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,IAAI,SAA0B,WAAW;AAE7D,QAAM,SAAS,YAAY,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,SAAS,YAAY,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,UAAU,YAAY,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,QAAQ;AAAA,IACZ,OAAO,EAAE,QAAQ,SAAS,OAAO,QAAQ,SAAS,QAAQ,KAAK;AAAA,IAC/D,CAAC,QAAQ,QAAQ,SAAS,QAAQ,IAAI;AAAA,EACxC;AAEA,SAAO,cAAc,mBAAmB,EAAE,MAAM,GAAG,QAAQ;AAC7D;AAGO,SAAS,UAA+B;AAC7C,QAAM,EAAE,QAAQ,SAAS,GAAG,KAAK,IAAI,WAAW,iBAAiB;AACjE,SAAO;AACT;AAGO,SAAS,aAA0D;AACxE,QAAM,EAAE,SAAS,KAAK,IAAI,WAAW,iBAAiB;AACtD,SAAO,EAAE,SAAS,KAAK;AACzB;AAGO,SAAS,sBAAwC;AACtD,QAAM,EAAE,OAAO,IAAI,WAAW,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,IAAI,WAAW,iBAAiB;AAErD,SAAO;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":[]}