hydrousdb 3.5.1 → 3.5.3

package/README.md

@@ -1,6 +1,6 @@
 # HydrousDB JS/TS SDK
 
-**A database that doesn't choke on big JSON.** Store, query, and analyse massive records — with auth and file storage built in.
+**A database that doesn't choke on big JSON.** Store, query, and analyse massive records — with auth, Google sign-in, and file storage built in.
 
 ```bash
 npm install hydrousdb
@@ -17,6 +17,7 @@ npm install hydrousdb
   - [Create, Read, Update, Delete](#create-read-update-delete)
   - [Querying & Filtering](#querying--filtering)
   - [Time Scope on Queries](#time-scope-on-queries)
+  - [Date Range Queries](#date-range-queries)
   - [Pagination](#pagination)
   - [Atomic Field Updates](#atomic-field-updates)
   - [Batch Operations](#batch-operations)
@@ -26,6 +27,7 @@ npm install hydrousdb
   - [Get All Records](#get-all-records)
 - [Auth](#auth)
   - [Sign Up & Log In](#sign-up--log-in)
+  - [Google Sign-In](#google-sign-in)
   - [Session Management](#session-management)
   - [User Profile](#user-profile)
   - [Password & Email](#password--email)
@@ -143,11 +145,37 @@ const { records, hasMore, nextCursor } = await posts.query({
 
 **Supported filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`
 
+You can combine multiple filters. The first equality filter (`==`) drives the GCS index — additional filters are applied in-memory after hydration. This means you get fast indexed lookups for equality filters and flexible in-memory filtering for everything else.
+
+**Filter combinations:**
+```ts
+// Equality only — fast index path
+await posts.query({ filters: [{ field: 'status', op: '==', value: 'published' }] });
+
+// Equality + range — index on status, range applied in-memory
+await posts.query({ filters: [
+  { field: 'status', op: '==', value: 'published' },
+  { field: 'views',  op: '>=', value: 100 },
+]});
+
+// Equality + contains — index on status, contains applied in-memory
+await posts.query({ filters: [
+  { field: 'status', op: '==',       value: 'published' },
+  { field: 'title',  op: 'contains', value: 'hello' },
+]});
+
+// Multiple equality — first drives index, rest applied in-memory
+await posts.query({ filters: [
+  { field: 'status',   op: '==', value: 'published' },
+  { field: 'category', op: '==', value: 'tech' },
+]});
+```
+
 ---
 
 ### Time Scope on Queries
 
-Pass `timeScope` to restrict records to a specific **day, month, or year** using the record ID prefix convention. This is the fastest way to scope a query by time — no timestamp arithmetic needed.
+Pass `timeScope` to restrict records to a specific **day, month, or year**. This is the fastest way to scope a query by time — no timestamp arithmetic needed.
 
 | Scope | Format | Example | Matches |
 |---|---|---|---|
@@ -185,7 +213,7 @@ const { records: yearRecords } = await posts.query({
   limit:     100,
 });
 
