@buildspacestudio/sdk 0.2.2 → 0.4.0

package/dist/server-CoPDzSUP.d.cts

@@ -0,0 +1,117 @@
+import { H as HttpTransport } from './http-D2gXpNpr.cjs';
+
+/** 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;
+}
+/**
+ * An active session for an authenticated user.
+ *
+ * Returned by {@link AuthServerNamespace.getSession}.
+ */
+interface AuthSession {
+    /** The app this session belongs to, or `null` for platform-level sessions. */
+    appId: string | null;
+    /** The authenticated user. */
+    user: AuthUser;
+}
+/**
+ * Token response returned after a successful OAuth callback exchange.
+ *
+ * Returned by {@link AuthServerNamespace.handleCallback}.
+ */
+interface TokenResponse {
+    /** The access token to use for authenticated requests. */
+    access_token: string;
+    /** Token lifetime in seconds. */
+    expires_in: number;
+    /** Always `"bearer"`. */
+    token_type: "bearer";
+    /** The authenticated user. */
+    user: AuthUser;
+}
+/**
+ * Server-side authentication methods.
+ *
+ * Access via `buildspace.auth` on the server SDK.
+ *
+ * @example
+ * ```ts
+ * import Buildspace from "@buildspacestudio/sdk";
+ *
+ * const buildspace = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);
+ *
+ * // Handle OAuth callback
+ * const tokens = await buildspace.auth.handleCallback(request);
+ *
+ * // Verify a session
+ * const session = await buildspace.auth.getSession(sessionToken);
+ *
+ * // Sign out
+ * await buildspace.auth.signOut(sessionToken);
+ * ```
+ */
+declare class AuthServerNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * 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).
+     */
+    getSession(sessionToken: string): Promise<AuthSession | null>;
+    /**
+     * 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: Request | URL | string, opts?: {
+        redirectUri?: string;
+    }): Promise<TokenResponse>;
+    /**
+     * Revoke a specific session token.
+     *
+     * @param sessionToken - The token to revoke.
+     * @throws {BuildspaceError} If the revocation fails.
+     */
+    revokeSession(sessionToken: string): Promise<void>;
+    /**
+     * 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()`.
+     */
+    signOut(sessionToken?: string): Promise<void>;
+}
+
+export { AuthServerNamespace as A, type TokenResponse as T, type AuthSession as a, type AuthUser as b };

package/dist/{auth/server.d.ts → server-Suq3tZZC.d.ts}

@@ -1,6 +1,7 @@
-import type { HttpTransport } from "../http";
+import { H as HttpTransport } from './http-D2gXpNpr.js';
+
 /** A Buildspace user returned from auth endpoints. */
