@buildspacestudio/sdk 0.2.2 → 0.4.0

package/dist/next/index.d.ts

@@ -0,0 +1,164 @@
+import { a as AuthSession, T as TokenResponse, b as AuthUser } from '../server-Suq3tZZC.js';
+import '../http-D2gXpNpr.js';
+
+/**
+ * Framework adapter for Next.js (and any framework using web-standard
+ * `Request`/`Response` route handlers).
+ *
+ * Replaces the auth glue every creator app used to hand-roll: the OAuth
+ * callback route, logout + session routes, a cookie-aware `getSession()`,
+ * and a middleware cookie guard — all standardized on the `bs_session`
+ * cookie.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/callback/route.ts
+ * import { createAuthCallback } from "@buildspacestudio/sdk/next";
+ * import { getServerClient } from "@/lib/buildspace";
+ *
+ * export const GET = createAuthCallback(getServerClient(), { redirectTo: "/dashboard" });
+ * ```
+ */
+/** The session cookie name shared by every Buildspace app. */
+declare const SESSION_COOKIE_NAME = "bs_session";
+/** The minimal server-client surface the adapter needs (a `Buildspace` instance). */
+interface AuthServerClient {
+    auth: {
+        getSession(sessionToken: string): Promise<AuthSession | null>;
+        handleCallback(request: Request | URL | string, opts?: {
+            redirectUri?: string;
+        }): Promise<TokenResponse>;
+        signOut(sessionToken?: string): Promise<void>;
+    };
+}
+/** Options controlling the `bs_session` cookie attributes. */
+interface SessionCookieOptions {
+    /** Cookie domain. Omitted by default (host-only cookie). */
+    domain?: string;
+    /** Cookie path. Defaults to `/`. */
+    path?: string;
+    /** SameSite attribute. Defaults to `Lax`. */
+    sameSite?: "lax" | "strict" | "none";
+    /** Set the `Secure` attribute. Defaults to `true` outside development. */
+    secure?: boolean;
+}
+/** Build a `Set-Cookie` header value that stores the session token. */
+declare function buildSessionCookie(token: string, maxAgeSeconds: number, opts?: SessionCookieOptions): string;
+/** Build a `Set-Cookie` header value that clears the session cookie. */
+declare function buildClearSessionCookie(opts?: SessionCookieOptions): string;
+/**
+ * Anything the adapter can read the session cookie from: a web `Request`,
+ * or a cookie store with a `get(name)` method (e.g. the object returned by
+ * Next.js `cookies()` in Server Components and Route Handlers).
+ */
+type SessionCookieSource = Request | {
+    get(name: string): {
+        value: string;
+    } | string | null | undefined;
+};
+/** Read the raw session token from a request or cookie store, or `null`. */
+declare function getSessionToken(source: SessionCookieSource): string | null;
+/** An {@link AuthSession} plus the raw token it was resolved from. */
+type SessionWithToken = AuthSession & {
+    token: string;
+};
+/**
+ * Cookie-aware session lookup.
+ *
+ * Reads the `bs_session` cookie from the given source and verifies it with
+ * the Buildspace API. Returns `null` when there is no cookie or the token
+ * is expired/revoked. Network/5xx errors also resolve to `null` so a blip
+ * never crashes rendering — sign-in state degrades to "signed out".
+ *
+ * @example
+ * ```ts
+ * // Server Component
+ * import { cookies } from "next/headers";
+ * const session = await getSession(getServerClient(), await cookies());
+ * ```
+ */
+declare function getSession(client: AuthServerClient, source: SessionCookieSource): Promise<SessionWithToken | null>;
+/**
+ * Like {@link getSession} but throws a `BuildspaceError` (401) when there is
+ * no valid session. Use in route handlers and server actions that must only
+ * run for signed-in users.
+ */
+declare function requireSession(client: AuthServerClient, source: SessionCookieSource): Promise<SessionWithToken>;
+/** Options for {@link createAuthCallback}. */
+interface CreateAuthCallbackOptions {
+    /** Cookie attribute overrides. */
+    cookie?: SessionCookieOptions;
+    /**
+     * Called when the code exchange fails. Return a `Response` to control the
+     * error page; by default the error is rethrown (surfacing your framework's
+     * error handling).
+     */
+    onError?: (error: unknown, request: Request) => Response | Promise<Response>;
+    /**
+     * Signup/sign-in side effects (mirror the user into your DB, send a
+     * welcome email, track an event). Failures are logged and never break
+     * login.
+     */
+    onSignIn?: (ctx: {
+        accessToken: string;
+        request: Request;
+        user: AuthUser;
+    }) => void | Promise<void>;
+    /** Where to send the user after login. Defaults to `/`. */
+    redirectTo?: string;
+}
+/**
+ * Create the OAuth callback route handler.
+ *
+ * Exchanges the `?code=` for tokens, runs your `onSignIn` hook, stores the
+ * access token in the `bs_session` cookie (with `expires_in` as `Max-Age`),
+ * and redirects to `redirectTo`.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/callback/route.ts
+ * export const GET = createAuthCallback(getServerClient(), {
+ *   redirectTo: "/dashboard",
+ *   onSignIn: async ({ user }) => upsertUser(user),
+ * });
+ * ```
+ */
+declare function createAuthCallback(client: AuthServerClient, options?: CreateAuthCallbackOptions): (request: Request) => Promise<Response>;
+/**
+ * Create the logout route handler (`POST /api/auth/logout`).
+ *
+ * Revokes the session with the Buildspace API (already-expired sessions are
+ * ignored) and clears the `bs_session` cookie.
+ */
+declare function createLogoutRoute(client: AuthServerClient, options?: {
+    cookie?: SessionCookieOptions;
+}): (request: Request) => Promise<Response>;
+/**
+ * Create the session route handler (`GET /api/auth/session`).
+ *
+ * Returns `{ session }` for the current cookie, with the raw token omitted —
+ * this response is safe to expose to the browser.
+ */
+declare function createSessionRoute(client: AuthServerClient): (request: Request) => Promise<Response>;
+/**
+ * Middleware helper: redirect requests that don't carry a session cookie.
+ *
+ * This is a fast presence check (no API call — middleware runs on every
+ * matched request); route handlers and pages must still verify the session
+ * with {@link getSession}.
+ *
+ * @example
+ * ```ts
+ * // middleware.ts / proxy.ts
+ * import { createSessionCookieGuard } from "@buildspacestudio/sdk/next";
+ *
+ * export const proxy = createSessionCookieGuard({ redirectTo: "/" });
+ * export const config = { matcher: ["/dashboard/:path*"] };
+ * ```
+ */
+declare function createSessionCookieGuard(options?: {
+    /** Where to send signed-out users. Defaults to `/`. */
+    redirectTo?: string;
+}): (request: Request) => Response | undefined;
+
+export { type AuthServerClient, type CreateAuthCallbackOptions, SESSION_COOKIE_NAME, type SessionCookieOptions, type SessionCookieSource, type SessionWithToken, buildClearSessionCookie, buildSessionCookie, createAuthCallback, createLogoutRoute, createSessionCookieGuard, createSessionRoute, getSession, getSessionToken, requireSession };

