@buildspacestudio/sdk 0.2.2 → 0.4.0

package/dist/index.cjs

@@ -0,0 +1,1029 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// 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/auth/server.ts
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0"]);
+var FORWARDED_HOST_RE = /host="?([^;"]+)"?/i;
+var FORWARDED_PROTO_RE = /proto="?([^;"]+)"?/i;
+function getFirstForwardedValue(value) {
+  if (!value) {
+    return null;
+  }
+  return value.split(",").map((part) => part.trim()).find(Boolean) ?? null;
+}
+function stripPort(host) {
+  if (host.startsWith("[") && host.includes("]")) {
+    return host.slice(1, host.indexOf("]"));
+  }
+  const colonIndex = host.indexOf(":");
+  return colonIndex >= 0 ? host.slice(0, colonIndex) : host;
+}
+function isPrivateIpv4(hostname) {
+  const parts = hostname.split(".").map((part) => Number(part));
+  if (parts.length !== 4 || parts.some((part) => Number.isNaN(part) || part < 0 || part > 255)) {
+    return false;
+  }
+  return parts[0] === 10 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 || parts[0] === 192 && parts[1] === 168;
+}
+function isInternalHostname(hostname) {
+  const normalized = hostname.toLowerCase();
+  return LOOPBACK_HOSTS.has(normalized) || normalized.endsWith(".local") || normalized.endsWith(".internal") || isPrivateIpv4(normalized);
+}
+function getForwardedOrigin(request) {
+  const forwarded = getFirstForwardedValue(request.headers.get("forwarded"));
+  if (forwarded) {
+    const forwardedHost2 = forwarded.match(FORWARDED_HOST_RE)?.[1]?.trim();
+    const forwardedProto2 = forwarded.match(FORWARDED_PROTO_RE)?.[1]?.trim();
+    if (forwardedHost2 && forwardedProto2) {
+      return `${forwardedProto2}://${forwardedHost2}`;
+    }
+  }
+  const forwardedHost = getFirstForwardedValue(request.headers.get("x-forwarded-host"));
+  const forwardedProto = getFirstForwardedValue(request.headers.get("x-forwarded-proto"));
+  if (forwardedHost && forwardedProto) {
+    return `${forwardedProto}://${forwardedHost}`;
+  }
+  return null;
+}
+function resolveDefaultRedirectUri(request, url) {
+  if (!(request instanceof Request)) {
+    return `${url.origin}${url.pathname}`;
+  }
+  const forwardedOrigin = getForwardedOrigin(request);
+  if (forwardedOrigin) {
+    return `${forwardedOrigin}${url.pathname}`;
+  }
+  const hostHeader = request.headers.get("host")?.trim();
+  if (hostHeader && !isInternalHostname(stripPort(hostHeader))) {
+    return `${url.protocol}//${hostHeader}${url.pathname}`;
+  }
+  if (!isInternalHostname(url.hostname)) {
+    return `${url.origin}${url.pathname}`;
+  }
+  return `${url.origin}${url.pathname}`;
+}
+var AuthServerNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Retrieve the session associated with a token.
+   *
+   * Returns the {@link AuthSession} if valid, or `null` if the token is
+   * expired, revoked, or invalid (401/404).
+   *
+   * @throws {BuildspaceError} On unexpected server errors (5xx, network issues).
+   */
+  async getSession(sessionToken) {
+    try {
+      return await this.transport.request({
+        service: "auth",
+        path: "/v1/auth/session",
+        headers: { "X-Session-Token": sessionToken }
+      });
+    } catch (error) {
+      if (error instanceof BuildspaceError && (error.status === 401 || error.status === 404)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Exchange an OAuth authorization code for tokens.
+   *
+   * Extracts the `code` query parameter from the callback URL and exchanges
+   * it with the Buildspace API for an access token and user info.
+   *
+   * @param request - The incoming callback request. Accepts a `Request` object,
+   *   a `URL`, or a raw URL string containing the `?code=` parameter.
+   * @param opts - Optional settings.
+   * @param opts.redirectUri - Override the redirect URI sent to the token endpoint.
+   *   Defaults to the origin + pathname of the callback URL.
+   * @returns The token response containing `access_token`, `expires_in`, and `user`.
+   *
+   * @throws {BuildspaceError} If the code exchange fails (invalid code, expired, etc.).
+   *
+   * @example
+   * ```ts
+   * // Next.js Route Handler
+   * export async function GET(request: Request) {
+   *   const { access_token, user } = await buildspace.auth.handleCallback(request);
+   *   // Store access_token as a session cookie
+   * }
+   * ```
+   */
+  handleCallback(request, opts) {
+    let url;
+    if (typeof request === "string") {
+      url = new URL(request);
+    } else if (request instanceof URL) {
+      url = request;
+    } else {
+      url = new URL(request.url);
+    }
+    const code = url.searchParams.get("code");
+    if (!code) {
+      throw new BuildspaceError({
+        service: "auth",
+        status: 400,
+        code: "auth/missing-code",
+        message: "No auth code found in callback URL. Expected ?code= parameter."
+      });
+    }
+    const redirectUri = opts?.redirectUri ?? resolveDefaultRedirectUri(request, url);
+    return this.transport.request({
+      service: "auth",
+      path: "/v1/auth/token",
+      method: "POST",
+      body: {
+        code,
+        redirect_uri: redirectUri
+      }
+    });
+  }
+  /**
+   * Revoke a specific session token.
+   *
+   * @param sessionToken - The token to revoke.
+   * @throws {BuildspaceError} If the revocation fails.
+   */
+  async revokeSession(sessionToken) {
+    await this.transport.request({
+      service: "auth",
+      path: "/v1/auth/session",
+      method: "DELETE",
+      headers: { "X-Session-Token": sessionToken }
+    });
+  }
+  /**
+   * Sign the user out by revoking the session and clearing the SDK's stored token.
+   *
+   * If the session is already expired or not found, the error is silently
+   * ignored and the local session is still cleared.
+   *
+   * @param sessionToken - Token to revoke. If omitted, uses the token
+   *   previously set via `buildspace.setSession()`.
+   */
+  async signOut(sessionToken) {
+    const token = sessionToken ?? this.transport.getSessionToken();
+    try {
+      if (token) {
+        await this.revokeSession(token);
+      }
+    } catch (error) {
+      if (!(error instanceof BuildspaceError && error.service === "auth" && (error.status === 401 || error.status === 404))) {
+        throw error;
+      }
+    } finally {
+      this.transport.clearSession();
+    }
+  }
+};
+
+// src/billing/shared.ts
+function shouldShowTestBanner(status) {
+  return status.testMode;
+}
+function billingIdentityQuery(opts) {
+  return { app_user_id: opts?.appUserId, user_id: opts?.userId };
+}
+function checkoutRequestBody(opts) {
+  return {
+    app_user_id: "appUserId" in opts ? opts.appUserId : void 0,
+    cancel_url: opts.cancelUrl,
+    checkout_request_id: opts.checkoutRequestId,
+    lookup_key: opts.lookupKey,
+    metadata: opts.metadata,
+    price_id: opts.priceId,
+    quantity: opts.quantity,
+    success_url: opts.successUrl,
+    user_id: "userId" in opts ? opts.userId : void 0
+  };
+}
+function portalRequestBody(opts) {
+  return {
+    app_user_id: "appUserId" in opts ? opts.appUserId : void 0,
+    return_url: opts.returnUrl,
+    user_id: "userId" in opts ? opts.userId : void 0
+  };
+}
+
+// src/billing/client.ts
+function redirectTo(url) {
+  const browser = globalThis;
+  if (!browser.window?.location) {
+    throw new Error("redirectToCheckout can only be used in a browser environment");
+  }
+  browser.window.location.href = url;
+}
+var BillingClientNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * 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() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/status"
+    });
+  }
+  /**
+   * List the active billing products for the app environment tied to this
+   * publishable key.
+   */
+  listProducts() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/products"
+    });
+  }
+  /**
+   * List the active billing prices for the app environment tied to this
+   * publishable key.
+   */
+  listPrices() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/prices"
+    });
+  }
+  /**
+   * 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.
+   */
+  async redirectToCheckout(opts) {
+    const checkout = await this.transport.request({
+      service: "billing",
+      path: "/v1/billing/checkout",
+      method: "POST",
+      body: checkoutRequestBody(opts)
+    });
+    redirectTo(checkout.url);
+  }
+  /**
+   * Open the Stripe-hosted customer portal for the signed-in browser user.
+   */
+  async redirectToPortal(opts) {
+    const portal = await this.transport.request({
+      service: "billing",
+      path: "/v1/billing/portal",
+      method: "POST",
+      body: portalRequestBody(opts)
+    });
+    redirectTo(portal.url);
+  }
+  /**
+   * 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) {
+    return this.redirectToPortal(opts);
+  }
+  /**
+   * Read the current subscription state for the signed-in browser user.
+   */
+  getSubscription() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/subscription"
+    });
+  }
+  /**
+   * Read the current paid entitlement state for the signed-in browser user.
+   */
+  getEntitlements() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/entitlements"
+    });
+  }
+};
+
+// src/billing/server.ts
+var BillingServerNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Read whether billing is enabled for the app environment tied to this API
+   * 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() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/status"
+    });
+  }
+  /**
+   * List the active billing products configured for the app environment tied to
+   * this API key.
+   */
+  listProducts() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/products"
+    });
+  }
+  /**
+   * List the active billing prices configured for the app environment tied to
+   * this API key.
+   */
+  listPrices() {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/prices"
+    });
+  }
+  /**
+   * Create a Stripe Checkout Session on the creator's connected Stripe account.
+   *
+   * Use `userId` for Buildspace-authenticated users, or `appUserId` when your
+   * app uses its own auth system and you want Buildspace to track billing state
+   * against an app-defined user id.
+   */
+  createCheckout(opts) {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/checkout",
+      method: "POST",
+      body: checkoutRequestBody(opts)
+    });
+  }
+  /**
+   * Create a Stripe-hosted customer portal session for the specified billing
+   * identity.
+   */
+  createPortalSession(opts) {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/portal",
+      method: "POST",
+      body: portalRequestBody(opts)
+    });
+  }
+  /**
+   * Read the current subscription state for a Buildspace user or app-defined
+   * billing identity.
+   */
+  getSubscription(opts) {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/subscription",
+      query: billingIdentityQuery(opts)
+    });
+  }
+  /**
+   * Read the current paid entitlement state for a Buildspace user or app-defined
+   * billing identity.
+   */
+  getEntitlements(opts) {
+    return this.transport.request({
+      service: "billing",
+      path: "/v1/billing/entitlements",
+      query: billingIdentityQuery(opts)
+    });
+  }
+};
+
+// 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/events/server.ts
+var EventsServerNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Track a single event.
+   *
+   * @param event - Event name, e.g. `"user.signed_up"`.
+   * @param properties - Arbitrary key-value data to attach to the event.
+   * @param actorId - Identifier of the user or entity that triggered the event.
+   * @returns The ID of the created event.
+   */
+  track(event, properties, actorId) {
+    return this.transport.request({
+      service: "events",
+      path: "/v1/events",
+      method: "POST",
+      body: {
+        event,
+        properties,
+        actor_id: actorId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+  /**
+   * Track multiple events in a single request.
+   *
+   * Events without a `timestamp` are automatically timestamped.
+   *
+   * @param events - Array of events to track.
+   * @returns The count and IDs of created events.
+   */
+  batchTrack(events) {
+    return this.transport.request({
+      service: "events",
+      path: "/v1/events/batch",
+      method: "POST",
+      body: {
+        events: events.map((event) => ({
+          ...event,
+          timestamp: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      }
+    });
+  }
+};
+
+// 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/notifications/server.ts
+var NotificationsServerNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Send a custom email with inline HTML content.
+   *
+   * @param opts - Email content and recipient options.
+   * @returns The notification ID and optional provider message ID.
+   */
+  send(opts) {
+    return this.transport.request({
+      service: "notifications",
+      path: "/v1/notifications/send",
+      method: "POST",
+      body: {
+        to: opts.to,
+        subject: opts.subject,
+        html: opts.html,
+        text: opts.text,
+        reply_to: opts.replyTo,
+        metadata: opts.metadata
+      }
+    });
+  }
+  /**
+   * Send an email using a pre-configured template.
+   *
+   * Templates are created in the Buildspace Creator Studio.
+   *
+   * @param templateSlug - The slug of the template to use, e.g. `"welcome-email"`.
+   * @param opts - Recipient and template variable options.
+   * @returns The notification ID and optional provider message ID.
+   */
+  sendTemplate(templateSlug, opts) {
+    return this.transport.request({
+      service: "notifications",
+      path: "/v1/notifications/send-template",
+      method: "POST",
+      body: {
+        template: templateSlug,
+        to: opts.to,
+        variables: opts.variables,
+        metadata: opts.metadata
+      }
+    });
+  }
+};
+
+// 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/storage/server.ts
+var StorageServerNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Request a pre-signed URL for direct file upload.
+   *
+   * @param opts - Upload options including the storage key, content type, and file size.
+   * @returns The signed upload URL, the resolved key, and expiry time in seconds.
+   */
+  getUploadUrl(opts) {
+    return this.transport.request({
+      service: "storage",
+      path: "/v1/storage/upload",
+      method: "POST",
+      body: {
+        path: opts.key,
+        content_type: opts.contentType,
+        size: opts.size
+      }
+    });
+  }
+  /**
+   * 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. Uses server default if omitted.
+   */
+  getSignedUrl(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, e.g. `"avatars/"`.
+   * @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 }
+    });
+  }
+  /**
+   * Get current storage usage statistics for the app.
+   *
+   * @returns Byte counts and object count.
+   */
+  getUsage() {
+    return this.transport.request({
+      service: "storage",
+      path: "/v1/storage/usage"
+    });
+  }
+};
+
+// src/index.ts
+var Buildspace = class {
+  transport;
+  _auth = null;
+  _billing = null;
+  _events = null;
+  _notifications = null;
+  _publicAuth = null;
+  _storage = null;
+  /**
+   * Create a new server SDK instance.
+   *
+   * @param secretKey - Your Buildspace secret key (starts with `bs_sec_`).
+   * @param config - Optional configuration overrides.
+   */
+  constructor(secretKey, config = {}) {
+    this.transport = new HttpTransport({
+      key: secretKey,
+      resolvedConfig: resolveConfig("server", config)
+    });
+  }
+  /** Server-side auth: session verification, OAuth callback handling, sign-out. */
+  get auth() {
+    this._auth ??= new AuthServerNamespace(this.transport);
+    return this._auth;
+  }
+  /**
+   * Client-style auth helpers available on the server (e.g. generating sign-in URLs
+   * in server-rendered pages). For full server auth, use {@link auth}.
+   */
+  get authClient() {
+    this._publicAuth ??= new AuthClientNamespace(this.transport);
+    return this._publicAuth;
+  }
+  /** Server-side event tracking. */
+  get events() {
+    this._events ??= new EventsServerNamespace(this.transport);
+    return this._events;
+  }
+  /** Server-side billing: Checkout, Portal, subscriptions, and entitlements. */
+  get billing() {
+    this._billing ??= new BillingServerNamespace(this.transport);
+    return this._billing;
+  }
+  /** Server-side file storage: upload URLs, signed downloads, listing, deletion. */
+  get storage() {
+    this._storage ??= new StorageServerNamespace(this.transport);
+    return this._storage;
+  }
+  /** Server-side transactional email notifications. */
+  get notifications() {
+    this._notifications ??= new NotificationsServerNamespace(this.transport);
+    return this._notifications;
+  }
+  /** 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);
+  }
+};
+var src_default = Buildspace;
+
+exports.AuthClientNamespace = AuthClientNamespace;
+exports.AuthServerNamespace = AuthServerNamespace;
+exports.BillingClientNamespace = BillingClientNamespace;
+exports.BillingServerNamespace = BillingServerNamespace;
+exports.Buildspace = Buildspace;
+exports.BuildspaceError = BuildspaceError;
+exports.EventsClientNamespace = EventsClientNamespace;
+exports.EventsServerNamespace = EventsServerNamespace;
+exports.NotificationsServerNamespace = NotificationsServerNamespace;
+exports.StorageClientNamespace = StorageClientNamespace;
+exports.StorageServerNamespace = StorageServerNamespace;
+exports.default = src_default;
+exports.shouldShowTestBanner = shouldShowTestBanner;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map