@buildspacestudio/sdk 0.1.1 → 0.2.0

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 +89 -0
  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 +3 -2
package/README.md CHANGED
@@ -52,8 +52,8 @@ if (!session) {
52
52
  // invalid or expired
53
53
  }
54
54
 
55
- // Revoke a session (sign out)
56
- await buildspace.auth.revokeSession(sessionToken);
55
+ // Sign out
56
+ await buildspace.auth.signOut(sessionToken);
57
57
  ```
58
58
 
59
59
  ### Client — generate sign-in / sign-up URLs
@@ -187,8 +187,8 @@ buildspace.setSession(sessionToken);
187
187
  // All subsequent requests carry the session
188
188
  const session = await buildspace.auth.getSession(sessionToken);
189
189
 
190
- // Clear when done
191
- buildspace.clearSession();
190
+ // Sign out and clear the SDK's stored session
191
+ await buildspace.auth.signOut();
192
192
  ```
193
193
 
194
194
  ---
@@ -1,16 +1,65 @@
1
1
  import type { HttpTransport } from "../http";
2
+ /** Options for generating a sign-in URL. */
3
+ export interface SignInUrlOptions {
4
+ /** App slug to scope the login to a specific creator app. */
5
+ appSlug?: string;
6
+ /** Environment to authenticate against. */
7
+ env?: "dev" | "prod";
8
+ /** URL to redirect the user to after authentication completes. */
9
+ redirectUri: string;
10
+ }
11
+ /** Options for generating a sign-up URL. */
12
+ export interface SignUpUrlOptions {
13
+ /** App slug to scope the registration to a specific creator app. */
14
+ appSlug?: string;
15
+ /** Environment to authenticate against. */
16
+ env?: "dev" | "prod";
17
+ /** URL to redirect the user to after registration completes. */
18
+ redirectUri: string;
19
+ }
20
+ /**
21
+ * Client-side authentication methods for generating login URLs.
22
+ *
23
+ * Access via `buildspace.auth` on the client SDK, or `buildspace.authClient`
24
+ * on the server SDK when you need to generate URLs from server-side code.
25
+ *
26
+ * @example
27
+ * ```ts
28
+ * import { createClient } from "@buildspacestudio/sdk/client";
29
+ *
30
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
31
+ *
32
+ * const signInUrl = buildspace.auth.getSignInUrl({
33
+ * redirectUri: "https://yourapp.com/auth/callback",
34
+ * });
35
+ *
36
+ * // Use in a link or redirect
37
+ * window.location.href = signInUrl;
38
+ * ```
39
+ */
2
40
  export declare class AuthClientNamespace {
3
41
  private readonly transport;
4
42
  constructor(transport: HttpTransport);
5
- getSignInUrl(opts: {
6
- appSlug?: string;
7
- env?: "dev" | "prod";
8
- redirectUri: string;
9
- }): string;
10
- getSignUpUrl(opts: {
11
- appSlug?: string;
12
- env?: "dev" | "prod";
13
- redirectUri: string;
14
- }): string;
43
+ /**
44
+ * Build a URL that redirects the user to the Buildspace sign-in page.
45
+ *
46
+ * After the user authenticates, they are redirected back to `redirectUri`
47
+ * with a `?code=` parameter that can be exchanged for tokens via
48
+ * `buildspace.auth.handleCallback()` on the server.
49
+ *
50
+ * @param opts - Sign-in URL options.
51
+ * @returns The full sign-in URL as a string.
52
+ */
53
+ getSignInUrl(opts: SignInUrlOptions): string;
54
+ /**
55
+ * Build a URL that redirects the user to the Buildspace sign-up page.
56
+ *
57
+ * Works identically to {@link getSignInUrl} but directs the user to the
58
+ * registration flow instead.
59
+ *
60
+ * @param opts - Sign-up URL options.
61
+ * @returns The full sign-up URL as a string.
62
+ */
63
+ getSignUpUrl(opts: SignUpUrlOptions): string;
15
64
  }