-export interface AuthUser {
+interface AuthUser {
     /** The user's email address. */
     email: string;
     /** Unique user identifier. */
@@ -13,7 +14,7 @@ export interface AuthUser {
  *
  * Returned by {@link AuthServerNamespace.getSession}.
  */
-export interface AuthSession {
+interface AuthSession {
     /** The app this session belongs to, or `null` for platform-level sessions. */
     appId: string | null;
     /** The authenticated user. */
@@ -24,7 +25,7 @@ export interface AuthSession {
  *
  * Returned by {@link AuthServerNamespace.handleCallback}.
  */
-export interface TokenResponse {
+interface TokenResponse {
     /** The access token to use for authenticated requests. */
     access_token: string;
     /** Token lifetime in seconds. */
@@ -55,7 +56,7 @@ export interface TokenResponse {
  * await buildspace.auth.signOut(sessionToken);
  * ```
  */
-export declare class AuthServerNamespace {
+declare class AuthServerNamespace {
     private readonly transport;
     constructor(transport: HttpTransport);
     /**
@@ -112,4 +113,5 @@ export declare class AuthServerNamespace {
      */
     signOut(sessionToken?: string): Promise<void>;
 }
-//# sourceMappingURL=server.d.ts.map
+
+export { AuthServerNamespace as A, type TokenResponse as T, type AuthSession as a, type AuthUser as b };

package/dist/storage/index.cjs

@@ -0,0 +1,213 @@
+'use strict';
+
+// 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/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"
+    });
+  }
+};
+
+exports.StorageClientNamespace = StorageClientNamespace;
+exports.StorageServerNamespace = StorageServerNamespace;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/storage/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/storage/client.ts","../../src/storage/server.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/** Services available in the Buildspace platform. */\nexport type BuildspaceService = \"auth\" | \"billing\" | \"events\" | \"notifications\" | \"storage\";\n\n/**\n * Error thrown by all Buildspace SDK methods on failure.\n *\n * @example\n * ```ts\n * try {\n *   await buildspace.auth.getSession(token);\n * } catch (err) {\n *   if (err instanceof BuildspaceError) {\n *     console.error(err.service, err.code, err.status, err.message);\n *   }\n * }\n * ```\n */\nexport class BuildspaceError extends Error {\n  /** Machine-readable error code, e.g. `\"auth/invalid-token\"`. */\n  readonly code: string;\n  /** Which service produced the error. */\n  readonly service: BuildspaceService;\n  /** HTTP status code from the API. */\n  readonly status: number;\n\n  constructor({\n    code,\n    message,\n    service,\n    status,\n  }: {\n    code: string;\n    message: string;\n    service: BuildspaceService;\n    status: number;\n  }) {\n    super(message);\n    this.name = \"BuildspaceError\";\n    this.code = code;\n    this.service = service;\n    this.status = status;\n  }\n}\n","import { 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 type { HttpTransport } from \"../http\";\n\n/** Options for requesting a pre-signed upload URL on the server. */\nexport interface ServerUploadOptions {\n  /** MIME type of the file, e.g. `\"image/png\"`. */\n  contentType: string;\n  /** Storage path/key for the file, e.g. `\"avatars/user-123.png\"`. */\n  key: string;\n  /** File size in bytes. */\n  size: number;\n}\n\n/** Metadata for a stored object. */\nexport interface StorageObject {\n  /** MIME type of the stored file. */\n  contentType: string;\n  /** ISO 8601 timestamp of when the object was created. */\n  createdAt: string;\n  /** Unique object identifier. */\n  id: string;\n  /** Storage key/path of the object. */\n  key: string;\n  /** File size in bytes. */\n  size: number;\n  /** ID of the user who uploaded the object, or `null` if uploaded via server key. */\n  uploadedBy: string | null;\n}\n\n/**\n * Server-side storage methods for managing file uploads and downloads.\n *\n * Access via `buildspace.storage` on the server SDK.\n *\n * @example\n * ```ts\n * // Get a pre-signed upload URL\n * const { upload_url, key } = await buildspace.storage.getUploadUrl({\n *   key: \"avatars/user-123.png\",\n *   contentType: \"image/png\",\n *   size: file.size,\n * });\n *\n * // Upload directly to the signed URL\n * await fetch(upload_url, { method: \"PUT\", body: file });\n *\n * // Get a signed download URL\n * const { url } = await buildspace.storage.getSignedUrl(key);\n * ```\n */\nexport class StorageServerNamespace {\n  private readonly transport: HttpTransport;\n\n  constructor(transport: HttpTransport) {\n    this.transport = transport;\n  }\n\n  /**\n   * Request a pre-signed URL for direct file upload.\n   *\n   * @param opts - Upload options including the storage key, content type, and file size.\n   * @returns The signed upload URL, the resolved key, and expiry time in seconds.\n   */\n  getUploadUrl(\n    opts: ServerUploadOptions\n  ): Promise<{ expires_in: number; key: string; upload_url: string }> {\n    return this.transport.request<{ expires_in: number; key: string; upload_url: string }>({\n      service: \"storage\",\n      path: \"/v1/storage/upload\",\n      method: \"POST\",\n      body: {\n        path: opts.key,\n        content_type: opts.contentType,\n        size: opts.size,\n      },\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. Uses server default if omitted.\n   */\n  getSignedUrl(\n    key: string,\n    opts?: { expiresIn?: number }\n  ): Promise<{ expiresIn?: number; key: string; url: string }> {\n    return this.transport.request<{ expiresIn?: number; key: string; url: string }>({\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, e.g. `\"avatars/\"`.\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  /**\n   * Get current storage usage statistics for the app.\n   *\n   * @returns Byte counts and object count.\n   */\n  getUsage(): Promise<{\n    maxStorageBytes: number;\n    objectCount: number;\n    storageBytes: number;\n  }> {\n    return this.transport.request<{\n      maxStorageBytes: number;\n      objectCount: number;\n      storageBytes: number;\n    }>({\n      service: \"storage\",\n      path: \"/v1/storage/usage\",\n    });\n  }\n}\n"]}

package/dist/storage/index.d.cts

@@ -0,0 +1,195 @@
+import { H as HttpTransport } from '../http-D2gXpNpr.cjs';
+
+/** Options for requesting a pre-signed upload URL on the server. */
+interface ServerUploadOptions {
+    /** MIME type of the file, e.g. `"image/png"`. */
+    contentType: string;
+    /** Storage path/key for the file, e.g. `"avatars/user-123.png"`. */
+    key: string;
+    /** File size in bytes. */
+    size: number;
+}
+/** 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;
+}
+/**
+ * Server-side storage methods for managing file uploads and downloads.
+ *
+ * Access via `buildspace.storage` on the server SDK.
+ *
+ * @example
+ * ```ts
+ * // Get a pre-signed upload URL
+ * const { upload_url, key } = await buildspace.storage.getUploadUrl({
+ *   key: "avatars/user-123.png",
+ *   contentType: "image/png",
+ *   size: file.size,
+ * });
+ *
+ * // Upload directly to the signed URL
+ * await fetch(upload_url, { method: "PUT", body: file });
+ *
+ * // Get a signed download URL
+ * const { url } = await buildspace.storage.getSignedUrl(key);
+ * ```
+ */
+declare class StorageServerNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * 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: ServerUploadOptions): Promise<{
+        expires_in: number;
+        key: string;
+        upload_url: string;
+    }>;
+    /**
+     * 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: string, opts?: {
+        expiresIn?: number;
+    }): Promise<{
+        expiresIn?: number;
+        key: string;
+        url: string;
+    }>;
+    /**
+     * 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?: 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>;
+    /**
+     * Get current storage usage statistics for the app.
+     *
+     * @returns Byte counts and object count.
+     */
+    getUsage(): Promise<{
+        maxStorageBytes: number;
+        objectCount: number;
+        storageBytes: number;
+    }>;
+}
+
+/** 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>;
+}
+
+export { type GetUrlResponse, type ServerUploadOptions, StorageClientNamespace, type StorageObject, StorageServerNamespace, type UploadOptions, type UploadResponse };