busabase-sdk 0.14.1 → 0.15.0

package/dist/airapp-node.d.ts

@@ -0,0 +1,66 @@
+import { BusabaseAirAppCredentialStoreOptions } from './oauth-node.js';
+import './oauth.js';
+
+declare const BUSABASE_AIRAPP_GATEWAY_REASONS: {
+    readonly authRequired: "AUTH_REQUIRED";
+    readonly authUnavailable: "AUTH_UNAVAILABLE";
+    readonly connectionRequired: "CONNECTION_REQUIRED";
+    readonly oauthCallbackInvalid: "OAUTH_CALLBACK_INVALID";
+    readonly spaceNotAllowed: "SPACE_NOT_ALLOWED";
+    readonly spaceSelectionRequired: "SPACE_SELECTION_REQUIRED";
+};
+type GatewayReason = (typeof BUSABASE_AIRAPP_GATEWAY_REASONS)[keyof typeof BUSABASE_AIRAPP_GATEWAY_REASONS];
+interface AuthSpace {
+    id: string;
+    name: string;
+    slug?: string | null;
+    plan?: string | null;
+}
+interface GatewayTarget {
+    baseUrl: string;
+    accessToken: string;
+    selectedSpace?: AuthSpace;
+    source: "airapp-oauth-local" | "environment" | "open-server";
+}
+interface BusabaseAirAppLocalGatewayOptions {
+    appId: string;
+    cloudBaseUrl?: string;
+    clientId?: string;
+    environment?: Record<string, string | undefined>;
+    fetch?: typeof fetch;
+    now?: () => number;
+    oauthPendingTtlMs?: number;
+    requestTimeoutMs?: number;
+    credentialStore?: BusabaseAirAppCredentialStoreOptions;
+    successPath?: string;
+    errorPath?: string;
+}
+interface BusabaseAirAppAuthStatus {
+    connected: boolean;
+    cloudBaseUrl: string;
+    baseUrl?: string;
+    source?: GatewayTarget["source"];
+    readiness: "needs_connection" | "needs_auth" | "needs_space" | "ready" | "retry";
+    action: "connect" | "reconnect" | "select_space" | "continue" | "retry";
+    requiresSpace?: boolean;
+    selectedSpace?: AuthSpace | null;
+    space?: AuthSpace | null;
+    spaces?: AuthSpace[];
+    reason?: GatewayReason;
+    message?: string;
+}
+declare class BusabaseAirAppLocalGateway {
+    #private;
+    constructor(options: BusabaseAirAppLocalGatewayOptions);
+    get cloudBaseUrl(): string;
+    status(): Promise<BusabaseAirAppAuthStatus>;
+    statusResponse: () => Promise<Response>;
+    start: (request: Request) => Promise<Response>;
+    callback: (request: Request) => Promise<Response>;
+    selectSpace: (request: Request) => Promise<Response>;
+    logout: (request: Request) => Promise<Response>;
+    proxy: (request: Request) => Promise<Response>;
+}
+declare const createBusabaseAirAppLocalGateway: (options: BusabaseAirAppLocalGatewayOptions) => BusabaseAirAppLocalGateway;
+
+export { BUSABASE_AIRAPP_GATEWAY_REASONS, type BusabaseAirAppAuthStatus, BusabaseAirAppLocalGateway, type BusabaseAirAppLocalGatewayOptions, createBusabaseAirAppLocalGateway };

package/dist/airapp-node.js

