@buildspacestudio/sdk 0.2.1 → 0.3.0

package/dist/client/index.cjs

@@ -0,0 +1,428 @@
+'use strict';
+
+// src/auth/client.ts
+var AuthClientNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * 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) {
+    const url = new URL("/sign-in", this.transport.loginUrl);
+    if (opts.appSlug) {
+      url.searchParams.set("app", opts.appSlug);
+    }
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    url.searchParams.set("client_id", this.transport.key);
+    if (opts.env) {
+      url.searchParams.set("env", opts.env);
+    }
+    return url.toString();
+  }
+  /**
+   * 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) {
+    const url = new URL("/sign-up", this.transport.loginUrl);
+    if (opts.appSlug) {
+      url.searchParams.set("app", opts.appSlug);
+    }
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    url.searchParams.set("client_id", this.transport.key);
+    if (opts.env) {
+      url.searchParams.set("env", opts.env);
+    }
+    return url.toString();
+  }
+};
+
+// 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/config.ts
+var DEFAULT_BASE_URL = "https://api.buildspace.studio";
+var DEFAULT_LOGIN_URL = "https://login.buildspace.studio";
+var DEFAULT_API_VERSION = "2025-06-01";
+function resolveConfig(mode, config = {}) {
+  return {
+    mode,
+    baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+    loginUrl: config.loginUrl ?? DEFAULT_LOGIN_URL,
+    version: config.version ?? DEFAULT_API_VERSION,
+    fetch: config.fetch ?? fetch
+  };
+}
+function formatMode(mode) {
+  return mode === "server" ? "server SDK" : "client SDK";
+}
+function validateApiKey({ mode, key }) {
+  if (!key) {
+    throw new Error(`Missing API key. The ${formatMode(mode)} requires a valid Buildspace key.`);
+  }
+  if (mode === "server" && !key.startsWith("bs_sec_")) {
+    throw new Error(
+      "The server SDK requires a secret key (bs_sec_*). Use createClient() from '@buildspacestudio/sdk/client' for browser usage with publishable keys."
+    );
+  }
+  if (mode === "client" && !key.startsWith("bs_pub_")) {
+    throw new Error(
+      "The client SDK requires a publishable key (bs_pub_*). Use new Buildspace() from '@buildspacestudio/sdk' for server usage with secret keys."
+    );
+  }
+}
+
+// src/events/client.ts
+var EventsClientNamespace = class {
+  queue = [];
+  transport;
+  timer = null;
+  constructor(transport, config = {}) {
+    this.transport = transport;
+    const flushInterval = config.flushInterval ?? 5e3;
+    this.maxBatchSize = config.maxBatchSize ?? 20;
+    this.timer = setInterval(() => {
+      this.flush().catch(() => {
+      });
+    }, flushInterval);
+  }
+  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, properties, actorId) {
+    this.queue.push({
+      event,
+      properties,
+      actor_id: actorId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (this.queue.length >= this.maxBatchSize) {
+      this.flush().catch(() => {
+      });
+    }
+  }
+  /**
+   * Send all queued events to the API immediately.
+   *
+   * If the flush fails, events are re-queued for the next attempt.
+   */
+  async flush() {
+    if (this.queue.length === 0) {
+      return;
+    }
+    const batch = this.queue.splice(0, this.queue.length);
+    try {
+      await this.transport.request({
+        service: "events",
+        path: "/v1/events/batch",
+        method: "POST",
+        keepalive: true,
+        body: { events: batch }
+      });
+    } catch {
+      this.queue.unshift(...batch);
+      throw new Error("Failed to flush events batch.");
+    }
+  }
+  /**
+   * Stop the automatic flush timer and send any remaining events.
+   *
+   * Call this during app shutdown or cleanup to ensure no events are lost.
+   */
+  async shutdown() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+};
+
+// src/http.ts
+var HttpTransport = class {
+  baseUrl;
+  fetcher;
+  key;
+  loginUrl;
+  mode;
+  version;
+  sessionToken = null;
+  constructor({ key, resolvedConfig }) {
+    validateApiKey({ mode: resolvedConfig.mode, key });
+    this.key = key;
+    this.mode = resolvedConfig.mode;
+    this.baseUrl = resolvedConfig.baseUrl;
+    this.loginUrl = resolvedConfig.loginUrl;
+    this.version = resolvedConfig.version;
+    this.fetcher = resolvedConfig.fetch;
+  }
+  /** Remove the stored session token. */
+  clearSession() {
+    this.sessionToken = null;
+  }
+  /** Return the current session token, or `null` if none is set. */
+  getSessionToken() {
+    return this.sessionToken;
+  }
+  /** Store a session token that will be sent as `X-Session-Token` on subsequent requests. */
+  setSession(sessionToken) {
+    this.sessionToken = sessionToken;
+  }
+  async request({
+    service,
+    path,
+    method = "GET",
+    query,
+    body,
+    headers,
+    keepalive
+  }) {
+    const url = new URL(path, this.baseUrl);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const response = await this.fetcher(url.toString(), {
+      method,
+      keepalive,
+      headers: {
+        Authorization: `Bearer ${this.key}`,
+        "Content-Type": "application/json",
+        "X-Buildspace-Version": this.version,
+        ...this.sessionToken ? { "X-Session-Token": this.sessionToken } : {},
+        ...headers
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      throw new BuildspaceError({
+        service,
+        status: response.status,
+        code: payload?.code ?? `${service}/http-${response.status}`,
+        message: payload?.error ?? payload?.message ?? response.statusText
+      });
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return response.json();
+  }
+};
+
+// src/storage/client.ts
+var StorageClientNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * 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.
+   */
+  async upload(file, opts) {
+    const contentType = opts.contentType ?? (file instanceof File ? file.type : "application/octet-stream");
+    const signed = await this.transport.request({
+      service: "storage",
+      path: "/v1/storage/upload",
+      method: "POST",
+      body: {
+        path: opts.path,
+        content_type: contentType,
+        size: file.size
+      }
+    });
+    const response = await this.transport.fetcher(signed.upload_url, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      body: file
+    });
+    if (!response.ok) {
+      throw new BuildspaceError({
+        service: "storage",
+        status: response.status,
+        code: "storage/upload-failed",
+        message: `Direct upload failed: ${response.statusText}`
+      });
+    }
+    const { url } = await this.getUrl(signed.key);
+    return {
+      key: signed.key,
+      size: file.size,
+      url
+    };
+  }
+  /**
+   * 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, opts) {
+    return this.transport.request({
+      service: "storage",
+      path: "/v1/storage/url",
+      query: {
+        key,
+        expires_in: opts?.expiresIn
+      }
+    });
+  }
+  /**
+   * 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, opts) {
+    return this.transport.request({
+      service: "storage",
+      path: "/v1/storage/objects",
+      query: {
+        prefix,
+        limit: opts?.limit,
+        offset: opts?.offset
+      }
+    });
+  }
+  /**
+   * Delete a stored object by key.
+   *
+   * @param key - The storage key of the object to delete.
+   */
+  async delete(key) {
+    await this.transport.request({
+      service: "storage",
+      path: "/v1/storage/object",
+      method: "DELETE",
+      body: { key }
+    });
+  }
+};
+
+// src/client/index.ts
+var BuildspaceClient = class {
+  transport;
+  config;
+  _auth = null;
+  _events = null;
+  _storage = null;
+  /**
+   * Create a new client SDK instance.
+   *
+   * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).
+   * @param config - Optional configuration overrides.
+   */
+  constructor(publishableKey, config = {}) {
+    this.config = config;
+    this.transport = new HttpTransport({
+      key: publishableKey,
+      resolvedConfig: resolveConfig("client", config)
+    });
+  }
+  /** Client-side auth: sign-in and sign-up URL generation. */
+  get auth() {
+    this._auth ??= new AuthClientNamespace(this.transport);
+    return this._auth;
+  }
+  /** Client-side event tracking with automatic batching. */
+  get events() {
+    this._events ??= new EventsClientNamespace(this.transport, this.config.events);
+    return this._events;
+  }
+  /** Client-side file storage: uploads, downloads, listing, deletion. */
+  get storage() {
+    this._storage ??= new StorageClientNamespace(this.transport);
+    return this._storage;
+  }
+  /**
+   * Notifications are server-only and not available on the client SDK.
+   *
+   * @throws {BuildspaceError} Always throws — use the server SDK for notifications.
+   */
+  get notifications() {
+    throw new BuildspaceError({
+      service: "notifications",
+      status: 400,
+      code: "notifications/server-only",
+      message: "Notifications require a secret key. Use the server SDK via new Buildspace() from '@buildspacestudio/sdk'."
+    });
+  }
+  /** Clear the stored session token. */
+  clearSession() {
+    this.transport.clearSession();
+  }
+  /**
+   * 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) {
+    this.transport.setSession(sessionToken);
+  }
+};
+function createClient(publishableKey, config = {}) {
+  return new BuildspaceClient(publishableKey, config);
+}
+
+exports.BuildspaceClient = BuildspaceClient;
+exports.createClient = createClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/client.ts","../../src/errors.ts","../../src/config.ts","../../src/events/client.ts","../../src/http.ts","../../src/storage/client.ts","../../src/client/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { HttpTransport } from \"../http\";\n\n/** Options for generating a sign-in URL. */\nexport interface SignInUrlOptions {\n  /** App slug to scope the login to a specific creator app. */\n  appSlug?: string;\n  /** Environment to authenticate against. */\n  env?: \"dev\" | \"prod\";\n  /** URL to redirect the user to after authentication completes. */\n  redirectUri: string;\n}\n\n/** Options for generating a sign-up URL. */\nexport interface SignUpUrlOptions {\n  /** App slug to scope the registration to a specific creator app. */\n  appSlug?: string;\n  /** Environment to authenticate against. */\n  env?: \"dev\" | \"prod\";\n  /** URL to redirect the user to after registration completes. */\n  redirectUri: string;\n}\n\n/**\n * Client-side authentication methods for generating login URLs.\n *\n * Access via `buildspace.auth` on the client SDK, or `buildspace.authClient`\n * on the server SDK when you need to generate URLs from server-side code.\n *\n * @example\n * ```ts\n * import { createClient } from \"@buildspacestudio/sdk/client\";\n *\n * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);\n *\n * const signInUrl = buildspace.auth.getSignInUrl({\n *   redirectUri: \"https://yourapp.com/auth/callback\",\n * });\n *\n * // Use in a link or redirect\n * window.location.href = signInUrl;\n * ```\n */\nexport class AuthClientNamespace {\n  private readonly transport: HttpTransport;\n\n  constructor(transport: HttpTransport) {\n    this.transport = transport;\n  }\n\n  /**\n   * Build a URL that redirects the user to the Buildspace sign-in page.\n   *\n   * After the user authenticates, they are redirected back to `redirectUri`\n   * with a `?code=` parameter that can be exchanged for tokens via\n   * `buildspace.auth.handleCallback()` on the server.\n   *\n   * @param opts - Sign-in URL options.\n   * @returns The full sign-in URL as a string.\n   */\n  getSignInUrl(opts: SignInUrlOptions): string {\n    const url = new URL(\"/sign-in\", this.transport.loginUrl);\n\n    if (opts.appSlug) {\n      url.searchParams.set(\"app\", opts.appSlug);\n    }\n\n    url.searchParams.set(\"redirect_uri\", opts.redirectUri);\n    url.searchParams.set(\"client_id\", this.transport.key);\n\n    if (opts.env) {\n      url.searchParams.set(\"env\", opts.env);\n    }\n\n    return url.toString();\n  }\n\n  /**\n   * Build a URL that redirects the user to the Buildspace sign-up page.\n   *\n   * Works identically to {@link getSignInUrl} but directs the user to the\n   * registration flow instead.\n   *\n   * @param opts - Sign-up URL options.\n   * @returns The full sign-up URL as a string.\n   */\n  getSignUpUrl(opts: SignUpUrlOptions): string {\n    const url = new URL(\"/sign-up\", this.transport.loginUrl);\n\n    if (opts.appSlug) {\n      url.searchParams.set(\"app\", opts.appSlug);\n    }\n\n    url.searchParams.set(\"redirect_uri\", opts.redirectUri);\n    url.searchParams.set(\"client_id\", this.transport.key);\n\n    if (opts.env) {\n      url.searchParams.set(\"env\", opts.env);\n    }\n\n    return url.toString();\n  }\n}\n","/** Services available in the Buildspace platform. */\nexport type BuildspaceService = \"auth\" | \"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","export const DEFAULT_BASE_URL = \"https://api.buildspace.studio\";\nexport const DEFAULT_LOGIN_URL = \"https://login.buildspace.studio\";\nexport const DEFAULT_API_VERSION = \"2025-06-01\";\n\nexport type ClientMode = \"server\" | \"client\";\n\n/** Configuration options for the server SDK (`new Buildspace()`). */\nexport interface BuildspaceConfig {\n  /** Base URL of the Buildspace API. Defaults to `\"https://api.buildspace.studio\"`. */\n  baseUrl?: string;\n  /** Custom `fetch` implementation (useful for testing or edge runtimes). */\n  fetch?: typeof fetch;\n  /** Base URL of the Buildspace login service. Defaults to `\"https://login.buildspace.studio\"`. */\n  loginUrl?: string;\n  /** API version string sent via the `X-Buildspace-Version` header. Defaults to `\"2025-06-01\"`. */\n  version?: string;\n}\n\n/** Configuration for client-side event batching behavior. */\nexport interface EventsBatchingConfig {\n  /** How often queued events are flushed to the API, in milliseconds. Defaults to `5000`. */\n  flushInterval?: number;\n  /** Maximum number of events to queue before an automatic flush. Defaults to `20`. */\n  maxBatchSize?: number;\n}\n\n/** Configuration options for the client SDK (`createClient()`). */\nexport interface BuildspaceClientConfig extends BuildspaceConfig {\n  /** Options for client-side event batching. */\n  events?: EventsBatchingConfig;\n}\n\nexport interface ResolvedConfig {\n  baseUrl: string;\n  fetch: typeof fetch;\n  loginUrl: string;\n  mode: ClientMode;\n  version: string;\n}\n\nexport function resolveConfig(mode: ClientMode, config: BuildspaceConfig = {}): ResolvedConfig {\n  return {\n    mode,\n    baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,\n    loginUrl: config.loginUrl ?? DEFAULT_LOGIN_URL,\n    version: config.version ?? DEFAULT_API_VERSION,\n    fetch: config.fetch ?? fetch,\n  };\n}\n\nfunction formatMode(mode: ClientMode): string {\n  return mode === \"server\" ? \"server SDK\" : \"client SDK\";\n}\n\nexport function validateApiKey({ mode, key }: { key: string; mode: ClientMode }): void {\n  if (!key) {\n    throw new Error(`Missing API key. The ${formatMode(mode)} requires a valid Buildspace key.`);\n  }\n\n  if (mode === \"server\" && !key.startsWith(\"bs_sec_\")) {\n    throw new Error(\n      \"The server SDK requires a secret key (bs_sec_*). Use createClient() from '@buildspacestudio/sdk/client' for browser usage with publishable keys.\"\n    );\n  }\n\n  if (mode === \"client\" && !key.startsWith(\"bs_pub_\")) {\n    throw new Error(\n      \"The client SDK requires a publishable key (bs_pub_*). Use new Buildspace() from '@buildspacestudio/sdk' for server usage with secret keys.\"\n    );\n  }\n}\n","import type { HttpTransport } from \"../http\";\n\ninterface QueuedEvent {\n  actor_id?: string;\n  event: string;\n  properties?: Record<string, unknown>;\n  timestamp: string;\n}\n\n/**\n * Client-side event tracking with automatic batching.\n *\n * Events are queued in memory and flushed to the API in batches,\n * either on a timer or when the batch size limit is reached.\n *\n * Access via `buildspace.events` on the client SDK.\n *\n * @example\n * ```ts\n * // Fire and forget — events are queued automatically\n * buildspace.events.track(\"button.clicked\", { label: \"upgrade\" });\n *\n * // Flush before page unload\n * await buildspace.events.flush();\n *\n * // Graceful shutdown (clears timer, flushes remaining)\n * await buildspace.events.shutdown();\n * ```\n */\nexport class EventsClientNamespace {\n  private readonly queue: QueuedEvent[] = [];\n  private readonly transport: HttpTransport;\n  private timer: ReturnType<typeof setInterval> | null = null;\n\n  constructor(\n    transport: HttpTransport,\n    config: { flushInterval?: number; maxBatchSize?: number } = {}\n  ) {\n    this.transport = transport;\n    const flushInterval = config.flushInterval ?? 5000;\n    this.maxBatchSize = config.maxBatchSize ?? 20;\n    this.timer = setInterval(() => {\n      this.flush().catch(() => {\n        // best effort flush for background timer\n      });\n    }, flushInterval);\n  }\n\n  private readonly maxBatchSize: number;\n\n  /**\n   * Queue an event for batched delivery.\n   *\n   * This method is synchronous and returns immediately. Events are\n   * automatically flushed when the batch size is reached or on the\n   * configured interval.\n   *\n   * @param event - Event name, e.g. `\"button.clicked\"`.\n   * @param properties - Arbitrary key-value data to attach.\n   * @param actorId - Identifier of the user or entity that triggered the event.\n   */\n  track(event: string, properties?: Record<string, unknown>, actorId?: string): void {\n    this.queue.push({\n      event,\n      properties,\n      actor_id: actorId,\n      timestamp: new Date().toISOString(),\n    });\n\n    if (this.queue.length >= this.maxBatchSize) {\n      this.flush().catch(() => {\n        // best effort flush on max batch size\n      });\n    }\n  }\n\n  /**\n   * Send all queued events to the API immediately.\n   *\n   * If the flush fails, events are re-queued for the next attempt.\n   */\n  async flush(): Promise<void> {\n    if (this.queue.length === 0) {\n      return;\n    }\n\n    const batch = this.queue.splice(0, this.queue.length);\n\n    try {\n      await this.transport.request<void>({\n        service: \"events\",\n        path: \"/v1/events/batch\",\n        method: \"POST\",\n        keepalive: true,\n        body: { events: batch },\n      });\n    } catch {\n      this.queue.unshift(...batch);\n      throw new Error(\"Failed to flush events batch.\");\n    }\n  }\n\n  /**\n   * Stop the automatic flush timer and send any remaining events.\n   *\n   * Call this during app shutdown or cleanup to ensure no events are lost.\n   */\n  async shutdown(): Promise<void> {\n    if (this.timer) {\n      clearInterval(this.timer);\n      this.timer = null;\n    }\n\n    await this.flush();\n  }\n}\n","import { type ClientMode, type ResolvedConfig, validateApiKey } from \"./config\";\nimport { BuildspaceError, type BuildspaceService } from \"./errors\";\n\ninterface RequestOptions {\n  body?: unknown;\n  headers?: Record<string, string>;\n  keepalive?: boolean;\n  method?: string;\n  path: string;\n  query?: Record<string, string | number | boolean | undefined>;\n  service: BuildspaceService;\n}\n\n/**\n * Low-level HTTP transport used internally by all SDK namespaces.\n *\n * Handles authentication headers, API versioning, session tokens,\n * and consistent error mapping to {@link BuildspaceError}.\n */\nexport class HttpTransport {\n  readonly baseUrl: string;\n  readonly fetcher: typeof fetch;\n  readonly key: string;\n  readonly loginUrl: string;\n  readonly mode: ClientMode;\n  readonly version: string;\n  private sessionToken: string | null = null;\n\n  constructor({ key, resolvedConfig }: { key: string; resolvedConfig: ResolvedConfig }) {\n    validateApiKey({ mode: resolvedConfig.mode, key });\n    this.key = key;\n    this.mode = resolvedConfig.mode;\n    this.baseUrl = resolvedConfig.baseUrl;\n    this.loginUrl = resolvedConfig.loginUrl;\n    this.version = resolvedConfig.version;\n    this.fetcher = resolvedConfig.fetch;\n  }\n\n  /** Remove the stored session token. */\n  clearSession(): void {\n    this.sessionToken = null;\n  }\n\n  /** Return the current session token, or `null` if none is set. */\n  getSessionToken(): string | null {\n    return this.sessionToken;\n  }\n\n  /** Store a session token that will be sent as `X-Session-Token` on subsequent requests. */\n  setSession(sessionToken: string): void {\n    this.sessionToken = sessionToken;\n  }\n\n  async request<T>({\n    service,\n    path,\n    method = \"GET\",\n    query,\n    body,\n    headers,\n    keepalive,\n  }: RequestOptions): Promise<T> {\n    const url = new URL(path, this.baseUrl);\n\n    if (query) {\n      for (const [key, value] of Object.entries(query)) {\n        if (value !== undefined) {\n          url.searchParams.set(key, String(value));\n        }\n      }\n    }\n\n    const response = await this.fetcher(url.toString(), {\n      method,\n      keepalive,\n      headers: {\n        Authorization: `Bearer ${this.key}`,\n        \"Content-Type\": \"application/json\",\n        \"X-Buildspace-Version\": this.version,\n        ...(this.sessionToken ? { \"X-Session-Token\": this.sessionToken } : {}),\n        ...headers,\n      },\n      body: body === undefined ? undefined : JSON.stringify(body),\n    });\n\n    if (!response.ok) {\n      const payload = (await response.json().catch(() => null)) as {\n        code?: string;\n        error?: string;\n        message?: string;\n      } | null;\n\n      throw new BuildspaceError({\n        service,\n        status: response.status,\n        code: payload?.code ?? `${service}/http-${response.status}`,\n        message: payload?.error ?? payload?.message ?? response.statusText,\n      });\n    }\n\n    if (response.status === 204) {\n      return undefined as T;\n    }\n\n    return response.json() as Promise<T>;\n  }\n}\n","import { BuildspaceError } from \"../errors\";\nimport type { HttpTransport } from \"../http\";\nimport type { StorageObject } from \"./server\";\n\n/** Options for uploading a file from the client. */\nexport interface UploadOptions {\n  /** MIME type override. If omitted, inferred from the `File` object or defaults to `\"application/octet-stream\"`. */\n  contentType?: string;\n  /** Storage path/key for the file, e.g. `\"avatars/user-123.png\"`. */\n  path: string;\n}\n\n/** Result of a successful client-side file upload. */\nexport interface UploadResponse {\n  /** The resolved storage key. */\n  key: string;\n  /** File size in bytes. */\n  size: number;\n  /** Signed download URL for the uploaded file. */\n  url: string;\n}\n\n/** Result of requesting a signed download URL. */\nexport interface GetUrlResponse {\n  /** URL lifetime in seconds, if applicable. */\n  expiresIn?: number;\n  /** The storage key of the object. */\n  key: string;\n  /** The signed download URL. */\n  url: string;\n}\n\n/**\n * Client-side storage methods for uploading and managing files.\n *\n * Access via `buildspace.storage` on the client SDK.\n *\n * @example\n * ```ts\n * // Upload a file (handles signed URL + PUT automatically)\n * const { key, url } = await buildspace.storage.upload(file, {\n *   path: \"avatars/user-123.png\",\n * });\n *\n * // Get a download URL for an existing file\n * const { url } = await buildspace.storage.getUrl(key);\n * ```\n */\nexport class StorageClientNamespace {\n  private readonly transport: HttpTransport;\n\n  constructor(transport: HttpTransport) {\n    this.transport = transport;\n  }\n\n  /**\n   * Upload a `File` or `Blob` to Buildspace storage.\n   *\n   * This method handles the full upload flow:\n   * 1. Requests a pre-signed upload URL from the API\n   * 2. Uploads the file directly to the storage provider\n   * 3. Returns a signed download URL for the uploaded file\n   *\n   * @param file - The file or blob to upload.\n   * @param opts - Upload options including the storage path.\n   * @returns The storage key, file size, and a signed download URL.\n   *\n   * @throws {BuildspaceError} If the upload URL request or the direct upload fails.\n   */\n  async upload(file: File | Blob, opts: UploadOptions): Promise<UploadResponse> {\n    const contentType =\n      opts.contentType ?? (file instanceof File ? file.type : \"application/octet-stream\");\n\n    const signed = await this.transport.request<{ key: string; upload_url: string }>({\n      service: \"storage\",\n      path: \"/v1/storage/upload\",\n      method: \"POST\",\n      body: {\n        path: opts.path,\n        content_type: contentType,\n        size: file.size,\n      },\n    });\n\n    const response = await this.transport.fetcher(signed.upload_url, {\n      method: \"PUT\",\n      headers: { \"Content-Type\": contentType },\n      body: file,\n    });\n\n    if (!response.ok) {\n      throw new BuildspaceError({\n        service: \"storage\",\n        status: response.status,\n        code: \"storage/upload-failed\",\n        message: `Direct upload failed: ${response.statusText}`,\n      });\n    }\n\n    const { url } = await this.getUrl(signed.key);\n\n    return {\n      key: signed.key,\n      size: file.size,\n      url,\n    };\n  }\n\n  /**\n   * Get a time-limited signed URL for downloading a stored file.\n   *\n   * @param key - The storage key of the object.\n   * @param opts - Optional settings.\n   * @param opts.expiresIn - URL lifetime in seconds.\n   */\n  getUrl(key: string, opts?: { expiresIn?: number }): Promise<GetUrlResponse> {\n    return this.transport.request<GetUrlResponse>({\n      service: \"storage\",\n      path: \"/v1/storage/url\",\n      query: {\n        key,\n        expires_in: opts?.expiresIn,\n      },\n    });\n  }\n\n  /**\n   * List stored objects, optionally filtered by key prefix.\n   *\n   * @param prefix - Only return objects whose key starts with this prefix.\n   * @param opts - Pagination options.\n   */\n  list(\n    prefix?: string,\n    opts?: { limit?: number; offset?: number }\n  ): Promise<{ objects: StorageObject[] }> {\n    return this.transport.request<{ objects: StorageObject[] }>({\n      service: \"storage\",\n      path: \"/v1/storage/objects\",\n      query: {\n        prefix,\n        limit: opts?.limit,\n        offset: opts?.offset,\n      },\n    });\n  }\n\n  /**\n   * Delete a stored object by key.\n   *\n   * @param key - The storage key of the object to delete.\n   */\n  async delete(key: string): Promise<void> {\n    await this.transport.request<void>({\n      service: \"storage\",\n      path: \"/v1/storage/object\",\n      method: \"DELETE\",\n      body: { key },\n    });\n  }\n}\n","import { AuthClientNamespace } from \"../auth\";\nimport { type BuildspaceClientConfig, resolveConfig } from \"../config\";\nimport { BuildspaceError } from \"../errors\";\nimport { EventsClientNamespace } from \"../events\";\nimport { HttpTransport } from \"../http\";\nimport { StorageClientNamespace } from \"../storage\";\n\n/**\n * Buildspace client SDK — use with a publishable key (`bs_pub_*`).\n *\n * Provides client-safe access to auth URL generation, event tracking\n * (with automatic batching), and file uploads. For server-side usage\n * with full API access, use `new Buildspace()` from `@buildspacestudio/sdk`.\n *\n * @example\n * ```ts\n * import { createClient } from \"@buildspacestudio/sdk/client\";\n *\n * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);\n *\n * // Generate a sign-in URL\n * const url = buildspace.auth.getSignInUrl({\n *   redirectUri: \"https://yourapp.com/auth/callback\",\n * });\n *\n * // Track an event (fire and forget)\n * buildspace.events.track(\"button.clicked\", { label: \"upgrade\" });\n *\n * // Upload a file\n * const { key, url } = await buildspace.storage.upload(file, {\n *   path: \"avatars/user-123.png\",\n * });\n * ```\n */\nclass BuildspaceClient {\n  private readonly transport: HttpTransport;\n  private readonly config: BuildspaceClientConfig;\n  private _auth: AuthClientNamespace | null = null;\n  private _events: EventsClientNamespace | null = null;\n  private _storage: StorageClientNamespace | null = null;\n\n  /**\n   * Create a new client SDK instance.\n   *\n   * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).\n   * @param config - Optional configuration overrides.\n   */\n  constructor(publishableKey: string, config: BuildspaceClientConfig = {}) {\n    this.config = config;\n    this.transport = new HttpTransport({\n      key: publishableKey,\n      resolvedConfig: resolveConfig(\"client\", config),\n    });\n  }\n\n  /** Client-side auth: sign-in and sign-up URL generation. */\n  get auth(): AuthClientNamespace {\n    this._auth ??= new AuthClientNamespace(this.transport);\n    return this._auth;\n  }\n\n  /** Client-side event tracking with automatic batching. */\n  get events(): EventsClientNamespace {\n    this._events ??= new EventsClientNamespace(this.transport, this.config.events);\n    return this._events;\n  }\n\n  /** Client-side file storage: uploads, downloads, listing, deletion. */\n  get storage(): StorageClientNamespace {\n    this._storage ??= new StorageClientNamespace(this.transport);\n    return this._storage;\n  }\n\n  /**\n   * Notifications are server-only and not available on the client SDK.\n   *\n   * @throws {BuildspaceError} Always throws — use the server SDK for notifications.\n   */\n  get notifications(): never {\n    throw new BuildspaceError({\n      service: \"notifications\",\n      status: 400,\n      code: \"notifications/server-only\",\n      message:\n        \"Notifications require a secret key. Use the server SDK via new Buildspace() from '@buildspacestudio/sdk'.\",\n    });\n  }\n\n  /** Clear the stored session token. */\n  clearSession(): void {\n    this.transport.clearSession();\n  }\n\n  /**\n   * Set a session token that will be sent as `X-Session-Token` on all\n   * subsequent API requests.\n   *\n   * @param sessionToken - The session token to attach to requests.\n   */\n  setSession(sessionToken: string): void {\n    this.transport.setSession(sessionToken);\n  }\n}\n\n/**\n * Create a Buildspace client SDK instance.\n *\n * Preferred over `new BuildspaceClient()` for a more concise API.\n *\n * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).\n * @param config - Optional configuration overrides.\n *\n * @example\n * ```ts\n * import { createClient } from \"@buildspacestudio/sdk/client\";\n *\n * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);\n * ```\n */\nexport function createClient(\n  publishableKey: string,\n  config: BuildspaceClientConfig = {}\n): BuildspaceClient {\n  return new BuildspaceClient(publishableKey, config);\n}\n\nexport { BuildspaceClient };\n"]}

package/dist/client/index.d.cts

@@ -0,0 +1,85 @@
+import { A as AuthClientNamespace } from '../client-DqWXAwCr.cjs';
+import { a as BuildspaceClientConfig } from '../http-U-zzKmFF.cjs';
+import { E as EventsClientNamespace } from '../client-C67hy1kt.cjs';
+import { StorageClientNamespace } from '../storage/index.cjs';
+
+/**
+ * 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 _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 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;
+}
+/**
+ * Create a Buildspace client SDK instance.
+ *
+ * Preferred over `new BuildspaceClient()` for a more concise API.
+ *
+ * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).
+ * @param config - Optional configuration overrides.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@buildspacestudio/sdk/client";
+ *
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
+ * ```
+ */
+declare function createClient(publishableKey: string, config?: BuildspaceClientConfig): BuildspaceClient;
+
+export { BuildspaceClient, createClient };

package/dist/client/index.d.ts

@@ -1,7 +1,8 @@
-import { AuthClientNamespace } from "../auth";
-import { type BuildspaceClientConfig } from "../config";
-import { EventsClientNamespace } from "../events";
-import { StorageClientNamespace } from "../storage";
+import { A as AuthClientNamespace } from '../client-BH7LbrKM.js';
+import { a as BuildspaceClientConfig } from '../http-U-zzKmFF.js';
+import { E as EventsClientNamespace } from '../client-Dlif1JBf.js';
+import { StorageClientNamespace } from '../storage/index.js';
+
 /**
  * Buildspace client SDK — use with a publishable key (`bs_pub_*`).
  *
@@ -79,6 +80,6 @@ declare class BuildspaceClient {
  * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
  * ```
  */
-export declare function createClient(publishableKey: string, config?: BuildspaceClientConfig): BuildspaceClient;
-export { BuildspaceClient };
-//# sourceMappingURL=index.d.ts.map
+declare function createClient(publishableKey: string, config?: BuildspaceClientConfig): BuildspaceClient;
+
+export { BuildspaceClient, createClient };