sqlcrud-client 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# sqlcrud-client
+
+HTTP client library for the [sqlcrud](https://github.com/bnielsen1965/sqlcrud) SQLite REST API. Works in browsers and Node.js (native `fetch`, zero runtime dependencies).
+
+## Installation
+
+```bash
+npm install sqlcrud-client
+```
+
+## Quick Start
+
+```js
+import { SqlCrudClient } from 'sqlcrud-client';
+
+const client = new SqlCrudClient({
+  baseUrl: 'http://localhost:3123',
+  username: 'admin',
+  password: 'password',
+});
+
+// List tables
+const tables = await client.listTables();
+
+// Create a schema
+await client.setSchema('users', {
+  name: { type: 'string', length: 100, primary: true },
+  email: { type: 'string', unique: true },
+  active: { type: 'boolean' },
+});
+
+// Create a record (booleans coerced to 1/0 automatically)
+const user = await client.createRecord('users', {
+  name: 'Alice',
+  email: 'alice@example.com',
+  active: true,
+});
+
+// Query records
+const activeUsers = await client.queryRecords('users', { active: 1 });
+
+// Update a record
+const result = await client.updateRecord('users', { name: 'Alice' }, { email: 'new@example.com' });
+console.log(result.before, result.after);
+
+// Delete records
+await client.deleteRecord('users', { name: 'Alice' });
+```
+
+## Constructor
+
+```js
+new SqlCrudClient(config)
+```
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `baseUrl` | `string` | Yes | sqlcrud server URL (e.g. `'http://localhost:3123'`) |
+| `username` | `string` | No | Username for Basic Auth |
+| `password` | `string` | No | Password for Basic Auth |
+| `headers` | `object` | No | Additional headers sent with every request |
+
+## API Methods
+
+### Schema Management
+
+| Method | HTTP | Description |
+|--------|------|-------------|
+| `listTables()` | `GET /api/tables` | Returns `string[]` of table names |
+| `listModels()` | `GET /api/models` | Returns model info array |
+| `getSchema(model)` | `GET /api/schema/:model` | Returns schema definition object |
+| `setSchema(model, schema)` | `POST /api/schema/:model` | Create or update a schema |
+| `deleteSchema(model)` | `DELETE /api/schema/:model` | Delete schema and drop table |
+
+### Record Operations
+
+| Method | HTTP | Description |
+|--------|------|-------------|
+| `queryRecords(model, params?)` | `GET /api/record/:model` | Query records by field criteria (returns `[]` if no match) |
+| `createRecord(model, data)` | `POST /api/record/:model` | Create a new record |
+| `updateRecord(model, criteria, data)` | `PUT /api/record/:model` | Update a record (criteria must match exactly one row) |
+| `deleteRecord(model, criteria)` | `DELETE /api/record/:model` | Delete records matching criteria |
+
+## Error Handling
+
+All errors extend `SqlCrudError` for easy `instanceof` checking:
+
+```js
+import { SqlCrudError, SqlCrudAuthError, SqlCrudNotFoundError } from 'sqlcrud-client';
+
+try {
+  await client.getSchema('nonexistent');
+} catch (err) {
+  if (err instanceof SqlCrudAuthError) {
+    console.error('Authentication failed');
+  } else if (err instanceof SqlCrudNotFoundError) {
+    console.error('Model not found');
+  } else if (err instanceof SqlCrudError) {
+    console.error('Error:', err.message, 'Status:', err.statusCode);
+  }
+}
+```
+
+| Error Class | When |
+|-------------|------|
+| `SqlCrudError` | Base class for all library errors |
+| `SqlCrudAuthError` | 401 Unauthorized |
+| `SqlCrudNotFoundError` | 404 Not Found |
+| `SqlCrudValidationError` | Client-side validation failure |
+| `SqlCrudServerError` | 5xx server error |
+
+All errors expose `statusCode` (number) and `endpoint` (string).
+
+## Utility Functions
+
+Import standalone (tree-shakeable):
+
+```js
+import { validateSchema, coerceBooleans, FIELD_TYPES } from 'sqlcrud-client/utils';
+```
+
+### Validation
+
+- `validateIdentifier(name, label?)` — Validates model/field names against `^[a-zA-Z_][a-zA-Z0-9_]*$`
+- `validateFieldName(name)` — Validates field names (identifier + reserved name check)
+- `validateSchema(schema)` — Validates a complete schema definition object
+
+### Constants
+
+- `FIELD_TYPES` — Valid schema field types: `'string'`, `'integer'`, `'float'`, `'boolean'`, `'json'`, `'datetime'`, `'time'`
+- `RESERVED_FIELD_NAMES` — Reserved field names: `'model'`, `'schema'`
+- `IDENTIFIER_PATTERN` — Regex: `/^[a-zA-Z_][a-zA-Z0-9_]*$/`
+
+### Helpers
+
+- `coerceBooleans(record)` — Converts `true`/`false` to `1`/`0` in a record (SQLite compatibility; applied automatically by `createRecord` and `updateRecord`)
+- `buildQueryString(params)` — Builds a URL query string from an object
+
+## Features
+
+- **Boolean coercion** — `createRecord` and `updateRecord` automatically convert JavaScript booleans to `1`/`0` for SQLite compatibility. On read, the server coerces `0`/`1` back to `true`/`false`, so you always work with native booleans.
+- **JSON field support** — The sqlcrud server automatically serializes objects and arrays to JSON strings on write and deserializes them on read. Send native JavaScript objects and arrays directly — no manual `JSON.stringify`/`JSON.parse` needed.
+- **Composite primary keys** — Schemas may define multiple fields with `primary: true`; the server creates composite primary key constraints automatically.
+- **Empty query results** — `queryRecords` returns an empty array (`[]`) when no records match, rather than throwing a `SqlCrudNotFoundError`.
+- **Query parameter building** — Record query methods build and encode URL query parameters automatically.
+- **Basic Auth** — Credentials from the constructor are sent as `Authorization: Basic` on every request.
+- **No dependencies** — Uses native `fetch` (Node.js 18+, all modern browsers).
+
+## TypeScript
+
+Type definitions are included. Import normally — your TypeScript compiler will pick up `types.d.ts` automatically via the `exports` field in `package.json`.
+
+```ts
+import { SqlCrudClient, SchemaDefinition, SqlCrudError } from 'sqlcrud-client';
+```
+
+## Requirements
+
+- Node.js >= 18.0.0 or any modern browser with `fetch` support

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "sqlcrud-client",
+  "version": "1.0.0",
+  "description": "HTTP client library for sqlcrud SQLite REST API",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./errors": {
+      "types": "./types.d.ts",
+      "import": "./src/errors.js",
+      "default": "./src/errors.js"
+    },
+    "./utils": {
+      "types": "./types.d.ts",
+      "import": "./src/utils.js",
+      "default": "./src/utils.js"
+    }
+  },
+  "files": ["src/", "types.d.ts", "package.json", "README.md"],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["sqlcrud", "sqlite", "rest", "client", "crud", "node"],
+  "author": "Bryan Nielsen (@bnielsen1965)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bnielsen1965/sqlcrud-client.git"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0"
+  },
+  "sideEffects": false
+}

