@buildspacestudio/sdk 0.2.2 → 0.3.0

package/dist/http-U-zzKmFF.d.ts

@@ -0,0 +1,100 @@
+type ClientMode = "server" | "client";
+/** Configuration options for the server SDK (`new Buildspace()`). */
+interface BuildspaceConfig {
+    /** Base URL of the Buildspace API. Defaults to `"https://api.buildspace.studio"`. */
+    baseUrl?: string;
+    /** Custom `fetch` implementation (useful for testing or edge runtimes). */
+    fetch?: typeof fetch;
+    /** Base URL of the Buildspace login service. Defaults to `"https://login.buildspace.studio"`. */
+    loginUrl?: string;
+    /** API version string sent via the `X-Buildspace-Version` header. Defaults to `"2025-06-01"`. */
+    version?: string;
+}
+/** Configuration for client-side event batching behavior. */
+interface EventsBatchingConfig {
+    /** How often queued events are flushed to the API, in milliseconds. Defaults to `5000`. */
+    flushInterval?: number;
+    /** Maximum number of events to queue before an automatic flush. Defaults to `20`. */
+    maxBatchSize?: number;
+}
+/** Configuration options for the client SDK (`createClient()`). */
+interface BuildspaceClientConfig extends BuildspaceConfig {
+    /** Options for client-side event batching. */
+    events?: EventsBatchingConfig;
+}
+interface ResolvedConfig {
+    baseUrl: string;
+    fetch: typeof fetch;
+    loginUrl: string;
+    mode: ClientMode;
+    version: string;
+}
+
+/** Services available in the Buildspace platform. */
+type BuildspaceService = "auth" | "events" | "notifications" | "storage";
+/**
+ * Error thrown by all Buildspace SDK methods on failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await buildspace.auth.getSession(token);
+ * } catch (err) {
+ *   if (err instanceof BuildspaceError) {
+ *     console.error(err.service, err.code, err.status, err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class BuildspaceError extends Error {
+    /** Machine-readable error code, e.g. `"auth/invalid-token"`. */
+    readonly code: string;
+    /** Which service produced the error. */
+    readonly service: BuildspaceService;
+    /** HTTP status code from the API. */
+    readonly status: number;
+    constructor({ code, message, service, status, }: {
+        code: string;
+        message: string;
+        service: BuildspaceService;
+        status: number;
+    });
+}
+
+interface RequestOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+    keepalive?: boolean;
+    method?: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    service: BuildspaceService;
+}
+/**
+ * Low-level HTTP transport used internally by all SDK namespaces.
+ *
+ * Handles authentication headers, API versioning, session tokens,
+ * and consistent error mapping to {@link BuildspaceError}.
+ */
+declare class HttpTransport {
+    readonly baseUrl: string;
+    readonly fetcher: typeof fetch;
+    readonly key: string;
+    readonly loginUrl: string;
+    readonly mode: ClientMode;
+    readonly version: string;
+    private sessionToken;
+    constructor({ key, resolvedConfig }: {
+        key: string;
+        resolvedConfig: ResolvedConfig;
+    });
+    /** Remove the stored session token. */
+    clearSession(): void;
+    /** Return the current session token, or `null` if none is set. */
+    getSessionToken(): string | null;
+    /** Store a session token that will be sent as `X-Session-Token` on subsequent requests. */
+    setSession(sessionToken: string): void;
+    request<T>({ service, path, method, query, body, headers, keepalive, }: RequestOptions): Promise<T>;
+}
+
+export { type BuildspaceConfig as B, HttpTransport as H, type BuildspaceClientConfig as a, BuildspaceError as b, type BuildspaceService as c };