@@ -0,0 +1,408 @@
+import { getBusabaseAirAppAccessToken, storeBusabaseAirAppSelectedSpace, storeBusabaseAirAppOAuthCredential, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential } from './chunk-B2AWPFDI.js';
+import { BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, createBusabaseOAuthRequest, parseBusabaseOAuthCallback, exchangeBusabaseOAuthCode } from './chunk-J2DZKX7A.js';
+import './chunk-5NYQX65A.js';
+
+// src/airapp-node.ts
+var DEFAULT_CLOUD_BASE_URL = "https://busabase.com";
+var DEFAULT_PENDING_TTL_MS = 5 * 6e4;
+var DEFAULT_TIMEOUT_MS = 8e3;
+var BUSABASE_AIRAPP_GATEWAY_REASONS = {
+  authRequired: "AUTH_REQUIRED",
+  authUnavailable: "AUTH_UNAVAILABLE",
+  connectionRequired: "CONNECTION_REQUIRED",
+  oauthCallbackInvalid: "OAUTH_CALLBACK_INVALID",
+  spaceNotAllowed: "SPACE_NOT_ALLOWED",
+  spaceSelectionRequired: "SPACE_SELECTION_REQUIRED"
+};
+var jsonError = (status, reason, message, data) => Response.json(
+  {
+    error: message,
+    code: status === 401 ? "UNAUTHORIZED" : status === 403 ? "FORBIDDEN" : status === 409 ? "CONFLICT" : status === 503 ? "SERVICE_UNAVAILABLE" : "BAD_REQUEST",
+    data: { reason, ...data }
+  },
+  { status }
+);
+var normalizeOrigin = (raw, fallback = DEFAULT_CLOUD_BASE_URL) => {
+  const withoutApi = String(raw || fallback).trim().replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+  let url;
+  try {
+    url = new URL(withoutApi);
+  } catch {
+    throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL is invalid");
+  }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" && url.pathname !== "") {
+    throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL must be an origin");
+  }
+  const loopback = ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new BusabaseOAuthError(
+      "invalid_base_url",
+      "Busabase requires HTTPS except for a loopback development server"
+    );
+  }
+  return url.origin;
+};
+var requestOrigin = (request) => new URL(request.url).origin;
+var assertSameOrigin = (request) => {
+  const origin = request.headers.get("origin");
+  if (origin && origin !== requestOrigin(request)) {
+    throw new BusabaseOAuthError("origin_mismatch", "Request origin did not match");
+  }
+};
+var readInput = async (request) => {
+  const contentType = request.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    return await request.json().catch(() => ({}));
+  }
+  const form = await request.formData().catch(() => new FormData());
+  return Object.fromEntries(form.entries());
+};
+var safeSpaces = (spaces) => spaces.map(({ id, name, slug, plan }) => ({ id, name, slug, plan }));
+var BusabaseAirAppLocalGateway = class {
+  #options;
+  #pendingOAuth = /* @__PURE__ */ new Map();
+  #environmentSelectedSpace;
+  constructor(options) {
+    this.#options = {
+      ...options,
+      appId: options.appId,
+      cloudBaseUrl: normalizeOrigin(options.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL),
+      clientId: options.clientId || BUSABASE_AIRAPP_CLIENT_ID,
+      oauthPendingTtlMs: options.oauthPendingTtlMs ?? DEFAULT_PENDING_TTL_MS,
+      requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+      successPath: options.successPath || "/",
+      errorPath: options.errorPath || "/"
+    };
+  }
+  get cloudBaseUrl() {
+    return this.#options.cloudBaseUrl;
+  }
+  #fetch() {
+    return this.#options.fetch ?? fetch;
+  }
+  #now() {
+    return this.#options.now?.() ?? Date.now();
+  }
+  #environment() {
+    return this.#options.environment ?? process.env;
+  }
+  async #target() {
+    const environment = this.#environment();
+    if (environment.BUSABASE_BASE_URL) {
+      const selectedSpaceId = environment.BUSABASE_SPACE_ID?.trim();
+      return {
+        baseUrl: normalizeOrigin(environment.BUSABASE_BASE_URL),
+        accessToken: environment.BUSABASE_API_KEY || "",
+        source: environment.BUSABASE_API_KEY ? "environment" : "open-server",
+        ...selectedSpaceId ? { selectedSpace: { id: selectedSpaceId, name: selectedSpaceId } } : this.#environmentSelectedSpace ? { selectedSpace: this.#environmentSelectedSpace } : {}
+      };
+    }
+    const credential = await getBusabaseAirAppAccessToken(
+      this.#options.appId,
+      this.#options.credentialStore,
+      this.#fetch()
+    );
+    return credential ? {
+      baseUrl: credential.baseUrl,
+      accessToken: credential.accessToken,
+      source: "airapp-oauth-local",
+      ...credential.selectedSpace ? { selectedSpace: credential.selectedSpace } : {}
+    } : null;
+  }
+  async #authInfo(target, spaceId = "") {
+    const headers = new Headers({ accept: "application/json" });
+    if (target.accessToken) headers.set("authorization", `Bearer ${target.accessToken}`);
+    if (spaceId) headers.set("x-busabase-space", spaceId);
+    const response = await this.#fetch()(new URL("/api/v1/auth", target.baseUrl), {
+      headers,
+      signal: AbortSignal.timeout(this.#options.requestTimeoutMs)
+    });
+    if (!response.ok) {
+      throw new BusabaseOAuthError(
+        response.status === 401 ? "auth_required" : "auth_verification_failed",
+        `Busabase auth verification failed (${response.status})`,
+        response.status
+      );
+    }
+    const info = await response.json();
+    if (!Array.isArray(info.spaces)) {
+      throw new BusabaseOAuthError(
+        "invalid_auth_response",
+        "Busabase auth response did not include Spaces"
+      );
+    }
+    return info;
+  }
+  #persistSelectedSpace(target, selectedSpace) {
+    if (target.source === "airapp-oauth-local") {
+      storeBusabaseAirAppSelectedSpace(
+        this.#options.appId,
+        selectedSpace ? { id: selectedSpace.id, name: selectedSpace.name } : null,
+        this.#options.credentialStore
+      );
+    } else {
+      this.#environmentSelectedSpace = selectedSpace || void 0;
+    }
+  }
+  async status() {
+    let target = null;
+    try {
+      target = await this.#target();
+      if (!target) {
+        return {
+          connected: false,
+          cloudBaseUrl: this.cloudBaseUrl,
+          readiness: "needs_connection",
+          action: "connect",
+          reason: BUSABASE_AIRAPP_GATEWAY_REASONS.connectionRequired
+        };
+      }
+      const info = await this.#authInfo(target);
+      const spaces = safeSpaces(info.spaces);
+      if (!spaces.length) {
+        this.#persistSelectedSpace(target, null);
+        return {
+          connected: true,
+          cloudBaseUrl: this.cloudBaseUrl,
+          baseUrl: target.baseUrl,
+          source: target.source,
+          readiness: "needs_space",
+          action: "retry",
+          requiresSpace: true,
+          selectedSpace: null,
+          space: null,
+          spaces,
+          reason: BUSABASE_AIRAPP_GATEWAY_REASONS.spaceSelectionRequired,
+          message: "This account has no accessible Busabase Space"
+        };
+      }
+      const selectedSpaceId = target.selectedSpace?.id;
+      let selected = selectedSpaceId ? spaces.find((space) => space.id === selectedSpaceId) : void 0;
+      if (!selected && spaces.length === 1) selected = spaces[0];
+      if (target.selectedSpace && !selected) this.#persistSelectedSpace(target, null);
+      if (selected && selected.id !== selectedSpaceId) {
+        await this.#authInfo(target, selected.id);
+        this.#persistSelectedSpace(target, selected);
+      }
+      return {
+        connected: true,
+        cloudBaseUrl: this.cloudBaseUrl,
+        baseUrl: target.baseUrl,
+        source: target.source,
+        readiness: selected ? "ready" : "needs_space",
+        action: selected ? "continue" : "select_space",
+        requiresSpace: !selected,
+        selectedSpace: selected || null,
+        space: selected || null,
+        spaces,
+        ...selected ? {} : { reason: BUSABASE_AIRAPP_GATEWAY_REASONS.spaceSelectionRequired }
+      };
+    } catch (error) {
+      const authRequired = error instanceof BusabaseOAuthError && error.status === 401;
+      return {
+        connected: Boolean(target) && !authRequired,
+        cloudBaseUrl: this.cloudBaseUrl,
+        ...target ? { baseUrl: target.baseUrl, source: target.source, requiresSpace: true } : {},
+        readiness: authRequired ? "needs_auth" : "retry",
+        action: authRequired ? "reconnect" : "retry",
+        reason: authRequired ? BUSABASE_AIRAPP_GATEWAY_REASONS.authRequired : BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        message: error instanceof Error ? error.message : "Busabase auth verification failed"
+      };
+    }
+  }
+  statusResponse = async () => Response.json(await this.status());
+  start = async (request) => {
+    try {
+      assertSameOrigin(request);
+      const body = await readInput(request);
+      const baseUrl = normalizeOrigin(String(body.base_url || ""), this.cloudBaseUrl);
+      const redirectUri = new URL("/auth/callback", requestOrigin(request)).toString();
+      const oauthRequest = await createBusabaseOAuthRequest({
+        baseUrl,
+        redirectUri,
+        clientId: this.#options.clientId
+      });
+      const probe = await this.#fetch()(oauthRequest.authorizeUrl, {
+        headers: { accept: "text/html" },
+        redirect: "manual",
+        signal: AbortSignal.timeout(this.#options.requestTimeoutMs)
+      });
+      if (probe.status >= 400) {
+        throw new BusabaseOAuthError(
+          "oauth_unavailable",
+          `Busabase OAuth is unavailable (${probe.status})`,
+          probe.status
+        );
+      }
+      this.#pendingOAuth.set(oauthRequest.state, {
+        ...oauthRequest,
+        expiresAt: this.#now() + this.#options.oauthPendingTtlMs
+      });
+      return Response.redirect(oauthRequest.authorizeUrl, 303);
+    } catch (error) {
+      const redirect = new URL(this.#options.errorPath, requestOrigin(request));
+      redirect.searchParams.set(
+        "oauth_error",
+        error instanceof Error ? error.message : "Unable to start Busabase OAuth"
+      );
+      return Response.redirect(redirect, 303);
+    }
+  };
+  callback = async (request) => {
+    const callback = new URL(request.url);
+    const state = callback.searchParams.get("state") || "";
+    const pending = this.#pendingOAuth.get(state);
+    this.#pendingOAuth.delete(state);
+    try {
+      if (!pending || pending.expiresAt <= this.#now()) {
+        throw new BusabaseOAuthError("oauth_request_expired", "OAuth request expired");
+      }
+      const code = parseBusabaseOAuthCallback(callback.toString(), pending);
+      const tokenSet = await exchangeBusabaseOAuthCode(pending, code, this.#fetch());
+      storeBusabaseAirAppOAuthCredential(
+        {
+          appId: this.#options.appId,
+          baseUrl: pending.baseUrl,
+          clientId: this.#options.clientId,
+          tokenSet
+        },
+        this.#options.credentialStore
+      );
+      return Response.redirect(new URL(this.#options.successPath, requestOrigin(request)), 303);
+    } catch (error) {
+      const redirect = new URL(this.#options.errorPath, requestOrigin(request));
+      redirect.searchParams.set(
+        "oauth_error",
+        error instanceof Error ? error.message : "Busabase OAuth callback failed"
+      );
+      return Response.redirect(redirect, 303);
+    }
+  };
+  selectSpace = async (request) => {
+    try {
+      assertSameOrigin(request);
+      const body = await readInput(request);
+      const spaceId = String(body.space_id || "").trim();
+      const target = await this.#target();
+      if (!target) {
+        return jsonError(
+          401,
+          BUSABASE_AIRAPP_GATEWAY_REASONS.connectionRequired,
+          "Connect Busabase before selecting a Space"
+        );
+      }
+      const info = await this.#authInfo(target);
+      const selected = info.spaces.find((space) => space.id === spaceId);
+      if (!selected) {
+        return jsonError(
+          403,
+          BUSABASE_AIRAPP_GATEWAY_REASONS.spaceNotAllowed,
+          "The selected Space is not accessible to this account"
+        );
+      }
+      await this.#authInfo(target, selected.id);
+      this.#persistSelectedSpace(target, selected);
+      return Response.json({ ok: true, space: { id: selected.id, name: selected.name } });
+    } catch (error) {
+      return jsonError(
+        400,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        error instanceof Error ? error.message : "Unable to select Busabase Space"
+      );
+    }
+  };
+  logout = async (request) => {
+    try {
+      assertSameOrigin(request);
+      if (loadBusabaseAirAppOAuthCredential(this.#options.appId, this.#options.credentialStore)) {
+        await revokeBusabaseAirAppOAuthCredential(
+          this.#options.appId,
+          this.#options.credentialStore,
+          this.#fetch()
+        ).catch(() => void 0);
+      }
+      this.#environmentSelectedSpace = void 0;
+      return Response.json({ ok: true });
+    } catch (error) {
+      return jsonError(
+        400,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        error instanceof Error ? error.message : "Unable to disconnect Busabase"
+      );
+    }
+  };
+  proxy = async (request) => {
+    let target;
+    try {
+      target = await this.#target();
+    } catch {
+      return jsonError(
+        401,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authRequired,
+        "Busabase authentication expired"
+      );
+    }
+    if (!target) {
+      return jsonError(
+        401,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.connectionRequired,
+        "Busabase connection required"
+      );
+    }
+    let selectedSpace = target.selectedSpace;
+    if (!selectedSpace) {
+      try {
+        const info = await this.#authInfo(target);
+        if (info.spaces.length === 1) {
+          selectedSpace = info.spaces[0];
+          this.#persistSelectedSpace(target, selectedSpace);
+        }
+      } catch {
+        return jsonError(
+          503,
+          BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+          "Busabase authentication could not be verified"
+        );
+      }
+    }
+    if (!selectedSpace) {
+      return jsonError(
+        409,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.spaceSelectionRequired,
+        "Busabase Space selection required"
+      );
+    }
+    const incoming = new URL(request.url);
+    const targetUrl = new URL(incoming.pathname + incoming.search, target.baseUrl);
+    const headers = new Headers();
+    const contentType = request.headers.get("content-type");
+    const accept = request.headers.get("accept");
+    if (contentType) headers.set("content-type", contentType);
+    if (accept) headers.set("accept", accept);
+    headers.set("x-busabase-space", selectedSpace.id);
+    if (target.accessToken) headers.set("authorization", `Bearer ${target.accessToken}`);
+    const hasBody = request.method !== "GET" && request.method !== "HEAD";
+    let upstream;
+    try {
+      upstream = await this.#fetch()(targetUrl, {
+        method: request.method,
+        headers,
+        body: hasBody ? await request.arrayBuffer() : void 0,
+        redirect: "manual"
+      });
+    } catch {
+      return jsonError(
+        503,
+        BUSABASE_AIRAPP_GATEWAY_REASONS.authUnavailable,
+        "Busabase API is temporarily unavailable"
+      );
+    }
+    const responseHeaders = new Headers();
+    const upstreamType = upstream.headers.get("content-type");
+    if (upstreamType) responseHeaders.set("content-type", upstreamType);
+    return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
+  };
+};
+var createBusabaseAirAppLocalGateway = (options) => new BusabaseAirAppLocalGateway(options);
+
+export { BUSABASE_AIRAPP_GATEWAY_REASONS, BusabaseAirAppLocalGateway, createBusabaseAirAppLocalGateway };

package/dist/chunk-B2AWPFDI.js

@@ -0,0 +1,175 @@
+import { BusabaseOAuthError, BUSABASE_AIRAPP_CLIENT_ID, refreshBusabaseOAuthToken, revokeBusabaseOAuthToken } from './chunk-J2DZKX7A.js';
+import { normalizeBaseUrl } from './chunk-5NYQX65A.js';
+import { randomUUID } from 'crypto';
+import { readFileSync, mkdirSync, chmodSync, writeFileSync, renameSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+
+var STORE_VERSION = 1;
+var APP_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var REFRESH_WINDOW_MS = 6e4;
+var refreshesByCredentialPath = /* @__PURE__ */ new Map();
+var assertAppId = (appId) => {
+  if (!APP_ID_RE.test(appId)) {
+    throw new BusabaseOAuthError(
+      "invalid_airapp_id",
+      "AirApp id must use letters, digits, dot, dash, or underscore"
+    );
+  }
+  return appId;
+};
+var storeRoot = (options = {}) => options.rootDir ?? join(homedir(), ".busabase");
+var busabaseAirAppCredentialsDir = (options = {}) => join(storeRoot(options), "airapps");
+var busabaseAirAppCredentialPath = (appId, options = {}) => join(busabaseAirAppCredentialsDir(options), `${assertAppId(appId)}.json`);
+var normalizeOrigin = (raw) => {
+  const url = new URL(normalizeBaseUrl(raw));
+  if (url.username || url.password || url.search || url.hash) {
+    throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL must be an origin");
+  }
+  return url.origin;
+};
+var parseCredential = (raw, expectedAppId) => {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new BusabaseOAuthError("invalid_local_credential", "AirApp OAuth credential is invalid");
+  }
+  const item = value;
+  if (item.version !== STORE_VERSION || item.appId !== expectedAppId || typeof item.baseUrl !== "string" || typeof item.clientId !== "string" || typeof item.accessToken !== "string" || typeof item.refreshToken !== "string" || typeof item.expiresAt !== "string" || !Array.isArray(item.scope) || item.scope.some((scope) => typeof scope !== "string") || typeof item.tokenType !== "string") {
+    throw new BusabaseOAuthError("invalid_local_credential", "AirApp OAuth credential is invalid");
+  }
+  if (item.selectedSpace !== void 0 && (typeof item.selectedSpace !== "object" || item.selectedSpace === null || typeof item.selectedSpace.id !== "string" || typeof item.selectedSpace.name !== "string")) {
+    throw new BusabaseOAuthError("invalid_local_credential", "AirApp OAuth credential is invalid");
+  }
+  return item;
+};
+function loadBusabaseAirAppOAuthCredential(appId, options = {}) {
+  const path = busabaseAirAppCredentialPath(appId, options);
+  try {
+    return parseCredential(readFileSync(path, "utf8"), appId);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function storeBusabaseAirAppOAuthCredential(input, options = {}) {
+  if (!input.tokenSet.refreshToken) {
+    throw new BusabaseOAuthError(
+      "missing_refresh_token",
+      "A refresh token is required for a persistent local AirApp login"
+    );
+  }
+  const credential = {
+    version: STORE_VERSION,
+    appId: assertAppId(input.appId),
+    baseUrl: normalizeOrigin(input.baseUrl),
+    clientId: input.clientId ?? BUSABASE_AIRAPP_CLIENT_ID,
+    accessToken: input.tokenSet.accessToken,
+    refreshToken: input.tokenSet.refreshToken,
+    expiresAt: input.tokenSet.expiresAt,
+    scope: input.tokenSet.scope,
+    tokenType: input.tokenSet.tokenType,
+    ...input.selectedSpace ? { selectedSpace: input.selectedSpace } : {}
+  };
+  const path = busabaseAirAppCredentialPath(input.appId, options);
+  const directory = dirname(path);
+  mkdirSync(directory, { recursive: true, mode: 448 });
+  try {
+    chmodSync(directory, 448);
+  } catch {
+  }
+  const temporaryPath = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(temporaryPath, `${JSON.stringify(credential, null, 2)}
+`, { mode: 384 });
+  try {
+    chmodSync(temporaryPath, 384);
+  } catch {
+  }
+  renameSync(temporaryPath, path);
+  return credential;
+}
+async function getBusabaseAirAppAccessToken(appId, options = {}, fetchImpl = fetch) {
+  const credential = loadBusabaseAirAppOAuthCredential(appId, options);
+  if (!credential) return null;
+  const expiresAt = Date.parse(credential.expiresAt);
+  if (Number.isFinite(expiresAt) && expiresAt > Date.now() + REFRESH_WINDOW_MS) return credential;
+  const credentialPath = busabaseAirAppCredentialPath(appId, options);
+  const activeRefresh = refreshesByCredentialPath.get(credentialPath);
+  if (activeRefresh) return activeRefresh;
+  const refresh = (async () => {
+    const tokenSet = await refreshBusabaseOAuthToken(
+      {
+        baseUrl: credential.baseUrl,
+        refreshToken: credential.refreshToken,
+        clientId: credential.clientId
+      },
+      fetchImpl
+    );
+    return storeBusabaseAirAppOAuthCredential(
+      {
+        appId,
+        baseUrl: credential.baseUrl,
+        clientId: credential.clientId,
+        tokenSet: {
+          ...tokenSet,
+          refreshToken: tokenSet.refreshToken ?? credential.refreshToken
+        },
+        selectedSpace: credential.selectedSpace
+      },
+      options
+    );
+  })();
+  refreshesByCredentialPath.set(credentialPath, refresh);
+  try {
+    return await refresh;
+  } finally {
+    if (refreshesByCredentialPath.get(credentialPath) === refresh) {
+      refreshesByCredentialPath.delete(credentialPath);
+    }
+  }
+}
+function storeBusabaseAirAppSelectedSpace(appId, selectedSpace, options = {}) {
+  const credential = loadBusabaseAirAppOAuthCredential(appId, options);
+  if (!credential) {
+    throw new BusabaseOAuthError(
+      "missing_local_credential",
+      "Connect this local AirApp before selecting a Space"
+    );
+  }
+  const next = {
+    ...credential,
+    ...selectedSpace ? { selectedSpace } : { selectedSpace: void 0 }
+  };
+  const path = busabaseAirAppCredentialPath(appId, options);
+  const temporaryPath = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(temporaryPath, `${JSON.stringify(next, null, 2)}
+`, { mode: 384 });
+  try {
+    chmodSync(temporaryPath, 384);
+  } catch {
+  }
+  renameSync(temporaryPath, path);
+  return next;
+}
+function clearBusabaseAirAppOAuthCredential(appId, options = {}) {
+  rmSync(busabaseAirAppCredentialPath(appId, options), { force: true });
+}
+async function revokeBusabaseAirAppOAuthCredential(appId, options = {}, fetchImpl = fetch) {
+  const credential = loadBusabaseAirAppOAuthCredential(appId, options);
+  if (!credential) return;
+  try {
+    await revokeBusabaseOAuthToken(
+      {
+        baseUrl: credential.baseUrl,
+        token: credential.refreshToken,
+        clientId: credential.clientId
+      },
+      fetchImpl
+    );
+  } finally {
+    clearBusabaseAirAppOAuthCredential(appId, options);
+  }
+}
+
+export { busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppOAuthCredential, storeBusabaseAirAppSelectedSpace };

package/dist/oauth-node.d.ts

@@ -10,6 +10,11 @@ interface BusabaseAirAppOAuthCredential {
     expiresAt: string;
     scope: string[];
     tokenType: string;
+    /** Validated target for this local AirApp. Tokens remain user-scoped. */
+    selectedSpace?: {
+        id: string;
+        name: string;
+    };
 }
 interface BusabaseAirAppCredentialStoreOptions {
     /** Override only for tests or an explicitly isolated installation. */
@@ -24,10 +29,16 @@ declare function storeBusabaseAirAppOAuthCredential(input: {
     baseUrl: string;
     tokenSet: BusabaseOAuthTokenSet;
     clientId?: string;
+    selectedSpace?: BusabaseAirAppOAuthCredential["selectedSpace"];
 }, options?: BusabaseAirAppCredentialStoreOptions): BusabaseAirAppOAuthCredential;
 /** Load a valid access token, rotating and persisting the token set when needed. */
 declare function getBusabaseAirAppAccessToken(appId: string, options?: BusabaseAirAppCredentialStoreOptions, fetchImpl?: typeof fetch): Promise<BusabaseAirAppOAuthCredential | null>;
+/** Persist a Space only after the caller has verified membership through `/api/v1/auth`. */
+declare function storeBusabaseAirAppSelectedSpace(appId: string, selectedSpace: {
+    id: string;
+    name: string;
+} | null, options?: BusabaseAirAppCredentialStoreOptions): BusabaseAirAppOAuthCredential;
 declare function clearBusabaseAirAppOAuthCredential(appId: string, options?: BusabaseAirAppCredentialStoreOptions): void;
 declare function revokeBusabaseAirAppOAuthCredential(appId: string, options?: BusabaseAirAppCredentialStoreOptions, fetchImpl?: typeof fetch): Promise<void>;
 
-export { type BusabaseAirAppCredentialStoreOptions, type BusabaseAirAppOAuthCredential, busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppOAuthCredential };
+export { type BusabaseAirAppCredentialStoreOptions, type BusabaseAirAppOAuthCredential, busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppOAuthCredential, storeBusabaseAirAppSelectedSpace };

package/dist/oauth-node.js

@@ -1,147 +1,3 @@
-import { BusabaseOAuthError, BUSABASE_AIRAPP_CLIENT_ID, refreshBusabaseOAuthToken, revokeBusabaseOAuthToken } from './chunk-J2DZKX7A.js';
-import { normalizeBaseUrl } from './chunk-5NYQX65A.js';
-import { randomUUID } from 'crypto';
-import { readFileSync, mkdirSync, chmodSync, writeFileSync, renameSync, rmSync } from 'fs';
-import { homedir } from 'os';
-import { join, dirname } from 'path';
-
-var STORE_VERSION = 1;
-var APP_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-var REFRESH_WINDOW_MS = 6e4;
-var refreshesByCredentialPath = /* @__PURE__ */ new Map();
-var assertAppId = (appId) => {
-  if (!APP_ID_RE.test(appId)) {
-    throw new BusabaseOAuthError(
-      "invalid_airapp_id",
-      "AirApp id must use letters, digits, dot, dash, or underscore"
-    );
-  }
-  return appId;
-};
-var storeRoot = (options = {}) => options.rootDir ?? join(homedir(), ".busabase");
-var busabaseAirAppCredentialsDir = (options = {}) => join(storeRoot(options), "airapps");
-var busabaseAirAppCredentialPath = (appId, options = {}) => join(busabaseAirAppCredentialsDir(options), `${assertAppId(appId)}.json`);
-var normalizeOrigin = (raw) => {
-  const url = new URL(normalizeBaseUrl(raw));
-  if (url.username || url.password || url.search || url.hash) {
-    throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL must be an origin");
-  }
-  return url.origin;
-};
-var parseCredential = (raw, expectedAppId) => {
-  let value;
-  try {
-    value = JSON.parse(raw);
-  } catch {
-    throw new BusabaseOAuthError("invalid_local_credential", "AirApp OAuth credential is invalid");
-  }
-  const item = value;
-  if (item.version !== STORE_VERSION || item.appId !== expectedAppId || typeof item.baseUrl !== "string" || typeof item.clientId !== "string" || typeof item.accessToken !== "string" || typeof item.refreshToken !== "string" || typeof item.expiresAt !== "string" || !Array.isArray(item.scope) || item.scope.some((scope) => typeof scope !== "string") || typeof item.tokenType !== "string") {
-    throw new BusabaseOAuthError("invalid_local_credential", "AirApp OAuth credential is invalid");
-  }
-  return item;
-};
-function loadBusabaseAirAppOAuthCredential(appId, options = {}) {
-  const path = busabaseAirAppCredentialPath(appId, options);
-  try {
-    return parseCredential(readFileSync(path, "utf8"), appId);
-  } catch (error) {
-    if (error.code === "ENOENT") return null;
-    throw error;
-  }
-}
-function storeBusabaseAirAppOAuthCredential(input, options = {}) {
-  if (!input.tokenSet.refreshToken) {
-    throw new BusabaseOAuthError(
-      "missing_refresh_token",
-      "A refresh token is required for a persistent local AirApp login"
-    );
-  }
-  const credential = {
-    version: STORE_VERSION,
-    appId: assertAppId(input.appId),
-    baseUrl: normalizeOrigin(input.baseUrl),
-    clientId: input.clientId ?? BUSABASE_AIRAPP_CLIENT_ID,
-    accessToken: input.tokenSet.accessToken,
-    refreshToken: input.tokenSet.refreshToken,
-    expiresAt: input.tokenSet.expiresAt,
-    scope: input.tokenSet.scope,
-    tokenType: input.tokenSet.tokenType
-  };
-  const path = busabaseAirAppCredentialPath(input.appId, options);
-  const directory = dirname(path);
-  mkdirSync(directory, { recursive: true, mode: 448 });
-  try {
-    chmodSync(directory, 448);
-  } catch {
-  }
-  const temporaryPath = `${path}.${randomUUID()}.tmp`;
-  writeFileSync(temporaryPath, `${JSON.stringify(credential, null, 2)}
-`, { mode: 384 });
-  try {
-    chmodSync(temporaryPath, 384);
-  } catch {
-  }
-  renameSync(temporaryPath, path);
-  return credential;
-}
-async function getBusabaseAirAppAccessToken(appId, options = {}, fetchImpl = fetch) {
-  const credential = loadBusabaseAirAppOAuthCredential(appId, options);
-  if (!credential) return null;
-  const expiresAt = Date.parse(credential.expiresAt);
-  if (Number.isFinite(expiresAt) && expiresAt > Date.now() + REFRESH_WINDOW_MS) return credential;
-  const credentialPath = busabaseAirAppCredentialPath(appId, options);
-  const activeRefresh = refreshesByCredentialPath.get(credentialPath);
-  if (activeRefresh) return activeRefresh;
-  const refresh = (async () => {
-    const tokenSet = await refreshBusabaseOAuthToken(
-      {
-        baseUrl: credential.baseUrl,
-        refreshToken: credential.refreshToken,
-        clientId: credential.clientId
-      },
-      fetchImpl
-    );
-    return storeBusabaseAirAppOAuthCredential(
-      {
-        appId,
-        baseUrl: credential.baseUrl,
-        clientId: credential.clientId,
-        tokenSet: {
-          ...tokenSet,
-          refreshToken: tokenSet.refreshToken ?? credential.refreshToken
-        }
-      },
-      options
-    );
-  })();
-  refreshesByCredentialPath.set(credentialPath, refresh);
-  try {
-    return await refresh;
-  } finally {
-    if (refreshesByCredentialPath.get(credentialPath) === refresh) {
-      refreshesByCredentialPath.delete(credentialPath);
-    }
-  }
-}
-function clearBusabaseAirAppOAuthCredential(appId, options = {}) {
-  rmSync(busabaseAirAppCredentialPath(appId, options), { force: true });
-}
-async function revokeBusabaseAirAppOAuthCredential(appId, options = {}, fetchImpl = fetch) {
-  const credential = loadBusabaseAirAppOAuthCredential(appId, options);
-  if (!credential) return;
-  try {
-    await revokeBusabaseOAuthToken(
-      {
-        baseUrl: credential.baseUrl,
-        token: credential.refreshToken,
-        clientId: credential.clientId
-      },
-      fetchImpl
-    );
-  } finally {
-    clearBusabaseAirAppOAuthCredential(appId, options);
-  }
-}
-
-export { busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppOAuthCredential };
+export { busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppOAuthCredential, storeBusabaseAirAppSelectedSpace } from './chunk-B2AWPFDI.js';
+import './chunk-J2DZKX7A.js';
+import './chunk-5NYQX65A.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud).",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",
@@ -30,6 +30,10 @@
     "./oauth-node": {
       "types": "./dist/oauth-node.d.ts",
       "default": "./dist/oauth-node.js"
+    },
+    "./airapp-node": {
+      "types": "./dist/airapp-node.d.ts",
+      "default": "./dist/airapp-node.js"
     }
   },
   "files": [
@@ -49,8 +53,8 @@
     "tsx": "^4.20.5",
     "typescript": "^5.9.3",
     "vitest": "^2.1.8",
-    "busabase-contract": "0.14.1",
     "open-domains": "0.0.2",
+    "busabase-contract": "0.15.0",
     "openlib": "0.1.1"
   },
   "engines": {