@rebasepro/client 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,164 @@
+# @rebasepro/client
+
+HTTP SDK client for the Rebase backend — typed CRUD, auth, storage, realtime WebSockets, admin, cron, and custom functions.
+
+## Installation
+
+```bash
+pnpm add @rebasepro/client
+```
+
+## What This Package Does
+
+`@rebasepro/client` is the primary SDK for interacting with a Rebase backend from any JavaScript/TypeScript environment (browser, Node.js, edge). It creates a single client instance that provides:
+
+- **Collection CRUD** with a fluent query builder (`.where()`, `.orderBy()`, `.limit()`, etc.)
+- **Authentication** — email/password, Google, 10+ OAuth providers, session management, password reset
+- **Admin** — user CRUD for admins
+- **Storage** — file upload, download, delete, list
+- **Realtime** — WebSocket subscriptions for collection and entity changes
+- **Cron** — list, trigger, and manage cron jobs
+- **Custom functions** — invoke server-side Hono route functions
+- **Type-safe data proxy** — `client.data.products` auto-maps to the `products` collection
+
+## Key Exports
+
+### Client Factory
+
+| Export | Description |
+|---|---|
+| `createRebaseClient<DB>(options)` | Create a `RebaseClient` instance. Generic `DB` parameter enables type-safe `client.data.*` access. |
+| `RebaseClient<DB>` | The client type — includes `auth`, `admin`, `cron`, `functions`, `storage`, `ws`, `data`, `call`, and token management methods. |
+| `CreateRebaseClientOptions` | Extends `RebaseClientConfig` with `auth`, `admin`, and `cron` sub-configs. |
+
+### Config
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `""` | Backend URL (e.g. `http://localhost:3001`) |
+| `token` | `string` | — | Static auth token |
+| `apiPath` | `string` | `"/api"` | API path prefix |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation |
+| `onUnauthorized` | `() => Promise<boolean>` | auto-refresh | Handler for 401 responses |
+| `websocketUrl` | `string` | derived from `baseUrl` | WebSocket URL for realtime |
+
+### Collection Client
+
+`client.data.collection("slug")` or `client.data.myCollection` returns a `CollectionClient<M>`:
+
+| Method | Description |
+|---|---|
+| `find(params?)` | Query with pagination. Returns `FindResponse<M>` (`{ data, meta }`) |
+| `findById(id)` | Fetch a single entity. Returns `Entity<M> \| undefined` |
+| `create(data, id?)` | Create entity. Returns `Entity<M>` |
+| `update(id, data)` | Update entity. Returns `Entity<M>` |
+| `delete(id)` | Delete entity |
+| `count(params?)` | Count matching entities |
+| `where(col, op, val)` | Start a fluent query — returns `QueryBuilder` |
+| `orderBy(col, dir?)` | Order results — returns `QueryBuilder` |
+| `limit(n)` / `offset(n)` | Pagination — returns `QueryBuilder` |
+| `search(str)` | Full-text search — returns `QueryBuilder` |
+| `include(...rels)` | Include related entities — returns `QueryBuilder` |
+| `listen(params, onUpdate, onError?)` | Realtime subscription (requires WebSocket) |
+| `listenById(id, onUpdate, onError?)` | Realtime single-entity subscription |
+
+### Auth Module (`client.auth`)
+
+| Method | Description |
+|---|---|
+| `signInWithEmail(email, password)` | Email/password login |
+| `signUp(email, password, displayName?)` | Register new user |
+| `signInWithGoogle(payload)` | Google OAuth (ID token, access token, or auth code) |
+| `signInWithOAuth(providerId, payload)` | Generic OAuth for any provider |
+| `signInWithGitHub/Microsoft/Apple/Facebook/Twitter/Discord/GitLab/Bitbucket/Slack/Spotify` | Provider-specific convenience methods |
+| `signOut()` | Sign out and invalidate refresh token |
+| `refreshSession()` | Refresh the access token |
+| `getUser()` / `updateUser(updates)` | Current user profile |
+| `resetPasswordForEmail(email)` | Request password reset |
+| `resetPassword(token, password)` | Complete password reset |
+| `changePassword(old, new)` | Change password (authenticated) |
+| `sendVerificationEmail()` / `verifyEmail(token)` | Email verification |
+| `getSessions()` / `revokeSession(id)` / `revokeAllSessions()` | Session management |
+| `getAuthConfig()` | Fetch backend auth configuration |
+| `getSession()` | Get current session (sync) |
+| `onAuthStateChange(callback)` | Subscribe to auth events (`SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `USER_UPDATED`) |
+
+### Storage Module (`client.storage`)
+
+| Method | Description |
+|---|---|
+| `putObject({ file, key, metadata, bucket })` | Upload a file |
+| `getSignedUrl(key, bucket?)` | Get download URL + metadata |
+| `getObject(key, bucket?)` | Download file as `File` object |
+| `deleteObject(key, bucket?)` | Delete a file |
+| `listObjects(prefix, options?)` | List files with optional pagination |
+
+### Admin Module (`client.admin`)
+
+| Method | Description |
+|---|---|
+| `listUsers()` / `listUsersPaginated(options?)` | List all users |
+| `getUser(userId)` | Get a single user |
+| `createUser(data)` | Create a user |
+| `updateUser(userId, data)` | Update a user |
+| `deleteUser(userId)` | Delete a user |
+| `bootstrap()` | First-user bootstrap |
+
+### Functions Module (`client.functions`)
+
+| Method | Description |
+|---|---|
+| `invoke<T>(name, payload?, options?)` | Call a custom backend function at `/api/functions/{name}` |
+
+### Other Exports
+
+| Export | Description |
+|---|---|
+| `RebaseApiError` | Error class with `status`, `message`, `code`, `details` |
+| `RebaseWebSocketClient` | WebSocket client for realtime subscriptions |
+| `createCookieStorage(options?)` | Cookie-based auth storage adapter |
+| `createMemoryStorage()` | In-memory auth storage adapter |
+| `QueryBuilder` | Fluent query builder (also re-exported from `@rebasepro/common`) |
+| `Entity`, `FindResponse` | Re-exported from `@rebasepro/types` |
+
+## Quick Start
+
+```ts
+import { createRebaseClient } from "@rebasepro/client";
+
+const client = createRebaseClient({
+    baseUrl: "http://localhost:3001",
+});
+
+// Auth
+await client.auth.signInWithEmail("user@example.com", "password");
+
+// CRUD
+const { data: products } = await client.data.products.find({ limit: 10 });
+const product = await client.data.products.create({ name: "Camera", price: 299 });
+await client.data.products.update(product.id, { price: 249 });
+await client.data.products.delete(product.id);
+
+// Fluent queries
+const { data: expensive } = await client.data.products
+    .where("price", ">=", 100)
+    .orderBy("price", "desc")
+    .limit(5)
+    .find();
+
+// Custom function
+const result = await client.functions.invoke("process-order", { orderId: "123" });
+
+// Realtime
+const unsubscribe = client.data.products.listen(
+    { limit: 50 },
+    (response) => console.log("Update:", response.data)
+);
+```
+
+## Related Packages
+
+- [`@rebasepro/common`](../common) — `QueryBuilder`, `buildRebaseData`, shared utilities
+- [`@rebasepro/types`](../types) — `Entity`, `FindResponse`, `CollectionAccessor`, etc.
+- [`@rebasepro/utils`](../utils) — `toSnakeCase` and other helpers
+- [`@rebasepro/auth`](../auth) — React hook adapter that wraps `client.auth` for CMS integration

package/dist/admin.d.ts

@@ -1,14 +1,6 @@
 import type { Transport } from "./transport";
-export interface AdminUser {
-    uid: string;
-    email: string;
-    displayName: string | null;
-    photoURL: string | null;
-    provider: string;
-    roles: string[];
-    createdAt: string;
-    updatedAt: string;
-}
+import { AdminUser } from "@rebasepro/types";
+export type { AdminUser };
 export interface CreateAdminOptions {
     adminPath?: string;
 }

package/dist/auth.d.ts

@@ -1,4 +1,5 @@
 import { Transport } from "./transport";
+import { AuthChangeEvent } from "@rebasepro/types";
 export interface RebaseUser {
     uid: string;
     email: string | null;
@@ -20,7 +21,7 @@ export interface RebaseSession {
     expiresAt: number;
     user: RebaseUser;
 }
-export type AuthChangeEvent = "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "USER_UPDATED";
+export type { AuthChangeEvent };
 export interface AuthConfig {
     needsSetup: boolean;
     registrationEnabled: boolean;

package/dist/index.d.ts

@@ -3,7 +3,9 @@ import { createAuth, CreateAuthOptions } from "./auth";
 import { createAdmin, CreateAdminOptions } from "./admin";
 import { createCron, CreateCronOptions } from "./cron";
 import { CollectionClient } from "./collection";
-import type { FunctionsClient } from "./functions";
+import { createFunctionsClient } from "./functions";
+import { RebaseWebSocketClient } from "./websocket";
+import { RebaseClient, RebaseData, StorageSource } from "@rebasepro/types";
 export * from "./transport";
 export * from "./auth";
 export * from "./admin";
@@ -14,16 +16,30 @@ export * from "./websocket";
 export * from "./storage";
 export * from "./reviver";
 export * from "./functions";
+export type { Entity, FindResponse } from "@rebasepro/types";
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
     admin?: CreateAdminOptions;
     cron?: CreateCronOptions;
 }
-import { RebaseWebSocketClient } from "./websocket";
-import { RebaseClient as BaseRebaseClient, RebaseData, StorageSource } from "@rebasepro/types";
-export type { Entity, FindResponse } from "@rebasepro/types";
 type KebabToCamelCase<S extends string> = S extends `${infer T}-${infer U}` ? `${T}${Capitalize<KebabToCamelCase<U>>}` : S;
-export type RebaseClient<DB = Record<string, unknown>> = Omit<BaseRebaseClient<DB>, "data"> & {
+type TypedDataLayer<DB> = {
+    collection<S extends string>(slug: S): CollectionClient<KebabToCamelCase<S> extends keyof DB ? (DB[KebabToCamelCase<S>] extends {
+        Row: infer R extends Record<string, unknown>;
+    } ? R : Record<string, unknown>) : Record<string, unknown>>;
+} & {
+    [K in keyof DB]: CollectionClient<DB[K] extends {
+        Row: infer R extends Record<string, unknown>;
+    } ? R : Record<string, unknown>>;
+} & RebaseData;
+/**
+ * The return type of `createRebaseClient<DB>()`.
+ *
+ * This is `RebaseClient` (from `@rebasepro/types`) with all optional
+ * capabilities populated and the `data` layer narrowed to provide
+ * typed collection accessors when a `DB` schema generic is supplied.
+ */
+export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<RebaseClient, "data"> & {
     setToken: (token: string | null) => void;
     setAuthTokenGetter: (getter: () => Promise<string | null>) => void;
     setOnUnauthorized: (handler: () => Promise<boolean>) => void;
@@ -31,18 +47,10 @@ export type RebaseClient<DB = Record<string, unknown>> = Omit<BaseRebaseClient<D
     auth: ReturnType<typeof createAuth>;
     admin: ReturnType<typeof createAdmin>;
     cron: ReturnType<typeof createCron>;
-    functions: FunctionsClient;
+    functions: ReturnType<typeof createFunctionsClient>;
     ws?: RebaseWebSocketClient;
-    storage?: StorageSource;
+    storage: StorageSource;
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
-    data: {
-        collection<S extends string>(slug: S): CollectionClient<KebabToCamelCase<S> extends keyof DB ? (DB[KebabToCamelCase<S>] extends {
-            Row: infer R extends Record<string, unknown>;
-        } ? R : Record<string, unknown>) : Record<string, unknown>>;
-    } & {
-        [K in keyof DB]: CollectionClient<DB[K] extends {
-            Row: infer R extends Record<string, unknown>;
-        } ? R : Record<string, unknown>>;
-    } & RebaseData;
+    data: TypedDataLayer<DB>;
 };
-export declare function createRebaseClient<DB = Record<string, unknown>>(options: CreateRebaseClientOptions): RebaseClient<DB>;
+export declare function createRebaseClient<DB = Record<string, unknown>>(options: CreateRebaseClientOptions): CreateRebaseClientResult<DB>;