mesh-catalog/modules/baserow/client.ts

// The Baserow API client — baserow's own code, living in the module (novox/hq ADR 0039). Both this
// module's tools and anything else baserow-specific import it; nothing outside baserow does.
//
// Baserow authenticates a person with email + password, exchanged for a JWT at /api/user/token-auth/.
// Those credentials are the mesh's own: a person signs up in Baserow (the standard image creates no
// admin from env), and the credential is placed in the runtime config file the mesh mounts. Until
// that happens fromEnv throws and the module simply exposes no tools — the same dormant-until-
// configured shape gitea uses for its token.

import { readFileSync } from "node:fs";

export interface BaserowApplication {
  id: number;
  name: string;
  type: string;
}

export interface BaserowRow {
  id: number;
  [key: string]: unknown;
}

function meshConfig(file?: string): Record<string, string> {
  if (!file) return {};
  try {
    return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>;
  } catch {
    return {};
  }
}

export class BaserowClient {
  readonly baseUrl: string;
  private token: string | null = null;

  constructor(
    url: string,
    private readonly email: string,
    private readonly password: string,
    private readonly hostHeader?: string,
  ) {
    this.baseUrl = url.replace(/\/+$/, "");
  }

  /**
   * Build from the module's resolved environment. URL, credentials and an optional Host override
   * come from the runtime config file first (MESH_BASEROW_CONFIG_FILE), then the mesh's own env
   * names, then the bare BASEROW_* names. Credentials are required — without them there is no
   * authenticated call to make, so this throws rather than hand back a client that fails on first use.
   */
  static fromEnv(env: NodeJS.ProcessEnv = process.env): BaserowClient {
    const cfg = meshConfig(env.MESH_BASEROW_CONFIG_FILE);
    const url = cfg.url ?? env.MESH_BASEROW_URL ?? env.BASEROW_URL ?? "http://127.0.0.1:80";
    const email = cfg.email ?? env.MESH_BASEROW_EMAIL ?? env.BASEROW_EMAIL;
    const password = cfg.password ?? env.MESH_BASEROW_PASSWORD ?? env.BASEROW_PASSWORD;
    // Baserow's bundled Caddy routes by the Host header against BASEROW_PUBLIC_URL; a co-located
    // caller reaching it over the container network may need to present that host.
    const hostHeader = cfg.host ?? env.MESH_BASEROW_HOST;
    if (!email || !password) {
      throw new Error("no Baserow credentials — set MESH_BASEROW_EMAIL and MESH_BASEROW_PASSWORD");
    }
    return new BaserowClient(url, email, password, hostHeader);
  }

  private headers(extra: Record<string, string> = {}): Record<string, string> {
    const h: Record<string, string> = { "Content-Type": "application/json", ...extra };
    if (this.hostHeader) h.Host = this.hostHeader;
    return h;
  }

  /** Exchange email + password for a JWT, caching it for the client's lifetime. Handles both the
   *  older `{ token }` and the newer `{ access_token }` response shapes. */
  async authenticate(): Promise<string> {
    if (this.token) return this.token;
    const res = await fetch(`${this.baseUrl}/api/user/token-auth/`, {
      method: "POST",
      headers: this.headers(),
      body: JSON.stringify({ email: this.email, password: this.password }),
    });
    if (!res.ok) throw new Error(`baserow auth failed: ${res.status} ${await res.text()}`);
    const data = (await res.json()) as { token?: string; access_token?: string };
    const token = data.access_token ?? data.token;
    if (!token) throw new Error("baserow auth returned no token");
    this.token = token;
    return token;
  }

  private async authed<T>(path: string, options: RequestInit = {}): Promise<T> {
    const token = await this.authenticate();
    const res = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: this.headers({
        Authorization: `JWT ${token}`,
        ...(options.headers as Record<string, string> | undefined),
      }),
    });
    if (!res.ok) throw new Error(`baserow ${path}: ${res.status} ${await res.text()}`);
    const text = await res.text();
    return (text ? JSON.parse(text) : null) as T;
  }

  /** The applications (databases) the account can see, across all its workspaces. */
  async listApplications(): Promise<BaserowApplication[]> {
    return (await this.authed<BaserowApplication[]>(`/api/applications/`)) ?? [];
  }

  /** Rows of a table, by numeric table id, with human field names. */
  async listRows(tableId: number, size = 100): Promise<BaserowRow[]> {
    const data = await this.authed<{ results: BaserowRow[] }>(
      `/api/database/rows/table/${tableId}/?size=${size}&user_field_names=true`,
    );
    return data?.results ?? [];
  }
}