package/dist/next/index.js

@@ -0,0 +1,172 @@
+// src/errors.ts
+var BuildspaceError = class extends Error {
+  /** Machine-readable error code, e.g. `"auth/invalid-token"`. */
+  code;
+  /** Which service produced the error. */
+  service;
+  /** HTTP status code from the API. */
+  status;
+  constructor({
+    code,
+    message,
+    service,
+    status
+  }) {
+    super(message);
+    this.name = "BuildspaceError";
+    this.code = code;
+    this.service = service;
+    this.status = status;
+  }
+};
+
+// src/next/index.ts
+var SESSION_COOKIE_NAME = "bs_session";
+function isSecureDefault() {
+  return globalThis.process?.env?.NODE_ENV !== "development";
+}
+function serializeSessionCookie(value, maxAge, opts) {
+  const parts = [
+    `${SESSION_COOKIE_NAME}=${value}`,
+    `Path=${opts?.path ?? "/"}`,
+    "HttpOnly",
+    `SameSite=${opts?.sameSite === "strict" ? "Strict" : opts?.sameSite === "none" ? "None" : "Lax"}`
+  ];
+  if (maxAge !== null) {
+    parts.push(`Max-Age=${Math.max(0, Math.floor(maxAge))}`);
+  }
+  if (opts?.secure ?? isSecureDefault()) {
+    parts.push("Secure");
+  }
+  if (opts?.domain) {
+    parts.push(`Domain=${opts.domain}`);
+  }
+  return parts.join("; ");
+}
+function buildSessionCookie(token, maxAgeSeconds, opts) {
+  return serializeSessionCookie(token, maxAgeSeconds, opts);
+}
+function buildClearSessionCookie(opts) {
+  return serializeSessionCookie("", 0, opts);
+}
+function parseCookieHeader(header, name) {
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) {
+      continue;
+    }
+    if (part.slice(0, eq).trim() === name) {
+      return part.slice(eq + 1).trim();
+    }
+  }
+  return null;
+}
+function getSessionToken(source) {
+  if (source instanceof Request) {
+    const header = source.headers.get("cookie");
+    return header ? parseCookieHeader(header, SESSION_COOKIE_NAME) : null;
+  }
+  const cookie = source.get(SESSION_COOKIE_NAME);
+  if (!cookie) {
+    return null;
+  }
+  const value = typeof cookie === "string" ? cookie : cookie.value;
+  return value || null;
+}
+async function getSession(client, source) {
+  const token = getSessionToken(source);
+  if (!token) {
+    return null;
+  }
+  try {
+    const session = await client.auth.getSession(token);
+    return session ? { ...session, token } : null;
+  } catch {
+    return null;
+  }
+}
+async function requireSession(client, source) {
+  const session = await getSession(client, source);
+  if (!session) {
+    throw new BuildspaceError({
+      service: "auth",
+      status: 401,
+      code: "auth/session-required",
+      message: "No valid session. The bs_session cookie is missing, expired, or revoked."
+    });
+  }
+  return session;
+}
+function createAuthCallback(client, options) {
+  return async (request) => {
+    let tokens;
+    try {
+      tokens = await client.auth.handleCallback(request);
+    } catch (error) {
+      if (options?.onError) {
+        return await options.onError(error, request);
+      }
+      throw error;
+    }
+    if (options?.onSignIn) {
+      try {
+        await options.onSignIn({
+          accessToken: tokens.access_token,
+          request,
+          user: tokens.user
+        });
+      } catch (error) {
+        console.error("[buildspace] onSignIn hook failed", error);
+      }
+    }
+    return new Response(null, {
+      status: 303,
+      headers: {
+        Location: options?.redirectTo ?? "/",
+        "Set-Cookie": buildSessionCookie(tokens.access_token, tokens.expires_in, options?.cookie)
+      }
+    });
+  };
+}
+function createLogoutRoute(client, options) {
+  return async (request) => {
+    const token = getSessionToken(request);
+    if (token) {
+      try {
+        await client.auth.signOut(token);
+      } catch (error) {
+        console.error("[buildspace] session revoke failed during logout", error);
+      }
+    }
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json",
+        "Set-Cookie": buildClearSessionCookie(options?.cookie)
+      }
+    });
+  };
+}
+function createSessionRoute(client) {
+  return async (request) => {
+    const session = await getSession(client, request);
+    const publicSession = session ? { appId: session.appId, user: session.user } : null;
+    return new Response(JSON.stringify({ session: publicSession }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" }
+    });
+  };
+}
+function createSessionCookieGuard(options) {
+  return (request) => {
+    if (getSessionToken(request)) {
+      return;
+    }
+    const target = new URL(options?.redirectTo ?? "/", new URL(request.url).origin);
+    return Response.redirect(target.toString(), 307);
+  };
+}
+
+export { SESSION_COOKIE_NAME, buildClearSessionCookie, buildSessionCookie, createAuthCallback, createLogoutRoute, createSessionCookieGuard, createSessionRoute, getSession, getSessionToken, requireSession };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/next/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/next/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** Services available in the Buildspace platform. */\nexport type BuildspaceService = \"auth\" | \"billing\" | \"events\" | \"notifications\" | \"storage\";\n\n/**\n * Error thrown by all Buildspace SDK methods on failure.\n *\n * @example\n * ```ts\n * try {\n *   await buildspace.auth.getSession(token);\n * } catch (err) {\n *   if (err instanceof BuildspaceError) {\n *     console.error(err.service, err.code, err.status, err.message);\n *   }\n * }\n * ```\n */\nexport class BuildspaceError extends Error {\n  /** Machine-readable error code, e.g. `\"auth/invalid-token\"`. */\n  readonly code: string;\n  /** Which service produced the error. */\n  readonly service: BuildspaceService;\n  /** HTTP status code from the API. */\n  readonly status: number;\n\n  constructor({\n    code,\n    message,\n    service,\n    status,\n  }: {\n    code: string;\n    message: string;\n    service: BuildspaceService;\n    status: number;\n  }) {\n    super(message);\n    this.name = \"BuildspaceError\";\n    this.code = code;\n    this.service = service;\n    this.status = status;\n  }\n}\n","import type { AuthSession, AuthUser, TokenResponse } from \"../auth\";\nimport { BuildspaceError } from \"../errors\";\n\n/**\n * Framework adapter for Next.js (and any framework using web-standard\n * `Request`/`Response` route handlers).\n *\n * Replaces the auth glue every creator app used to hand-roll: the OAuth\n * callback route, logout + session routes, a cookie-aware `getSession()`,\n * and a middleware cookie guard — all standardized on the `bs_session`\n * cookie.\n *\n * @example\n * ```ts\n * // app/api/auth/callback/route.ts\n * import { createAuthCallback } from \"@buildspacestudio/sdk/next\";\n * import { getServerClient } from \"@/lib/buildspace\";\n *\n * export const GET = createAuthCallback(getServerClient(), { redirectTo: \"/dashboard\" });\n * ```\n */\n\n/** The session cookie name shared by every Buildspace app. */\nexport const SESSION_COOKIE_NAME = \"bs_session\";\n\n/** The minimal server-client surface the adapter needs (a `Buildspace` instance). */\nexport interface AuthServerClient {\n  auth: {\n    getSession(sessionToken: string): Promise<AuthSession | null>;\n    handleCallback(\n      request: Request | URL | string,\n      opts?: { redirectUri?: string }\n    ): Promise<TokenResponse>;\n    signOut(sessionToken?: string): Promise<void>;\n  };\n}\n\n/** Options controlling the `bs_session` cookie attributes. */\nexport interface SessionCookieOptions {\n  /** Cookie domain. Omitted by default (host-only cookie). */\n  domain?: string;\n  /** Cookie path. Defaults to `/`. */\n  path?: string;\n  /** SameSite attribute. Defaults to `Lax`. */\n  sameSite?: \"lax\" | \"strict\" | \"none\";\n  /** Set the `Secure` attribute. Defaults to `true` outside development. */\n  secure?: boolean;\n}\n\nfunction isSecureDefault(): boolean {\n  return (\n    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env\n      ?.NODE_ENV !== \"development\"\n  );\n}\n\nfunction serializeSessionCookie(\n  value: string,\n  maxAge: number | null,\n  opts?: SessionCookieOptions\n): string {\n  const parts = [\n    `${SESSION_COOKIE_NAME}=${value}`,\n    `Path=${opts?.path ?? \"/\"}`,\n    \"HttpOnly\",\n    `SameSite=${opts?.sameSite === \"strict\" ? \"Strict\" : opts?.sameSite === \"none\" ? \"None\" : \"Lax\"}`,\n  ];\n\n  if (maxAge !== null) {\n    parts.push(`Max-Age=${Math.max(0, Math.floor(maxAge))}`);\n  }\n\n  if (opts?.secure ?? isSecureDefault()) {\n    parts.push(\"Secure\");\n  }\n\n  if (opts?.domain) {\n    parts.push(`Domain=${opts.domain}`);\n  }\n\n  return parts.join(\"; \");\n}\n\n/** Build a `Set-Cookie` header value that stores the session token. */\nexport function buildSessionCookie(\n  token: string,\n  maxAgeSeconds: number,\n  opts?: SessionCookieOptions\n): string {\n  return serializeSessionCookie(token, maxAgeSeconds, opts);\n}\n\n/** Build a `Set-Cookie` header value that clears the session cookie. */\nexport function buildClearSessionCookie(opts?: SessionCookieOptions): string {\n  return serializeSessionCookie(\"\", 0, opts);\n}\n\n/**\n * Anything the adapter can read the session cookie from: a web `Request`,\n * or a cookie store with a `get(name)` method (e.g. the object returned by\n * Next.js `cookies()` in Server Components and Route Handlers).\n */\nexport type SessionCookieSource =\n  | Request\n  | {\n      get(name: string): { value: string } | string | null | undefined;\n    };\n\nfunction parseCookieHeader(header: string, name: string): string | null {\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq === -1) {\n      continue;\n    }\n\n    if (part.slice(0, eq).trim() === name) {\n      return part.slice(eq + 1).trim();\n    }\n  }\n\n  return null;\n}\n\n/** Read the raw session token from a request or cookie store, or `null`. */\nexport function getSessionToken(source: SessionCookieSource): string | null {\n  if (source instanceof Request) {\n    const header = source.headers.get(\"cookie\");\n    return header ? parseCookieHeader(header, SESSION_COOKIE_NAME) : null;\n  }\n\n  const cookie = source.get(SESSION_COOKIE_NAME);\n  if (!cookie) {\n    return null;\n  }\n\n  const value = typeof cookie === \"string\" ? cookie : cookie.value;\n  return value || null;\n}\n\n/** An {@link AuthSession} plus the raw token it was resolved from. */\nexport type SessionWithToken = AuthSession & { token: string };\n\n/**\n * Cookie-aware session lookup.\n *\n * Reads the `bs_session` cookie from the given source and verifies it with\n * the Buildspace API. Returns `null` when there is no cookie or the token\n * is expired/revoked. Network/5xx errors also resolve to `null` so a blip\n * never crashes rendering — sign-in state degrades to \"signed out\".\n *\n * @example\n * ```ts\n * // Server Component\n * import { cookies } from \"next/headers\";\n * const session = await getSession(getServerClient(), await cookies());\n * ```\n */\nexport async function getSession(\n  client: AuthServerClient,\n  source: SessionCookieSource\n): Promise<SessionWithToken | null> {\n  const token = getSessionToken(source);\n  if (!token) {\n    return null;\n  }\n\n  try {\n    const session = await client.auth.getSession(token);\n    return session ? { ...session, token } : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Like {@link getSession} but throws a `BuildspaceError` (401) when there is\n * no valid session. Use in route handlers and server actions that must only\n * run for signed-in users.\n */\nexport async function requireSession(\n  client: AuthServerClient,\n  source: SessionCookieSource\n): Promise<SessionWithToken> {\n  const session = await getSession(client, source);\n  if (!session) {\n    throw new BuildspaceError({\n      service: \"auth\",\n      status: 401,\n      code: \"auth/session-required\",\n      message: \"No valid session. The bs_session cookie is missing, expired, or revoked.\",\n    });\n  }\n\n  return session;\n}\n\n/** Options for {@link createAuthCallback}. */\nexport interface CreateAuthCallbackOptions {\n  /** Cookie attribute overrides. */\n  cookie?: SessionCookieOptions;\n  /**\n   * Called when the code exchange fails. Return a `Response` to control the\n   * error page; by default the error is rethrown (surfacing your framework's\n   * error handling).\n   */\n  onError?: (error: unknown, request: Request) => Response | Promise<Response>;\n  /**\n   * Signup/sign-in side effects (mirror the user into your DB, send a\n   * welcome email, track an event). Failures are logged and never break\n   * login.\n   */\n  onSignIn?: (ctx: {\n    accessToken: string;\n    request: Request;\n    user: AuthUser;\n  }) => void | Promise<void>;\n  /** Where to send the user after login. Defaults to `/`. */\n  redirectTo?: string;\n}\n\n/**\n * Create the OAuth callback route handler.\n *\n * Exchanges the `?code=` for tokens, runs your `onSignIn` hook, stores the\n * access token in the `bs_session` cookie (with `expires_in` as `Max-Age`),\n * and redirects to `redirectTo`.\n *\n * @example\n * ```ts\n * // app/api/auth/callback/route.ts\n * export const GET = createAuthCallback(getServerClient(), {\n *   redirectTo: \"/dashboard\",\n *   onSignIn: async ({ user }) => upsertUser(user),\n * });\n * ```\n */\nexport function createAuthCallback(\n  client: AuthServerClient,\n  options?: CreateAuthCallbackOptions\n): (request: Request) => Promise<Response> {\n  return async (request: Request): Promise<Response> => {\n    let tokens: TokenResponse;\n    try {\n      tokens = await client.auth.handleCallback(request);\n    } catch (error) {\n      if (options?.onError) {\n        return await options.onError(error, request);\n      }\n      throw error;\n    }\n\n    if (options?.onSignIn) {\n      try {\n        await options.onSignIn({\n          accessToken: tokens.access_token,\n          request,\n          user: tokens.user,\n        });\n      } catch (error) {\n        console.error(\"[buildspace] onSignIn hook failed\", error);\n      }\n    }\n\n    return new Response(null, {\n      status: 303,\n      headers: {\n        Location: options?.redirectTo ?? \"/\",\n        \"Set-Cookie\": buildSessionCookie(tokens.access_token, tokens.expires_in, options?.cookie),\n      },\n    });\n  };\n}\n\n/**\n * Create the logout route handler (`POST /api/auth/logout`).\n *\n * Revokes the session with the Buildspace API (already-expired sessions are\n * ignored) and clears the `bs_session` cookie.\n */\nexport function createLogoutRoute(\n  client: AuthServerClient,\n  options?: { cookie?: SessionCookieOptions }\n): (request: Request) => Promise<Response> {\n  return async (request: Request): Promise<Response> => {\n    const token = getSessionToken(request);\n\n    if (token) {\n      try {\n        await client.auth.signOut(token);\n      } catch (error) {\n        console.error(\"[buildspace] session revoke failed during logout\", error);\n      }\n    }\n\n    return new Response(JSON.stringify({ ok: true }), {\n      status: 200,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        \"Set-Cookie\": buildClearSessionCookie(options?.cookie),\n      },\n    });\n  };\n}\n\n/**\n * Create the session route handler (`GET /api/auth/session`).\n *\n * Returns `{ session }` for the current cookie, with the raw token omitted —\n * this response is safe to expose to the browser.\n */\nexport function createSessionRoute(\n  client: AuthServerClient\n): (request: Request) => Promise<Response> {\n  return async (request: Request): Promise<Response> => {\n    const session = await getSession(client, request);\n    const publicSession = session ? { appId: session.appId, user: session.user } : null;\n\n    return new Response(JSON.stringify({ session: publicSession }), {\n      status: 200,\n      headers: { \"Content-Type\": \"application/json\" },\n    });\n  };\n}\n\n/**\n * Middleware helper: redirect requests that don't carry a session cookie.\n *\n * This is a fast presence check (no API call — middleware runs on every\n * matched request); route handlers and pages must still verify the session\n * with {@link getSession}.\n *\n * @example\n * ```ts\n * // middleware.ts / proxy.ts\n * import { createSessionCookieGuard } from \"@buildspacestudio/sdk/next\";\n *\n * export const proxy = createSessionCookieGuard({ redirectTo: \"/\" });\n * export const config = { matcher: [\"/dashboard/:path*\"] };\n * ```\n */\nexport function createSessionCookieGuard(options?: {\n  /** Where to send signed-out users. Defaults to `/`. */\n  redirectTo?: string;\n}): (request: Request) => Response | undefined {\n  return (request: Request): Response | undefined => {\n    if (getSessionToken(request)) {\n      return;\n    }\n\n    const target = new URL(options?.redirectTo ?? \"/\", new URL(request.url).origin);\n    return Response.redirect(target.toString(), 307);\n  };\n}\n"]}

