@buildspacestudio/sdk 0.2.2 → 0.3.0

package/dist/client-C67hy1kt.d.cts

@@ -0,0 +1,58 @@
+import { H as HttpTransport } from './http-U-zzKmFF.cjs';
+
+/**
+ * Client-side event tracking with automatic batching.
+ *
+ * Events are queued in memory and flushed to the API in batches,
+ * either on a timer or when the batch size limit is reached.
+ *
+ * Access via `buildspace.events` on the client SDK.
+ *
+ * @example
+ * ```ts
+ * // Fire and forget — events are queued automatically
+ * buildspace.events.track("button.clicked", { label: "upgrade" });
+ *
+ * // Flush before page unload
+ * await buildspace.events.flush();
+ *
+ * // Graceful shutdown (clears timer, flushes remaining)
+ * await buildspace.events.shutdown();
+ * ```
+ */
+declare class EventsClientNamespace {
+    private readonly queue;
+    private readonly transport;
+    private timer;
+    constructor(transport: HttpTransport, config?: {
+        flushInterval?: number;
+        maxBatchSize?: number;
+    });
+    private readonly 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: string, properties?: Record<string, unknown>, actorId?: string): void;
+    /**
+     * Send all queued events to the API immediately.
+     *
+     * If the flush fails, events are re-queued for the next attempt.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the automatic flush timer and send any remaining events.
+     *
+     * Call this during app shutdown or cleanup to ensure no events are lost.
+     */
+    shutdown(): Promise<void>;
+}
+
+export { EventsClientNamespace as E };

package/dist/{events/client.d.ts → client-Dlif1JBf.d.ts}

@@ -1,4 +1,5 @@
-import type { HttpTransport } from "../http";
+import { H as HttpTransport } from './http-U-zzKmFF.js';
+
 /**
  * Client-side event tracking with automatic batching.
  *
@@ -19,7 +20,7 @@ import type { HttpTransport } from "../http";
  * await buildspace.events.shutdown();
  * ```
  */
