cresco-js 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# cresco-js
+
+The official JavaScript / TypeScript client for [CrescoDB](https://crescodb.com) — auth + CRUD over your project's auto-generated REST API. **Zero dependencies** (uses `fetch`), works in the browser and Node 18+.
+
+```bash
+npm install cresco-js
+```
+
+## Quick start
+
+```js
+import { createClient } from 'cresco-js';
+
+const cresco = createClient('http://localhost:3000');
+
+// Auth (when your project has `cresco add auth`)
+await cresco.auth.register('me@example.com', 'secret1');
+// or: await cresco.auth.login('me@example.com', 'secret1');
+
+// Create
+const post = await cresco.from('posts').create({ title: 'Hello', published: true });
+
+// Read — list (thenable: await the builder, or call .list())
+const published = await cresco.from('posts').eq('published', true).limit(10).offset(0);
+const one = await cresco.from('posts').get(post.id);
+
+// Update / replace / delete
+await cresco.from('posts').update(post.id, { title: 'Edited' });   // PATCH
+await cresco.from('posts').replace(post.id, { title: 'New', published: false }); // PUT
+await cresco.from('posts').remove(post.id);
+
+// Bulk insert (transactional)
+await cresco.from('posts').bulk([{ title: 'a' }, { title: 'b' }]);
+```
+
+## Auth
+
+```js
+const { token, user } = await cresco.auth.login('me@example.com', 'secret1');
+cresco.auth.user();            // last-known user, or null
+await cresco.auth.me();        // refetch the current user (GET /auth/me)
+cresco.auth.logout();          // clears the token
+
+// React to sign-in/out (e.g. to update UI)
+const off = cresco.onAuthChange(({ token, user }) => { /* ... */ });
+off(); // unsubscribe
+```
+
+The token is kept in memory and, in the browser, persisted to `localStorage` (key `cresco-token`) so a session survives a reload. In Node it stays in memory unless you pass your own `storage`.
+
+## Options
+
+```js
+createClient('https://api.example.com', {
+  token,        // start signed-in with an existing token
+  apiKey,       // project API key (x-cresco-key) — trusted server-to-server, full access
+  fetch,        // custom fetch (e.g. older Node)
+  storage,      // custom token store, or null to disable persistence
+});
+```
+
+## Row-level security
+
+If a table is configured with a row owner (`access.rowOwner`), the API automatically scopes rows to the signed-in user — `list()` returns only their rows, and reads/writes to others' rows return a `404`. Just sign in and use the table normally.
+
+## Errors
+
+Non-2xx responses throw a `CrescoError` with `.status` and `.body`:
+
+```js
+import { CrescoError } from 'cresco-js';
+try {
+  await cresco.from('posts').get('missing-id');
+} catch (e) {
+  if (e instanceof CrescoError && e.status === 404) { /* not found */ }
+}
+```

package/index.d.ts

@@ -0,0 +1,141 @@
+// Type definitions for cresco-js — the CrescoDB JavaScript client.
+
+export interface CrescoUser {
+  id: string;
+  email: string;
+  role: string;
+  [key: string]: unknown;
+}
+
+export interface AuthResult {
+  token: string;
+  user: CrescoUser;
+}
+
+export interface AuthState {
+  token: string | null;
+  user: CrescoUser | null;
+}
+
+/** A minimal localStorage-like interface for token persistence. */
+export interface CrescoStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface CrescoClientOptions {
+  /** Start signed-in with an existing token. */
+  token?: string | null;
+  /** Project API key (x-cresco-key) for trusted server-to-server access (full access). */
+  apiKey?: string | null;
+  /** Custom fetch implementation (e.g. for older Node). Defaults to global fetch. */
+  fetch?: typeof fetch;
+  /** Token persistence. Defaults to localStorage in the browser, in-memory in Node. Pass null to disable. */
+  storage?: CrescoStorage | null;
+}
+
+export class CrescoError extends Error {
+  name: 'CrescoError';
+  /** HTTP status (0 on a network error). */
+  status: number;
+  /** Parsed response body, when present. */
+  body: unknown;
+  constructor(message: string, status: number, body: unknown);
+}
+
+export interface CrescoAuth {
+  register(email: string, password: string, extra?: Record<string, unknown>): Promise<AuthResult>;
+  login(email: string, password: string): Promise<AuthResult>;
+  /** GET /auth/me — the current user (throws if not signed in). */
+  me(): Promise<CrescoUser>;
+  logout(): void;
+  /** The last-known user (from login/register/me), or null. */
+  user(): CrescoUser | null;
+  /** The current bearer token, or null. */
+  token(): string | null;
+}
+
+/** Fluent query + CRUD for one table. Thenable: awaiting it runs list(). */
+export interface CrescoTable<T = any> extends PromiseLike<T[]> {
+  eq(column: string, value: unknown): CrescoTable<T>;
+  where(column: string, value: unknown): CrescoTable<T>;
+  limit(n: number): CrescoTable<T>;
+  offset(n: number): CrescoTable<T>;
+  list(): Promise<T[]>;
+  get(id: string | number): Promise<T>;
+  create(values: Partial<T>): Promise<T>;
+  bulk(rows: Partial<T>[]): Promise<{ count: number; rows: T[] }>;
+  update(id: string | number, patch: Partial<T>): Promise<T>;
+  replace(id: string | number, values: Partial<T>): Promise<T>;
+  remove(id: string | number): Promise<void>;
+  schema(): Promise<{ schema: { model: string; table: string; fields: unknown[] } }>;
+}
+
+export interface FileMeta {
+  bucket: string;
+  key: string;
+  name: string;
+  size: number;
+  content_type: string;
+  created_at: string;
+  url?: string;
+}
+
+/** Scoped file storage for one bucket. */
+export interface CrescoStorage {
+  list(): Promise<{ bucket: string; public: boolean; objects: FileMeta[] }>;
+  upload(key: string, data: Blob | ArrayBuffer | Uint8Array | string, opts?: { contentType?: string; name?: string }): Promise<FileMeta>;
+  /** Returns the raw Response — call .blob() / .arrayBuffer() / .text(). */
+  download(key: string): Promise<Response>;
+  remove(key: string): Promise<void>;
+  /** Direct object URL (useful for public buckets / <img src>). */
+  url(key: string): string;
+}
+
+/** The row-change verb a realtime event carries. */
+export type ChangeEvent = 'created' | 'updated' | 'deleted';
+
+/** A realtime change pushed over the subscription. */
+export interface ChangePayload<T = any> {
+  type: 'change';
+  event: ChangeEvent;
+  table: string;
+  data: T;
+  at: string;
+}
+
+export interface ChannelOptions {
+  tables?: string | string[] | null;
+  events?: ChangeEvent | ChangeEvent[] | null;
+}
+
+/** A live subscription to row changes (Server-Sent Events; auto-reconnects). */
+export interface CrescoChannel {
+  /** Register a handler for a verb, or '*' for every change. Chainable. */
+  on(verb: ChangeEvent | '*', cb: (payload: ChangePayload) => void): CrescoChannel;
+  onError(cb: (err: CrescoError) => void): CrescoChannel;
+  onReady(cb: (info: { tables: string[] | 'all'; events: string[] | 'all' }) => void): CrescoChannel;
+  /** Open the stream. Keep the returned handle to unsubscribe later. */
+  subscribe(): CrescoChannel;
+  /** Close the stream and stop reconnecting. */
+  unsubscribe(): CrescoChannel;
+}
+
+export interface CrescoClient {
+  readonly baseUrl: string;
+  readonly auth: CrescoAuth;
+  from<T = any>(table: string): CrescoTable<T>;
+  storage(bucket: string): CrescoStorage;
+  /** Subscribe to live row changes. Pass a table name/array, or { tables, events }. */
+  channel(tables?: string | string[] | ChannelOptions | null, events?: ChangeEvent | ChangeEvent[] | null): CrescoChannel;
+  setToken(token: string | null): this;
+  getToken(): string | null;
+  onAuthChange(cb: (state: AuthState) => void): () => void;
+  request(method: string, path: string, opts?: { body?: unknown; query?: Record<string, unknown>; auth?: boolean; headers?: Record<string, string> }): Promise<any>;
+}
+
+export function createClient(baseUrl: string, options?: CrescoClientOptions): CrescoClient;
+
+declare const _default: { createClient: typeof createClient; CrescoError: typeof CrescoError };
+export default _default;

package/index.js

@@ -0,0 +1,333 @@
+// cresco-js — the official JavaScript client for a CrescoDB project's HTTP API.
+// Zero dependencies; works in the browser and in Node 18+ (global fetch). It wraps
+// the auto-generated REST API (/:table CRUD) and the built-in auth (/auth/*).
+//
+//   import { createClient } from 'cresco-js';
+//   const cresco = createClient('http://localhost:3000');
+//   await cresco.auth.login('me@x.dev', 'secret1');
+//   const posts = await cresco.from('posts').eq('published', true).limit(10);
+//   const post  = await cresco.from('posts').create({ title: 'Hello' });
+//
+// Auth tokens are kept in memory and (in the browser) persisted to localStorage,
+// so a signed-in session survives a page reload. Pass `apiKey` for trusted
+// server-to-server access (sends x-cresco-key, full access).
+
+export class CrescoError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'CrescoError';
+    this.status = status;   // HTTP status (0 on a network error)
+    this.body = body;       // parsed response body, if any
+  }
+}
+
+// localStorage when available (browser), else null → token lives only in memory.
+function defaultStorage() {
+  try { if (typeof globalThis !== 'undefined' && globalThis.localStorage) return globalThis.localStorage; } catch { /* access denied */ }
+  return null;
+}
+
+function queryString(params) {
+  if (!params) return '';
+  const parts = [];
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === null) continue;
+    parts.push(encodeURIComponent(k) + '=' + encodeURIComponent(String(v)));
+  }
+  return parts.length ? '?' + parts.join('&') : '';
+}
+
+const STORAGE_KEY = 'cresco-token';
+
+class CrescoClient {
+  constructor(baseUrl, { token = null, apiKey = null, fetch: customFetch, storage } = {}) {
+    if (!baseUrl) throw new Error('createClient(baseUrl): baseUrl is required');
+    this.baseUrl = String(baseUrl).replace(/\/+$/, '');
+    this._apiKey = apiKey || null;
+    this._fetch = customFetch || (typeof globalThis !== 'undefined' ? globalThis.fetch : undefined);
+    if (typeof this._fetch !== 'function') throw new Error('No fetch available — pass options.fetch (e.g. node-fetch) on this runtime');
+    this._fetch = this._fetch.bind(globalThis);
+    this._storage = storage !== undefined ? storage : defaultStorage();
+    this._token = token || (this._storage && this._storage.getItem(STORAGE_KEY)) || null;
+    this._user = null;
+    this._listeners = new Set();
+    this.auth = new CrescoAuth(this);
+  }
+
+  // A scoped query/CRUD builder for one table (resource), e.g. cresco.from('posts').
+  from(table) { return new CrescoTable(this, table); }
+
+  // A scoped file-storage client for one bucket, e.g. cresco.storage('avatars').
+  storage(bucket) { return new CrescoStorage(this, bucket); }
+
+  // A realtime change-feed subscription (step 9). Accepts either an options object
+  // ({ tables, events }) or a tables arg + events arg:
+  //   cresco.channel('posts').on('created', r => …).subscribe()
+  //   cresco.channel({ tables: ['posts','comments'] }).on('*', p => …).subscribe()
+  channel(tablesOrOpts, events) {
+    if (tablesOrOpts && typeof tablesOrOpts === 'object' && !Array.isArray(tablesOrOpts)) return new CrescoChannel(this, tablesOrOpts);
+    return new CrescoChannel(this, { tables: tablesOrOpts || null, events: events || null });
+  }
+
+  // Auth headers for non-JSON requests (file upload/download).
+  _authHeaders() {
+    const h = {};
+    if (this._apiKey) h['x-cresco-key'] = this._apiKey;
+    else if (this._token) h['Authorization'] = 'Bearer ' + this._token;
+    return h;
+  }
+
+  // Token management. setToken(null) signs out. Persisted via storage when present.
+  setToken(token) {
+    this._token = token || null;
+    if (this._storage) {
+      try { if (this._token) this._storage.setItem(STORAGE_KEY, this._token); else this._storage.removeItem(STORAGE_KEY); } catch { /* quota / denied */ }
+    }
+    return this;
+  }
+  getToken() { return this._token; }
+
+  // Subscribe to sign-in/sign-out. Returns an unsubscribe function.
+  onAuthChange(cb) { this._listeners.add(cb); return () => this._listeners.delete(cb); }
+  _emit() { for (const cb of this._listeners) { try { cb({ token: this._token, user: this._user }); } catch { /* listener error */ } } }
+
+  // The single request primitive every method goes through.
+  async request(method, path, { body, query, auth = true, headers = {} } = {}) {
+    const url = this.baseUrl + path + queryString(query);
+    const h = { ...headers };
+    if (body !== undefined) h['Content-Type'] = 'application/json';
+    if (this._apiKey) h['x-cresco-key'] = this._apiKey;          // server-to-server: full access
+    else if (auth && this._token) h['Authorization'] = 'Bearer ' + this._token;
+
+    let res;
+    try {
+      res = await this._fetch(url, { method, headers: h, body: body !== undefined ? JSON.stringify(body) : undefined });
+    } catch (e) {
+      throw new CrescoError(e.message || 'Network request failed', 0, null);
+    }
+
+    let data = null;
+    const text = await res.text();
+    if (text) { try { data = JSON.parse(text); } catch { data = text; } }
+
+    if (!res.ok) {
+      const msg = (data && data.error) || res.statusText || `HTTP ${res.status}`;
+      throw new CrescoError(msg, res.status, data);
+    }
+    return data;
+  }
+}
+
+class CrescoAuth {
+  constructor(client) { this._c = client; }
+
+  async register(email, password, extra = {}) {
+    const d = await this._c.request('POST', '/auth/register', { body: { email, password, ...extra }, auth: false });
+    this._c.setToken(d && d.token); this._c._user = (d && d.user) || null; this._c._emit();
+    return d;
+  }
+  async login(email, password) {
+    const d = await this._c.request('POST', '/auth/login', { body: { email, password }, auth: false });
+    this._c.setToken(d && d.token); this._c._user = (d && d.user) || null; this._c._emit();
+    return d;
+  }
+  // Load the current user from the token (GET /auth/me). Throws if not signed in.
+  async me() {
+    const d = await this._c.request('GET', '/auth/me');
+    this._c._user = (d && d.user) || null;
+    return this._c._user;
+  }
+  logout() { this._c._user = null; this._c.setToken(null); this._c._emit(); }
+
+  user() { return this._c._user; }
+  token() { return this._c.getToken(); }
+}
+
+// Fluent query + CRUD for one resource. It's thenable, so awaiting the builder
+// runs a list() — `await cresco.from('posts').eq('published', true).limit(10)`.
+class CrescoTable {
+  constructor(client, table) {
+    this._c = client;
+    this._path = '/' + encodeURIComponent(table);
+    this._query = {};
+  }
+
+  // ── query options (chainable) ──
+  // CrescoDB's list endpoint supports one equality filter (?where=col:value).
+  eq(column, value) { this._query.where = `${column}:${value}`; return this; }
+  where(column, value) { return this.eq(column, value); }
+  limit(n) { this._query.limit = n; return this; }
+  offset(n) { this._query.offset = n; return this; }
+
+  // ── terminal operations ──
+  list() { return this._c.request('GET', this._path, { query: this._query }); }
+  get(id) { return this._c.request('GET', `${this._path}/${encodeURIComponent(id)}`); }
+  create(values) { return this._c.request('POST', this._path, { body: values }); }
+  bulk(rows) { return this._c.request('POST', `${this._path}/bulk`, { body: rows }); }
+  update(id, patch) { return this._c.request('PATCH', `${this._path}/${encodeURIComponent(id)}`, { body: patch }); }
+  replace(id, values) { return this._c.request('PUT', `${this._path}/${encodeURIComponent(id)}`, { body: values }); }
+  remove(id) { return this._c.request('DELETE', `${this._path}/${encodeURIComponent(id)}`); }
+  schema() { return this._c.request('GET', `${this._path}/schema`); }
+
+  // thenable → `await cresco.from('posts')...` resolves to the list.
+  then(onFulfilled, onRejected) { return this.list().then(onFulfilled, onRejected); }
+  catch(onRejected) { return this.list().catch(onRejected); }
+}
+
+// Scoped file storage for one bucket. Uploads raw bytes (Content-Type preserved);
+// downloads return the Response so you can choose .blob()/.arrayBuffer()/.text().
+class CrescoStorage {
+  constructor(client, bucket) {
+    this._c = client;
+    this._bucket = bucket;
+    this._base = '/storage/' + encodeURIComponent(bucket);
+  }
+  _keyPath(key) { return String(key).split('/').map(encodeURIComponent).join('/'); }
+
+  list() { return this._c.request('GET', this._base); }
+
+  // upload(key, data, { contentType, name }) — data: Blob | ArrayBuffer | Buffer | string.
+  async upload(key, data, { contentType, name } = {}) {
+    const url = this._c.baseUrl + this._base + '/' + this._keyPath(key) + (name ? '?name=' + encodeURIComponent(name) : '');
+    const headers = { ...this._c._authHeaders() };
+    headers['Content-Type'] = contentType || (data && data.type) || 'application/octet-stream';
+    let res;
+    try { res = await this._c._fetch(url, { method: 'PUT', headers, body: data }); }
+    catch (e) { throw new CrescoError(e.message || 'Upload failed', 0, null); }
+    const text = await res.text();
+    let body = null; if (text) { try { body = JSON.parse(text); } catch { body = text; } }
+    if (!res.ok) throw new CrescoError((body && body.error) || res.statusText, res.status, body);
+    return body;
+  }
+
+  // download(key) → the raw Response (caller picks .blob()/.arrayBuffer()/.text()).
+  async download(key) {
+    const url = this._c.baseUrl + this._base + '/' + this._keyPath(key);
+    let res;
+    try { res = await this._c._fetch(url, { headers: this._c._authHeaders() }); }
+    catch (e) { throw new CrescoError(e.message || 'Download failed', 0, null); }
+    if (!res.ok) {
+      let body = null; const t = await res.text(); if (t) { try { body = JSON.parse(t); } catch { body = t; } }
+      throw new CrescoError((body && body.error) || res.statusText, res.status, body);
+    }
+    return res;
+  }
+
+  remove(key) { return this._c.request('DELETE', this._base + '/' + this._keyPath(key)); }
+
+  // Direct URL to an object (useful for public buckets / <img src>).
+  url(key) { return this._c.baseUrl + this._base + '/' + this._keyPath(key); }
+}
+
+// A realtime change-feed subscription over Server-Sent Events. Uses a streaming
+// fetch (not EventSource) so it can send the auth header / API key and run in both
+// the browser and Node 18+. Auto-reconnects with backoff until unsubscribe().
+//
+//   const sub = cresco.channel('posts')
+//     .on('created', (p) => console.log('new post', p.data))
+//     .on('*', (p) => console.log(p.event, p.table, p.data))
+//     .subscribe();
+//   // later: sub.unsubscribe();
+class CrescoChannel {
+  constructor(client, { tables = null, events = null } = {}) {
+    this._c = client;
+    this._tables = tables ? (Array.isArray(tables) ? tables : [tables]) : null;
+    this._events = events ? (Array.isArray(events) ? events : [events]) : null;
+    this._handlers = { '*': new Set() };   // verb → Set<cb>; '*' = every change
+    this._abort = null;
+    this._closed = false;
+    this._onError = null;
+    this._onReady = null;
+  }
+
+  // Register a handler. verb is 'created' | 'updated' | 'deleted' | '*'.
+  on(verb, cb) { (this._handlers[verb] = this._handlers[verb] || new Set()).add(cb); return this; }
+  onError(cb) { this._onError = cb; return this; }
+  onReady(cb) { this._onReady = cb; return this; }  // fired once the server confirms the subscription
+
+  _emit(payload) {
+    const set = this._handlers[payload.event];
+    if (set) for (const cb of set) { try { cb(payload); } catch { /* handler error */ } }
+    for (const cb of this._handlers['*']) { try { cb(payload); } catch { /* handler error */ } }
+  }
+
+  // Open the stream. Returns `this` so you can keep the handle for unsubscribe().
+  subscribe() { this._closed = false; this._run(); return this; }
+
+  // Close the stream and stop reconnecting.
+  unsubscribe() { this._closed = true; if (this._abort) { try { this._abort.abort(); } catch { /* ignore */ } } return this; }
+
+  async _run() {
+    let backoff = 500;
+    while (!this._closed) {
+      try {
+        await this._stream();         // resolves when the server closes the stream
+        backoff = 500;                // clean end → reset backoff before reconnecting
+      } catch (e) {
+        if (this._closed) break;
+        if (this._onError) { try { this._onError(e); } catch { /* ignore */ } }
+      }
+      if (this._closed) break;
+      await new Promise((r) => setTimeout(r, backoff));
+      backoff = Math.min(backoff * 2, 10000);
+    }
+  }
+
+  async _stream() {
+    const q = {};
+    if (this._tables) q.tables = this._tables.join(',');
+    if (this._events) q.events = this._events.join(',');
+    const url = this._c.baseUrl + '/realtime' + queryString(q);
+    const headers = { Accept: 'text/event-stream', ...this._c._authHeaders() };
+
+    this._abort = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    const res = await this._c._fetch(url, { headers, signal: this._abort ? this._abort.signal : undefined });
+    if (!res.ok) {
+      let body = null; try { const t = await res.text(); if (t) body = JSON.parse(t); } catch { /* non-JSON */ }
+      throw new CrescoError((body && body.error) || res.statusText || `HTTP ${res.status}`, res.status, body);
+    }
+    if (!res.body || typeof res.body.getReader !== 'function') {
+      throw new CrescoError('Realtime needs a streaming fetch (res.body.getReader) — not available on this runtime', 0, null);
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    try {
+      while (!this._closed) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        let i;
+        while ((i = buf.indexOf('\n\n')) !== -1) {     // one full SSE frame
+          this._frame(buf.slice(0, i));
+          buf = buf.slice(i + 2);
+        }
+      }
+    } finally {
+      // cancel() rejects when the stream was aborted — swallow it (sync + async).
+      try { const c = reader.cancel(); if (c && c.catch) c.catch(() => {}); } catch { /* ignore */ }
+    }
+  }
+
+  _frame(frame) {
+    let event = 'message';
+    const data = [];
+    for (const line of frame.split('\n')) {
+      if (!line || line[0] === ':') continue;            // blank or comment (heartbeat)
+      if (line.startsWith('event:')) event = line.slice(6).trim();
+      else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
+    }
+    if (!data.length) return;
+    let parsed; try { parsed = JSON.parse(data.join('\n')); } catch { parsed = data.join('\n'); }
+    if (event === 'ready') { if (this._onReady) { try { this._onReady(parsed); } catch { /* ignore */ } } return; }
+    if (event === 'change') this._emit(parsed);
+  }
+}
+
+// Create a CrescoDB client for a project's API base URL.
+export function createClient(baseUrl, options = {}) {
+  return new CrescoClient(baseUrl, options);
+}
+
+export default { createClient, CrescoError };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "cresco-js",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript client for CrescoDB — auth + CRUD over the auto-generated REST API. Zero dependencies (uses fetch).",
+  "type": "module",
+  "main": "index.js",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "crescodb",
+    "client",
+    "sdk",
+    "rest",
+    "database"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}