16
65
  //# sourceMappingURL=client.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,SAAS,EAAE,aAAa;IAIpC,YAAY,CAAC,IAAI,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAiB3F,YAAY,CAAC,IAAI,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;CAgB5F"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,SAAS,EAAE,aAAa;IAIpC;;;;;;;;;OASG;IACH,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM;IAiB5C;;;;;;;;OAQG;IACH,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM;CAgB7C"}
@@ -1,8 +1,38 @@
1
+ /**
2
+ * Client-side authentication methods for generating login URLs.
3
+ *
4
+ * Access via `buildspace.auth` on the client SDK, or `buildspace.authClient`
5
+ * on the server SDK when you need to generate URLs from server-side code.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { createClient } from "@buildspacestudio/sdk/client";
10
+ *
11
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
12
+ *
13
+ * const signInUrl = buildspace.auth.getSignInUrl({
14
+ * redirectUri: "https://yourapp.com/auth/callback",
15
+ * });
16
+ *
17
+ * // Use in a link or redirect
18
+ * window.location.href = signInUrl;
19
+ * ```
20
+ */
1
21
  export class AuthClientNamespace {
2
22
  transport;
3
23
  constructor(transport) {
4
24
  this.transport = transport;
5
25
  }
26
+ /**
27
+ * Build a URL that redirects the user to the Buildspace sign-in page.
28
+ *
29
+ * After the user authenticates, they are redirected back to `redirectUri`
30
+ * with a `?code=` parameter that can be exchanged for tokens via
31
+ * `buildspace.auth.handleCallback()` on the server.
32
+ *
33
+ * @param opts - Sign-in URL options.
34
+ * @returns The full sign-in URL as a string.
35
+ */
6
36
  getSignInUrl(opts) {
7
37
  const url = new URL("/sign-in", this.transport.loginUrl);
8
38
  if (opts.appSlug) {
@@ -15,6 +45,15 @@ export class AuthClientNamespace {
15
45
  }
16
46
  return url.toString();
17
47
  }
48
+ /**
49
+ * Build a URL that redirects the user to the Buildspace sign-up page.
50
+ *
51
+ * Works identically to {@link getSignInUrl} but directs the user to the
52
+ * registration flow instead.
53
+ *
54
+ * @param opts - Sign-up URL options.
55
+ * @returns The full sign-up URL as a string.
56
+ */
18
57
  getSignUpUrl(opts) {
19
58
  const url = new URL("/sign-up", this.transport.loginUrl);
20
59
  if (opts.appSlug) {
@@ -1 +1 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,mBAAmB;IACb,SAAS,CAAgB;IAE1C,YAAY,SAAwB;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,YAAY,CAAC,IAAqE;QAChF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAEzD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QAED,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACvD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAEtD,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAED,YAAY,CAAC,IAAqE;QAChF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAEzD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QAED,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACvD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAEtD,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;CACF"}
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,mBAAmB;IACb,SAAS,CAAgB;IAE1C,YAAY,SAAwB;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;;;;OASG;IACH,YAAY,CAAC,IAAsB;QACjC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAEzD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QAED,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACvD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAEtD,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAED;;;;;;;;OAQG;IACH,YAAY,CAAC,IAAsB;QACjC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAEzD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QAED,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACvD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAEtD,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;CACF"}
@@ -1,3 +1,4 @@
1
+ export type { SignInUrlOptions, SignUpUrlOptions } from "./client";
1
2
  export { AuthClientNamespace } from "./client";
2
3
  export type { AuthSession, AuthUser, TokenResponse } from "./server";
3
4
  export { AuthServerNamespace } from "./server";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}
@@ -1,26 +1,115 @@
1
1
  import type { HttpTransport } from "../http";
2
+ /** A Buildspace user returned from auth endpoints. */
2
3
  export interface AuthUser {
4
+ /** The user's email address. */
3
5
  email: string;
6
+ /** Unique user identifier. */
4
7
  id: string;
8
+ /** The user's display name, or `null` if not set. */
5
9
  name: string | null;
6
10
  }
11
+ /**
12
+ * An active session for an authenticated user.
13
+ *
14
+ * Returned by {@link AuthServerNamespace.getSession}.
15
+ */
7
16
  export interface AuthSession {
17
+ /** The app this session belongs to, or `null` for platform-level sessions. */
8
18
  appId: string | null;
19
+ /** The authenticated user. */
9
20
  user: AuthUser;
10
21
  }
22
+ /**
23
+ * Token response returned after a successful OAuth callback exchange.
24
+ *
25
+ * Returned by {@link AuthServerNamespace.handleCallback}.
26
+ */
11
27
  export interface TokenResponse {
28
+ /** The access token to use for authenticated requests. */
12
29
  access_token: string;
30
+ /** Token lifetime in seconds. */
13
31
  expires_in: number;
32
+ /** Always `"bearer"`. */
14
33
  token_type: string;
34
+ /** The authenticated user. */
15
35
  user: AuthUser;
16
36
  }
37
+ /**
38
+ * Server-side authentication methods.
39
+ *
40
+ * Access via `buildspace.auth` on the server SDK.
41
+ *
42
+ * @example
43
+ * ```ts
44
+ * import Buildspace from "@buildspacestudio/sdk";
45
+ *
46
+ * const buildspace = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);
47
+ *
48
+ * // Handle OAuth callback
49
+ * const tokens = await buildspace.auth.handleCallback(request);
50
+ *
51
+ * // Verify a session
52
+ * const session = await buildspace.auth.getSession(sessionToken);
53
+ *
54
+ * // Sign out
55
+ * await buildspace.auth.signOut(sessionToken);
56
+ * ```
57
+ */
17
58
  export declare class AuthServerNamespace {
18
59
  private readonly transport;
19
60
  constructor(transport: HttpTransport);
61
+ /**
62
+ * Retrieve the session associated with a token.
63
+ *
64
+ * Returns the {@link AuthSession} if valid, or `null` if the token is
65
+ * expired, revoked, or invalid (401/404).
66
+ *
67
+ * @throws {BuildspaceError} On unexpected server errors (5xx, network issues).
68
+ */
20
69
  getSession(sessionToken: string): Promise<AuthSession | null>;
70
+ /**
71
+ * Exchange an OAuth authorization code for tokens.
72
+ *
73
+ * Extracts the `code` query parameter from the callback URL and exchanges
74
+ * it with the Buildspace API for an access token and user info.
75
+ *
76
+ * @param request - The incoming callback request. Accepts a `Request` object,
77
+ * a `URL`, or a raw URL string containing the `?code=` parameter.
78
+ * @param opts - Optional settings.
79
+ * @param opts.redirectUri - Override the redirect URI sent to the token endpoint.
80
+ * Defaults to the origin + pathname of the callback URL.
81
+ * @returns The token response containing `access_token`, `expires_in`, and `user`.
82
+ *
83
+ * @throws {BuildspaceError} If the code exchange fails (invalid code, expired, etc.).
84
+ *
85
+ * @example
86
+ * ```ts
87
+ * // Next.js Route Handler
88
+ * export async function GET(request: Request) {
89
+ * const { access_token, user } = await buildspace.auth.handleCallback(request);
90
+ * // Store access_token as a session cookie
91
+ * }
92
+ * ```
93
+ */
21
94
  handleCallback(request: Request | URL | string, opts?: {
22
95
  redirectUri?: string;
23
96
  }): Promise<TokenResponse>;
97
+ /**
98
+ * Revoke a specific session token.
99
+ *
100
+ * @param sessionToken - The token to revoke.
101
+ * @throws {BuildspaceError} If the revocation fails.
102
+ */
24
103
  revokeSession(sessionToken: string): Promise<void>;
104
+ /**
105
+ * Sign the user out by revoking the session and clearing the SDK's stored token.
106
+ *
107
+ * If the session is already expired or not found, the error is silently
108
+ * ignored and the local session is still cleared.
109
+ *
110
+ * @param sessionToken - Token to revoke. If omitted, uses the token
111
+ * previously set via `buildspace.setSession()`.
112
+ */
113
+ signOut(sessionToken?: string): Promise<void>;
25
114
  }
26
115
  //# sourceMappingURL=server.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/auth/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,SAAS,EAAE,aAAa;IAI9B,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAYnE,cAAc,CACZ,OAAO,EAAE,OAAO,GAAG,GAAG,GAAG,MAAM,EAC/B,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9B,OAAO,CAAC,aAAa,CAAC;IA4BnB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQzD"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/auth/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,sDAAsD;AACtD,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8BAA8B;IAC9B,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,SAAS,EAAE,aAAa;IAIpC;;;;;;;OAOG;IACG,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAenE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,cAAc,CACZ,OAAO,EAAE,OAAO,GAAG,GAAG,GAAG,MAAM,EAC/B,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9B,OAAO,CAAC,aAAa,CAAC;IAiCzB;;;;;OAKG;IACG,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASxD;;;;;;;;OAQG;IACG,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBpD"}
@@ -1,8 +1,38 @@
1
+ import { BuildspaceError } from "../errors";
2
+ /**
3
+ * Server-side authentication methods.
4
+ *
5
+ * Access via `buildspace.auth` on the server SDK.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import Buildspace from "@buildspacestudio/sdk";
10
+ *
11
+ * const buildspace = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);
12
+ *
13
+ * // Handle OAuth callback
14
+ * const tokens = await buildspace.auth.handleCallback(request);
15
+ *
16
+ * // Verify a session
17
+ * const session = await buildspace.auth.getSession(sessionToken);
18
+ *
19
+ * // Sign out
20
+ * await buildspace.auth.signOut(sessionToken);
21
+ * ```
22
+ */
1
23
  export class AuthServerNamespace {
2
24
  transport;
3
25
  constructor(transport) {
4
26
  this.transport = transport;
5
27
  }
28
+ /**
29
+ * Retrieve the session associated with a token.
30
+ *
31
+ * Returns the {@link AuthSession} if valid, or `null` if the token is
32
+ * expired, revoked, or invalid (401/404).
33
+ *
34
+ * @throws {BuildspaceError} On unexpected server errors (5xx, network issues).
35
+ */
6
36
  async getSession(sessionToken) {
7
37
  try {
8
38
  return await this.transport.request({
@@ -11,10 +41,37 @@ export class AuthServerNamespace {
11
41
  headers: { "X-Session-Token": sessionToken },
12
42
  });
13
43
  }
14
- catch {
15
- return null;
44
+ catch (error) {
45
+ if (error instanceof BuildspaceError && (error.status === 401 || error.status === 404)) {
46
+ return null;
47
+ }
48
+ throw error;
16
49
  }
17
50
  }
51
+ /**
52
+ * Exchange an OAuth authorization code for tokens.
53
+ *
54
+ * Extracts the `code` query parameter from the callback URL and exchanges
55
+ * it with the Buildspace API for an access token and user info.
56
+ *
57
+ * @param request - The incoming callback request. Accepts a `Request` object,
58
+ * a `URL`, or a raw URL string containing the `?code=` parameter.
59
+ * @param opts - Optional settings.
60
+ * @param opts.redirectUri - Override the redirect URI sent to the token endpoint.
61
+ * Defaults to the origin + pathname of the callback URL.
62
+ * @returns The token response containing `access_token`, `expires_in`, and `user`.
63
+ *
64
+ * @throws {BuildspaceError} If the code exchange fails (invalid code, expired, etc.).
65
+ *
66
+ * @example
67
+ * ```ts
68
+ * // Next.js Route Handler
69
+ * export async function GET(request: Request) {
70
+ * const { access_token, user } = await buildspace.auth.handleCallback(request);
71
+ * // Store access_token as a session cookie
72
+ * }
73
+ * ```
74
+ */
18
75
  handleCallback(request, opts) {
19
76
  let url;
20
77
  if (typeof request === "string") {
@@ -28,7 +85,12 @@ export class AuthServerNamespace {
28
85
  }
29
86
  const code = url.searchParams.get("code");
30
87
  if (!code) {
31
- throw new Error("No auth code found in callback URL. Expected ?code= parameter.");
88
+ throw new BuildspaceError({
89
+ service: "auth",
90
+ status: 400,
91
+ code: "auth/missing-code",
92
+ message: "No auth code found in callback URL. Expected ?code= parameter.",
93
+ });
32
94
  }
33
95
  const redirectUri = opts?.redirectUri ?? `${url.origin}${url.pathname}`;
34
96
  return this.transport.request({
@@ -41,6 +103,12 @@ export class AuthServerNamespace {
41
103
  },
42
104
  });
43
105
  }
106
+ /**
107
+ * Revoke a specific session token.
108
+ *
109
+ * @param sessionToken - The token to revoke.
110
+ * @throws {BuildspaceError} If the revocation fails.
111
+ */
44
112
  async revokeSession(sessionToken) {
45
113
  await this.transport.request({
46
114
  service: "auth",
@@ -49,5 +117,32 @@ export class AuthServerNamespace {
49
117
  headers: { "X-Session-Token": sessionToken },
50
118
  });
51
119
  }
120
+ /**
121
+ * Sign the user out by revoking the session and clearing the SDK's stored token.
122
+ *
123
+ * If the session is already expired or not found, the error is silently
124
+ * ignored and the local session is still cleared.
125
+ *
126
+ * @param sessionToken - Token to revoke. If omitted, uses the token
127
+ * previously set via `buildspace.setSession()`.
128
+ */
129
+ async signOut(sessionToken) {
130
+ const token = sessionToken ?? this.transport.getSessionToken();
131
+ try {
132
+ if (token) {
133
+ await this.revokeSession(token);
134
+ }
135
+ }
136
+ catch (error) {
137
+ if (!(error instanceof BuildspaceError &&
138
+ error.service === "auth" &&
139
+ (error.status === 401 || error.status === 404))) {
140
+ throw error;
141
+ }
142
+ }
143
+ finally {
144
+ this.transport.clearSession();
145
+ }
146
+ }
52
147
  }
53
148
  //# sourceMappingURL=server.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/auth/server.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,mBAAmB;IACb,SAAS,CAAgB;IAE1C,YAAY,SAAwB;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,YAAoB;QACnC,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAc;gBAC/C,OAAO,EAAE,MAAM;gBACf,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,EAAE,iBAAiB,EAAE,YAAY,EAAE;aAC7C,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,cAAc,CACZ,OAA+B,EAC/B,IAA+B;QAE/B,IAAI,GAAQ,CAAC;QACb,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;aAAM,IAAI,OAAO,YAAY,GAAG,EAAE,CAAC;YAClC,GAAG,GAAG,OAAO,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAED,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;QACpF,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,EAAE,WAAW,IAAI,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QAExE,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAgB;YAC3C,OAAO,EAAE,MAAM;YACf,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACJ,IAAI;gBACJ,YAAY,EAAE,WAAW;aAC1B;SACF,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,YAAoB;QACtC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAO;YACjC,OAAO,EAAE,MAAM;YACf,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,EAAE,iBAAiB,EAAE,YAAY,EAAE;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/auth/server.ts"],"names":[],"mappings":"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"}
@@ -2,20 +2,83 @@ import { AuthClientNamespace } from "../auth";
2
2
  import { type BuildspaceClientConfig } from "../config";
3
3
  import { EventsClientNamespace } from "../events";
4
4
  import { StorageClientNamespace } from "../storage";
5
+ /**
6
+ * Buildspace client SDK — use with a publishable key (`bs_pub_*`).
7
+ *
8
+ * Provides client-safe access to auth URL generation, event tracking
9
+ * (with automatic batching), and file uploads. For server-side usage
10
+ * with full API access, use `new Buildspace()` from `@buildspacestudio/sdk`.
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * import { createClient } from "@buildspacestudio/sdk/client";
15
+ *
16
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
17
+ *
18
+ * // Generate a sign-in URL
19
+ * const url = buildspace.auth.getSignInUrl({
20
+ * redirectUri: "https://yourapp.com/auth/callback",
21
+ * });
22
+ *
23
+ * // Track an event (fire and forget)
24
+ * buildspace.events.track("button.clicked", { label: "upgrade" });
25
+ *
26
+ * // Upload a file
27
+ * const { key, url } = await buildspace.storage.upload(file, {
28
+ * path: "avatars/user-123.png",
29
+ * });
30
+ * ```
31
+ */
5
32
  declare class BuildspaceClient {
6
33
  private readonly transport;
7
34
  private readonly config;
8
35
  private _auth;
9
36
  private _events;
10
37
  private _storage;
38
+ /**
39
+ * Create a new client SDK instance.
40
+ *
41
+ * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).
42
+ * @param config - Optional configuration overrides.
43
+ */
11
44
  constructor(publishableKey: string, config?: BuildspaceClientConfig);
45
+ /** Client-side auth: sign-in and sign-up URL generation. */
12
46
  get auth(): AuthClientNamespace;
47
+ /** Client-side event tracking with automatic batching. */
13
48
  get events(): EventsClientNamespace;
49
+ /** Client-side file storage: uploads, downloads, listing, deletion. */
14
50
  get storage(): StorageClientNamespace;
51
+ /**
52
+ * Notifications are server-only and not available on the client SDK.
53
+ *
54
+ * @throws {BuildspaceError} Always throws — use the server SDK for notifications.
55
+ */
15
56
  get notifications(): never;
57
+ /** Clear the stored session token. */
16
58
  clearSession(): void;
59
+ /**
60
+ * Set a session token that will be sent as `X-Session-Token` on all
61
+ * subsequent API requests.
62
+ *
63
+ * @param sessionToken - The session token to attach to requests.
64
+ */
17
65
  setSession(sessionToken: string): void;
18
66
  }
67
+ /**
68
+ * Create a Buildspace client SDK instance.
69
+ *
70
+ * Preferred over `new BuildspaceClient()` for a more concise API.
71
+ *
72
+ * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).
73
+ * @param config - Optional configuration overrides.
74
+ *
75
+ * @example
76
+ * ```ts
77
+ * import { createClient } from "@buildspacestudio/sdk/client";
78
+ *
79
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
80
+ * ```
81
+ */
19
82
  export declare function createClient(publishableKey: string, config?: BuildspaceClientConfig): BuildspaceClient;
20
83
  export { BuildspaceClient };
21
84
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,KAAK,sBAAsB,EAAiB,MAAM,WAAW,CAAC;AAEvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,cAAM,gBAAgB;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,QAAQ,CAAuC;gBAE3C,cAAc,EAAE,MAAM,EAAE,MAAM,GAAE,sBAA2B;IAQvE,IAAI,IAAI,IAAI,mBAAmB,CAG9B;IAED,IAAI,MAAM,IAAI,qBAAqB,CAGlC;IAED,IAAI,OAAO,IAAI,sBAAsB,CAGpC;IAED,IAAI,aAAa,IAAI,KAAK,CAQzB;IAED,YAAY,IAAI,IAAI;IAIpB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;CAGvC;AAED,wBAAgB,YAAY,CAC1B,cAAc,EAAE,MAAM,EACtB,MAAM,GAAE,sBAA2B,GAClC,gBAAgB,CAElB;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,KAAK,sBAAsB,EAAiB,MAAM,WAAW,CAAC;AAEvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,cAAM,gBAAgB;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,QAAQ,CAAuC;IAEvD;;;;;OAKG;gBACS,cAAc,EAAE,MAAM,EAAE,MAAM,GAAE,sBAA2B;IAQvE,4DAA4D;IAC5D,IAAI,IAAI,IAAI,mBAAmB,CAG9B;IAED,0DAA0D;IAC1D,IAAI,MAAM,IAAI,qBAAqB,CAGlC;IAED,uEAAuE;IACvE,IAAI,OAAO,IAAI,sBAAsB,CAGpC;IAED;;;;OAIG;IACH,IAAI,aAAa,IAAI,KAAK,CAQzB;IAED,sCAAsC;IACtC,YAAY,IAAI,IAAI;IAIpB;;;;;OAKG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;CAGvC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,cAAc,EAAE,MAAM,EACtB,MAAM,GAAE,sBAA2B,GAClC,gBAAgB,CAElB;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}
@@ -4,12 +4,45 @@ import { BuildspaceError } from "../errors";
4
4
  import { EventsClientNamespace } from "../events";
5
5
  import { HttpTransport } from "../http";
6
6
  import { StorageClientNamespace } from "../storage";
7
+ /**
8
+ * Buildspace client SDK — use with a publishable key (`bs_pub_*`).
9
+ *
10
+ * Provides client-safe access to auth URL generation, event tracking
11
+ * (with automatic batching), and file uploads. For server-side usage
12
+ * with full API access, use `new Buildspace()` from `@buildspacestudio/sdk`.
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * import { createClient } from "@buildspacestudio/sdk/client";
17
+ *
18
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
19
+ *
20
+ * // Generate a sign-in URL
21
+ * const url = buildspace.auth.getSignInUrl({
22
+ * redirectUri: "https://yourapp.com/auth/callback",
23
+ * });
24
+ *
25
+ * // Track an event (fire and forget)
26
+ * buildspace.events.track("button.clicked", { label: "upgrade" });
27
+ *
28
+ * // Upload a file
29
+ * const { key, url } = await buildspace.storage.upload(file, {
30
+ * path: "avatars/user-123.png",
31
+ * });
32
+ * ```
33
+ */
7
34
  class BuildspaceClient {
8
35
  transport;
9
36
  config;
10
37
  _auth = null;
11
38
  _events = null;
12
39
  _storage = null;
40
+ /**
41
+ * Create a new client SDK instance.
42
+ *
43
+ * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).
44
+ * @param config - Optional configuration overrides.
45
+ */
13
46
  constructor(publishableKey, config = {}) {
14
47
  this.config = config;
15
48
  this.transport = new HttpTransport({
@@ -17,18 +50,26 @@ class BuildspaceClient {
17
50
  resolvedConfig: resolveConfig("client", config),
18
51
  });
19
52
  }
53
+ /** Client-side auth: sign-in and sign-up URL generation. */
20
54
  get auth() {
21
55
  this._auth ??= new AuthClientNamespace(this.transport);
22
56
  return this._auth;
23
57
  }
58
+ /** Client-side event tracking with automatic batching. */
24
59
  get events() {
25
60
  this._events ??= new EventsClientNamespace(this.transport, this.config.events);
26
61
  return this._events;
27
62
  }
63
+ /** Client-side file storage: uploads, downloads, listing, deletion. */
28
64
  get storage() {
29
65
  this._storage ??= new StorageClientNamespace(this.transport);
30
66
  return this._storage;
31
67
  }
68
+ /**
69
+ * Notifications are server-only and not available on the client SDK.
70
+ *
71
+ * @throws {BuildspaceError} Always throws — use the server SDK for notifications.
72
+ */
32
73
  get notifications() {
33
74
  throw new BuildspaceError({
34
75
  service: "notifications",
@@ -37,13 +78,35 @@ class BuildspaceClient {
37
78
  message: "Notifications require a secret key. Use the server SDK via new Buildspace() from '@buildspacestudio/sdk'.",
38
79
  });
39
80
  }
81
+ /** Clear the stored session token. */
40
82
  clearSession() {
41
83
  this.transport.clearSession();
42
84
  }
85
+ /**
86
+ * Set a session token that will be sent as `X-Session-Token` on all
87
+ * subsequent API requests.
88
+ *
89
+ * @param sessionToken - The session token to attach to requests.
90
+ */
43
91
  setSession(sessionToken) {
44
92
  this.transport.setSession(sessionToken);
45
93
  }
46
94
  }
95
+ /**
96
+ * Create a Buildspace client SDK instance.
97
+ *
98
+ * Preferred over `new BuildspaceClient()` for a more concise API.
99
+ *
100
+ * @param publishableKey - Your Buildspace publishable key (starts with `bs_pub_`).
101
+ * @param config - Optional configuration overrides.
102
+ *
103
+ * @example
104
+ * ```ts
105
+ * import { createClient } from "@buildspacestudio/sdk/client";
106
+ *
107
+ * const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
108
+ * ```
109
+ */
47
110
  export function createClient(publishableKey, config = {}) {
48
111
  return new BuildspaceClient(publishableKey, config);
49
112
  }
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAA+B,aAAa,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,gBAAgB;IACH,SAAS,CAAgB;IACzB,MAAM,CAAyB;IACxC,KAAK,GAA+B,IAAI,CAAC;IACzC,OAAO,GAAiC,IAAI,CAAC;IAC7C,QAAQ,GAAkC,IAAI,CAAC;IAEvD,YAAY,cAAsB,EAAE,SAAiC,EAAE;QACrE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,aAAa,CAAC;YACjC,GAAG,EAAE,cAAc;YACnB,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,MAAM;QACR,IAAI,CAAC,OAAO,KAAK,IAAI,qBAAqB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/E,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,MAAM,IAAI,eAAe,CAAC;YACxB,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,2BAA2B;YACjC,OAAO,EACL,2GAA2G;SAC9G,CAAC,CAAC;IACL,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,MAAM,UAAU,YAAY,CAC1B,cAAsB,EACtB,SAAiC,EAAE;IAEnC,OAAO,IAAI,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAA+B,aAAa,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,gBAAgB;IACH,SAAS,CAAgB;IACzB,MAAM,CAAyB;IACxC,KAAK,GAA+B,IAAI,CAAC;IACzC,OAAO,GAAiC,IAAI,CAAC;IAC7C,QAAQ,GAAkC,IAAI,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,cAAsB,EAAE,SAAiC,EAAE;QACrE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,aAAa,CAAC;YACjC,GAAG,EAAE,cAAc;YACnB,cAAc,EAAE,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC;SAChD,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IAC5D,IAAI,IAAI;QACN,IAAI,CAAC,KAAK,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,0DAA0D;IAC1D,IAAI,MAAM;QACR,IAAI,CAAC,OAAO,KAAK,IAAI,qBAAqB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,uEAAuE;IACvE,IAAI,OAAO;QACT,IAAI,CAAC,QAAQ,KAAK,IAAI,sBAAsB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,IAAI,aAAa;QACf,MAAM,IAAI,eAAe,CAAC;YACxB,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,2BAA2B;YACjC,OAAO,EACL,2GAA2G;SAC9G,CAAC,CAAC;IACL,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;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,cAAsB,EACtB,SAAiC,EAAE;IAEnC,OAAO,IAAI,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}