@buildspacestudio/sdk 0.1.2 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +4 -4
  2. package/dist/auth/client.d.ts +59 -10
  3. package/dist/auth/client.d.ts.map +1 -1
  4. package/dist/auth/client.js +39 -0
  5. package/dist/auth/client.js.map +1 -1
  6. package/dist/auth/index.d.ts +1 -0
  7. package/dist/auth/index.d.ts.map +1 -1
  8. package/dist/auth/index.js.map +1 -1
  9. package/dist/auth/server.d.ts +90 -1
  10. package/dist/auth/server.d.ts.map +1 -1
  11. package/dist/auth/server.js +98 -3
  12. package/dist/auth/server.js.map +1 -1
  13. package/dist/client/index.d.ts +63 -0
  14. package/dist/client/index.d.ts.map +1 -1
  15. package/dist/client/index.js +63 -0
  16. package/dist/client/index.js.map +1 -1
  17. package/dist/config.d.ts +10 -0
  18. package/dist/config.d.ts.map +1 -1
  19. package/dist/config.js.map +1 -1
  20. package/dist/errors.d.ts +18 -0
  21. package/dist/errors.d.ts.map +1 -1
  22. package/dist/errors.js +17 -0
  23. package/dist/errors.js.map +1 -1
  24. package/dist/events/client.d.ts +41 -0
  25. package/dist/events/client.d.ts.map +1 -1
  26. package/dist/events/client.js +41 -0
  27. package/dist/events/client.js.map +1 -1
  28. package/dist/events/server.d.ts +37 -0
  29. package/dist/events/server.d.ts.map +1 -1
  30. package/dist/events/server.js +32 -0
  31. package/dist/events/server.js.map +1 -1
  32. package/dist/http.d.ts +10 -0
  33. package/dist/http.d.ts.map +1 -1
  34. package/dist/http.js +12 -0
  35. package/dist/http.js.map +1 -1
  36. package/dist/index.d.ts +56 -0
  37. package/dist/index.d.ts.map +1 -1
  38. package/dist/index.js +55 -0
  39. package/dist/index.js.map +1 -1
  40. package/dist/notifications/server.d.ts +52 -0
  41. package/dist/notifications/server.d.ts.map +1 -1
  42. package/dist/notifications/server.js +38 -0
  43. package/dist/notifications/server.js.map +1 -1
  44. package/dist/storage/client.d.ts +59 -0
  45. package/dist/storage/client.d.ts.map +1 -1
  46. package/dist/storage/client.js +55 -1
  47. package/dist/storage/client.js.map +1 -1
  48. package/dist/storage/server.d.ts +61 -0
  49. package/dist/storage/server.d.ts.map +1 -1
  50. package/dist/storage/server.js +50 -0
  51. package/dist/storage/server.js.map +1 -1
  52. package/package.json +1 -1
package/dist/config.d.ts CHANGED
@@ -2,17 +2,27 @@ export declare const DEFAULT_BASE_URL = "https://api.buildspace.studio";
2
2
  export declare const DEFAULT_LOGIN_URL = "https://login.buildspace.studio";
3
3
  export declare const DEFAULT_API_VERSION = "2025-06-01";
4
4
  export type ClientMode = "server" | "client";
5
+ /** Configuration options for the server SDK (`new Buildspace()`). */
5
6
  export interface BuildspaceConfig {
7
+ /** Base URL of the Buildspace API. Defaults to `"https://api.buildspace.studio"`. */
6
8
  baseUrl?: string;
9
+ /** Custom `fetch` implementation (useful for testing or edge runtimes). */
7
10
  fetch?: typeof fetch;
11
+ /** Base URL of the Buildspace login service. Defaults to `"https://login.buildspace.studio"`. */
8
12
  loginUrl?: string;
13
+ /** API version string sent via the `X-Buildspace-Version` header. Defaults to `"2025-06-01"`. */
9
14
  version?: string;
10
15
  }
16
+ /** Configuration for client-side event batching behavior. */
11
17
  export interface EventsBatchingConfig {
18
+ /** How often queued events are flushed to the API, in milliseconds. Defaults to `5000`. */
12
19
  flushInterval?: number;
20
+ /** Maximum number of events to queue before an automatic flush. Defaults to `20`. */
13
21
  maxBatchSize?: number;
14
22
  }
23
+ /** Configuration options for the client SDK (`createClient()`). */
15
24
  export interface BuildspaceClientConfig extends BuildspaceConfig {
25
+ /** Options for client-side event batching. */
16
26
  events?: EventsBatchingConfig;
17
27
  }