package/src/client.js

@@ -0,0 +1,223 @@
+import { coerceBooleans, buildQueryString } from './utils.js';
+import {
+  SqlCrudError,
+  SqlCrudAuthError,
+  SqlCrudNotFoundError,
+  SqlCrudServerError,
+} from './errors.js';
+
+/**
+ * HTTP client for the sqlcrud REST API.
+ * Works in browsers and Node.js (native fetch).
+ *
+ * @example
+ * import { SqlCrudClient } from 'sqlcrud-client';
+ *
+ * const client = new SqlCrudClient({
+ *   baseUrl: 'http://localhost:3123',
+ *   username: 'admin',
+ *   password: 'password',
+ * });
+ *
+ * await client.setSchema('users', { name: { type: 'string', primary: true } });
+ * await client.createRecord('users', { name: 'Alice', active: true });
+ */
+export class SqlCrudClient {
+  /**
+   * @param {object} config - Client configuration.
+   * @param {string} config.baseUrl - The base URL of the sqlcrud server (e.g. 'http://localhost:3123').
+   * @param {string} [config.username] - Username for Basic Auth.
+   * @param {string} [config.password] - Password for Basic Auth.
+   * @param {object} [config.headers] - Additional headers to send with every request.
+   */
+  constructor(config) {
+    if (!config?.baseUrl) {
+      throw new TypeError('SqlCrudClient requires a baseUrl');
+    }
+
+    /** @readonly */
+    this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+
+    /** @readonly */
+    this.authHeader =
+      config.username && config.password
+        ? `Basic ${btoa(`${config.username}:${config.password}`)}`
+        : null;
+
+    /** @readonly */
+    this.extraHeaders = config.headers ?? {};
+  }
+
+  // ─────────────────────────────────────────────
+  // Schema Management
+  // ─────────────────────────────────────────────
+
+  /**
+   * List all table names in the database.
+   * @returns {Promise<string[]>} Array of table names.
+   */
+  async listTables() {
+    return this._request('GET', '/api/tables');
+  }
+
+  /**
+   * List all registered models with their schemas.
+   * @returns {Promise<Array<{model: string, schema: string}>>} Array of model info objects.
+   */
+  async listModels() {
+    return this._request('GET', '/api/models');
+  }
+
+  /**
+   * Get the schema definition for a model.
+   * @param {string} model - The model name.
+   * @returns {Promise<object>} The schema definition object.
+   * @throws {SqlCrudNotFoundError} If the model does not exist.
+   */
+  async getSchema(model) {
+    return this._request('GET', `/api/schema/${model}`);
+  }
+
+  /**
+   * Create or update a schema. Creates the underlying SQLite table if new.
+   * @param {string} model - The model name.
+   * @param {object} schema - The schema definition object.
+   */
+  async setSchema(model, schema) {
+    await this._request('POST', `/api/schema/${model}`, { body: schema });
+  }
+
+  /**
+   * Delete a schema and drop its table.
+   * @param {string} model - The model name.
+   */
+  async deleteSchema(model) {
+    await this._request('DELETE', `/api/schema/${model}`);
+  }
+
+  // ─────────────────────────────────────────────
+  // Record Operations
+  // ─────────────────────────────────────────────
+
+  /**
+   * Query records matching field criteria (AND-combined).
+   * @param {string} model - The model name.
+   * @param {object} [params] - Field name → value pairs for WHERE clause.
+   * @returns {Promise<object[]>} Array of matching record objects.
+   */
+  async queryRecords(model, params) {
+    const qs = buildQueryString(params ?? {});
+    return this._request('GET', `/api/record/${model}${qs}`);
+  }
+
+  /**
+   * Create a new record. Boolean values are coerced to 0/1 automatically.
+   * @param {string} model - The model name.
+   * @param {object} data - The record data.
+   * @returns {Promise<object>} The created record as persisted (includes rowid).
+   */
+  async createRecord(model, data) {
+    return this._request('POST', `/api/record/${model}`, {
+      body: coerceBooleans(data),
+    });
+  }
+
+  /**
+   * Update a single record. Criteria must match exactly one row.
+   * @param {string} model - The model name.
+   * @param {object} criteria - Field name → value pairs to identify the target record.
+   * @param {object} data - The updated field values.
+   * @returns {Promise<{before: object, after: object}>} The record before and after the update.
+   */
+  async updateRecord(model, criteria, data) {
+    const qs = buildQueryString(criteria);
+    return this._request('PUT', `/api/record/${model}${qs}`, {
+      body: coerceBooleans(data),
+    });
+  }
+
+  /**
+   * Delete records matching field criteria (deletes all matches).
+   * @param {string} model - The model name.
+   * @param {object} criteria - Field name → value pairs for WHERE clause.
+   */
+  async deleteRecord(model, criteria) {
+    const qs = buildQueryString(criteria);
+    await this._request('DELETE', `/api/record/${model}${qs}`);
+  }
+
+  // ─────────────────────────────────────────────
+  // Internal Helpers
+  // ─────────────────────────────────────────────
+
+  /**
+   * Build request headers for a given method and body presence.
+   * @param {string} method - HTTP method.
+   * @param {boolean} hasBody - Whether the request has a body.
+   * @returns {object} Headers object.
+   * @private
+   */
+  _buildHeaders(method, hasBody) {
+    const headers = {
+      Accept: 'application/json',
+      ...this.extraHeaders,
+    };
+    if (this.authHeader) {
+      headers['Authorization'] = this.authHeader;
+    }
+    if (hasBody) {
+      headers['Content-Type'] = 'application/json';
+    }
+    return headers;
+  }
+
+  /**
+   * Execute an HTTP request and handle responses/errors.
+   * @param {string} method - HTTP method.
+   * @param {string} path - API path (relative to baseUrl).
+   * @param {object} [options] - Request options.
+   * @param {object} [options.body] - Request body (will be JSON-stringified).
+   * @returns {Promise<any>} Parsed JSON response body.
+   * @throws {SqlCrudError} On HTTP errors.
+   * @private
+   */
+  async _request(method, path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const hasBody = options.body !== undefined;
+    const headers = this._buildHeaders(method, hasBody);
+
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: hasBody ? JSON.stringify(options.body) : undefined,
+    });
+
+    const body = await response.json();
+
+    if (!response.ok) {
+      const errorDetails = typeof body === 'object' && body !== null ? body : undefined;
+
+      if (response.status === 401) {
+        throw new SqlCrudAuthError(path, errorDetails);
+      }
+      if (response.status === 404) {
+        const model = decodeURIComponent(path.split('/').pop() ?? path);
+        throw new SqlCrudNotFoundError(model, path);
+      }
+      if (response.status >= 500) {
+        throw new SqlCrudServerError(path, response.status, errorDetails);
+      }
+
+      // Other errors (400, etc.)
+      const message =
+        typeof body === 'object' && body?.error ? body.error : `HTTP ${response.status}`;
+      throw new SqlCrudError(message, {
+        statusCode: response.status,
+        endpoint: path,
+        details: errorDetails,
+      });
+    }
+
+    return body;
+  }
+}

