@pawabase/client 0.0.0-stage → 0.1.3

package/src/cli/gen-types.ts

@@ -0,0 +1,105 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { generateTypes } from "../typegen.js";
+
+const USAGE = `pawabase-types: generate TypeScript types for createClient<Database>()
+
+Usage:
+  pawabase-types --url <gateway> --project <ref> --env <name> [--out types.ts]
+  pawabase-types --file openapi.json [--out types.ts]
+
+Options:
+  --url, -u       The gateway origin             (env PAWABASE_URL)
+  --project, -p   The project's ref              (env PAWABASE_PROJECT)
+  --env, -e       The environment's name         (env PAWABASE_ENV)
+  --api-key, -k   An API key, sent as 'apikey'   (env PAWABASE_API_KEY)
+  --file, -f      Read the OpenAPI document from a file instead of the gateway
+  --out, -o       Where to write the types. Default: pawabase.types.ts. '-' prints them.
+  --name          The root interface's name. Default: Database
+  --check         Exit 1 if --out is out of date (for CI); writes nothing
+  --help, -h      Show this
+
+The gateway serves /docs/v1/<project>/<env>/openapi.json when the environment's
+"public docs" setting is on. Otherwise download the document from Studio (API
+Explorer) and pass it with --file.
+`;
+
+function parse(argv: string[]): Record<string, string | boolean> {
+  const out: Record<string, string | boolean> = {};
+  const alias: Record<string, string> = { u: "url", p: "project", e: "env", k: "api-key", f: "file", o: "out", h: "help" };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (!arg.startsWith("-")) continue;
+    const name = arg.startsWith("--") ? arg.slice(2) : (alias[arg.slice(1)] ?? arg.slice(1));
+    if (name === "help" || name === "check") out[name] = true;
+    else out[name] = argv[++i] ?? "";
+  }
+  return out;
+}
+
+async function main(): Promise<number> {
+  const args = parse(process.argv.slice(2));
+  if (args["help"]) {
+    console.log(USAGE);
+    return 0;
+  }
+  const file = args["file"] as string | undefined;
+  const url = (args["url"] as string | undefined) ?? process.env["PAWABASE_URL"];
+  const project = (args["project"] as string | undefined) ?? process.env["PAWABASE_PROJECT"];
+  const env = (args["env"] as string | undefined) ?? process.env["PAWABASE_ENV"];
+  const apiKey = (args["api-key"] as string | undefined) ?? process.env["PAWABASE_API_KEY"];
+
+  let spec: unknown;
+  let source: string;
+  if (file) {
+    spec = JSON.parse(readFileSync(file, "utf8"));
+    source = file;
+  } else {
+    if (!url || !project || !env) {
+      console.error("Give --url, --project and --env (or --file).\n\n" + USAGE);
+      return 2;
+    }
+    const endpoint = `${url.replace(/\/+$/, "")}/docs/v1/${encodeURIComponent(project)}/${encodeURIComponent(env)}/openapi.json`;
+    const response = await fetch(endpoint, { headers: apiKey ? { apikey: apiKey } : {} });
+    if (!response.ok) {
+      console.error(
+        `Could not read ${endpoint}: ${response.status}. ` +
+          (response.status === 404 ? "Turn on public docs for this environment, or use --file with the document from Studio." : ""),
+      );
+      return 1;
+    }
+    spec = await response.json();
+    source = endpoint;
+  }
+
+  const text = generateTypes(spec as Record<string, unknown>, {
+    ...(args["name"] ? { name: String(args["name"]) } : {}),
+    source,
+  });
+  const out = (args["out"] as string | undefined) ?? "pawabase.types.ts";
+  if (out === "-") {
+    process.stdout.write(text);
+    return 0;
+  }
+  if (args["check"]) {
+    const current = existsSync(out) ? readFileSync(out, "utf8") : "";
+    // The header names the source and version; compare the body only.
+    const body = (value: string) => value.split("\n").slice(3).join("\n");
+    if (body(current) !== body(text)) {
+      console.error(`${out} is out of date. Run pawabase-types again.`);
+      return 1;
+    }
+    console.log(`${out} is up to date.`);
+    return 0;
+  }
+  writeFileSync(out, text);
+  console.log(`Wrote ${out}`);
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  },
+);

package/src/client.ts