18
28
  export interface ResolvedConfig {
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,kCAAkC,CAAC;AAChE,eAAO,MAAM,iBAAiB,oCAAoC,CAAC;AACnE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,GAAE,gBAAqB,GAAG,cAAc,CAQ7F;AAMD,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAgBrF"}
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,kCAAkC,CAAC;AAChE,eAAO,MAAM,iBAAiB,oCAAoC,CAAC;AACnE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,8CAA8C;IAC9C,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,GAAE,gBAAqB,GAAG,cAAc,CAQ7F;AAMD,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAgBrF"}
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG,iCAAiC,CAAC;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;AA4BhD,MAAM,UAAU,aAAa,CAAC,IAAgB,EAAE,SAA2B,EAAE;IAC3E,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,gBAAgB;QAC3C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,iBAAiB;QAC9C,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,mBAAmB;QAC9C,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAgB;IAClC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,EAAE,IAAI,EAAE,GAAG,EAAqC;IAC7E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,wBAAwB,UAAU,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,kJAAkJ,CACnJ,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,4IAA4I,CAC7I,CAAC;IACJ,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG,iCAAiC,CAAC;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAsChD,MAAM,UAAU,aAAa,CAAC,IAAgB,EAAE,SAA2B,EAAE;IAC3E,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,gBAAgB;QAC3C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,iBAAiB;QAC9C,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,mBAAmB;QAC9C,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAgB;IAClC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,EAAE,IAAI,EAAE,GAAG,EAAqC;IAC7E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,wBAAwB,UAAU,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,kJAAkJ,CACnJ,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,4IAA4I,CAC7I,CAAC;IACJ,CAAC;AACH,CAAC"}
package/dist/errors.d.ts CHANGED
@@ -1,7 +1,25 @@
1
+ /** Services available in the Buildspace platform. */
1
2
  export type BuildspaceService = "auth" | "events" | "notifications" | "storage";
3
+ /**
4
+ * Error thrown by all Buildspace SDK methods on failure.
5
+ *
6
+ * @example
7
+ * ```ts
8
+ * try {
9
+ * await buildspace.auth.getSession(token);
10
+ * } catch (err) {
11
+ * if (err instanceof BuildspaceError) {
12
+ * console.error(err.service, err.code, err.status, err.message);
13
+ * }
14
+ * }
15
+ * ```
16
+ */
2
17
  export declare class BuildspaceError extends Error {
18
+ /** Machine-readable error code, e.g. `"auth/invalid-token"`. */
3
19
  readonly code: string;
20
+ /** Which service produced the error. */
4
21
  readonly service: BuildspaceService;
22
+ /** HTTP status code from the API. */
5
23
  readonly status: number;
6
24
  constructor({ code, message, service, status, }: {
7
25
  code: string;
@@ -1 +1 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,eAAe,GAAG,SAAS,CAAC;AAEhF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,EACV,IAAI,EACJ,OAAO,EACP,OAAO,EACP,MAAM,GACP,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,iBAAiB,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC;KAChB;CAOF"}
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,eAAe,GAAG,SAAS,CAAC;AAEhF;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,EACV,IAAI,EACJ,OAAO,EACP,OAAO,EACP,MAAM,GACP,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,iBAAiB,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC;KAChB;CAOF"}
package/dist/errors.js CHANGED
@@ -1,6 +1,23 @@
1
+ /**
2
+ * Error thrown by all Buildspace SDK methods on failure.
3
+ *
4
+ * @example
5
+ * ```ts
6
+ * try {
7
+ * await buildspace.auth.getSession(token);
8
+ * } catch (err) {
9
+ * if (err instanceof BuildspaceError) {
10
+ * console.error(err.service, err.code, err.status, err.message);
11
+ * }
12
+ * }
13
+ * ```
14
+ */
1
15
  export class BuildspaceError extends Error {
16
+ /** Machine-readable error code, e.g. `"auth/invalid-token"`. */
2
17
  code;
18
+ /** Which service produced the error. */
3
19
  service;
20
+ /** HTTP status code from the API. */
4
21
  status;
5
22
  constructor({ code, message, service, status, }) {
6
23
  super(message);
@@ -1 +1 @@
1
- {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IACb,OAAO,CAAoB;IAC3B,MAAM,CAAS;IAExB,YAAY,EACV,IAAI,EACJ,OAAO,EACP,OAAO,EACP,MAAM,GAMP;QACC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,gEAAgE;IACvD,IAAI,CAAS;IACtB,wCAAwC;IAC/B,OAAO,CAAoB;IACpC,qCAAqC;IAC5B,MAAM,CAAS;IAExB,YAAY,EACV,IAAI,EACJ,OAAO,EACP,OAAO,EACP,MAAM,GAMP;QACC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
@@ -1,4 +1,24 @@
1
1
  import type { HttpTransport } from "../http";
2
+ /**
3
+ * Client-side event tracking with automatic batching.
4
+ *
5
+ * Events are queued in memory and flushed to the API in batches,
6
+ * either on a timer or when the batch size limit is reached.
7
+ *
8
+ * Access via `buildspace.events` on the client SDK.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * // Fire and forget — events are queued automatically
13
+ * buildspace.events.track("button.clicked", { label: "upgrade" });
14
+ *
15
+ * // Flush before page unload
16
+ * await buildspace.events.flush();
17
+ *
18
+ * // Graceful shutdown (clears timer, flushes remaining)
19
+ * await buildspace.events.shutdown();
20
+ * ```
21
+ */
2
22
  export declare class EventsClientNamespace {
3
23
  private readonly queue;
4
24
  private readonly transport;
@@ -8,8 +28,29 @@ export declare class EventsClientNamespace {
8
28
  maxBatchSize?: number;
9
29
  });
10
30
  private readonly maxBatchSize;
31
+ /**
32
+ * Queue an event for batched delivery.
33
+ *
34
+ * This method is synchronous and returns immediately. Events are
35
+ * automatically flushed when the batch size is reached or on the
36
+ * configured interval.
37
+ *
38
+ * @param event - Event name, e.g. `"button.clicked"`.
39
+ * @param properties - Arbitrary key-value data to attach.
40
+ * @param actorId - Identifier of the user or entity that triggered the event.
41
+ */
11
42
  track(event: string, properties?: Record<string, unknown>, actorId?: string): void;
43
+ /**
44
+ * Send all queued events to the API immediately.
45
+ *
46
+ * If the flush fails, events are re-queued for the next attempt.
47
+ */
12
48
  flush(): Promise<void>;
49
+ /**
50
+ * Stop the automatic flush timer and send any remaining events.
51
+ *
52
+ * Call this during app shutdown or cleanup to ensure no events are lost.
53
+ */
13
54
  shutdown(): Promise<void>;
14
55
  }
15
56
  //# sourceMappingURL=client.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/events/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAS7C,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,KAAK,CAA+C;gBAG1D,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO;IAYhE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAe5E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAQhC"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/events/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAS7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,KAAK,CAA+C;gBAG1D,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO;IAYhE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAelF;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAQhC"}
@@ -1,3 +1,23 @@
1
+ /**
2
+ * Client-side event tracking with automatic batching.
3
+ *
4
+ * Events are queued in memory and flushed to the API in batches,
5
+ * either on a timer or when the batch size limit is reached.
6
+ *
7
+ * Access via `buildspace.events` on the client SDK.
8
+ *
9
+ * @example
10
+ * ```ts
11
+ * // Fire and forget — events are queued automatically
12
+ * buildspace.events.track("button.clicked", { label: "upgrade" });
13
+ *
14
+ * // Flush before page unload
15
+ * await buildspace.events.flush();
16
+ *
17
+ * // Graceful shutdown (clears timer, flushes remaining)
18
+ * await buildspace.events.shutdown();
19
+ * ```
20
+ */
1
21
  export class EventsClientNamespace {
2
22
  queue = [];
3
23
  transport;
@@ -13,6 +33,17 @@ export class EventsClientNamespace {
13
33
  }, flushInterval);
14
34
  }
15
35
  maxBatchSize;
36
+ /**
37
+ * Queue an event for batched delivery.
38
+ *
39
+ * This method is synchronous and returns immediately. Events are
40
+ * automatically flushed when the batch size is reached or on the
41
+ * configured interval.
42
+ *
43
+ * @param event - Event name, e.g. `"button.clicked"`.
44
+ * @param properties - Arbitrary key-value data to attach.
45
+ * @param actorId - Identifier of the user or entity that triggered the event.
46
+ */
16
47
  track(event, properties, actorId) {
17
48
  this.queue.push({
18
49
  event,
@@ -26,6 +57,11 @@ export class EventsClientNamespace {
26
57
  });
27
58
  }
28
59
  }
60
+ /**
61
+ * Send all queued events to the API immediately.
62
+ *
63
+ * If the flush fails, events are re-queued for the next attempt.
64
+ */
29
65
  async flush() {
30
66
  if (this.queue.length === 0) {
31
67
  return;
@@ -45,6 +81,11 @@ export class EventsClientNamespace {
45
81
  throw new Error("Failed to flush events batch.");
46
82
  }
47
83
  }
84
+ /**
85
+ * Stop the automatic flush timer and send any remaining events.
86
+ *
87
+ * Call this during app shutdown or cleanup to ensure no events are lost.
88
+ */
48
89
  async shutdown() {
49
90
  if (this.timer) {
50
91
  clearInterval(this.timer);
@@ -1 +1 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/events/client.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,qBAAqB;IACf,KAAK,GAAkB,EAAE,CAAC;IAC1B,SAAS,CAAgB;IAClC,KAAK,GAA0C,IAAI,CAAC;IAE5D,YACE,SAAwB,EACxB,SAA4D,EAAE;QAE9D,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,IAAI,CAAC;QACnD,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACtB,yCAAyC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,aAAa,CAAC,CAAC;IACpB,CAAC;IAEgB,YAAY,CAAS;IAEtC,KAAK,CAAC,KAAa,EAAE,UAAoC,EAAE,OAAgB;QACzE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YACd,KAAK;YACL,UAAU;YACV,QAAQ,EAAE,OAAO;YACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACtB,sCAAsC;YACxC,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAEtD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAO;gBACjC,OAAO,EAAE,QAAQ;gBACjB,IAAI,EAAE,kBAAkB;gBACxB,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE,IAAI;gBACf,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;aACxB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QAED,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/events/client.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,qBAAqB;IACf,KAAK,GAAkB,EAAE,CAAC;IAC1B,SAAS,CAAgB;IAClC,KAAK,GAA0C,IAAI,CAAC;IAE5D,YACE,SAAwB,EACxB,SAA4D,EAAE;QAE9D,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,IAAI,CAAC;QACnD,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACtB,yCAAyC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,aAAa,CAAC,CAAC;IACpB,CAAC;IAEgB,YAAY,CAAS;IAEtC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAa,EAAE,UAAoC,EAAE,OAAgB;QACzE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YACd,KAAK;YACL,UAAU;YACV,QAAQ,EAAE,OAAO;YACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACtB,sCAAsC;YACxC,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAEtD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAO;gBACjC,OAAO,EAAE,QAAQ;gBACjB,IAAI,EAAE,kBAAkB;gBACxB,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE,IAAI;gBACf,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;aACxB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QAED,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}
@@ -1,16 +1,53 @@
1
1
  import type { HttpTransport } from "../http";
2
+ /** An event to include in a batch tracking call. */
2
3
  export interface ServerTrackedEvent {
4
+ /** Identifier of the user or entity that triggered the event. */
3
5
  actor_id?: string;
6
+ /** Event name, e.g. `"user.signed_up"` or `"page.viewed"`. */
4
7
  event: string;
8
+ /** Arbitrary key-value data attached to the event. */
5
9
  properties?: Record<string, unknown>;
10
+ /** ISO 8601 timestamp. Auto-filled with `new Date().toISOString()` if omitted. */
6
11
  timestamp?: string;
7
12
  }
13
+ /**
14
+ * Server-side event tracking methods.
15
+ *
16
+ * Access via `buildspace.events` on the server SDK.
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * // Track a single event
21
+ * await buildspace.events.track("user.signed_up", { plan: "pro" }, userId);
22
+ *
23
+ * // Batch track multiple events
24
+ * await buildspace.events.batchTrack([
25
+ * { event: "page.viewed", properties: { path: "/home" }, actor_id: userId },
26
+ * ]);
27
+ * ```
28
+ */
8
29
  export declare class EventsServerNamespace {
9
30
  private readonly transport;
10
31
  constructor(transport: HttpTransport);
32
+ /**
33
+ * Track a single event.
34
+ *
35
+ * @param event - Event name, e.g. `"user.signed_up"`.
36
+ * @param properties - Arbitrary key-value data to attach to the event.
37
+ * @param actorId - Identifier of the user or entity that triggered the event.
38
+ * @returns The ID of the created event.
39
+ */
11
40
  track(event: string, properties?: Record<string, unknown>, actorId?: string): Promise<{
12
41
  event_id: string;
13
42
  }>;
43
+ /**
44
+ * Track multiple events in a single request.
45
+ *
46
+ * Events without a `timestamp` are automatically timestamped.
47
+ *
48
+ * @param events - Array of events to track.
49
+ * @returns The count and IDs of created events.
50
+ */
14
51
  batchTrack(events: ServerTrackedEvent[]): Promise<{
15
52
  count: number;
16
53
  event_ids: string[];
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/events/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,SAAS,EAAE,aAAa;IAIpC,KAAK,CACH,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAchC,UAAU,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAa1F"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/events/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,SAAS,EAAE,aAAa;IAIpC;;;;;;;OAOG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAchC;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAa1F"}
@@ -1,8 +1,32 @@
1
+ /**
2
+ * Server-side event tracking methods.
3
+ *
4
+ * Access via `buildspace.events` on the server SDK.
5
+ *
6
+ * @example
7
+ * ```ts
8
+ * // Track a single event
9
+ * await buildspace.events.track("user.signed_up", { plan: "pro" }, userId);
10
+ *
11
+ * // Batch track multiple events
12
+ * await buildspace.events.batchTrack([
13
+ * { event: "page.viewed", properties: { path: "/home" }, actor_id: userId },
14
+ * ]);
15
+ * ```
16
+ */
1
17
  export class EventsServerNamespace {
2
18
  transport;
3
19
  constructor(transport) {
4
20
  this.transport = transport;
5
21
  }
22
+ /**
23
+ * Track a single event.
24
+ *
25
+ * @param event - Event name, e.g. `"user.signed_up"`.
26
+ * @param properties - Arbitrary key-value data to attach to the event.
27
+ * @param actorId - Identifier of the user or entity that triggered the event.
28
+ * @returns The ID of the created event.
29
+ */
6
30
  track(event, properties, actorId) {
7
31
  return this.transport.request({
8
32
  service: "events",
@@ -16,6 +40,14 @@ export class EventsServerNamespace {
16
40
  },
17
41
  });
18
42
  }
43
+ /**
44
+ * Track multiple events in a single request.
45
+ *
46
+ * Events without a `timestamp` are automatically timestamped.
47
+ *
48
+ * @param events - Array of events to track.
49
+ * @returns The count and IDs of created events.
50
+ */
19
51
  batchTrack(events) {
20
52
  return this.transport.request({
21
53
  service: "events",
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/events/server.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,qBAAqB;IACf,SAAS,CAAgB;IAE1C,YAAY,SAAwB;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CACH,KAAa,EACb,UAAoC,EACpC,OAAgB;QAEhB,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAuB;YAClD,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,YAAY;YAClB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACJ,KAAK;gBACL,UAAU;gBACV,QAAQ,EAAE,OAAO;gBACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC;SACF,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC,MAA4B;QACrC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAyC;YACpE,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACJ,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC7B,GAAG,KAAK;oBACR,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACvD,CAAC,CAAC;aACJ;SACF,CAAC,CAAC;IACL,CAAC;CACF"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/events/server.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,qBAAqB;IACf,SAAS,CAAgB;IAE1C,YAAY,SAAwB;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CACH,KAAa,EACb,UAAoC,EACpC,OAAgB;QAEhB,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAuB;YAClD,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,YAAY;YAClB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACJ,KAAK;gBACL,UAAU;gBACV,QAAQ,EAAE,OAAO;gBACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,MAA4B;QACrC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAyC;YACpE,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACJ,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC7B,GAAG,KAAK;oBACR,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACvD,CAAC,CAAC;aACJ;SACF,CAAC,CAAC;IACL,CAAC;CACF"}
package/dist/http.d.ts CHANGED
@@ -9,6 +9,12 @@ interface RequestOptions {
9
9
  query?: Record<string, string | number | boolean | undefined>;
10
10
  service: BuildspaceService;
11
11
  }
12
+ /**
13
+ * Low-level HTTP transport used internally by all SDK namespaces.
14
+ *
15
+ * Handles authentication headers, API versioning, session tokens,
16
+ * and consistent error mapping to {@link BuildspaceError}.
17
+ */
12
18
  export declare class HttpTransport {
13
19
  readonly baseUrl: string;
14
20
  readonly fetcher: typeof fetch;
@@ -21,7 +27,11 @@ export declare class HttpTransport {
21
27
  key: string;
22
28
  resolvedConfig: ResolvedConfig;
23
29
  });
30
+ /** Remove the stored session token. */
24
31
  clearSession(): void;
32
+ /** Return the current session token, or `null` if none is set. */
33
+ getSessionToken(): string | null;
34
+ /** Store a session token that will be sent as `X-Session-Token` on subsequent requests. */
25
35
  setSession(sessionToken: string): void;
26
36
  request<T>({ service, path, method, query, body, headers, keepalive, }: RequestOptions): Promise<T>;
27
37
  }
@@ -1 +1 @@
1
- {"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAkB,MAAM,UAAU,CAAC;AAChF,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEnE,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,YAAY,CAAuB;gBAE/B,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,cAAc,CAAA;KAAE;IAUpF,YAAY,IAAI,IAAI;IAIpB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAIhC,OAAO,CAAC,CAAC,EAAE,EACf,OAAO,EACP,IAAI,EACJ,MAAc,EACd,KAAK,EACL,IAAI,EACJ,OAAO,EACP,SAAS,GACV,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CA6C/B"}
1
+ {"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAkB,MAAM,UAAU,CAAC;AAChF,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEnE,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,YAAY,CAAuB;gBAE/B,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,cAAc,CAAA;KAAE;IAUpF,uCAAuC;IACvC,YAAY,IAAI,IAAI;IAIpB,kEAAkE;IAClE,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,2FAA2F;IAC3F,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAIhC,OAAO,CAAC,CAAC,EAAE,EACf,OAAO,EACP,IAAI,EACJ,MAAc,EACd,KAAK,EACL,IAAI,EACJ,OAAO,EACP,SAAS,GACV,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CA6C/B"}
package/dist/http.js CHANGED
@@ -1,5 +1,11 @@
1
1
  import { validateApiKey } from "./config";
2
2
  import { BuildspaceError } from "./errors";
3
+ /**
4
+ * Low-level HTTP transport used internally by all SDK namespaces.
5
+ *
6
+ * Handles authentication headers, API versioning, session tokens,
7
+ * and consistent error mapping to {@link BuildspaceError}.
8
+ */
3
9
  export class HttpTransport {
4
10
  baseUrl;
5
11
  fetcher;
@@ -17,9 +23,15 @@ export class HttpTransport {
17
23
  this.version = resolvedConfig.version;
18
24
  this.fetcher = resolvedConfig.fetch;
19
25
  }
26
+ /** Remove the stored session token. */
20
27
  clearSession() {
21
28
  this.sessionToken = null;
22
29
  }
30
+ /** Return the current session token, or `null` if none is set. */
31
+ getSessionToken() {
32
+ return this.sessionToken;
33
+ }
34
+ /** Store a session token that will be sent as `X-Session-Token` on subsequent requests. */
23
35
  setSession(sessionToken) {
24
36
  this.sessionToken = sessionToken;
25
37
  }
package/dist/http.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -5,10 +5,45 @@ import { NotificationsServerNamespace } from "./notifications";
5
5
  import { StorageServerNamespace } from "./storage";
6
6
  export * from "./auth";
7
7
  export type { BuildspaceClientConfig, BuildspaceConfig } from "./config";
8
+ export type { BuildspaceService } from "./errors";
8
9
  export { BuildspaceError } from "./errors";
9
10
  export * from "./events";
10
11
  export * from "./notifications";
11
12
  export * from "./storage";
13
+ /**
14
+ * Buildspace server SDK — use with a secret key (`bs_sec_*`).
15
+ *
16
+ * Provides access to all Buildspace services: auth, events, storage,
17
+ * and notifications. For client-side (browser) usage, use
18
+ * `createClient()` from `@buildspacestudio/sdk/client` instead.
19
+ *
20
+ * @example
21
+ * ```ts
22
+ * import Buildspace from "@buildspacestudio/sdk";
23
+ *
24
+ * const buildspace = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);
25
+ *
26
+ * // Verify a session
27
+ * const session = await buildspace.auth.getSession(sessionToken);
28
+ *
29
+ * // Track an event
30
+ * await buildspace.events.track("user.signed_up", { plan: "pro" }, userId);
31
+ *
32
+ * // Upload a file
33
+ * const { upload_url } = await buildspace.storage.getUploadUrl({
34
+ * key: "avatars/user-123.png",
35
+ * contentType: "image/png",
36
+ * size: fileSize,
37
+ * });
38
+ *
39
+ * // Send an email
40
+ * await buildspace.notifications.send({
41
+ * to: "user@example.com",
42
+ * subject: "Welcome!",
43
+ * html: "<h1>You're in!</h1>",
44
+ * });
45
+ * ```
46
+ */
12
47
  declare class Buildspace {
13
48
  private readonly transport;
14
49
  private _auth;
@@ -16,13 +51,34 @@ declare class Buildspace {
16
51
  private _notifications;
17
52
  private _publicAuth;
18
53
  private _storage;
54
+ /**
55
+ * Create a new server SDK instance.
56
+ *
57
+ * @param secretKey - Your Buildspace secret key (starts with `bs_sec_`).
58
+ * @param config - Optional configuration overrides.
59
+ */
19
60
  constructor(secretKey: string, config?: BuildspaceConfig);
61
+ /** Server-side auth: session verification, OAuth callback handling, sign-out. */
20
62
  get auth(): AuthServerNamespace;
63
+ /**
64
+ * Client-style auth helpers available on the server (e.g. generating sign-in URLs
65
+ * in server-rendered pages). For full server auth, use {@link auth}.
66
+ */
21
67
  get authClient(): AuthClientNamespace;
68
+ /** Server-side event tracking. */
22
69
  get events(): EventsServerNamespace;
70
+ /** Server-side file storage: upload URLs, signed downloads, listing, deletion. */
23
71
  get storage(): StorageServerNamespace;
72
+ /** Server-side transactional email notifications. */
24
73
  get notifications(): NotificationsServerNamespace;
74
+ /** Clear the stored session token. */
25
75
  clearSession(): void;
76
+ /**
77
+ * Set a session token that will be sent as `X-Session-Token` on all
78
+ * subsequent API requests.
79
+ *
80
+ * @param sessionToken - The session token to attach to requests.
81
+ */
26
82
  setSession(sessionToken: string): void;
27
83
  }
28
84
  export { Buildspace };
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,KAAK,gBAAgB,EAAiB,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEnD,cAAc,QAAQ,CAAC;AACvB,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAE1B,cAAM,UAAU;IACd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,QAAQ,CAAuC;gBAE3C,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,gBAAqB;IAO5D,IAAI,IAAI,IAAI,mBAAmB,CAG9B;IAED,IAAI,UAAU,IAAI,mBAAmB,CAGpC;IAED,IAAI,MAAM,IAAI,qBAAqB,CAGlC;IAED,IAAI,OAAO,IAAI,sBAAsB,CAGpC;IAED,IAAI,aAAa,IAAI,4BAA4B,CAGhD;IAED,YAAY,IAAI,IAAI;IAIpB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;CAGvC;AAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,eAAe,UAAU,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,KAAK,gBAAgB,EAAiB,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEnD,cAAc,QAAQ,CAAC;AACvB,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACzE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,cAAM,UAAU;IACd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,QAAQ,CAAuC;IAEvD;;;;;OAKG;gBACS,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,gBAAqB;IAO5D,iFAAiF;IACjF,IAAI,IAAI,IAAI,mBAAmB,CAG9B;IAED;;;OAGG;IACH,IAAI,UAAU,IAAI,mBAAmB,CAGpC;IAED,kCAAkC;IAClC,IAAI,MAAM,IAAI,qBAAqB,CAGlC;IAED,kFAAkF;IAClF,IAAI,OAAO,IAAI,sBAAsB,CAGpC;IAED,qDAAqD;IACrD,IAAI,aAAa,IAAI,4BAA4B,CAGhD;IAED,sCAAsC;IACtC,YAAY,IAAI,IAAI;IAIpB;;;;;OAKG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;CAGvC;AAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,eAAe,UAAU,CAAC"}
package/dist/index.js CHANGED
@@ -9,6 +9,40 @@ export { BuildspaceError } from "./errors";
9
9
  export * from "./events";
10
10
  export * from "./notifications";
11
11
  export * from "./storage";
12
+ /**
13
+ * Buildspace server SDK — use with a secret key (`bs_sec_*`).
14
+ *
15
+ * Provides access to all Buildspace services: auth, events, storage,
16
+ * and notifications. For client-side (browser) usage, use
17
+ * `createClient()` from `@buildspacestudio/sdk/client` instead.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * import Buildspace from "@buildspacestudio/sdk";
22
+ *
23
+ * const buildspace = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);
24
+ *
25
+ * // Verify a session
26
+ * const session = await buildspace.auth.getSession(sessionToken);
27
+ *
28
+ * // Track an event
29
+ * await buildspace.events.track("user.signed_up", { plan: "pro" }, userId);
30
+ *
31
+ * // Upload a file
32
+ * const { upload_url } = await buildspace.storage.getUploadUrl({
33
+ * key: "avatars/user-123.png",
34
+ * contentType: "image/png",
35
+ * size: fileSize,
36
+ * });
37
+ *
38
+ * // Send an email
39
+ * await buildspace.notifications.send({
40
+ * to: "user@example.com",
41
+ * subject: "Welcome!",
42
+ * html: "<h1>You're in!</h1>",
43
+ * });
44
+ * ```
45
+ */
12
46
  class Buildspace {
13
47
  transport;
14
48
  _auth = null;
@@ -16,35 +50,56 @@ class Buildspace {
16
50
  _notifications = null;
17
51
  _publicAuth = null;
18
52
  _storage = null;
53
+ /**
54
+ * Create a new server SDK instance.
55
+ *
56
+ * @param secretKey - Your Buildspace secret key (starts with `bs_sec_`).
57
+ * @param config - Optional configuration overrides.
58
+ */
19
59
  constructor(secretKey, config = {}) {
20
60
  this.transport = new HttpTransport({
21
61
  key: secretKey,
22
62
  resolvedConfig: resolveConfig("server", config),
23
63
  });
24
64
  }
65
+ /** Server-side auth: session verification, OAuth callback handling, sign-out. */
25
66
  get auth() {
26
67
  this._auth ??= new AuthServerNamespace(this.transport);
27
68
  return this._auth;
28
69
  }
70
+ /**
71
+ * Client-style auth helpers available on the server (e.g. generating sign-in URLs
72
+ * in server-rendered pages). For full server auth, use {@link auth}.
73
+ */
29
74
  get authClient() {
30
75
  this._publicAuth ??= new AuthClientNamespace(this.transport);
31
76
  return this._publicAuth;
32
77
  }
78
+ /** Server-side event tracking. */
33
79
  get events() {
34
80
  this._events ??= new EventsServerNamespace(this.transport);
35
81
  return this._events;
36
82
  }
83
+ /** Server-side file storage: upload URLs, signed downloads, listing, deletion. */
37
84
  get storage() {
38
85
  this._storage ??= new StorageServerNamespace(this.transport);
39
86
  return this._storage;
40
87
  }
88
+ /** Server-side transactional email notifications. */
41
89
  get notifications() {
42
90
  this._notifications ??= new NotificationsServerNamespace(this.transport);
43
91
  return this._notifications;
44
92
  }
93
+ /** Clear the stored session token. */
45
94
  clearSession() {
46
95
  this.transport.clearSession();
47
96
  }
97
+ /**
98
+ * Set a session token that will be sent as `X-Session-Token` on all
99
+ * subsequent API requests.
100
+ *
101
+ * @param sessionToken - The session token to attach to requests.
102
+ */
48
103
  setSession(sessionToken) {
49
104
  this.transport.setSession(sessionToken);
50
105
  }
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAyB,aAAa,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEnD,cAAc,QAAQ,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAE1B,MAAM,UAAU;IACG,SAAS,CAAgB;IAClC,KAAK,GAA+B,IAAI,CAAC;IACzC,OAAO,GAAiC,IAAI,CAAC;IAC7C,cAAc,GAAwC,IAAI,CAAC;IAC3D,WAAW,GAA+B,IAAI,CAAC;IAC/C,QAAQ,GAAkC,IAAI,CAAC;IAEvD,YAAY,SAAiB,EAAE,SAA2B,EAAE;QAC1D,IAAI,CAAC,SAAS,GAAG,IAAI,aAAa,CAAC;YACjC,GAAG,EAAE,SAAS;YACd,cAAc,EAAE,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC;SAChD,CAAC,CAAC;IACL,CAAC;IAED,IAAI,IAAI;QACN,IAAI,CAAC,KAAK,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,UAAU;QACZ,IAAI,CAAC,WAAW,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,IAAI,MAAM;QACR,IAAI,CAAC,OAAO,KAAK,IAAI,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,IAAI,OAAO;QACT,IAAI,CAAC,QAAQ,KAAK,IAAI,sBAAsB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAI,aAAa;QACf,IAAI,CAAC,cAAc,KAAK,IAAI,4BAA4B,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzE,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,YAAY;QACV,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,UAAU,CAAC,YAAoB;QAC7B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,eAAe,UAAU,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAyB,aAAa,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEnD,cAAc,QAAQ,CAAC;AAGvB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU;IACG,SAAS,CAAgB;IAClC,KAAK,GAA+B,IAAI,CAAC;IACzC,OAAO,GAAiC,IAAI,CAAC;IAC7C,cAAc,GAAwC,IAAI,CAAC;IAC3D,WAAW,GAA+B,IAAI,CAAC;IAC/C,QAAQ,GAAkC,IAAI,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,SAAiB,EAAE,SAA2B,EAAE;QAC1D,IAAI,CAAC,SAAS,GAAG,IAAI,aAAa,CAAC;YACjC,GAAG,EAAE,SAAS;YACd,cAAc,EAAE,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC;SAChD,CAAC,CAAC;IACL,CAAC;IAED,iFAAiF;IACjF,IAAI,IAAI;QACN,IAAI,CAAC,KAAK,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,IAAI,UAAU;QACZ,IAAI,CAAC,WAAW,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,kCAAkC;IAClC,IAAI,MAAM;QACR,IAAI,CAAC,OAAO,KAAK,IAAI,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,kFAAkF;IAClF,IAAI,OAAO;QACT,IAAI,CAAC,QAAQ,KAAK,IAAI,sBAAsB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,qDAAqD;IACrD,IAAI,aAAa;QACf,IAAI,CAAC,cAAc,KAAK,IAAI,4BAA4B,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzE,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,sCAAsC;IACtC,YAAY;QACV,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,YAAoB;QAC7B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,eAAe,UAAU,CAAC"}