package/src/errors.js

@@ -0,0 +1,77 @@
+/**
+ * Base error class for all sqlcrud client errors.
+ * All library errors extend this class for easy instanceof checking.
+ */
+export class SqlCrudError extends Error {
+  /**
+   * @param {string} message - The error message.
+   * @param {object} [options] - Optional error details.
+   * @param {number} [options.statusCode] - HTTP status code.
+   * @param {string} [options.endpoint] - The API endpoint that failed.
+   * @param {object} [options.details] - Additional error details from the server.
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'SqlCrudError';
+    this.statusCode = options.statusCode;
+    this.endpoint = options.endpoint;
+    this.details = options.details;
+  }
+}
+
+/**
+ * Thrown when the server returns a 401 Unauthorized response.
+ */
+export class SqlCrudAuthError extends SqlCrudError {
+  /**
+   * @param {string} endpoint - The API endpoint that failed.
+   * @param {object} [details] - Server error details.
+   */
+  constructor(endpoint, details) {
+    super(`Authentication failed for ${endpoint}`, { statusCode: 401, endpoint, details });
+    this.name = 'SqlCrudAuthError';
+  }
+}
+
+/**
+ * Thrown when the server returns a 404 Not Found response.
+ */
+export class SqlCrudNotFoundError extends SqlCrudError {
+  /**
+   * @param {string} model - The model name that was not found.
+   * @param {string} endpoint - The API endpoint that failed.
+   */
+  constructor(model, endpoint) {
+    super(`Model "${model}" not found at ${endpoint}`, { statusCode: 404, endpoint });
+    this.name = 'SqlCrudNotFoundError';
+  }
+}
+
+/**
+ * Thrown when client-side validation fails (invalid schema, bad identifier, etc.).
+ */
+export class SqlCrudValidationError extends SqlCrudError {
+  /**
+   * @param {string} message - The validation error message.
+   * @param {object} [details] - Additional validation details.
+   */
+  constructor(message, details) {
+    super(`Validation error: ${message}`, { statusCode: 400, details });
+    this.name = 'SqlCrudValidationError';
+  }
+}
+
+/**
+ * Thrown when the server returns a 5xx error response.
+ */
+export class SqlCrudServerError extends SqlCrudError {
+  /**
+   * @param {string} endpoint - The API endpoint that failed.
+   * @param {number} statusCode - The HTTP 5xx status code.
+   * @param {object} [details] - Server error details.
+   */
+  constructor(endpoint, statusCode, details) {
+    super(`Server error (${statusCode}) at ${endpoint}`, { statusCode, endpoint, details });
+    this.name = 'SqlCrudServerError';
+  }
+}

package/src/index.js

@@ -0,0 +1,23 @@
+// SqlCrudClient (main export)
+export { SqlCrudClient } from './client.js';
+
+// Error classes
+export {
+  SqlCrudError,
+  SqlCrudAuthError,
+  SqlCrudNotFoundError,
+  SqlCrudValidationError,
+  SqlCrudServerError,
+} from './errors.js';
+
+// Utility functions and constants
+export {
+  FIELD_TYPES,
+  RESERVED_FIELD_NAMES,
+  IDENTIFIER_PATTERN,
+  validateIdentifier,
+  validateFieldName,
+  validateSchema,
+  coerceBooleans,
+  buildQueryString,
+} from './utils.js';

package/src/utils.js

@@ -0,0 +1,119 @@
+import { SqlCrudValidationError } from './errors.js';
+
+/**
+ * Valid schema field types.
+ * @readonly
+ * @type {readonly ['string', 'integer', 'float', 'boolean', 'json', 'datetime', 'time']}
+ */
+export const FIELD_TYPES = ['string', 'integer', 'float', 'boolean', 'json', 'datetime', 'time'];
+
+/**
+ * Field names reserved by sqlcrud (cannot be used in user schemas).
+ * @readonly
+ * @type {readonly ['model', 'schema']}
+ */
+export const RESERVED_FIELD_NAMES = ['model', 'schema'];
+
+/**
+ * Pattern for valid SQL identifiers (model and field names).
+ * @readonly
+ * @type {RegExp}
+ */
+export const IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/**
+ * Validates that a name matches SQL identifier conventions.
+ * @param {string} name - The name to validate.
+ * @param {string} [label='Identifier'] - Human-readable label for error messages.
+ * @throws {SqlCrudValidationError}
+ */
+export function validateIdentifier(name, label = 'Identifier') {
+  if (typeof name !== 'string' || !IDENTIFIER_PATTERN.test(name)) {
+    throw new SqlCrudValidationError(
+      `${label} "${name}" must match ${IDENTIFIER_PATTERN.source}`
+    );
+  }
+}
+
+/**
+ * Validates a field name (identifier rules + reserved names).
+ * @param {string} name - The field name to validate.
+ * @throws {SqlCrudValidationError}
+ */
+export function validateFieldName(name) {
+  validateIdentifier(name, 'Field name');
+  if (RESERVED_FIELD_NAMES.includes(name)) {
+    throw new SqlCrudValidationError(`Field name "${name}" is reserved`);
+  }
+}
+
+/**
+ * Validates a complete schema definition object.
+ * @param {object} schema - The schema to validate.
+ * @throws {SqlCrudValidationError}
+ */
+export function validateSchema(schema) {
+  if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) {
+    throw new SqlCrudValidationError('Schema must be a JSON object');
+  }
+
+  for (const [fieldName, def] of Object.entries(schema)) {
+    validateFieldName(fieldName);
+
+    if (typeof def !== 'object' || def === null || Array.isArray(def)) {
+      throw new SqlCrudValidationError(`Field "${fieldName}" definition must be a non-null object`);
+    }
+
+    if (!def.type || !FIELD_TYPES.includes(def.type)) {
+      throw new SqlCrudValidationError(
+        `Field "${fieldName}" must have a valid type from [${FIELD_TYPES.join(', ')}]`
+      );
+    }
+
+    if (def.length !== undefined) {
+      if (def.type !== 'string') {
+        throw new SqlCrudValidationError(`Field "${fieldName}" length is only valid for string types`);
+      }
+      if (typeof def.length !== 'number' || def.length < 1) {
+        throw new SqlCrudValidationError(`Field "${fieldName}" length must be a positive number`);
+      }
+    }
+
+    for (const attr of ['unique', 'primary', 'notnull']) {
+      if (def[attr] !== undefined && typeof def[attr] !== 'boolean') {
+        throw new SqlCrudValidationError(`Field "${fieldName}" '${attr}' must be a boolean`);
+      }
+    }
+  }
+}
+
+/**
+ * Coerces boolean values in a record to 0/1 (SQLite compatibility).
+ * Returns a new object; does not mutate the input.
+ * @param {object} record - The record data.
+ * @returns {object} A new object with booleans coerced.
+ */
+export function coerceBooleans(record) {
+  const result = {};
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = typeof value === 'boolean' ? (value ? 1 : 0) : value;
+  }
+  return result;
+}
+
+/**
+ * Converts a params object into a URL query string fragment.
+ * Filters out null and undefined values.
+ * @param {object} params - Key-value pairs for query parameters.
+ * @returns {string} Query string starting with '?' or empty string.
+ */
+export function buildQueryString(params) {
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== null && value !== undefined) {
+      searchParams.set(key, String(value));
+    }
+  }
+  const qs = searchParams.toString();
+  return qs ? `?${qs}` : '';
+}