-export declare class EventsClientNamespace {
+declare class EventsClientNamespace {
     private readonly queue;
     private readonly transport;
     private timer;
@@ -53,4 +54,5 @@ export declare class EventsClientNamespace {
      */
     shutdown(): Promise<void>;
 }
-//# sourceMappingURL=client.d.ts.map
+
+export { EventsClientNamespace as E };

package/dist/{auth/client.js → client-DqWXAwCr.d.cts}

@@ -1,3 +1,23 @@
+import { H as HttpTransport } from './http-U-zzKmFF.cjs';
+
+/** Options for generating a sign-in URL. */
+interface SignInUrlOptions {
+    /** App slug to scope the login to a specific creator app. */
+    appSlug?: string;
+    /** Environment to authenticate against. */
+    env?: "dev" | "prod";
+    /** URL to redirect the user to after authentication completes. */
+    redirectUri: string;
+}
+/** Options for generating a sign-up URL. */
+interface SignUpUrlOptions {
+    /** App slug to scope the registration to a specific creator app. */
+    appSlug?: string;
+    /** Environment to authenticate against. */
+    env?: "dev" | "prod";
+    /** URL to redirect the user to after registration completes. */
+    redirectUri: string;
+}
 /**
  * Client-side authentication methods for generating login URLs.
  *
@@ -18,11 +38,9 @@
  * window.location.href = signInUrl;
  * ```
  */
-export class AuthClientNamespace {
-    transport;
-    constructor(transport) {
-        this.transport = transport;
-    }
+declare class AuthClientNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
     /**
      * Build a URL that redirects the user to the Buildspace sign-in page.
      *
@@ -33,18 +51,7 @@ export class AuthClientNamespace {
      * @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();
-    }
+    getSignInUrl(opts: SignInUrlOptions): string;
     /**
      * Build a URL that redirects the user to the Buildspace sign-up page.
      *
@@ -54,17 +61,7 @@ export class AuthClientNamespace {
      * @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();
-    }
+    getSignUpUrl(opts: SignUpUrlOptions): string;
 }
-//# sourceMappingURL=client.js.map
+
+export { AuthClientNamespace as A, type SignInUrlOptions as S, type SignUpUrlOptions as a };

package/dist/events/index.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+// 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()
+        }))
+      }
+    });
+  }
+};
+
+exports.EventsClientNamespace = EventsClientNamespace;
+exports.EventsServerNamespace = EventsServerNamespace;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/events/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/events/client.ts","../../src/events/server.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["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 { HttpTransport } from \"../http\";\n\n/** An event to include in a batch tracking call. */\nexport interface ServerTrackedEvent {\n  /** Identifier of the user or entity that triggered the event. */\n  actor_id?: string;\n  /** Event name, e.g. `\"user.signed_up\"` or `\"page.viewed\"`. */\n  event: string;\n  /** Arbitrary key-value data attached to the event. */\n  properties?: Record<string, unknown>;\n  /** ISO 8601 timestamp. Auto-filled with `new Date().toISOString()` if omitted. */\n  timestamp?: string;\n}\n\n/**\n * Server-side event tracking methods.\n *\n * Access via `buildspace.events` on the server SDK.\n *\n * @example\n * ```ts\n * // Track a single event\n * await buildspace.events.track(\"user.signed_up\", { plan: \"pro\" }, userId);\n *\n * // Batch track multiple events\n * await buildspace.events.batchTrack([\n *   { event: \"page.viewed\", properties: { path: \"/home\" }, actor_id: userId },\n * ]);\n * ```\n */\nexport class EventsServerNamespace {\n  private readonly transport: HttpTransport;\n\n  constructor(transport: HttpTransport) {\n    this.transport = transport;\n  }\n\n  /**\n   * Track a single event.\n   *\n   * @param event - Event name, e.g. `\"user.signed_up\"`.\n   * @param properties - Arbitrary key-value data to attach to the event.\n   * @param actorId - Identifier of the user or entity that triggered the event.\n   * @returns The ID of the created event.\n   */\n  track(\n    event: string,\n    properties?: Record<string, unknown>,\n    actorId?: string\n  ): Promise<{ event_id: string }> {\n    return this.transport.request<{ event_id: string }>({\n      service: \"events\",\n      path: \"/v1/events\",\n      method: \"POST\",\n      body: {\n        event,\n        properties,\n        actor_id: actorId,\n        timestamp: new Date().toISOString(),\n      },\n    });\n  }\n\n  /**\n   * Track multiple events in a single request.\n   *\n   * Events without a `timestamp` are automatically timestamped.\n   *\n   * @param events - Array of events to track.\n   * @returns The count and IDs of created events.\n   */\n  batchTrack(events: ServerTrackedEvent[]): Promise<{ count: number; event_ids: string[] }> {\n    return this.transport.request<{ count: number; event_ids: string[] }>({\n      service: \"events\",\n      path: \"/v1/events/batch\",\n      method: \"POST\",\n      body: {\n        events: events.map((event) => ({\n          ...event,\n          timestamp: event.timestamp ?? new Date().toISOString(),\n        })),\n      },\n    });\n  }\n}\n"]}

package/dist/events/{server.d.ts → index.d.cts}

@@ -1,6 +1,8 @@
-import type { HttpTransport } from "../http";
+export { E as EventsClientNamespace } from '../client-C67hy1kt.cjs';
+import { H as HttpTransport } from '../http-U-zzKmFF.cjs';
+
 /** An event to include in a batch tracking call. */
-export interface ServerTrackedEvent {
+interface ServerTrackedEvent {
     /** Identifier of the user or entity that triggered the event. */
     actor_id?: string;
     /** Event name, e.g. `"user.signed_up"` or `"page.viewed"`. */
@@ -26,7 +28,7 @@ export interface ServerTrackedEvent {
  * ]);
  * ```
  */
-export declare class EventsServerNamespace {
+declare class EventsServerNamespace {
     private readonly transport;
     constructor(transport: HttpTransport);
     /**
@@ -53,4 +55,5 @@ export declare class EventsServerNamespace {
         event_ids: string[];
     }>;
 }
-//# sourceMappingURL=server.d.ts.map
+
+export { EventsServerNamespace, type ServerTrackedEvent };

package/dist/events/index.d.ts

@@ -1,4 +1,59 @@
-export { EventsClientNamespace } from "./client";
-export type { ServerTrackedEvent } from "./server";
-export { EventsServerNamespace } from "./server";
-//# sourceMappingURL=index.d.ts.map
+export { E as EventsClientNamespace } from '../client-Dlif1JBf.js';
+import { H as HttpTransport } from '../http-U-zzKmFF.js';
+
+/** An event to include in a batch tracking call. */
+interface ServerTrackedEvent {
+    /** Identifier of the user or entity that triggered the event. */
+    actor_id?: string;
+    /** Event name, e.g. `"user.signed_up"` or `"page.viewed"`. */
+    event: string;
+    /** Arbitrary key-value data attached to the event. */
+    properties?: Record<string, unknown>;
+    /** ISO 8601 timestamp. Auto-filled with `new Date().toISOString()` if omitted. */
+    timestamp?: string;
+}
+/**
+ * Server-side event tracking methods.
+ *
+ * Access via `buildspace.events` on the server SDK.
+ *
+ * @example
+ * ```ts
+ * // Track a single event
+ * await buildspace.events.track("user.signed_up", { plan: "pro" }, userId);
+ *
+ * // Batch track multiple events
+ * await buildspace.events.batchTrack([
+ *   { event: "page.viewed", properties: { path: "/home" }, actor_id: userId },
+ * ]);
+ * ```
+ */
+declare class EventsServerNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * 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: string, properties?: Record<string, unknown>, actorId?: string): Promise<{
+        event_id: string;
+    }>;
+    /**
+     * 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: ServerTrackedEvent[]): Promise<{
+        count: number;
+        event_ids: string[];
+    }>;
+}
+
+export { EventsServerNamespace, type ServerTrackedEvent };

package/dist/events/index.js

@@ -1,3 +1,128 @@
-export { EventsClientNamespace } from "./client";
-export { EventsServerNamespace } from "./server";
+// 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()
+        }))
+      }
+    });
+  }
+};
+
+export { EventsClientNamespace, EventsServerNamespace };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"sources":["../../src/events/client.ts","../../src/events/server.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["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 { HttpTransport } from \"../http\";\n\n/** An event to include in a batch tracking call. */\nexport interface ServerTrackedEvent {\n  /** Identifier of the user or entity that triggered the event. */\n  actor_id?: string;\n  /** Event name, e.g. `\"user.signed_up\"` or `\"page.viewed\"`. */\n  event: string;\n  /** Arbitrary key-value data attached to the event. */\n  properties?: Record<string, unknown>;\n  /** ISO 8601 timestamp. Auto-filled with `new Date().toISOString()` if omitted. */\n  timestamp?: string;\n}\n\n/**\n * Server-side event tracking methods.\n *\n * Access via `buildspace.events` on the server SDK.\n *\n * @example\n * ```ts\n * // Track a single event\n * await buildspace.events.track(\"user.signed_up\", { plan: \"pro\" }, userId);\n *\n * // Batch track multiple events\n * await buildspace.events.batchTrack([\n *   { event: \"page.viewed\", properties: { path: \"/home\" }, actor_id: userId },\n * ]);\n * ```\n */\nexport class EventsServerNamespace {\n  private readonly transport: HttpTransport;\n\n  constructor(transport: HttpTransport) {\n    this.transport = transport;\n  }\n\n  /**\n   * Track a single event.\n   *\n   * @param event - Event name, e.g. `\"user.signed_up\"`.\n   * @param properties - Arbitrary key-value data to attach to the event.\n   * @param actorId - Identifier of the user or entity that triggered the event.\n   * @returns The ID of the created event.\n   */\n  track(\n    event: string,\n    properties?: Record<string, unknown>,\n    actorId?: string\n  ): Promise<{ event_id: string }> {\n    return this.transport.request<{ event_id: string }>({\n      service: \"events\",\n      path: \"/v1/events\",\n      method: \"POST\",\n      body: {\n        event,\n        properties,\n        actor_id: actorId,\n        timestamp: new Date().toISOString(),\n      },\n    });\n  }\n\n  /**\n   * Track multiple events in a single request.\n   *\n   * Events without a `timestamp` are automatically timestamped.\n   *\n   * @param events - Array of events to track.\n   * @returns The count and IDs of created events.\n   */\n  batchTrack(events: ServerTrackedEvent[]): Promise<{ count: number; event_ids: string[] }> {\n    return this.transport.request<{ count: number; event_ids: string[] }>({\n      service: \"events\",\n      path: \"/v1/events/batch\",\n      method: \"POST\",\n      body: {\n        events: events.map((event) => ({\n          ...event,\n          timestamp: event.timestamp ?? new Date().toISOString(),\n        })),\n      },\n    });\n  }\n}\n"]}

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

@@ -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 };