@everystack/api 0.1.0

package/src/client/index.ts

@@ -0,0 +1,352 @@
+/**
+ * Typed PostgREST client — pure fetch, zero React dependency.
+ *
+ * Usage:
+ *   import { createClient } from 'everystack/client';
+ *   const api = createClient({ baseUrl: 'https://myapp.com/api' });
+ *   const { data } = await api.from('posts').eq('status', 'published').limit(10).execute();
+ */
+
+export interface ClientOptions {
+  baseUrl: string;
+  headers?: Record<string, string>;
+  getToken?: () => string | null | Promise<string | null>;
+  /** Called on 401 — return a new token to retry, or null to fail */
+  onTokenExpired?: () => Promise<string | null>;
+  /** Client credentials sent with every request */
+  clientCredentials?: {
+    id: string;
+    secret: string;
+    /** Custom header names. Defaults: { id: 'X-Client-Id', secret: 'X-Client-Secret' } */
+    headers?: { id: string; secret: string };
+  };
+}
+
+export interface ClientError {
+  status: number;
+  message: string;
+}
+
+export interface ClientResponse<T> {
+  data: T | null;
+  error: ClientError | null;
+}
+
+export interface CountResponse<T> extends ClientResponse<T> {
+  /** Total count from Content-Range header (0 if unavailable) */
+  total: number;
+}
+
+export interface QueryBuilder {
+  eq(column: string, value: string): QueryBuilder;
+  neq(column: string, value: string): QueryBuilder;
+  gt(column: string, value: string): QueryBuilder;
+  gte(column: string, value: string): QueryBuilder;
+  lt(column: string, value: string): QueryBuilder;
+  lte(column: string, value: string): QueryBuilder;
+  like(column: string, value: string): QueryBuilder;
+  ilike(column: string, value: string): QueryBuilder;
+  is(column: string, value: string): QueryBuilder;
+  in(column: string, values: string[]): QueryBuilder;
+  /** Negation: ?column=not.eq.value */
+  notEq(column: string, value: string): QueryBuilder;
+  notNeq(column: string, value: string): QueryBuilder;
+  notGt(column: string, value: string): QueryBuilder;
+  notGte(column: string, value: string): QueryBuilder;
+  notLt(column: string, value: string): QueryBuilder;
+  notLte(column: string, value: string): QueryBuilder;
+  notLike(column: string, value: string): QueryBuilder;
+  notIlike(column: string, value: string): QueryBuilder;
+  notIs(column: string, value: string): QueryBuilder;
+  notIn(column: string, values: string[]): QueryBuilder;
+  /** Logical groups: ?or=(status.eq.draft,status.eq.pending) */
+  or(expression: string): QueryBuilder;
+  and(expression: string): QueryBuilder;
+  select(columns: string): QueryBuilder;
+  order(column: string, direction?: 'asc' | 'desc'): QueryBuilder;
+  limit(count: number): QueryBuilder;
+  offset(count: number): QueryBuilder;
+  execute(): Promise<ClientResponse<unknown[]>>;
+  executeWithCount(): Promise<CountResponse<unknown[]>>;
+  single(): Promise<ClientResponse<unknown>>;
+  insert(data: Record<string, unknown>): Promise<ClientResponse<unknown>>;
+  update(data: Record<string, unknown>): Promise<ClientResponse<unknown[]>>;
+  remove(): Promise<ClientResponse<unknown[]>>;
+}
+
+export interface Client {
+  from(table: string): QueryBuilder;
+}
+
+/**
+ * Token refresh deduplication — only one refresh happens at a time.
+ * Concurrent 401s wait for the same refresh promise.
+ */
+let activeRefresh: Promise<string | null> | null = null;
+
+export function createClient(options: ClientOptions): Client {
+  return {
+    from(table: string): QueryBuilder {
+      return createQueryBuilder(options, table);
+    },
+  };
+}
+
+function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder {
+  const filters: Array<[string, string]> = [];
+  let selectParam: string | null = null;
+  let orderParam: string | null = null;
+  let limitParam: number | null = null;
+  let offsetParam: number | null = null;
+
+  const builder: QueryBuilder = {
+    eq(column, value) { filters.push([column, `eq.${value}`]); return builder; },
+    neq(column, value) { filters.push([column, `neq.${value}`]); return builder; },
+    gt(column, value) { filters.push([column, `gt.${value}`]); return builder; },
+    gte(column, value) { filters.push([column, `gte.${value}`]); return builder; },
+    lt(column, value) { filters.push([column, `lt.${value}`]); return builder; },
+    lte(column, value) { filters.push([column, `lte.${value}`]); return builder; },
+    like(column, value) { filters.push([column, `like.${value}`]); return builder; },
+    ilike(column, value) { filters.push([column, `ilike.${value}`]); return builder; },
+    is(column, value) { filters.push([column, `is.${value}`]); return builder; },
+    in(column, values) { filters.push([column, `in.(${values.join(',')})`]); return builder; },
+    notEq(column, value) { filters.push([column, `not.eq.${value}`]); return builder; },
+    notNeq(column, value) { filters.push([column, `not.neq.${value}`]); return builder; },
+    notGt(column, value) { filters.push([column, `not.gt.${value}`]); return builder; },
+    notGte(column, value) { filters.push([column, `not.gte.${value}`]); return builder; },
+    notLt(column, value) { filters.push([column, `not.lt.${value}`]); return builder; },
+    notLte(column, value) { filters.push([column, `not.lte.${value}`]); return builder; },
+    notLike(column, value) { filters.push([column, `not.like.${value}`]); return builder; },
+    notIlike(column, value) { filters.push([column, `not.ilike.${value}`]); return builder; },
+    notIs(column, value) { filters.push([column, `not.is.${value}`]); return builder; },
+    notIn(column, values) { filters.push([column, `not.in.(${values.join(',')})`]); return builder; },
+    or(expression) { filters.push(['or', `(${expression})`]); return builder; },
+    and(expression) { filters.push(['and', `(${expression})`]); return builder; },
+    select(columns) { selectParam = columns; return builder; },
+    order(column, direction = 'asc') { orderParam = `${column}.${direction}`; return builder; },
+    limit(count) { limitParam = count; return builder; },
+    offset(count) { offsetParam = count; return builder; },
+
+    async execute(): Promise<ClientResponse<unknown[]>> {
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam);
+      const headers = await buildHeaders(options);
+      const { response, retried } = await fetchWithRetry(url, { method: 'GET', headers }, options);
+
+      if (retried) return retried as ClientResponse<unknown[]>;
+
+      if (!response.ok) {
+        return { data: null, error: await parseError(response) };
+      }
+
+      const data = await response.json();
+      return { data, error: null };
+    },
+
+    async executeWithCount(): Promise<CountResponse<unknown[]>> {
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam);
+      const headers = await buildHeaders(options);
+      headers['Prefer'] = 'count=exact';
+
+      const { response, retried } = await fetchWithRetry(url, { method: 'GET', headers }, options);
+
+      if (retried) return { ...retried as ClientResponse<unknown[]>, total: 0 };
+
+      if (!response.ok) {
+        return { data: null, error: await parseError(response), total: 0 };
+      }
+
+      const data = await response.json();
+      const total = parseContentRange(response.headers.get('Content-Range'));
+      return { data, error: null, total };
+    },
+
+    async single(): Promise<ClientResponse<unknown>> {
+      const result = await builder.execute();
+
+      if (result.error) return { data: null, error: result.error };
+
+      const rows = result.data as unknown[];
+      if (!rows || rows.length === 0) {
+        return { data: null, error: { status: 406, message: 'No rows returned' } };
+      }
+
+      return { data: rows[0], error: null };
+    },
+
+    async insert(data: Record<string, unknown>): Promise<ClientResponse<unknown>> {
+      const url = buildUrl(options.baseUrl, table, [], null, null, null, null);
+      const headers = await buildHeaders(options);
+      headers['Content-Type'] = 'application/json';
+
+      const { response, retried } = await fetchWithRetry(
+        url,
+        { method: 'POST', headers, body: JSON.stringify(data) },
+        options,
+      );
+
+      if (retried) return retried as ClientResponse<unknown>;
+
+      if (!response.ok) {
+        return { data: null, error: await parseError(response) };
+      }
+
+      const result = await response.json();
+      return { data: result, error: null };
+    },
+
+    async update(data: Record<string, unknown>): Promise<ClientResponse<unknown[]>> {
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, null, null);
+      const headers = await buildHeaders(options);
+      headers['Content-Type'] = 'application/json';
+
+      const { response, retried } = await fetchWithRetry(
+        url,
+        { method: 'PATCH', headers, body: JSON.stringify(data) },
+        options,
+      );
+
+      if (retried) return retried as ClientResponse<unknown[]>;
+
+      if (!response.ok) {
+        return { data: null, error: await parseError(response) };
+      }
+
+      const result = await response.json();
+      return { data: result, error: null };
+    },
+
+    async remove(): Promise<ClientResponse<unknown[]>> {
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, null, null);
+      const headers = await buildHeaders(options);
+
+      const { response, retried } = await fetchWithRetry(
+        url,
+        { method: 'DELETE', headers },
+        options,
+      );
+
+      if (retried) return retried as ClientResponse<unknown[]>;
+
+      if (!response.ok) {
+        return { data: null, error: await parseError(response) };
+      }
+
+      const result = await response.json();
+      return { data: result, error: null };
+    },
+  };
+
+  return builder;
+}
+
+/**
+ * Ensures only one token refresh is in-flight at a time.
+ * Concurrent 401 responses all wait for the same refresh promise.
+ */
+async function deduplicatedRefresh(refreshFn: () => Promise<string | null>): Promise<string | null> {
+  if (activeRefresh) {
+    return activeRefresh;
+  }
+
+  activeRefresh = refreshFn().finally(() => {
+    activeRefresh = null;
+  });
+
+  return activeRefresh;
+}
+
+/**
+ * Fetch with automatic 401 retry using token refresh.
+ * Returns either the final response or a pre-built error result from retry failure.
+ */
+async function fetchWithRetry(
+  url: string,
+  init: RequestInit,
+  options: ClientOptions,
+): Promise<{ response: Response; retried?: never } | { response?: never; retried: ClientResponse<unknown> }> {
+  const response = await fetch(url, init);
+
+  if (response.status === 401 && options.onTokenExpired) {
+    const newToken = await deduplicatedRefresh(options.onTokenExpired);
+    if (newToken) {
+      const retryHeaders = { ...(init.headers as Record<string, string>), 'Authorization': `Bearer ${newToken}` };
+      const retryResponse = await fetch(url, { ...init, headers: retryHeaders });
+
+      if (!retryResponse.ok) {
+        return { retried: { data: null, error: await parseError(retryResponse) } };
+      }
+
+      // Return the successful retry response for the caller to parse
+      return { response: retryResponse };
+    }
+
+    // Refresh failed
+    return { retried: { data: null, error: await parseError(response) } };
+  }
+
+  return { response };
+}
+
+/**
+ * Parse total count from Content-Range header.
+ * Formats: "0-9/42", "* /0", "0-0/*"
+ */
+function parseContentRange(header: string | null): number {
+  if (!header) return 0;
+  const parts = header.split('/');
+  if (parts.length !== 2) return 0;
+  const total = parseInt(parts[1], 10);
+  return isNaN(total) ? 0 : total;
+}
+
+async function parseError(response: Response): Promise<ClientError> {
+  const body = await response.json().catch(() => ({}));
+  return { status: response.status, message: body.message || response.statusText };
+}
+
+function buildUrl(
+  baseUrl: string,
+  table: string,
+  filters: Array<[string, string]>,
+  select: string | null,
+  order: string | null,
+  limit: number | null,
+  offset: number | null,
+): string {
+  const path = `${baseUrl}/${table}`;
+  const base = typeof globalThis.location !== 'undefined' ? globalThis.location.origin : undefined;
+  const url = new URL(path, base);
+
+  for (const [key, value] of filters) {
+    url.searchParams.set(key, value);
+  }
+  if (select) url.searchParams.set('select', select);
+  if (order) url.searchParams.set('order', order);
+  if (limit !== null) url.searchParams.set('limit', String(limit));
+  if (offset !== null) url.searchParams.set('offset', String(offset));
+
+  return url.toString();
+}
+
+async function buildHeaders(options: ClientOptions): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    ...options.headers,
+  };
+
+  if (options.getToken) {
+    const token = await Promise.resolve(options.getToken());
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+  }
+
+  if (options.clientCredentials) {
+    const idHeader = options.clientCredentials.headers?.id ?? 'X-Client-Id';
+    const secretHeader = options.clientCredentials.headers?.secret ?? 'X-Client-Secret';
+    headers[idHeader] = options.clientCredentials.id;
+    headers[secretHeader] = options.clientCredentials.secret;
+  }
+
+  return headers;
+}