package/types.d.ts

@@ -0,0 +1,143 @@
+// ─────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────
+
+export type FieldType =
+  | 'string'
+  | 'integer'
+  | 'float'
+  | 'boolean'
+  | 'json'
+  | 'datetime'
+  | 'time';
+
+export interface FieldDefinition {
+  type: FieldType;
+  length?: number;
+  unique?: boolean;
+  primary?: boolean;
+  notnull?: boolean;
+}
+
+export type SchemaDefinition = Record<string, FieldDefinition>;
+
+export interface ModelInfo {
+  model: string;
+  schema: string;
+}
+
+export type RecordData = Record<string, unknown>;
+
+export interface UpdateResponse {
+  before: RecordData;
+  after: RecordData;
+}
+
+export type QueryParams = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
+
+export interface SqlCrudClientConfig {
+  baseUrl: string;
+  username?: string;
+  password?: string;
+  headers?: Record<string, string>;
+}
+
+// ─────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────
+
+export const FIELD_TYPES: readonly FieldType[];
+export const RESERVED_FIELD_NAMES: readonly ['model', 'schema'];
+export const IDENTIFIER_PATTERN: RegExp;
+
+// ─────────────────────────────────────────────
+// Utility Functions
+// ─────────────────────────────────────────────
+
+export function validateIdentifier(
+  name: string,
+  label?: string
+): void;
+
+export function validateFieldName(name: string): void;
+
+export function validateSchema(schema: unknown): void;
+
+export function coerceBooleans(record: RecordData): RecordData;
+
+export function buildQueryString(params: QueryParams): string;
+
+// ─────────────────────────────────────────────
+// Errors
+// ─────────────────────────────────────────────
+
+export class SqlCrudError extends Error {
+  constructor(message: string, options?: {
+    statusCode?: number;
+    endpoint?: string;
+    details?: Record<string, unknown>;
+  });
+  name: 'SqlCrudError';
+  statusCode?: number;
+  endpoint?: string;
+  details?: Record<string, unknown>;
+}
+
+export class SqlCrudAuthError extends SqlCrudError {
+  constructor(endpoint?: string, details?: Record<string, unknown>);
+  name: 'SqlCrudAuthError';
+}
+
+export class SqlCrudNotFoundError extends SqlCrudError {
+  constructor(model: string, endpoint: string);
+  name: 'SqlCrudNotFoundError';
+}
+
+export class SqlCrudValidationError extends SqlCrudError {
+  constructor(message: string, details?: Record<string, unknown>);
+  name: 'SqlCrudValidationError';
+}
+
+export class SqlCrudServerError extends SqlCrudError {
+  constructor(
+    endpoint: string,
+    statusCode: number,
+    details?: Record<string, unknown>
+  );
+  name: 'SqlCrudServerError';
+}
+
+// ─────────────────────────────────────────────
+// SqlCrudClient
+// ─────────────────────────────────────────────
+
+export class SqlCrudClient {
+  constructor(config: SqlCrudClientConfig);
+
+  readonly baseUrl: string;
+  readonly authHeader: string | null;
+  readonly extraHeaders: Record<string, string>;
+
+  // Schema management
+  listTables(): Promise<string[]>;
+  listModels(): Promise<ModelInfo[]>;
+  getSchema(model: string): Promise<SchemaDefinition>;
+  setSchema(model: string, schema: SchemaDefinition): Promise<void>;
+  deleteSchema(model: string): Promise<void>;
+
+  // Record operations
+  queryRecords(
+    model: string,
+    params?: QueryParams
+  ): Promise<RecordData[]>;
+  createRecord(model: string, data: RecordData): Promise<RecordData>;
+  updateRecord(
+    model: string,
+    criteria: QueryParams,
+    data: RecordData
+  ): Promise<UpdateResponse>;
+  deleteRecord(model: string, criteria: QueryParams): Promise<void>;
+}