@@ -0,0 +1,189 @@
+import { AuthClient, type AuthOptions } from "./auth.js";
+import { ResourceClient, type AnyRow, type ResourceTypes } from "./data.js";
+import { ConfigError } from "./errors.js";
+import { StorageClient } from "./files.js";
+import { FlowsClient, FunctionsClient, RoutesClient } from "./functions.js";
+import { HttpClient, type FetchLike, type Hooks, type RetryOptions, type TokenProvider } from "./http.js";
+import { RealtimeClient, type RealtimeOptions } from "./realtime.js";
+import { MemoryStorage } from "./session-store.js";
+import { isSecretKey, trimSlash } from "./util.js";
+
+/** The shape `createClient<Database>()` expects. `pawabase-types` generates one from your project. */
+export interface DatabaseShape {
+  resources: Record<string, ResourceTypes<any, any, any>>;
+}
+
+type Untyped = { resources: Record<string, ResourceTypes> };
+
+export interface ClientOptions {
+  /** The gateway's origin, e.g. `https://api.example.com`. */
+  url: string;
+  /** The project API key: `pb_pk_…` (publishable, safe in a browser) or `pb_sk_…` (secret, servers only). */
+  apiKey: string;
+  /**
+   * The environment this client talks to (`development`, `production`, a preview's name). The API key already names
+   * one, so it is optional for data calls; social sign-in, realtime and the management clients (`@pawabase/client/manage`,
+   * `@pawabase/client/admin`) use it. `project` is only sent as a scope hint.
+   */
+  project?: string;
+  environment?: string;
+  /** Per-attempt timeout in milliseconds. Default `30000`; `0` disables it. */
+  timeoutMs?: number;
+  /** Retry policy for rate limits, `502`/`503`/`504` and network failures. `false` to never retry. */
+  retry?: RetryOptions | false;
+  /** Your `fetch` (Node < 18 polyfills, React Native, a test double, instrumentation). */
+  fetch?: FetchLike;
+  /** Extra headers sent on every request. */
+  headers?: Record<string, string>;
+  hooks?: Hooks;
+  auth?: AuthOptions;
+  realtime?: RealtimeOptions;
+  /**
+   * Use this user's access token instead of a stored session: a string, or a function
+   * (for frameworks that own the session). With it the client keeps no session, does not
+   * refresh, and is meant for one server-side request.
+   */
+  accessToken?: string | (() => string | null | Promise<string | null>);
+  /** A secret key in a browser leaks it to every visitor, so it is refused. Set this to override. */
+  dangerouslyAllowBrowser?: boolean;
+}
+
+function isBrowser(): boolean {
+  return typeof window !== "undefined" && typeof (globalThis as { document?: unknown }).document !== "undefined";
+}
+
+function staticTokens(source: NonNullable<ClientOptions["accessToken"]>): TokenProvider {
+  const get = async () => (typeof source === "string" ? source : await source());
+  return { getAccessToken: get, onUnauthorized: async () => null };
+}
+
+/**
+ * The entry point.
+ *
+ * ```ts
+ * const pawabase = createClient({ url: "https://api.example.com", apiKey: "pb_pk_…" });
+ * await pawabase.auth.signInWithPassword({ email, password });
+ * const { data } = await pawabase.from("posts").eq("status", "live").order("created_at", "desc");
+ * ```
+ */
+export class PawabaseClient<DB extends DatabaseShape = Untyped> {
+  readonly http: HttpClient;
+  /** Sign-in, session lifecycle and the signed-in user. */
+  readonly auth: AuthClient;
+  /** Storage buckets. */
+  readonly storage: StorageClient;
+  /** Functions: `/functions/v1`. */
+  readonly functions: FunctionsClient;
+  /** Flows with a pathless HTTP trigger: `/flows/v1`. */
+  readonly flows: FlowsClient;
+  /** Custom routes: `/rest/v1/<path>`. */
+  readonly routes: RoutesClient;
+  /** Channels, presence and publishing. */
+  readonly realtime: RealtimeClient;
+
+  constructor(readonly options: ClientOptions) {
+    if (!options.url) throw new ConfigError("createClient needs the gateway `url`.");
+    if (!options.apiKey) throw new ConfigError("createClient needs an `apiKey`.");
+    let origin: URL;
+    try {
+      origin = new URL(options.url);
+    } catch {
+      throw new ConfigError(`"${options.url}" is not a valid URL.`);
+    }
+    if (origin.protocol !== "http:" && origin.protocol !== "https:") {
+      throw new ConfigError("The `url` must start with http:// or https://.");
+    }
+    if (isSecretKey(options.apiKey) && isBrowser() && !options.dangerouslyAllowBrowser) {
+      throw new ConfigError(
+        "A secret key (pb_sk_…) must never run in a browser: it bypasses every policy and anyone can read it. Use a publishable key (pb_pk_…) here, or set `dangerouslyAllowBrowser`.",
+      );
+    }
+    const fetchImpl: FetchLike | undefined =
+      options.fetch ?? (typeof fetch === "function" ? ((input, init) => fetch(input, init)) : undefined);
+    if (!fetchImpl) throw new ConfigError("No `fetch` is available. Pass one in the options.");
+
+    const stateless = options.accessToken !== undefined;
+    const config = {
+      baseUrl: trimSlash(options.url),
+      apiKey: options.apiKey,
+      fetch: fetchImpl,
+      headers: {
+        ...(options.project ? { "x-project-id": options.project } : {}),
+        ...(options.environment ? { "x-environment": options.environment } : {}),
+        ...options.headers,
+      },
+      timeoutMs: options.timeoutMs ?? 30_000,
+      retry: options.retry ?? ({} as RetryOptions),
+      hooks: options.hooks ?? {},
+      tokens: null as TokenProvider | null,
+    };
+    this.http = new HttpClient(config);
+    this.auth = new AuthClient(this.http, {
+      ...(stateless ? { persistSession: false, autoRefreshToken: false, storage: new MemoryStorage(), detectSessionInUrl: false } : {}),
+      ...options.auth,
+      ...(options.project ? { project: options.project } : {}),
+      ...(options.environment ? { environment: options.environment } : {}),
+    });
+    config.tokens = stateless ? staticTokens(options.accessToken as NonNullable<ClientOptions["accessToken"]>) : this.auth;
+    this.storage = new StorageClient(this.http);
+    this.functions = new FunctionsClient(this.http);
+    this.flows = new FlowsClient(this.http);
+    this.routes = new RoutesClient(this.http);
+    this.realtime = new RealtimeClient(this.http, stateless ? null : this.auth, {
+      ...options.realtime,
+      ...(options.project ? { project: options.project } : {}),
+      ...(options.environment ? { environment: options.environment } : {}),
+    });
+  }
+
+  /**
+   * Records of a resource. With a generated `Database` type the name and row types are checked;
+   * without one rows are `Record<string, unknown>`.
+   */
+  from<K extends keyof DB["resources"] & string>(
+    name: K,
+  ): ResourceClient<DB["resources"][K]["Row"], DB["resources"][K]["Insert"], DB["resources"][K]["Update"]> {
+    return new ResourceClient(this.http, name);
+  }
+
+  /** Records of a resource, typed by hand: `pawabase.resource<Post, NewPost>("posts")`. */
+  resource<Row = AnyRow, Insert = Partial<Row>, Update = Partial<Row>>(name: string): ResourceClient<Row, Insert, Update> {
+    return new ResourceClient<Row, Insert, Update>(this.http, name);
+  }
+
+  /** A client that acts as one user, from a token you hold (a server rendering a page, an edge function). It keeps no session. */
+  asUser(accessToken: string | (() => string | null | Promise<string | null>)): PawabaseClient<DB> {
+    return new PawabaseClient<DB>({ ...this.options, accessToken });
+  }
+
+  /**
+   * A raw request to any path on the gateway, with the key and the user's token attached,
+   * the retry policy and the typed errors applied. For endpoints the client has no method for.
+   */
+  request<T = unknown>(method: string, path: string, options: { body?: unknown; query?: Record<string, string | number | boolean | undefined | null>; headers?: Record<string, string>; signal?: AbortSignal } = {}): Promise<T> {
+    return this.http.request<T>({
+      method,
+      path,
+      ...(options.query ? { query: options.query } : {}),
+      ...(options.body !== undefined ? { body: options.body } : {}),
+      ...(options.headers ? { headers: options.headers } : {}),
+      signal: options.signal,
+    });
+  }
+
+  /** The health of every Pawabase service behind the gateway. */
+  status(): Promise<{ ok: boolean; services?: Record<string, { ok: boolean }> }> {
+    return this.http.request({ path: "/v1/status", auth: "none", headers: {} });
+  }
+
+  /** Stop timers and close the realtime connection. Call when discarding a client. */
+  dispose(): void {
+    this.realtime.disconnect();
+    this.auth.dispose();
+  }
+}
+
+/** Create a client. See {@link ClientOptions}. */
+export function createClient<DB extends DatabaseShape = Untyped>(options: ClientOptions): PawabaseClient<DB> {
+  return new PawabaseClient<DB>(options);
+}