package/dist/notifications/index.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+// src/notifications/server.ts
+var NotificationsServerNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Send a custom email with inline HTML content.
+   *
+   * @param opts - Email content and recipient options.
+   * @returns The notification ID and optional provider message ID.
+   */
+  send(opts) {
+    return this.transport.request({
+      service: "notifications",
+      path: "/v1/notifications/send",
+      method: "POST",
+      body: {
+        to: opts.to,
+        subject: opts.subject,
+        html: opts.html,
+        text: opts.text,
+        reply_to: opts.replyTo,
+        metadata: opts.metadata
+      }
+    });
+  }
+  /**
+   * Send an email using a pre-configured template.
+   *
+   * Templates are created in the Buildspace Creator Studio.
+   *
+   * @param templateSlug - The slug of the template to use, e.g. `"welcome-email"`.
+   * @param opts - Recipient and template variable options.
+   * @returns The notification ID and optional provider message ID.
+   */
+  sendTemplate(templateSlug, opts) {
+    return this.transport.request({
+      service: "notifications",
+      path: "/v1/notifications/send-template",
+      method: "POST",
+      body: {
+        template: templateSlug,
+        to: opts.to,
+        variables: opts.variables,
+        metadata: opts.metadata
+      }
+    });
+  }
+};
+
+exports.NotificationsServerNamespace = NotificationsServerNamespace;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/notifications/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/notifications/server.ts"],"names":[],"mappings":";;;AA2DO,IAAM,+BAAN,MAAmC;AAAA,EACvB,SAAA;AAAA,EAEjB,YAAY,SAAA,EAA0B;AACpC,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAK,IAAA,EAAwC;AAC3C,IAAA,OAAO,IAAA,CAAK,UAAU,OAAA,CAAoB;AAAA,MACxC,OAAA,EAAS,eAAA;AAAA,MACT,IAAA,EAAM,wBAAA;AAAA,MACN,MAAA,EAAQ,MAAA;AAAA,MACR,IAAA,EAAM;AAAA,QACJ,IAAI,IAAA,CAAK,EAAA;AAAA,QACT,SAAS,IAAA,CAAK,OAAA;AAAA,QACd,MAAM,IAAA,CAAK,IAAA;AAAA,QACX,MAAM,IAAA,CAAK,IAAA;AAAA,QACX,UAAU,IAAA,CAAK,OAAA;AAAA,QACf,UAAU,IAAA,CAAK;AAAA;AACjB,KACD,CAAA;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,YAAA,CAAa,cAAsB,IAAA,EAAgD;AACjF,IAAA,OAAO,IAAA,CAAK,UAAU,OAAA,CAAoB;AAAA,MACxC,OAAA,EAAS,eAAA;AAAA,MACT,IAAA,EAAM,iCAAA;AAAA,MACN,MAAA,EAAQ,MAAA;AAAA,MACR,IAAA,EAAM;AAAA,QACJ,QAAA,EAAU,YAAA;AAAA,QACV,IAAI,IAAA,CAAK,EAAA;AAAA,QACT,WAAW,IAAA,CAAK,SAAA;AAAA,QAChB,UAAU,IAAA,CAAK;AAAA;AACjB,KACD,CAAA;AAAA,EACH;AACF","file":"index.cjs","sourcesContent":["import type { HttpTransport } from \"../http\";\n\n/** Options for sending a custom email. */\nexport interface SendOptions {\n  /** HTML body of the email. */\n  html: string;\n  /** Arbitrary metadata to attach to the notification for tracking. */\n  metadata?: Record<string, unknown>;\n  /** Reply-to email address. */\n  replyTo?: string;\n  /** Email subject line. */\n  subject: string;\n  /** Plain-text fallback body. Recommended for email accessibility. */\n  text?: string;\n  /** Recipient email address, or an array of addresses for multiple recipients. */\n  to: string | string[];\n}\n\n/** Options for sending a template-based email. */\nexport interface SendTemplateOptions {\n  /** Arbitrary metadata to attach to the notification for tracking. */\n  metadata?: Record<string, unknown>;\n  /** Recipient email address, or an array of addresses. */\n  to: string | string[];\n  /** Template variable substitutions, e.g. `{ firstName: \"Alex\" }`. */\n  variables?: Record<string, string>;\n}\n\n/** Result of a successfully sent notification. */\nexport interface SendResult {\n  /** Buildspace notification ID. */\n  id: string;\n  /** Underlying email provider's message ID, if available. */\n  providerMessageId?: string;\n}\n\n/**\n * Server-side notification methods for sending transactional emails.\n *\n * Access via `buildspace.notifications` on the server SDK.\n * **Not available on the client SDK** — calling `buildspace.notifications`\n * on the client throws a `BuildspaceError`.\n *\n * @example\n * ```ts\n * // Send a custom email\n * await buildspace.notifications.send({\n *   to: \"user@example.com\",\n *   subject: \"Welcome!\",\n *   html: \"<h1>You're in!</h1>\",\n * });\n *\n * // Send from a saved template\n * await buildspace.notifications.sendTemplate(\"welcome-email\", {\n *   to: \"user@example.com\",\n *   variables: { firstName: \"Alex\" },\n * });\n * ```\n */\nexport class NotificationsServerNamespace {\n  private readonly transport: HttpTransport;\n\n  constructor(transport: HttpTransport) {\n    this.transport = transport;\n  }\n\n  /**\n   * Send a custom email with inline HTML content.\n   *\n   * @param opts - Email content and recipient options.\n   * @returns The notification ID and optional provider message ID.\n   */\n  send(opts: SendOptions): Promise<SendResult> {\n    return this.transport.request<SendResult>({\n      service: \"notifications\",\n      path: \"/v1/notifications/send\",\n      method: \"POST\",\n      body: {\n        to: opts.to,\n        subject: opts.subject,\n        html: opts.html,\n        text: opts.text,\n        reply_to: opts.replyTo,\n        metadata: opts.metadata,\n      },\n    });\n  }\n\n  /**\n   * Send an email using a pre-configured template.\n   *\n   * Templates are created in the Buildspace Creator Studio.\n   *\n   * @param templateSlug - The slug of the template to use, e.g. `\"welcome-email\"`.\n   * @param opts - Recipient and template variable options.\n   * @returns The notification ID and optional provider message ID.\n   */\n  sendTemplate(templateSlug: string, opts: SendTemplateOptions): Promise<SendResult> {\n    return this.transport.request<SendResult>({\n      service: \"notifications\",\n      path: \"/v1/notifications/send-template\",\n      method: \"POST\",\n      body: {\n        template: templateSlug,\n        to: opts.to,\n        variables: opts.variables,\n        metadata: opts.metadata,\n      },\n    });\n  }\n}\n"]}

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

