@pawabase/client 0.0.0-stage → 0.1.0

package/src/session-store.ts

@@ -0,0 +1,36 @@
+/** Where the signed-in session is kept between page loads. */
+export interface SessionStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+/** Keeps the session in memory only: gone when the process or page ends. The default on servers. */
+export class MemoryStorage implements SessionStorage {
+  private readonly items = new Map<string, string>();
+  getItem(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+  setItem(key: string, value: string): void {
+    this.items.set(key, value);
+  }
+  removeItem(key: string): void {
+    this.items.delete(key);
+  }
+}
+
+/** `localStorage` when the browser allows it (it can be blocked), otherwise `null`. */
+export function browserStorage(): SessionStorage | null {
+  // Newer Node versions expose an experimental `localStorage` that warns when touched.
+  if (typeof window === "undefined") return null;
+  try {
+    const store = (globalThis as { localStorage?: Storage }).localStorage;
+    if (!store) return null;
+    const probe = "__pawabase_probe__";
+    store.setItem(probe, "1");
+    store.removeItem(probe);
+    return store;
+  } catch {
+    return null;
+  }
+}

package/src/typegen.ts

@@ -0,0 +1,192 @@
+/**
+ * Turn a project's OpenAPI document into TypeScript types for `createClient<Database>()`.
+ *
+ * The compiled API documents each resource as a read model, a create body and an update
+ * body. The create body says which fields are required; the read model marks every field
+ * nullable (a `select` can leave columns out as `null`), so the generator uses the create
+ * body to tell "always present" from "may be null".
+ */
+
+type Schema = Record<string, any>;
+
+export interface TypegenOptions {
+  /** The name of the exported root interface. Default `Database`. */
+  name?: string;
+  /** Text for the header comment, e.g. where the spec came from. */
+  source?: string;
+}
+
+const RESERVED_SYSTEM = new Set(["created_at", "updated_at"]);
+
+function pascal(name: string): string {
+  return name
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part[0]!.toUpperCase() + part.slice(1))
+    .join("");
+}
+
+function key(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+function resolve(spec: Schema, node: Schema | undefined): Schema | undefined {
+  let current = node;
+  for (let depth = 0; current && typeof current["$ref"] === "string" && depth < 10; depth++) {
+    const path = (current["$ref"] as string).replace(/^#\//, "").split("/");
+    let target: any = spec;
+    for (const part of path) target = target?.[part];
+    current = target;
+  }
+  return current;
+}
+
+/** A schema as a TypeScript type expression. */
+function typeOf(spec: Schema, node: Schema | undefined): string {
+  const schema = resolve(spec, node);
+  if (!schema || Object.keys(schema).length === 0) return "unknown";
+  const variants = schema["anyOf"] ?? schema["oneOf"];
+  if (Array.isArray(variants)) {
+    const parts = variants.map((variant: Schema) => typeOf(spec, variant));
+    const unique = [...new Set(parts)];
+    return unique.includes("unknown") ? "unknown" : unique.join(" | ");
+  }
+  if (Array.isArray(schema["enum"])) return schema["enum"].map((value: unknown) => JSON.stringify(value)).join(" | ");
+  switch (schema["type"]) {
+    case "integer":
+    case "number":
+      return "number";
+    case "string":
+      return "string";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "array": {
+      const inner = typeOf(spec, schema["items"]);
+      return inner.includes(" | ") ? `Array<${inner}>` : `${inner}[]`;
+    }
+    case "object":
+      return schema["properties"] ? "Record<string, unknown>" : "Record<string, unknown>";
+    default:
+      return "unknown";
+  }
+}
+
+/** The schema without its `null` variant, and whether it had one. */
+function stripNull(spec: Schema, node: Schema | undefined): { type: string; nullable: boolean } {
+  const type = typeOf(spec, node);
+  const parts = type.split(" | ");
+  const nullable = parts.includes("null");
+  const rest = parts.filter((part) => part !== "null");
+  return { type: rest.length ? rest.join(" | ") : "unknown", nullable };
+}
+
+function bodySchema(spec: Schema, operation: Schema | undefined): Schema | undefined {
+  return resolve(spec, operation?.["requestBody"]?.["content"]?.["application/json"]?.["schema"]);
+}
+
+function listRow(spec: Schema, operation: Schema | undefined): Schema | undefined {
+  const page = resolve(spec, operation?.["responses"]?.["200"]?.["content"]?.["application/json"]?.["schema"]);
+  return resolve(spec, page?.["properties"]?.["data"]?.["items"]);
+}
+
+interface Resource {
+  name: string;
+  row: Schema;
+  insert: Schema | undefined;
+  update: Schema | undefined;
+}
+
+export function findResources(spec: Schema): Resource[] {
+  const found: Resource[] = [];
+  for (const [path, item] of Object.entries<Schema>(spec["paths"] ?? {})) {
+    const match = /^\/rest\/v\d+\/([^/{}]+)$/.exec(path);
+    if (!match) continue;
+    const row = listRow(spec, item["get"]) ?? resolve(spec, item["post"]?.["responses"]?.["201"]?.["content"]?.["application/json"]?.["schema"]);
+    if (!row?.["properties"]) continue; // a custom route, not a resource
+    const withId = spec["paths"][`${path}/{id}`] as Schema | undefined;
+    found.push({
+      name: match[1]!,
+      row,
+      insert: bodySchema(spec, item["post"]),
+      update: bodySchema(spec, withId?.["patch"]),
+    });
+  }
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function describe(spec: Schema, resource: Resource): string {
+  const type = pascal(resource.name);
+  const required = new Set<string>(resource.insert?.["required"] ?? []);
+  const insertProps: Schema = resource.insert?.["properties"] ?? {};
+  const rowProps: Schema = resource.row["properties"] ?? {};
+  const lines: string[] = [];
+
+  // Row: what a read returns.
+  const row: string[] = [];
+  const primary = rowProps["id"];
+  if (primary) {
+    const id = stripNull(spec, primary).type;
+    row.push(`  id: ${id};`);
+  }
+  for (const [name, node] of Object.entries<Schema>(rowProps)) {
+    if (name === "id") continue;
+    const { type } = stripNull(spec, node);
+    const guaranteed = required.has(name) || (insertProps[name] && "default" in insertProps[name] && insertProps[name]["default"] !== null);
+    row.push(`  ${key(name)}: ${type === "unknown" ? "unknown" : guaranteed ? type : `${type} | null`};`);
+  }
+  for (const system of RESERVED_SYSTEM) {
+    if (!(system in rowProps)) row.push(`  ${system}?: string;`);
+  }
+  lines.push(`export interface ${type}Row {`, ...row, "}", "");
+
+  // Insert: what a create accepts.
+  const insert: string[] = [];
+  for (const [name, node] of Object.entries<Schema>(insertProps)) {
+    const { type, nullable } = stripNull(spec, node);
+    insert.push(`  ${key(name)}${required.has(name) ? "" : "?"}: ${type}${nullable && type !== "unknown" ? " | null" : ""};`);
+  }
+  lines.push(`export interface ${type}Insert {`, ...insert, "}", "");
+
+  // Update: a PATCH takes any field, null included.
+  const updateProps: Schema = resource.update?.["properties"] ?? insertProps;
+  const update: string[] = [];
+  for (const [name, node] of Object.entries<Schema>(updateProps)) {
+    const { type } = stripNull(spec, node);
+    update.push(`  ${key(name)}?: ${type === "unknown" ? "unknown" : `${type} | null`};`);
+  }
+  lines.push(`export interface ${type}Update {`, ...update, "}", "");
+  return lines.join("\n");
+}
+
+/** The generated file's text. */
+export function generateTypes(spec: Schema, options: TypegenOptions = {}): string {
+  const root = options.name ?? "Database";
+  const resources = findResources(spec);
+  const title: string = spec["info"]?.["title"] ?? "Pawabase API";
+  const version: string = spec["info"]?.["version"] ?? "";
+  const out: string[] = [
+    "/* eslint-disable */",
+    `// Generated by pawabase-types from "${title}" ${version}${options.source ? ` (${options.source})` : ""}.`,
+    "// Do not edit by hand: regenerate when your resources change.",
+    "",
+  ];
+  for (const resource of resources) out.push(describe(spec, resource));
+  out.push(`export interface ${root} {`, "  resources: {");
+  for (const resource of resources) {
+    const type = pascal(resource.name);
+    out.push(`    ${key(resource.name)}: { Row: ${type}Row; Insert: ${type}Insert; Update: ${type}Update };`);
+  }
+  out.push("  };", "}", "");
+  out.push(
+    `/** A resource's row: \`Row<"posts">\`. */`,
+    `export type Row<K extends keyof ${root}["resources"]> = ${root}["resources"][K]["Row"];`,
+    `/** What a create accepts: \`Insert<"posts">\`. */`,
+    `export type Insert<K extends keyof ${root}["resources"]> = ${root}["resources"][K]["Insert"];`,
+    `/** What an update accepts: \`Update<"posts">\`. */`,
+    `export type Update<K extends keyof ${root}["resources"]> = ${root}["resources"][K]["Update"];`,
+    "",
+  );
+  return out.join("\n");
+}

package/src/types.ts

@@ -0,0 +1,195 @@
+/** Shapes the platform sends. They keep the wire's `snake_case` names, so what you see in Studio and the docs is what you read in code. */
+
+export interface Identity {
+  id: number;
+  provider: string;
+  email: string | null;
+  last_sign_in_at: string | null;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  username: string;
+  name: string;
+  avatar_url: string | null;
+  email_verified: boolean;
+  email_verified_at: string | null;
+  /** Profile data the user may edit. Never trust it for authorization. */
+  user_metadata: Record<string, unknown>;
+  /** Data only the application (a secret key or Studio) can edit. */
+  app_metadata: Record<string, unknown>;
+  roles: string[];
+  mfa_enabled: boolean;
+  identities: Identity[];
+  created_at: string | null;
+  last_sign_in_at: string | null;
+  /** The assurance level of the current session: `aal1` (password) or `aal2` (second factor). Only on `getUser()`. */
+  aal?: string | null;
+  /** Only on `getUser()`. */
+  session_id?: string | null;
+}
+
+export interface Session {
+  access_token: string;
+  refresh_token: string;
+  token_type: "bearer";
+  /** Seconds the access token lives, as issued. */
+  expires_in: number;
+  /** Unix time (seconds) at which the access token expires. */
+  expires_at: number;
+  session_id?: string;
+  /** The organization (slug) the token is issued for, if any. */
+  org: string | null;
+  org_role: string | null;
+  user: User;
+}
+
+export interface AuthSettings {
+  signup_enabled: boolean;
+  email_verification_required: boolean;
+  magic_link_enabled: boolean;
+  email_code_enabled: boolean;
+  anonymous_enabled: boolean;
+  passkeys_enabled: boolean;
+  mfa_enabled: boolean;
+  providers: string[];
+  password_policy: { kind: string; min_length: number };
+}
+
+export interface MfaStatus {
+  enabled: boolean;
+  aal: string | null;
+  recovery_codes_remaining: number;
+}
+
+export interface MfaEnrollment {
+  factor_id: string;
+  /** The shared secret, for manual entry. */
+  secret: string;
+  /** An `otpauth://` URI to render as a QR code. */
+  otpauth_uri: string;
+}
+
+export interface SessionInfo {
+  id: string;
+  method: string;
+  aal: string;
+  ip: string | null;
+  user_agent: string | null;
+  created_at: string | null;
+  last_refreshed_at: string | null;
+  current: boolean;
+}
+
+export interface SignInEvent {
+  kind: string;
+  method: string;
+  success: boolean;
+  reason: string | null;
+  ip: string | null;
+  user_agent: string | null;
+  at: string;
+}
+
+export interface Organization {
+  id: number;
+  slug: string;
+  name: string;
+  metadata: Record<string, unknown>;
+  /** The caller's role in it. */
+  role: string | null;
+  created_at: string | null;
+}
+
+export type OrgRole = "viewer" | "member" | "admin" | "owner";
+
+export interface OrgMember {
+  user_id: string;
+  email: string;
+  name: string;
+  role: string;
+}
+
+export interface Invitation {
+  id: number;
+  email: string;
+  role: string;
+  expires_at: string;
+}
+
+export interface Team {
+  slug: string;
+  name: string;
+  [key: string]: unknown;
+}
+
+/** One page of a list. */
+export interface Page<T> {
+  data: T[];
+  /** The 1-based page number. */
+  page: number;
+  per_page: number;
+  /**
+   * How many records match for this caller. `null` when a per-row policy makes it unknowable
+   * (and then pages can be short, or empty, with more behind them).
+   */
+  total: number | null;
+}
+
+export interface StorageBucket {
+  name: string;
+  public: boolean;
+  accepts: string[];
+  max_bytes: number;
+}
+
+export interface StoredObject {
+  bucket: string;
+  key: string;
+  size: number;
+  content_type: string;
+  etag?: string;
+}
+
+export interface FileEntry {
+  key: string;
+  size: number;
+  content_type: string;
+  modified: string | number | null;
+}
+
+export interface FileListing {
+  files: FileEntry[];
+  /** "Folders": the distinct prefixes below the listed prefix. */
+  prefixes: string[];
+  /** Pass back to read the next page. Empty when this is the last. */
+  cursor: string;
+}
+
+export interface SignedUrl {
+  url: string;
+  /** Unix time (seconds). */
+  expires_at: number;
+  method: "GET" | "PUT";
+}
+
+export interface ChannelMessage<T = unknown> {
+  type: "message";
+  id: string;
+  channel: string;
+  event: string;
+  payload: T;
+  /** The sender's user id; `"server"` for server-side publishes. */
+  from: string | null;
+  sent_at: string;
+  /** Present on messages read from history. */
+  seq?: number;
+}
+
+export interface PresenceMember<M = Record<string, unknown>> {
+  presence_ref: string;
+  user_id: string | null;
+  meta: M;
+  online_at: string;
+}

package/src/util.ts

@@ -0,0 +1,114 @@
+import { AbortError } from "./errors.js";
+
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Sleep for `ms`, rejecting early with {@link AbortError} when `signal` fires. */
+export function sleep(ms: number, signal?: AbortSignal | null): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new AbortError(undefined, { cause: signal.reason }));
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new AbortError(undefined, { cause: signal?.reason }));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Exponential backoff with full jitter: a random delay in `[0, min(max, base * factor^attempt)]`. */
+export function backoff(
+  attempt: number,
+  options: { baseDelayMs: number; maxDelayMs: number; factor?: number },
+  random: () => number = Math.random,
+): number {
+  const ceiling = Math.min(options.maxDelayMs, options.baseDelayMs * (options.factor ?? 2) ** attempt);
+  return Math.floor(random() * ceiling);
+}
+
+/** One signal that fires when any of `signals` fires. Uses the platform's `AbortSignal.any` when present. */
+export function anySignal(signals: Array<AbortSignal | null | undefined>): AbortSignal | undefined {
+  const real = signals.filter((s): s is AbortSignal => !!s);
+  if (real.length === 0) return undefined;
+  if (real.length === 1) return real[0];
+  const native = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => AbortSignal }).any;
+  if (native) return native(real);
+  const controller = new AbortController();
+  for (const signal of real) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      break;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+/** `a/b c/d` to `a/b%20c/d`: encode each path segment, keep the slashes. */
+export function encodePath(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export type QueryValue = string | number | boolean | null | undefined | Date;
+
+/** A query string from a flat record. Drops `undefined`/`null`; arrays repeat the key. */
+export function queryString(params: Record<string, QueryValue | QueryValue[]> | undefined): string {
+  if (!params) return "";
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    const items = Array.isArray(value) ? value : [value];
+    for (const item of items) {
+      if (item === undefined || item === null) continue;
+      search.append(key, item instanceof Date ? item.toISOString() : String(item));
+    }
+  }
+  const text = search.toString();
+  return text ? `?${text}` : "";
+}
+
+export function trimSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+export function randomId(): string {
+  const c = (globalThis as { crypto?: Crypto }).crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function nowSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+/** Decode a JWT payload without verifying it (the server verifies). Returns `null` for malformed tokens. */
+export function decodeJwt(token: string): Record<string, unknown> | null {
+  const part = token.split(".")[1];
+  if (!part) return null;
+  try {
+    const base64 = part.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(part.length / 4) * 4, "=");
+    const text =
+      typeof atob === "function"
+        ? decodeURIComponent(
+            Array.from(atob(base64), (ch) => "%" + ch.charCodeAt(0).toString(16).padStart(2, "0")).join(""),
+          )
+        : (globalThis as unknown as { Buffer: { from(s: string, e: string): { toString(e: string): string } } }).Buffer.from(base64, "base64").toString("utf8");
+    const value = JSON.parse(text) as unknown;
+    return isRecord(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a key is a secret key (`pb_sk_…`, or `sk_…` in older docs). */
+export function isSecretKey(apiKey: string): boolean {
+  return /^(pb_)?sk_/.test(apiKey);
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";