hydrousdb 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HydrousDB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,686 @@
+# hydrousdb
+
+> **Official TypeScript SDK for [HydrousDB](https://db-api-82687684612.us-central1.run.app)**
+> — a cloud-native record store with built-in authentication, batch operations, analytics, and cursor-based pagination.
+
+[![npm version](https://img.shields.io/npm/v/hydrousdb)](https://npmjs.com/package/hydrousdb)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Framework Guides](#framework-guides)
+  - [Next.js (App Router)](#nextjs-app-router)
+  - [Next.js (Pages Router)](#nextjs-pages-router)
+  - [Vue 3 / Nuxt 3](#vue-3--nuxt-3)
+  - [React (Vite / CRA)](#react-vite--cra)
+  - [Node.js / Express](#nodejs--express)
+- [API Reference](#api-reference)
+  - [createClient](#createclient)
+  - [Records](#records)
+  - [Auth](#auth)
+  - [Analytics](#analytics)
+- [Error Handling](#error-handling)
+- [Pagination](#pagination)
+- [TypeScript](#typescript)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- ✅ **Full TypeScript** — every method and response is fully typed
+- ✅ **Modular** — import only what you need (`hydrousdb/records`, `hydrousdb/auth`, `hydrousdb/analytics`)
+- ✅ **Tree-shakeable** — ships ESM + CJS with dual exports
+- ✅ **Auto-retry** — retries on transient 5xx / network errors with linear back-off
+- ✅ **Timeout control** — configurable per-client request timeout
+- ✅ **Cursor pagination helpers** — `queryAll()` / `listAllUsers()` handle cursor following for you
+- ✅ **Zero dependencies** — uses the native `fetch` API (Node 18+, all modern browsers)
+
+---
+
+## Installation
+
+```bash
+npm install hydrousdb
+# or
+pnpm add hydrousdb
+# or
+yarn add hydrousdb
+```
+
+> **Node.js ≥ 18** is required (uses native `fetch`). For Node 16/17, polyfill `fetch` with `node-fetch` or `undici`.
+
+---
+
+## Quick Start
+
+```ts
+import { createClient } from 'hydrousdb';
+
+const db = createClient({
+  apiKey:    'your-api-key',
+  bucketKey: 'your-bucket-key',
+});
+
+// Insert a record
+const { data, meta } = await db.records.insert({
+  values: { name: 'Alice', score: 99 },
+  queryableFields: ['name'],
+});
+console.log('Created record:', meta.id);
+
+// Query records
+const { data: records } = await db.records.query({
+  filters: [{ field: 'score', op: '>=', value: 90 }],
+  limit: 20,
+});
+
+// Auth — sign a user in
+const { data: user, session } = await db.auth.signIn({
+  email: 'alice@example.com',
+  password: 'Str0ng@Pass!',
+});
+```
+
+---
+
+## Framework Guides
+
+### Next.js (App Router)
+
+**1. Create a shared client singleton**
+
+```ts
+// lib/db.ts
+import { createClient } from 'hydrousdb';
+
+// The client is re-used across all server components in the same process
+export const db = createClient({
+  apiKey:    process.env.HYDROUS_API_KEY!,
+  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+});
+```
+
+**2. Use in a Server Component**
+
+```tsx
+// app/products/page.tsx
+import { db } from '@/lib/db';
+
+export default async function ProductsPage() {
+  const { data: products } = await db.records.query({
+    filters: [{ field: 'category', op: '==', value: 'shoes' }],
+    limit: 24,
+    sortOrder: 'desc',
+  });
+
+  return (
+    <ul>
+      {products.map(p => (
+        <li key={p.id}>{String(p.name)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**3. Use in a Route Handler**
+
+```ts
+// app/api/records/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { HydrousError } from 'hydrousdb';
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const result = await db.records.insert({
+      values: body,
+      queryableFields: ['email', 'name'],
+    });
+    return NextResponse.json(result, { status: 201 });
+  } catch (err) {
+    if (err instanceof HydrousError) {
+      return NextResponse.json({ error: err.message }, { status: err.status });
+    }
+    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+  }
+}
+```
+
+**4. Auth middleware example**
+
+```ts
+// middleware.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+
+export async function middleware(req: NextRequest) {
+  const sessionId = req.cookies.get('sessionId')?.value;
+  if (!sessionId) return NextResponse.redirect(new URL('/login', req.url));
+
+  try {
+    await db.auth.validateSession(sessionId);
+    return NextResponse.next();
+  } catch {
+    return NextResponse.redirect(new URL('/login', req.url));
+  }
+}
+
+export const config = { matcher: ['/dashboard/:path*'] };
+```
+
+**5. Environment variables**
+
+```env
+# .env.local
+HYDROUS_API_KEY=your-api-key
+HYDROUS_BUCKET_KEY=your-bucket-key
+```
+
+---
+
+### Next.js (Pages Router)
+
+```ts
+// pages/api/records.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { createClient, HydrousError } from 'hydrousdb';
+
+const db = createClient({
+  apiKey:    process.env.HYDROUS_API_KEY!,
+  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+});
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method === 'GET') {
+    try {
+      const result = await db.records.query({ limit: 50 });
+      return res.status(200).json(result);
+    } catch (err) {
+      if (err instanceof HydrousError) return res.status(err.status).json({ error: err.message });
+      return res.status(500).json({ error: 'Internal Server Error' });
+    }
+  }
+  res.setHeader('Allow', ['GET']);
+  res.status(405).end();
+}
+```
+
+---
+
+### Vue 3 / Nuxt 3
+
+**Nuxt 3 — plugin**
+
+```ts
+// plugins/hydrousdb.ts
+import { createClient } from 'hydrousdb';
+
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig();
+
+  const db = createClient({
+    apiKey:    config.hydrousApiKey as string,
+    bucketKey: config.hydrousBucketKey as string,
+  });
+
+  return { provide: { db } };
+});
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  runtimeConfig: {
+    hydrousApiKey:    '',  // Set via NUXT_HYDROUS_API_KEY env var
+    hydrousBucketKey: '',  // Set via NUXT_HYDROUS_BUCKET_KEY env var
+  },
+});
+```
+
+**Usage in a component**
+
+```vue
+<script setup lang="ts">
+const { $db } = useNuxtApp();
+
+const { data: records, pending } = await useAsyncData('records', () =>
+  $db.records.query({ limit: 20 })
+);
+</script>
+
+<template>
+  <div v-if="pending">Loading…</div>
+  <ul v-else>
+    <li v-for="r in records?.data" :key="r.id">{{ r.name }}</li>
+  </ul>
+</template>
+```
+
+**Vue 3 standalone — composable**
+
+```ts
+// composables/useHydrous.ts
+import { createClient } from 'hydrousdb';
+
+const db = createClient({
+  apiKey:    import.meta.env.VITE_HYDROUS_API_KEY,
+  bucketKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
+});
+
+export function useHydrous() {
+  return db;
+}
+```
+
+---
+
+### React (Vite / CRA)
+
+```tsx
+// src/hooks/useRecords.ts
+import { useEffect, useState } from 'react';
+import { createClient, HydrousRecord, HydrousError } from 'hydrousdb';
+
+const db = createClient({
+  apiKey:    import.meta.env.VITE_HYDROUS_API_KEY,
+  bucketKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
+});
+
+export function useRecords(limit = 20) {
+  const [records, setRecords] = useState<HydrousRecord[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError]     = useState<string | null>(null);
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    db.records.query({ limit }, { signal: controller.signal })
+      .then(r  => setRecords(r.data))
+      .catch(e => { if (!(e instanceof DOMException)) setError(String(e)); })
+      .finally(() => setLoading(false));
+
+    return () => controller.abort();
+  }, [limit]);
+
+  return { records, loading, error };
+}
+```
+
+---
+
+### Node.js / Express
+
+```ts
+// server.ts
+import express from 'express';
+import { createClient, HydrousError } from 'hydrousdb';
+
+const db  = createClient({
+  apiKey:    process.env.HYDROUS_API_KEY!,
+  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+});
+const app = express();
+app.use(express.json());
+
+app.get('/records', async (req, res) => {
+  try {
+    const result = await db.records.query({ limit: 50 });
+    res.json(result);
+  } catch (err) {
+    if (err instanceof HydrousError) return res.status(err.status).json({ error: err.message });
+    res.status(500).json({ error: 'Internal Server Error' });
+  }
+});
+
+app.listen(3000, () => console.log('Listening on :3000'));
+```
+
+---
+
+## API Reference
+
+### `createClient`
+
+```ts
+import { createClient } from 'hydrousdb';
+
+const db = createClient({
+  apiKey:    string,           // required — your HydrousDB API key
+  bucketKey: string,           // required — your bucket identifier
+  baseUrl?:  string,           // override API base URL
+  timeout?:  number,           // request timeout in ms (default: 30_000)
+  retries?:  number,           // retries on network/5xx errors (default: 2)
+});
+```
+
+---
+
+### Records
+
+All methods live on `db.records`.
+
+| Method | Description |
+|---|---|
+| `get(recordId, opts?)` | Fetch a single record |
+| `getSnapshot(recordId, generation, opts?)` | Fetch a historical version |
+| `query(opts?)` | Query a collection with filters / pagination |
+| `queryAll(opts?)` | Fetch all pages automatically |
+| `insert(payload, opts?)` | Create a new record |
+| `update(payload, opts?)` | Update an existing record |
+| `delete(recordId, opts?)` | Delete a record |
+| `exists(recordId, opts?)` | HEAD check — returns metadata or `null` |
+| `batchInsert(payload, opts?)` | Insert up to 500 records |
+| `batchUpdate(payload, opts?)` | Update up to 500 records |
+| `batchDelete(payload, opts?)` | Delete up to 500 records |
+
+#### `db.records.get(recordId, options?)`
+
+```ts
+const { data, history } = await db.records.get('rec_abc', { showHistory: true });
+```
+
+#### `db.records.query(options?)`
+
+```ts
+const { data, meta } = await db.records.query({
+  filters:   [{ field: 'status', op: '==', value: 'active' }],
+  timeScope: '30d',
+  sortOrder: 'desc',
+  limit:     50,
+  cursor:    meta.nextCursor ?? undefined, // for pagination
+  fields:    'id,name,status',            // select specific fields
+});
+```
+
+**Filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`
+**Max 3 filters per query.**
+
+#### `db.records.insert(payload)`
+
+```ts
+const { data, meta } = await db.records.insert({
+  values: { name: 'Alice', role: 'admin', score: 100 },
+  queryableFields: ['name', 'role'],   // fields you want to filter by later
+  userEmail: 'system@example.com',
+});
+// meta.id — the new record's ID
+```
+
+#### `db.records.update(payload)`
+
+```ts
+await db.records.update({
+  recordId: 'rec_abc',
+  values:   { score: 150 },
+  track_record_history: true,  // snapshot the previous version
+  reason: 'Manual score adjustment',
+});
+```
+
+#### `db.records.batchInsert(payload)`
+
+```ts
+const result = await db.records.batchInsert({
+  records: [
+    { name: 'Alice', score: 99 },
+    { name: 'Bob',   score: 82 },
+  ],
+  queryableFields: ['name'],
+  userEmail: 'import@example.com',
+});
+// result.meta.failed — number of records that failed
+```
+
+---
+
+### Auth
+
+All methods live on `db.auth`.
+
+| Method | Description |
+|---|---|
+| `signUp(payload, opts?)` | Register a new user |
+| `signIn(payload, opts?)` | Authenticate with email + password |
+| `signOut(payload, opts?)` | Revoke session(s) |
+| `validateSession(sessionId, opts?)` | Verify a session is valid |
+| `refreshSession(refreshToken, opts?)` | Rotate session using refresh token |
+| `getUser(userId, opts?)` | Fetch user by ID |
+| `listUsers(opts?)` | Paginated user list |
+| `listAllUsers(opts?)` | All users (auto-paginates) |
+| `updateUser(payload, opts?)` | Update user profile |
+| `deleteUser(userId, opts?)` | Soft-delete a user |
+| `changePassword(payload, opts?)` | Change password (requires old password) |
+| `requestPasswordReset(payload, opts?)` | Trigger reset email |
+| `confirmPasswordReset(payload, opts?)` | Confirm reset with token |
+| `requestEmailVerification(payload, opts?)` | Trigger verification email |
+| `confirmEmailVerification(payload, opts?)` | Confirm email with token |
+| `lockAccount(payload, opts?)` | Lock account for a duration |
+| `unlockAccount(userId, opts?)` | Unlock account |
+
+#### Auth flow example
+
+```ts
+// 1. Sign up
+const { data: user, session } = await db.auth.signUp({
+  email:    'alice@example.com',
+  password: 'Str0ng@Pass!',
+  fullName: 'Alice Smith',
+});
+
+// 2. Store session tokens (e.g. in a cookie or localStorage)
+const { sessionId, refreshToken, expiresAt } = session;
+
+// 3. On each request, validate the session
+const { data: currentUser } = await db.auth.validateSession(sessionId);
+
+// 4. Before session expires, refresh it
+const { session: newSession } = await db.auth.refreshSession(refreshToken);
+
+// 5. Sign out
+await db.auth.signOut({ sessionId });
+```
+
+---
+
+### Analytics
+
+All methods live on `db.analytics`. Every method maps to a BigQuery-backed analytics query. The server `queryType` string each method sends is noted for reference.
+
+| Method | Server `queryType` | Description |
+|---|---|---|
+| `count(opts?)` | `"count"` | Total record count |
+| `distribution(field, opts?)` | `"distribution"` | Value histogram for a field |
+| `sum(field, opts?)` | `"sum"` | Sum a numeric field, with optional group-by |
+| `timeSeries(opts?)` | `"timeSeries"` | Record count over time |
+| `fieldTimeSeries(field, opts?)` | `"fieldTimeSeries"` | Numeric field aggregated over time |
+| `topN(field, n, opts?)` | `"topN"` | Top N field values by frequency |
+| `stats(field, opts?)` | `"stats"` | min/max/avg/stddev/p50/p90/p99 |
+| `records(opts?)` | `"records"` | Filtered + paginated raw records |
+| `multiMetric(metrics, opts?)` | `"multiMetric"` | Multiple aggregations in one call |
+| `storageStats(opts?)` | `"storageStats"` | Bucket storage usage |
+| `crossBucket(opts)` | `"crossBucket"` | Compare metric across buckets |
+| `query(payload, opts?)` | any | Raw query — full control |
+
+#### Date ranges
+
+All analytics methods accept a `dateRange` option:
+
+```ts
+// Scope to a specific date window
+const dateRange = { startDate: '2025-01-01', endDate: '2025-12-31' };
+
+// Or scope to a year / month / day
+const dateRange = { year: '2025', month: '03' };
+```
+
+#### Examples
+
+```ts
+// Total records
+const { data } = await db.analytics.count();
+console.log(data.count);
+
+// Status breakdown
+const { data } = await db.analytics.distribution('status');
+// [{ value: 'active', count: 80 }, { value: 'archived', count: 20 }]
+
+// Monthly revenue for Q1
+const { data } = await db.analytics.sum('amount', {
+  groupBy: 'region',
+  dateRange: { startDate: '2025-01-01', endDate: '2025-03-31' },
+});
+
+// Daily signups this week
+const { data } = await db.analytics.timeSeries({
+  granularity: 'day',
+  dateRange: { startDate: '2025-03-01' },
+});
+
+// Score percentiles
+const { data } = await db.analytics.stats('score');
+console.log(data.avg, data.p90, data.p99);
+
+// Top 5 countries
+const { data } = await db.analytics.topN('country', 5);
+
+// Dashboard stats — one round-trip for multiple metrics
+const { data } = await db.analytics.multiMetric([
+  { name: 'totalRevenue', field: 'amount',  aggregation: 'sum' },
+  { name: 'avgScore',     field: 'score',   aggregation: 'avg' },
+  { name: 'userCount',    field: 'userId',  aggregation: 'count' },
+]);
+console.log(data.totalRevenue, data.avgScore);
+
+// Storage usage
+const { data } = await db.analytics.storageStats();
+console.log(data.totalRecords, data.totalBytes);
+
+// Cross-bucket revenue comparison
+const { data } = await db.analytics.crossBucket({
+  bucketKeys:  ['sales-2024', 'sales-2025'],
+  field:       'amount',
+  aggregation: 'sum',
+});
+
+// Raw records with filters (supports: == != > < >= <= CONTAINS)
+const { data } = await db.analytics.records({
+  filters: [{ field: 'role', op: '==', value: 'admin' }],
+  selectFields: ['email', 'createdAt'],
+  limit: 50,
+  offset: 0,
+});
+console.log(data.data, data.hasMore);
+```
+
+---
+
+## Error Handling
+
+The SDK throws typed errors you can `instanceof` check:
+
+```ts
+import { HydrousError, HydrousNetworkError, HydrousTimeoutError } from 'hydrousdb';
+
+try {
+  await db.records.get('rec_does_not_exist');
+} catch (err) {
+  if (err instanceof HydrousError) {
+    console.error(err.message);   // human-readable message
+    console.error(err.status);    // HTTP status code (e.g. 404)
+    console.error(err.code);      // machine-readable code (e.g. 'NOT_FOUND')
+    console.error(err.details);   // validation error details array
+    console.error(err.requestId); // server request ID for support
+  } else if (err instanceof HydrousTimeoutError) {
+    console.error('Request timed out');
+  } else if (err instanceof HydrousNetworkError) {
+    console.error('Network failure:', err.cause);
+  }
+}
+```
+
+---
+
+## Pagination
+
+HydrousDB uses opaque cursor strings for pagination.
+
+```ts
+// Manual pagination
+let cursor: string | null = null;
+
+do {
+  const { data, meta } = await db.records.query({
+    limit:  100,
+    cursor: cursor ?? undefined,
+  });
+
+  processBatch(data);
+  cursor = meta.nextCursor;
+} while (cursor);
+
+// — OR — let the SDK handle it for you
+const allRecords = await db.records.queryAll({
+  filters: [{ field: 'status', op: '==', value: 'active' }],
+});
+```
+
+---
+
+## TypeScript
+
+All types are exported from the root package:
+
+```ts
+import type {
+  HydrousRecord,
+  QueryOptions,
+  InsertRecordPayload,
+  AuthUser,
+  SessionInfo,
+  HydrousConfig,
+  Filter,
+} from 'hydrousdb';
+```
+
+You can also use the generic `query<T>` overload to type your records:
+
+```ts
+interface Product {
+  name: string;
+  price: number;
+  category: string;
+}
+
+const { data } = await db.records.query<Product>({
+  filters: [{ field: 'category', op: '==', value: 'shoes' }],
+});
+
+// data is (Product & HydrousRecord)[]
+console.log(data[0].name, data[0].price);
+```
+
+---
+
+## Contributing
+
+1. Fork the repo and clone it
+2. `npm install`
+3. `npm run dev` — TypeScript watch mode
+4. `npm test` — run the test suite
+5. Open a PR 🚀
+
+---
+
+## License
+
+MIT © HydrousDB