-// Fully composable with filters
+// Fully composable with filters — this is the recommended pattern for large buckets
 const { records: published } = await posts.query({
   timeScope: '_month_2603',
   filters:   [{ field: 'status', op: '==', value: 'published' }],
@@ -199,6 +227,49 @@ const all = await posts.getAll({ timeScope: '_year_26' });
 
 ---
 
+### Date Range Queries
+
+Pass `startDate` and/or `endDate` (ISO date strings) to walk records within a calendar range. Both fields are optional — omit either for an open-ended range.
+
+```ts
+// Records from a specific month
+const { records } = await posts.query({
+  startDate: '2026-04-01',
+  endDate:   '2026-04-30',
+});
+
+// Records since a specific date (no end bound)
+const { records: recent } = await posts.query({
+  startDate: '2026-01-01',
+  orderBy:   'createdAt',
+  order:     'desc',
+});
+
+// Walk a specific year using the year shorthand
+const { records: yearRecords } = await posts.query({
+  year:  '26',        // two-digit year
+  order: 'desc',
+  limit: 100,
+});
+
+// Combine with filters
+const { records: paidOrders } = await orders.query({
+  startDate: '2026-04-01',
+  endDate:   '2026-04-30',
+  filters:   [{ field: 'status', op: '==', value: 'paid' }],
+});
+
+// Sort by any field
+const { records: byPrice } = await rooms.query({
+  timeScope: '_month_2604',
+  filters:   [{ field: 'status', op: '==', value: 'available' }],
+  sortBy:    'pricePerNight',
+  order:     'asc',
+});
+```
+
+---
+
 ### Pagination
 
 `query()` returns a cursor you can pass straight into the next call.
@@ -229,15 +300,16 @@ Avoid race conditions with server-side sentinels inside `patch()`:
 
 ```ts
 await posts.patch(post.id, {
-  views:    { __op: 'increment',      delta: 1 },          // add N
-  credits:  { __op: 'decrement',      delta: 5 },          // subtract N
-  slug:     { __op: 'setOnce',        value: 'my-post' },  // set only if currently empty
-  tags:     { __op: 'appendUnique',   item: 'featured' },  // add to array, no duplicates
-  tags:     { __op: 'removeFromArray', item: 'draft' },    // remove from array
-  rating:   { __op: 'clamp',          value: 6, min: 0, max: 5 }, // clamp to range
-  price:    { __op: 'multiplyBy',     factor: 1.1 },       // multiply
-  active:   { __op: 'toggleBool' },                        // flip boolean
-  syncedAt: { __op: 'serverTimestamp' },                   // set to server time
+  views:    { __op: 'increment',       delta: 1 },          // add N
+  credits:  { __op: 'decrement',       delta: 5 },          // subtract N
+  slug:     { __op: 'setOnce',         value: 'my-post' },  // set only if currently empty
+  tags:     { __op: 'appendUnique',    item: 'featured' },  // add to array, no duplicates
+  oldTag:   { __op: 'removeFromArray', item: 'draft' },     // remove from array
+  rating:   { __op: 'clamp',           value: 6, min: 0, max: 5 }, // clamp to range
+  price:    { __op: 'multiplyBy',      factor: 1.1 },       // multiply
+  active:   { __op: 'toggleBool' },                         // flip boolean
+  syncedAt: { __op: 'serverTimestamp' },                    // set to server time
+  score:    { __op: 'setIf', value: 99, cond: { op: '>=', value: 50 } }, // conditional set
 } as any);
 ```
 
@@ -341,7 +413,7 @@ const all = await posts.getAll({
 
 ## Auth
 
-A complete user system — signup, login, sessions, password reset, email verification, and admin controls.
+A complete user system — signup, login, Google sign-in, sessions, password reset, email verification, and admin controls.
 
 ```ts
 const auth = db.auth();
@@ -380,6 +452,118 @@ Store `session.sessionId` and `session.refreshToken` in your app.
 
 ---
 
+### Google Sign-In
+
+Allow users to sign in or create an account with one tap — no password required.
+
+The flow is the same regardless of platform: get a Google ID token on the client, pass it to `continueWithGoogle`. The server verifies the token and returns a session identical in shape to `login()` and `signup()`.
+
+**Web (Google Identity Services)**
+
+```html
+<!-- Add to your HTML <head> -->
+<script src="https://accounts.google.com/gsi/client" async defer></script>
+```
+
+```ts
+google.accounts.id.initialize({
+  client_id: 'YOUR_GOOGLE_CLIENT_ID',  // from Google Cloud Console
+  callback: async ({ credential }) => {
+    const { user, session, isNew } = await db.auth().continueWithGoogle({
+      idToken: credential,
+    });
+    if (isNew) router.push('/onboarding');  // brand-new account
+    else       router.push('/dashboard');   // returning user
+  },
+});
+
+// Render the button anywhere in your page
+google.accounts.id.renderButton(
+  document.getElementById('google-btn'),
+  { theme: 'outline', size: 'large', text: 'continue_with' },
+);
+```
+
+**React Native**
+
+```ts
+import { GoogleSignin } from '@react-native-google-signin/google-signin';
+
+GoogleSignin.configure({ webClientId: 'YOUR_GOOGLE_CLIENT_ID' });
+
+const { idToken } = await GoogleSignin.signIn();
+const { user, session, isNew } = await db.auth().continueWithGoogle({ idToken });
+if (isNew) navigation.navigate('Onboarding');
+```
+
+**Flutter**
+
+```dart
+final googleUser = await GoogleSignIn().signIn();
+final auth       = await googleUser!.authentication;
+// Send auth.idToken to your backend which calls the HydrousDB SDK
+```
+
+**What `isNew` tells you**
+
+```ts
+const { user, session, isNew } = await auth.continueWithGoogle({ idToken });
+
+if (isNew) {
+  // Account was just created — show onboarding, collect extra info, etc.
+  console.log('Welcome!', user.fullName);
+} else {
+  // Returning user — go straight to the app
+  console.log('Welcome back!', user.email);
+}
+```
+
+**Link Google to an existing email/password account**
+
+```ts
+// User is signed in with email. They click "Connect Google" in settings.
+const { idToken } = await GoogleSignin.signIn();
+const updatedUser = await auth.linkGoogle({
+  sessionId: currentSession.sessionId,
+  idToken,
+});
+// After linking, the user can sign in with either method
+```
+
+**Unlink Google**
+
+```ts
+// Only works if the user has a password set — prevents account lockout
+await auth.unlinkGoogle({ sessionId: currentSession.sessionId });
+```
+
+**Setting a password on a Google-only account**
+
+```ts
+// Google users have no password by default.
+// Pass an empty string for currentPassword to set the first one.
+await auth.changePassword({
+  sessionId:       session.sessionId,
+  userId:          user.id,
+  currentPassword: '',         // empty — no password set yet
+  newPassword:     'newpassword123',
+});
+// After this, the user can sign in with email+password AND Google
+```
+
+The `UserRecord` for Google users includes:
+
+```ts
+interface UserRecord {
+  authProvider?: 'email' | 'google';  // 'google' for Google sign-in users
+  picture?:      string | null;        // profile photo URL from Google
+  googleId?:     string;               // stable Google identifier
+  // ... all other standard fields
+}
+```
+
+---
+
 ### Session Management
 
 ```ts
@@ -423,7 +607,9 @@ interface UserRecord {
   createdAt:      number;   // Unix ms
   updatedAt:      number;   // Unix ms
   metadata?:      Record<string, unknown>;
-  [key: string]:  unknown;  // custom fields from signup
+  authProvider?:  'email' | 'google';   // how the account was created
+  picture?:       string | null;         // Google profile photo URL
+  [key: string]:  unknown;               // custom fields from signup
 }
 ```
 
@@ -433,6 +619,7 @@ interface UserRecord {
 
 ```ts
 // Change password — requires an active session AND the current password
+// Pass empty string for currentPassword to SET a first password (Google users)
 await auth.changePassword({
   sessionId:       session.sessionId,
   userId:          user.id,
@@ -632,7 +819,6 @@ const meta = await storage.getMetadata('avatars/alice.jpg');
 // → { path, size, mimeType, isPublic, publicUrl, downloadUrl, createdAt, updatedAt }
 
 // Generate a time-limited link — anyone with the URL can download (no key needed)
-// Note: downloads via signed URL bypass the server, so download stats are NOT tracked
 const { signedUrl, expiresAt, expiresIn } = await storage.getSignedUrl(
   'private/report.pdf',
   3600, // lifetime in seconds (default: 3600)
@@ -690,7 +876,7 @@ const reports = userFiles.scope('reports/');       // → users/{userId}/reports
 await reports.upload(file, 'q1.pdf');              // → users/{userId}/reports/q1.pdf
 
 // All StorageManager methods are available on ScopedStorage
-const meta        = await userFiles.getMetadata('contract.pdf');
+const meta          = await userFiles.getMetadata('contract.pdf');
 const { signedUrl } = await userFiles.getSignedUrl('contract.pdf', 900);
 await userFiles.move('old.pdf', 'new.pdf');
 await userFiles.deleteFile('contract.pdf');
@@ -723,7 +909,7 @@ const analytics = db.analytics('orders');
 
 ### Date Range (Time Scope)
 
-Almost every analytics method accepts an optional `dateRange` to restrict results to a time window. Both `start` and `end` are Unix timestamps **in milliseconds** — the server converts them to ISO strings internally. Both fields are optional; omit either for an open-ended range.
+Almost every analytics method accepts an optional `dateRange` to restrict results to a time window. Both `start` and `end` are Unix timestamps **in milliseconds**. Both fields are optional; omit either for an open-ended range.
 
 ```ts
 interface DateRange {
@@ -779,7 +965,7 @@ How many records have each value of a field.
 const dist = await analytics.distribution({
   field:     'status',
   limit:     10,
-  order:     'desc', // 'asc' | 'desc'
+  order:     'desc',
   dateRange: { start: new Date('2025-01-01').getTime() },
 });
 // → [{ value: 'published', count: 320 }, { value: 'draft', count: 80 }, …]
@@ -846,7 +1032,6 @@ const revTrend = await analytics.fieldTimeSeries({
     end:   Date.now(),
   },
 });
-// → [{ date: '2025-01-01', value: 4820.5 }, …]
 
 // Monthly average order value
 const avgTrend = await analytics.fieldTimeSeries({
@@ -863,11 +1048,10 @@ const avgTrend = await analytics.fieldTimeSeries({
 Most frequent values for a field by record count.
 
 ```ts
-// Top 10 countries
 const top10 = await analytics.topN({
   field:      'countryCode',
   n:          10,
-  labelField: 'countryName', // optional — include a human-readable label alongside the value
+  labelField: 'countryName',
   order:      'desc',
   dateRange:  { start: new Date('2025-01-01').getTime() },
 });
@@ -892,7 +1076,7 @@ const priceStats = await analytics.stats({
 
 ### Records via BigQuery
 
-Fetch filtered records through the BigQuery engine instead of Firestore. Useful for large result sets or complex server-side filtering.
+Fetch filtered records through the BigQuery engine instead of the GCS index. Useful for large result sets or complex server-side filtering.
 
 ```ts
 const records = await analytics.records<Order>({
@@ -901,7 +1085,7 @@ const records = await analytics.records<Order>({
     { field: 'amount',  op: '>=',       value: 100 },
     { field: 'country', op: 'CONTAINS', value: 'US' },
   ],
-  selectFields: ['id', 'amount', 'country', 'createdAt'], // optional projection
+  selectFields: ['id', 'amount', 'country', 'createdAt'],
   orderBy:      'createdAt',
   order:        'desc',
   limit:        1000,
@@ -951,7 +1135,7 @@ const storageInfo = await analytics.storageStats({
 
 ### Cross-Bucket
 
-Compare the same metric across multiple buckets in a single query. Your key must have read access to all listed buckets. System buckets are blocked.
+Compare the same metric across multiple buckets in a single query.
 
 ```ts
 const compare = await analytics.crossBucket({
@@ -1069,6 +1253,7 @@ import type {
   DateRange, Granularity, Aggregation, SortOrder,
   AnalyticsQuery, AnalyticsResult, AnalyticsFilter,
   UserRecord, AuthResult, Session,
+  GoogleSignInOptions, GoogleLinkOptions,
   UploadOptions, UploadResult,
   ListOptions, ListResult, FileMetadata, SignedUrlResult,
   StorageStats,
@@ -1084,6 +1269,7 @@ import type {
 - **Keys travel in headers only** — the SDK enforces this. They never appear in URLs, query strings, access logs, or browser history.
 - **Files are private by default.** `isPublic` defaults to `false`. Use `getSignedUrl()` for temporary external sharing.
 - **Use scoped storage** (`storage.scope('prefix/')`) to isolate files per user and prevent path-traversal bugs.
+- **Google ID tokens are verified server-side** — the SDK never sends tokens to Google directly after initial sign-in.
 
 ---
 
@@ -1165,7 +1351,7 @@ const db = createClient({
 | `patch(id, data, opts?)` | `{ id, updatedAt? }` | Partial update. `opts.merge` for deep merge. `opts.trackHistory` to save a version. |
 | `delete(id)` | `void` | Permanently delete a record. |
 | `exists(id)` | `boolean` | Lightweight existence check (HEAD request). |
-| `query(opts?)` | `QueryResult<T>` | Filter, sort, paginate. Supports `dateRange`. |
+| `query(opts?)` | `QueryResult<T>` | Filter, sort, paginate. Supports `dateRange`, `timeScope`, `startDate`, `endDate`, `year`, `sortBy`. |
 | `getAll(opts?)` | `(T & RecordResult)[]` | Fetch all records (no filter support — use `query` for filters). |
 | `batchCreate(items, opts?)` | `{ results, errors, successful, failed }` | Up to 500 records at once. |
 | `batchUpdate(updates, userEmail?)` | `{ successful, failed }` | Up to 500 records at once. |
@@ -1179,7 +1365,8 @@ const db = createClient({
 |---|---|---|
 | `filters` | `QueryFilter[]` | Array of `{ field, op, value }` |
 | `fields` | `string` | Comma-separated list of fields to return |
-| `orderBy` | `string` | Field to sort by |
+| `orderBy` | `string` | Field to sort by (server maps to `sortBy`) |
+| `sortBy` | `string` | Alias for `orderBy` — maps directly to `?sortBy=` |
 | `order` | `'asc' \| 'desc'` | Sort direction |
 | `limit` | `number` | Max records to return |
 | `offset` | `number` | Skip N records |
@@ -1188,6 +1375,9 @@ const db = createClient({
 | `endAt` | `string` | Cursor — stop at this cursor |
 | `dateRange` | `DateRange` | `{ start?, end? }` in Unix ms |
 | `timeScope` | `string` | Prefix-based time filter: `_day_YYMMDD`, `_month_YYMM`, or `_year_YY` |
+| `startDate` | `string` | ISO date string e.g. `'2026-01-01'` — GCS day-range walk start |
+| `endDate` | `string` | ISO date string e.g. `'2026-12-31'` — GCS day-range walk end |
+| `year` | `string` | Two-digit year e.g. `'26'` — restricts monthly walk to that year |
 
 ---
 
@@ -1197,17 +1387,20 @@ const db = createClient({
 |---|---|
 | `signup(opts)` | Register + create session. Extra fields on `opts` are stored on the user. |
 | `login(opts)` | Authenticate + create session. |
+| `continueWithGoogle({ idToken })` | Sign in or create account via Google ID token. Returns `isNew` flag. |
+| `linkGoogle({ sessionId, idToken })` | Add Google sign-in to an existing email/password account. |
+| `unlinkGoogle({ sessionId })` | Remove Google sign-in (only if a password is set). |
 | `logout({ sessionId, allDevices? })` | Revoke one session or all sessions. |
 | `validateSession(sessionId)` | Check if a session is active; returns current user. |
 | `refreshSession(refreshToken)` | Get a new session from a refresh token. |
 | `getUser(userId)` | Fetch a user by ID. |
 | `updateUser(opts)` | Update profile fields. |
-| `changePassword(opts)` | Authenticated password change (requires current password). |
+| `deleteUser(sessionId, userId)` | Soft-delete a user. |
+| `changePassword(opts)` | Authenticated password change. Pass `currentPassword: ''` to set first password on Google accounts. |
 | `requestPasswordReset(email)` | Send reset email (always succeeds to prevent enumeration). |
 | `confirmPasswordReset(token, newPw)` | Apply new password from reset token. |
-| `requestEmailVerification(userId)` | Send verification email. |
+| `requestEmailVerification(userId)` | Send verification email. Not needed for Google users. |
 | `confirmEmailVerification(token)` | Mark email verified from token. |
-| `getUser(userId)` | Fetch a user by ID. |
 | `listUsers(opts)` | Paginated user list. Admin only. |
 | `lockAccount(opts)` | Lock a user account. Admin only. |
 | `unlockAccount(sessionId, userId)` | Unlock a user account. Admin only. |
@@ -1242,8 +1435,6 @@ const db = createClient({
 | `info()` | Server info — no auth required. |
 | `scope(prefix)` | Get a `ScopedStorage` that auto-prefixes all paths. |
 
-`ScopedStorage` exposes every method above (except `info`) plus `scope(subPrefix)` for nesting deeper.
-
 ---
 
 ### `db.analytics(bucket)` — all methods