hydrousdb 3.5.0 → 3.5.2

package/dist/index.d.cts

@@ -57,6 +57,35 @@ interface LoginOptions {
     email: string;
     password: string;
 }
+/**
+ * Options for `auth.continueWithGoogle()`.
+ *
+ * Pass the Google ID token returned by the Google Sign-In SDK.
+ * Your server verifies this token — the SDK never calls Google APIs directly.
+ *
+ * How to get the idToken:
+ *   Web (Google Identity Services):
+ *     `google.accounts.id.initialize({ callback: ({ credential }) => ... })`
+ *     → credential IS the idToken
+ *   React Native (@react-native-google-signin/google-signin):
+ *     `const { idToken } = await GoogleSignin.signIn()`
+ *   Flutter (google_sign_in):
+ *     `final idToken = (await account.authentication).idToken`
+ */
+interface GoogleSignInOptions {
+    idToken: string;
+}
+/**
+ * Options for `auth.linkGoogle()`.
+ * Links a Google account to an existing email/password account so the
+ * user can sign in with either method going forward.
+ */
+interface GoogleLinkOptions {
+    /** Active session ID of the currently signed-in user. */
+    sessionId: string;
+    /** Google ID token from the Google Sign-In SDK. */
+    idToken: string;
+}
 interface UserRecord {
     id: string;
     email: string;
@@ -67,6 +96,24 @@ interface UserRecord {
     createdAt: number;
     updatedAt: number;
     metadata?: Record<string, unknown>;
+    /**
+     * Primary authentication provider for this account.
+     *   'email'  — signed up with email + password
+     *   'google' — signed up via Google (no password unless added later)
+     */
+    authProvider?: 'email' | 'google' | 'github';
+    /**
+     * Google profile picture URL.
+     * Present for users who signed up or linked Google.
+     * Refreshed automatically on each Google sign-in.
+     */
+    picture?: string | null;
+    /**
+     * Stable Google user ID (the `sub` claim from the Google ID token).
+     * Never changes even if the user changes their Google email.
+     * Only present for users with Google linked.
+     */
+    googleId?: string;
     [key: string]: unknown;
 }
 interface Session {
@@ -81,6 +128,19 @@ interface Session {
 interface AuthResult {
     user: UserRecord;
     session: Session;
+    /**
+     * `true` when this is the very first sign-in (account was just created).
+     * `false` for returning users.
+     * Present for all auth methods — signup, login, and continueWithGoogle.
+     *
+     * Use to drive onboarding flows:
+     * ```ts
+     * const { user, session, isNew } = await auth.continueWithGoogle({ idToken });
+     * if (isNew) router.push('/onboarding');
+     * else       router.push('/dashboard');
+     * ```
+     */
+    isNew?: boolean;
 }
 interface UpdateUserOptions {
     sessionId: string;
@@ -133,6 +193,49 @@ interface QueryOptions {
     startAt?: string;
     endAt?: string;
     dateRange?: DateRange;
+    /**
+     * Time-scope shorthand filter — narrows the query to a specific day, month, or year
+     * using the record ID prefix convention.
+     *
+     * Format: `_<type>_<code>`
+     *   - Day:   `_day_YYMMDD`   e.g. `_day_260305`  → March 5, 2026
+     *   - Month: `_month_YYMM`   e.g. `_month_2603`  → March 2026
+     *   - Year:  `_year_YY`      e.g. `_year_26`     → 2026
+     *
+     * Maps to `?timeScope=` on the server.
+     *
+     * @example
+     * // All records from March 2026
+     * await posts.query({ timeScope: '_month_2603' });
+     *
+     * // All records from a specific day
+     * await posts.query({ timeScope: '_day_260305' });
+     */
+    timeScope?: string;
+    /**
+     * Start of a date range — inclusive. ISO date string (YYYY-MM-DD).
+     * Maps to `?startDate=` on the server.
+     * @example '2026-01-01'
+     */
+    startDate?: string;
+    /**
+     * End of a date range — inclusive. ISO date string (YYYY-MM-DD).
+     * Maps to `?endDate=` on the server.
+     * @example '2026-12-31'
+     */
+    endDate?: string;
+    /**
+     * Restrict the monthly walk to a specific two-digit year.
+     * Maps to `?year=` on the server.
+     * @example '26' for 2026
+     */
+    year?: string;
+    /**
+     * Field to sort by. Maps to `?sortBy=` on the server.
+     * Works on every query path — sorting is always done in-memory after hydration
+     * so any field name is accepted, not just indexed ones.
+     */
+    sortBy?: string;
 }
 interface QueryResult<T = RecordData> {
     records: (T & RecordResult)[];
@@ -395,6 +498,83 @@ declare class AuthClient {
         sessionId: string;
         allDevices?: boolean;
     }): Promise<void>;
+    /**
+     * Sign in or create an account using a Google ID token.
+     *
+     * Pass the `idToken` from the Google Sign-In SDK. Your server verifies the
+     * token against Google's public keys, then either creates a new account or
+     * signs in the returning user. No password is ever set or required.
+     *
+     * The returned `AuthResult` is identical in shape to `login()` and `signup()`.
+     * Sessions from Google sign-in work with `validateSession`, `refreshSession`,
+     * and `logout` — nothing changes after the initial sign-in.
+     *
+     * Use `isNew` to drive onboarding flows.
+     *
+     * @example
+     * ```ts
+     * // Web — Google Identity Services
+     * google.accounts.id.initialize({
+     *   client_id: 'YOUR_GOOGLE_CLIENT_ID',
+     *   callback: async ({ credential }) => {
+     *     const { user, session, isNew } = await db.auth().continueWithGoogle({
+     *       idToken: credential,
+     *     });
+     *     if (isNew) router.push('/onboarding');
+     *     else       router.push('/dashboard');
+     *   },
+     * });
+     *
+     * // React Native
+     * const { idToken } = await GoogleSignin.signIn();
+     * const { user, session, isNew } = await db.auth().continueWithGoogle({ idToken });
+     * ```
+     *
+     * Server: POST /api/auth/google
+     * Body: { idToken }
+     */
+    continueWithGoogle(options: GoogleSignInOptions): Promise<AuthResult>;
+    /**
+     * Link a Google account to the currently signed-in user.
+     *
+     * After linking, the user can sign in with either their email + password
+     * or with Google — both produce valid sessions.
+     *
+     * The server is idempotent — calling this when Google is already linked
+     * returns the updated user without creating duplicate entries.
+     *
+     * @example
+     * ```ts
+     * // User is signed in with email. They click "Connect Google" in settings.
+     * const { idToken } = await GoogleSignin.signIn();
+     * const updatedUser = await db.auth().linkGoogle({
+     *   sessionId: currentSession.sessionId,
+     *   idToken,
+     * });
+     * ```
+     *
+     * Server: POST /api/auth/google/link
+     * Body: { sessionId, idToken }
+     */
+    linkGoogle(options: GoogleLinkOptions): Promise<UserRecord>;
+    /**
+     * Unlink Google from the currently signed-in user's account.
+     *
+     * Only succeeds if the user has a password set — you cannot remove the only
+     * sign-in method. If the account was created via Google and has no password,
+     * call `changePassword` first.
+     *
+     * @example
+     * ```ts
+     * await db.auth().unlinkGoogle({ sessionId: currentSession.sessionId });
+     * ```
+     *
+     * Server: DELETE /api/auth/google/unlink
+     * Body: { sessionId }
+     */
+    unlinkGoogle(options: {
+        sessionId: string;
+    }): Promise<void>;
     /**
      * Validate an existing session and retrieve the current user.
      *
@@ -1184,114 +1364,64 @@ declare class HydrousClient {
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
-/**
- * routes.ts — Single source of truth for every API path in the HydrousDB SDK.
- *
- * Base URL: https://db-api-82687684612.us-central1.run.app
- *
- * Mount points (from server.js):
- *   /api          → records router   (X-Api-Key: bucketSecurityKey)
- *   /api/analytics → analytics router (X-Api-Key: bucketSecurityKey)
- *   /api/auth      → auth router      (X-Api-Key: authKey)
- *   /storage       → storage router   (X-Storage-Key: ssk_…)
- *
- * ⚠️  Keys MUST be sent in headers — NEVER in URLs or query strings.
- *     Records + Analytics: X-Api-Key  (or Authorization: Bearer …)
- *     Storage:             X-Storage-Key (or Authorization: Bearer …)
- */
 declare const RECORDS: {
-    /** GET|POST|PATCH|DELETE|HEAD /api/:bucketKey */
+    /** Base path for a bucket: GET|POST /api/:bucketKey */
     readonly bucket: (bucketKey: string) => string;
-    /** POST /api/:bucketKey/batch/insert */
+    /** Batch insert: POST /api/:bucketKey/batch/insert */
     readonly batchInsert: (bucketKey: string) => string;
-    /** POST /api/:bucketKey/batch/update */
+    /** Batch update: POST /api/:bucketKey/batch/update */
     readonly batchUpdate: (bucketKey: string) => string;
-    /** POST /api/:bucketKey/batch/delete */
+    /** Batch delete: POST /api/:bucketKey/batch/delete */
     readonly batchDelete: (bucketKey: string) => string;
 };
 declare const ANALYTICS: {
-    /** POST /api/analytics/:bucketKey */
+    /** Analytics query: POST /api/analytics/:bucketKey */
     readonly query: (bucketKey: string) => string;
 };
 declare const AUTH: {
-    /** POST /api/auth/signup   body: { email, password, fullName?, ...extra } */
     readonly signup: "/api/auth/signup";
-    /** POST /api/auth/signin   body: { email, password } */
     readonly signin: "/api/auth/signin";
-    /** POST /api/auth/signout  body: { sessionId, allDevices? } */
     readonly signout: "/api/auth/signout";
-    /** POST /api/auth/session/validate  body: { sessionId } */
+    readonly googleSignIn: "/api/auth/google";
+    readonly googleLink: "/api/auth/google/link";
+    readonly googleUnlink: "/api/auth/google/unlink";
     readonly sessionValidate: "/api/auth/session/validate";
-    /** POST /api/auth/session/refresh   body: { refreshToken } */
     readonly sessionRefresh: "/api/auth/session/refresh";
-    /** GET  /api/auth/user?userId=... */
     readonly getUser: "/api/auth/user";
-    /** GET  /api/auth/users?limit=&cursor= */
-    readonly listUsers: "/api/auth/users";
-    /** PATCH /api/auth/user  body: { sessionId, userId, updates: {...} } */
     readonly updateUser: "/api/auth/user";
-    /** DELETE /api/auth/user?userId=...  body: { sessionId } */
     readonly deleteUser: "/api/auth/user";
-    /** DELETE /api/auth/user/hard?userId=...  body: { sessionId } */
+    readonly listUsers: "/api/auth/users";
     readonly hardDeleteUser: "/api/auth/user/hard";
-    /** DELETE /api/auth/users/bulk  body: { userIds, hard?, sessionId } */
     readonly bulkDeleteUsers: "/api/auth/users/bulk";
-    /** POST /api/auth/password/change  body: { sessionId, userId, oldPassword, newPassword } */
+    readonly accountLock: "/api/auth/account/lock";
+    readonly accountUnlock: "/api/auth/account/unlock";
     readonly passwordChange: "/api/auth/password/change";
-    /** POST /api/auth/password/reset/request  body: { email } */
     readonly passwordResetRequest: "/api/auth/password/reset/request";
-    /** POST /api/auth/password/reset/confirm  body: { resetToken, newPassword } */
     readonly passwordResetConfirm: "/api/auth/password/reset/confirm";
-    /** POST /api/auth/email/verify/request  body: { userId } */
     readonly emailVerifyRequest: "/api/auth/email/verify/request";
-    /** POST /api/auth/email/verify/confirm  body: { verifyToken } */
     readonly emailVerifyConfirm: "/api/auth/email/verify/confirm";
-    /** POST /api/auth/account/lock    body: { sessionId, userId, duration? } */
-    readonly accountLock: "/api/auth/account/lock";
-    /** POST /api/auth/account/unlock  body: { sessionId, userId } */
-    readonly accountUnlock: "/api/auth/account/unlock";
 };
 declare const STORAGE: {
-    /** GET /storage/info  — no auth required */
-    readonly info: "/storage/info";
-    /** GET /storage/public/:fullScopedPath  — no auth required */
-    readonly publicFile: (fullScopedPath: string) => string;
-    /** POST /storage/upload-url  body: { path, mimeType, size, isPublic?, overwrite?, expiresIn? } */
-    readonly uploadUrl: "/storage/upload-url";
-    /** POST /storage/batch-upload-urls  body: { files: [...], expiresIn? } */
-    readonly batchUploadUrls: "/storage/batch-upload-urls";
-    /** POST /storage/confirm  body: { path, mimeType, isPublic? } */
-    readonly confirm: "/storage/confirm";
-    /** POST /storage/batch-confirm  body: { files: [...] } */
-    readonly batchConfirm: "/storage/batch-confirm";
-    /** POST /storage/upload  multipart/form-data: file, path, mimeType, isPublic, overwrite */
+    readonly base: "/storage";
     readonly upload: "/storage/upload";
-    /** POST /storage/upload-raw  body: { path, content, mimeType?, isPublic?, overwrite? } */
-    readonly uploadRaw: "/storage/upload-raw";
-    /** GET /storage/list?prefix=&limit=&cursor= */
+    readonly uploadRaw: "/storage/upload/raw";
+    readonly uploadUrl: "/storage/upload/url";
+    readonly confirm: "/storage/upload/confirm";
+    readonly batchUploadUrls: "/storage/upload/batch/urls";
+    readonly batchConfirm: "/storage/upload/batch/confirm";
+    readonly download: (encodedPath: string) => string;
+    readonly batchDownload: "/storage/download/batch";
     readonly list: "/storage/list";
-    /** GET /storage/download/:path  — requires X-Storage-Key */
-    readonly download: (filePath: string) => string;
-    /** POST /storage/batch-download  body: { paths: [...], concurrency? } */
-    readonly batchDownload: "/storage/batch-download";
-    /** GET /storage/metadata/:path */
-    readonly metadata: (filePath: string) => string;
-    /** POST /storage/signed-url  body: { path, expiresIn? } */
+    readonly metadata: (encodedPath: string) => string;
     readonly signedUrl: "/storage/signed-url";
-    /** PATCH /storage/visibility  body: { path, isPublic } */
     readonly visibility: "/storage/visibility";
-    /** POST /storage/folder  body: { path } */
     readonly folder: "/storage/folder";
-    /** DELETE /storage/file  body: { path } */
     readonly file: "/storage/file";
-    /** DELETE /storage/folder  body: { path } */
-    readonly folderDelete: "/storage/folder";
-    /** POST /storage/move  body: { from, to } */
+    readonly folderDelete: "/storage/folder/delete";
     readonly move: "/storage/move";
-    /** POST /storage/copy  body: { from, to } */
     readonly copy: "/storage/copy";
-    /** GET /storage/stats */
     readonly stats: "/storage/stats";
+    readonly info: "/storage/info";
 };
 
 declare class HydrousError extends Error {
@@ -1322,4 +1452,4 @@ declare class NetworkError extends HydrousError {
     constructor(message: string, cause?: unknown);
 }
 
-export { ANALYTICS, AUTH, type Aggregation, AnalyticsClient, AnalyticsError, type AnalyticsFilter, type AnalyticsQuery, type AnalyticsResult, AuthClient, AuthError, type AuthResult, type BatchCreateOptions, type BatchDownloadResult, type BatchUploadItem, type BatchUploadUrlResult, type ChangePasswordOptions, type CountResult, type CreateRecordOptions, type CrossBucketRow, DEFAULT_BASE_URL, type DateRange, type DistributionRow, type FieldStats, type FieldTimeSeriesRow, type FileEntry, type FileMetadata, type Granularity, HttpClient, HydrousClient, type HydrousConfig, HydrousError, type ListOptions, type ListResult, type ListUsersOptions, type ListUsersResult, type LoginOptions, type MetricDefinition, type MultiMetricResult, NetworkError, type PatchRecordOptions, type QueryFilter, type QueryOptions, type QueryResult, type QueryType, RECORDS, type RecordData, RecordError, type RecordHistoryEntry, type RecordResult, RecordsClient, STORAGE, ScopedStorage, type Session, type SignedUrlResult, type SignupOptions, type SortOrder, StorageError, type StorageKeys, StorageManager, type StorageStats, type StorageStatsResult, type SumRow, type TimeSeriesRow, type TopNRow, type UpdateUserOptions, type UploadOptions, type UploadResult, type UploadUrlResult, type UserRecord, ValidationError, createClient };
+export { ANALYTICS, AUTH, type Aggregation, AnalyticsClient, AnalyticsError, type AnalyticsFilter, type AnalyticsQuery, type AnalyticsResult, AuthClient, AuthError, type AuthResult, type BatchCreateOptions, type BatchDownloadResult, type BatchUploadItem, type BatchUploadUrlResult, type ChangePasswordOptions, type CountResult, type CreateRecordOptions, type CrossBucketRow, DEFAULT_BASE_URL, type DateRange, type DistributionRow, type FieldStats, type FieldTimeSeriesRow, type FileEntry, type FileMetadata, type GoogleLinkOptions, type GoogleSignInOptions, type Granularity, HttpClient, HydrousClient, type HydrousConfig, HydrousError, type ListOptions, type ListResult, type ListUsersOptions, type ListUsersResult, type LoginOptions, type MetricDefinition, type MultiMetricResult, NetworkError, type PatchRecordOptions, type QueryFilter, type QueryOptions, type QueryResult, type QueryType, RECORDS, type RecordData, RecordError, type RecordHistoryEntry, type RecordResult, RecordsClient, STORAGE, ScopedStorage, type Session, type SignedUrlResult, type SignupOptions, type SortOrder, StorageError, type StorageKeys, StorageManager, type StorageStats, type StorageStatsResult, type SumRow, type TimeSeriesRow, type TopNRow, type UpdateUserOptions, type UploadOptions, type UploadResult, type UploadUrlResult, type UserRecord, ValidationError, createClient };