@buildspacestudio/sdk 0.2.2 → 0.4.0

package/dist/client/index.js

@@ -1,114 +1,555 @@
-import { AuthClientNamespace } from "../auth";
-import { resolveConfig } from "../config";
-import { BuildspaceError } from "../errors";
-import { EventsClientNamespace } from "../events";
-import { HttpTransport } from "../http";
-import { StorageClientNamespace } from "../storage";
-/**
- * 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",
- * });
- * ```
- */
-class BuildspaceClient {
-    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),
-        });
+// 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);
     }
-    /** Client-side auth: sign-in and sign-up URL generation. */
-    get auth() {
-        this._auth ??= new AuthClientNamespace(this.transport);
-        return this._auth;
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    url.searchParams.set("client_id", this.transport.key);
+    if (opts.env) {
+      url.searchParams.set("env", opts.env);
     }
-    /** Client-side event tracking with automatic batching. */
-    get events() {
-        this._events ??= new EventsClientNamespace(this.transport, this.config.events);
-        return this._events;
+    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);
     }
-    /** Client-side file storage: uploads, downloads, listing, deletion. */
-    get storage() {
-        this._storage ??= new StorageClientNamespace(this.transport);
-        return this._storage;
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    url.searchParams.set("client_id", this.transport.key);
+    if (opts.env) {
+      url.searchParams.set("env", opts.env);
     }
-    /**
-     * 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'.",
-        });
+    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/billing/shared.ts
+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/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(() => {
+      });
     }
-    /** Clear the stored session token. */
-    clearSession() {
-        this.transport.clearSession();
+  }
+  /**
+   * 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;
     }
-    /**
-     * 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);
+    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;
+  _billing = 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 billing: list prices and redirect to Checkout or Portal. */
+  get billing() {
+    this._billing ??= new BillingClientNamespace(this.transport);
+    return this._billing;
+  }
+  /** 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);
 }
-/**
- * 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!);
- * ```
- */
-export function createClient(publishableKey, config = {}) {
-    return new BuildspaceClient(publishableKey, config);
-}
-export { BuildspaceClient };
+
+export { BuildspaceClient, createClient };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map