@@ -1,6 +1,7 @@
-import type { HttpTransport } from "../http";
+import { H as HttpTransport } from '../http-D2gXpNpr.cjs';
+
 /** Options for sending a custom email. */
-export interface SendOptions {
+interface SendOptions {
     /** HTML body of the email. */
     html: string;
     /** Arbitrary metadata to attach to the notification for tracking. */
@@ -15,7 +16,7 @@ export interface SendOptions {
     to: string | string[];
 }
 /** Options for sending a template-based email. */
-export interface SendTemplateOptions {
+interface SendTemplateOptions {
     /** Arbitrary metadata to attach to the notification for tracking. */
     metadata?: Record<string, unknown>;
     /** Recipient email address, or an array of addresses. */
@@ -24,7 +25,7 @@ export interface SendTemplateOptions {
     variables?: Record<string, string>;
 }
 /** Result of a successfully sent notification. */
-export interface SendResult {
+interface SendResult {
     /** Buildspace notification ID. */
     id: string;
     /** Underlying email provider's message ID, if available. */
@@ -53,7 +54,7 @@ export interface SendResult {
  * });
  * ```
  */
-export declare class NotificationsServerNamespace {
+declare class NotificationsServerNamespace {
     private readonly transport;
     constructor(transport: HttpTransport);
     /**
@@ -74,4 +75,5 @@ export declare class NotificationsServerNamespace {
      */
     sendTemplate(templateSlug: string, opts: SendTemplateOptions): Promise<SendResult>;
 }
-//# sourceMappingURL=server.d.ts.map
+
+export { NotificationsServerNamespace, type SendOptions, type SendResult, type SendTemplateOptions };

package/dist/notifications/index.d.ts

@@ -1,3 +1,79 @@
-export type { SendOptions, SendResult, SendTemplateOptions } from "./server";
-export { NotificationsServerNamespace } from "./server";
-//# sourceMappingURL=index.d.ts.map
+import { H as HttpTransport } from '../http-D2gXpNpr.js';
+
+/** Options for sending a custom email. */
+interface SendOptions {
+    /** HTML body of the email. */
+    html: string;
+    /** Arbitrary metadata to attach to the notification for tracking. */
+    metadata?: Record<string, unknown>;
+    /** Reply-to email address. */
+    replyTo?: string;
+    /** Email subject line. */
+    subject: string;
+    /** Plain-text fallback body. Recommended for email accessibility. */
+    text?: string;
+    /** Recipient email address, or an array of addresses for multiple recipients. */
+    to: string | string[];
+}
+/** Options for sending a template-based email. */
+interface SendTemplateOptions {
+    /** Arbitrary metadata to attach to the notification for tracking. */
+    metadata?: Record<string, unknown>;
+    /** Recipient email address, or an array of addresses. */
+    to: string | string[];
+    /** Template variable substitutions, e.g. `{ firstName: "Alex" }`. */
+    variables?: Record<string, string>;
+}
+/** Result of a successfully sent notification. */
+interface SendResult {
+    /** Buildspace notification ID. */
+    id: string;
+    /** Underlying email provider's message ID, if available. */
+    providerMessageId?: string;
+}
+/**
+ * Server-side notification methods for sending transactional emails.
+ *
+ * Access via `buildspace.notifications` on the server SDK.
+ * **Not available on the client SDK** — calling `buildspace.notifications`
+ * on the client throws a `BuildspaceError`.
+ *
+ * @example
+ * ```ts
+ * // Send a custom email
+ * await buildspace.notifications.send({
+ *   to: "user@example.com",
+ *   subject: "Welcome!",
+ *   html: "<h1>You're in!</h1>",
+ * });
+ *
+ * // Send from a saved template
+ * await buildspace.notifications.sendTemplate("welcome-email", {
+ *   to: "user@example.com",
+ *   variables: { firstName: "Alex" },
+ * });
+ * ```
+ */
+declare class NotificationsServerNamespace {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Send a custom email with inline HTML content.
+     *
+     * @param opts - Email content and recipient options.
+     * @returns The notification ID and optional provider message ID.
+     */
+    send(opts: SendOptions): Promise<SendResult>;
+    /**
+     * Send an email using a pre-configured template.
+     *
+     * Templates are created in the Buildspace Creator Studio.
+     *
+     * @param templateSlug - The slug of the template to use, e.g. `"welcome-email"`.
+     * @param opts - Recipient and template variable options.
+     * @returns The notification ID and optional provider message ID.
+     */
+    sendTemplate(templateSlug: string, opts: SendTemplateOptions): Promise<SendResult>;
+}
+
+export { NotificationsServerNamespace, type SendOptions, type SendResult, type SendTemplateOptions };

package/dist/notifications/index.js

@@ -1,2 +1,54 @@
-export { NotificationsServerNamespace } from "./server";
+// src/notifications/server.ts
+var NotificationsServerNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Send a custom email with inline HTML content.
+   *
+   * @param opts - Email content and recipient options.
+   * @returns The notification ID and optional provider message ID.
+   */
+  send(opts) {
+    return this.transport.request({
+      service: "notifications",
+      path: "/v1/notifications/send",
+      method: "POST",
+      body: {
+        to: opts.to,
+        subject: opts.subject,
+        html: opts.html,
+        text: opts.text,
+        reply_to: opts.replyTo,
+        metadata: opts.metadata
+      }
+    });
+  }
+  /**
+   * Send an email using a pre-configured template.
+   *
+   * Templates are created in the Buildspace Creator Studio.
+   *
+   * @param templateSlug - The slug of the template to use, e.g. `"welcome-email"`.
+   * @param opts - Recipient and template variable options.
+   * @returns The notification ID and optional provider message ID.
+   */
+  sendTemplate(templateSlug, opts) {
+    return this.transport.request({
+      service: "notifications",
+      path: "/v1/notifications/send-template",
+      method: "POST",
+      body: {
+        template: templateSlug,
+        to: opts.to,
+        variables: opts.variables,
+        metadata: opts.metadata
+      }
+    });
+  }
+};
+
+export { NotificationsServerNamespace };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/notifications/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"sources":["../../src/notifications/server.ts"],"names":[],"mappings":";AA2DO,IAAM,+BAAN,MAAmC;AAAA,EACvB,SAAA;AAAA,EAEjB,YAAY,SAAA,EAA0B;AACpC,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAK,IAAA,EAAwC;AAC3C,IAAA,OAAO,IAAA,CAAK,UAAU,OAAA,CAAoB;AAAA,MACxC,OAAA,EAAS,eAAA;AAAA,MACT,IAAA,EAAM,wBAAA;AAAA,MACN,MAAA,EAAQ,MAAA;AAAA,MACR,IAAA,EAAM;AAAA,QACJ,IAAI,IAAA,CAAK,EAAA;AAAA,QACT,SAAS,IAAA,CAAK,OAAA;AAAA,QACd,MAAM,IAAA,CAAK,IAAA;AAAA,QACX,MAAM,IAAA,CAAK,IAAA;AAAA,QACX,UAAU,IAAA,CAAK,OAAA;AAAA,QACf,UAAU,IAAA,CAAK;AAAA;AACjB,KACD,CAAA;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,YAAA,CAAa,cAAsB,IAAA,EAAgD;AACjF,IAAA,OAAO,IAAA,CAAK,UAAU,OAAA,CAAoB;AAAA,MACxC,OAAA,EAAS,eAAA;AAAA,MACT,IAAA,EAAM,iCAAA;AAAA,MACN,MAAA,EAAQ,MAAA;AAAA,MACR,IAAA,EAAM;AAAA,QACJ,QAAA,EAAU,YAAA;AAAA,QACV,IAAI,IAAA,CAAK,EAAA;AAAA,QACT,WAAW,IAAA,CAAK,SAAA;AAAA,QAChB,UAAU,IAAA,CAAK;AAAA;AACjB,KACD,CAAA;AAAA,EACH;AACF","file":"index.js","sourcesContent":["import type { HttpTransport } from \"../http\";\n\n/** Options for sending a custom email. */\nexport interface SendOptions {\n  /** HTML body of the email. */\n  html: string;\n  /** Arbitrary metadata to attach to the notification for tracking. */\n  metadata?: Record<string, unknown>;\n  /** Reply-to email address. */\n  replyTo?: string;\n  /** Email subject line. */\n  subject: string;\n  /** Plain-text fallback body. Recommended for email accessibility. */\n  text?: string;\n  /** Recipient email address, or an array of addresses for multiple recipients. */\n  to: string | string[];\n}\n\n/** Options for sending a template-based email. */\nexport interface SendTemplateOptions {\n  /** Arbitrary metadata to attach to the notification for tracking. */\n  metadata?: Record<string, unknown>;\n  /** Recipient email address, or an array of addresses. */\n  to: string | string[];\n  /** Template variable substitutions, e.g. `{ firstName: \"Alex\" }`. */\n  variables?: Record<string, string>;\n}\n\n/** Result of a successfully sent notification. */\nexport interface SendResult {\n  /** Buildspace notification ID. */\n  id: string;\n  /** Underlying email provider's message ID, if available. */\n  providerMessageId?: string;\n}\n\n/**\n * Server-side notification methods for sending transactional emails.\n *\n * Access via `buildspace.notifications` on the server SDK.\n * **Not available on the client SDK** — calling `buildspace.notifications`\n * on the client throws a `BuildspaceError`.\n *\n * @example\n * ```ts\n * // Send a custom email\n * await buildspace.notifications.send({\n *   to: \"user@example.com\",\n *   subject: \"Welcome!\",\n *   html: \"<h1>You're in!</h1>\",\n * });\n *\n * // Send from a saved template\n * await buildspace.notifications.sendTemplate(\"welcome-email\", {\n *   to: \"user@example.com\",\n *   variables: { firstName: \"Alex\" },\n * });\n * ```\n */\nexport class NotificationsServerNamespace {\n  private readonly transport: HttpTransport;\n\n  constructor(transport: HttpTransport) {\n    this.transport = transport;\n  }\n\n  /**\n   * Send a custom email with inline HTML content.\n   *\n   * @param opts - Email content and recipient options.\n   * @returns The notification ID and optional provider message ID.\n   */\n  send(opts: SendOptions): Promise<SendResult> {\n    return this.transport.request<SendResult>({\n      service: \"notifications\",\n      path: \"/v1/notifications/send\",\n      method: \"POST\",\n      body: {\n        to: opts.to,\n        subject: opts.subject,\n        html: opts.html,\n        text: opts.text,\n        reply_to: opts.replyTo,\n        metadata: opts.metadata,\n      },\n    });\n  }\n\n  /**\n   * Send an email using a pre-configured template.\n   *\n   * Templates are created in the Buildspace Creator Studio.\n   *\n   * @param templateSlug - The slug of the template to use, e.g. `\"welcome-email\"`.\n   * @param opts - Recipient and template variable options.\n   * @returns The notification ID and optional provider message ID.\n   */\n  sendTemplate(templateSlug: string, opts: SendTemplateOptions): Promise<SendResult> {\n    return this.transport.request<SendResult>({\n      service: \"notifications\",\n      path: \"/v1/notifications/send-template\",\n      method: \"POST\",\n      body: {\n        template: templateSlug,\n        to: opts.to,\n        variables: opts.variables,\n        metadata: opts.metadata,\n      },\n    });\n  }\n}\n"]}