@rebasepro/cli 0.4.0 → 0.6.0

package/skills/rebase-realtime/references/.gitkeep

@@ -0,0 +1,3 @@
+# References
+
+Reference documentation for the rebase-realtime skill. Add detailed reference files here.

package/skills/rebase-sdk/SKILL.md

@@ -0,0 +1,594 @@
+---
+name: rebase-sdk
+description: Guide for using the Rebase generated TypeScript SDK and client library. Use this skill when the user needs to interact with a Rebase backend from client-side or server-side code, including CRUD operations, filtering, authentication, realtime subscriptions, file storage, custom functions, or admin operations.
+---
+
+# Rebase SDK
+
+The Rebase SDK consists of two packages that work together to provide end-to-end type-safe access to a Rebase backend:
+
+- **`@rebasepro/client`** — The runtime client with CRUD, auth, realtime, storage, and more
+- **SDK Generator** — Generates TypeScript types from your collection definitions (via CLI or MCP tool)
+
+The generated types are passed as a generic parameter to the client, providing full type safety across all operations.
+
+> **IMPORTANT FOR AGENTS:** Always generate the SDK types first before writing client code. Use the `rebase_generate_sdk` MCP tool or `npx rebase generate-sdk` CLI command. The generated types live at `./generated/sdk/database.types.ts` relative to the project root.
+
+## SDK Generation
+
+### How to Generate
+
+**Via MCP tool (preferred):**
+
+Use the `rebase_generate_sdk` MCP tool — no parameters required. It reads collections from `./config/collections` and writes the output to `./generated/sdk/`.
+
+**Via CLI:**
+
+```bash
+npx rebase generate-sdk
+```
+
+### What Gets Generated
+
+A single `database.types.ts` file containing:
+
+| Export | Description |
+|--------|-------------|
+| `Database` | Interface with a key per collection, each containing `Row`, `Insert`, and `Update` sub-types |
+| `CollectionName` | Union type of all collection slug strings |
+| `CollectionsDictionary` | Runtime constant mapping camelCase names to snake_case slugs |
+
+**Sub-type semantics:**
+
+| Sub-type | Purpose | ID fields | Required fields |
+|----------|---------|-----------|-----------------|
+| `Row` | Read type — what you get back from queries | Required | All present |
+| `Insert` | Create type — for new records | Optional (auto-generated) | Required fields stay required |
+| `Update` | Partial update type | N/A | All optional |
+
+### Property Type Mapping
+
+| Rebase Type | TypeScript Type |
+|-------------|-----------------|
+| `string` | `string` (or string literal union if `enum` defined) |
+| `number` | `number` (or number literal union if `enum` defined) |
+| `boolean` | `boolean` |
+| `date` | `string` (ISO 8601) |
+| `geopoint` | `{ latitude: number; longitude: number }` |
+| `reference` | `string \| number` |
+| `map` | Nested `{ ... }` or `Record<string, any>` |
+| `array` | `Array<T>` or `Array<any>` |
+| `vector` | `number[]` |
+| `binary` | `string` |
+
+Relations are typed as `{ id: string; path: string; __type: "relation"; data?: RelatedRow }`.
+
+## Client Initialization
+
+```typescript
+import { createRebaseClient } from '@rebasepro/client';
+import type { Database } from './generated/sdk/database.types';
+
+const rebase = createRebaseClient<Database>({
+    baseUrl: 'http://localhost:3001',
+});
+```
+
+### Typed SDK Return Type
+
+The `createRebaseClient<DB>()` factory returns a reconciled client type of `CreateRebaseClientResult<DB>` (which extends the base `RebaseClient` from `@rebasepro/types`). 
+
+Passing your generated `Database` type maps camelCase collection names (e.g. `posts`) to their database schemas (`Row`, `Insert`, and `Update` types), providing autocomplete and type safety across the entire `data` layer.
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | — | Backend URL (required) |
+| `token` | `string` | — | Static JWT token (e.g., service key for server-side scripts) |
+| `apiPath` | `string` | `'/api'` | API path prefix |
+| `websocketUrl` | `string` | Auto-derived from `baseUrl` | WebSocket URL for realtime |
+| `fetch` | `typeof fetch` | Global `fetch` | Custom fetch implementation |
+| `onUnauthorized` | `() => void` | — | Handler called on 401 responses |
+
+### Server-Side Usage
+
+For server-side scripts or service-to-service calls, pass a service key as the `token`:
+
+```typescript
+const rebase = createRebaseClient<Database>({
+    baseUrl: 'https://api.myapp.com',
+    token: process.env.REBASE_SERVICE_KEY,
+});
+```
+
+## CRUD Operations
+
+> **IMPORTANT FOR AGENTS:** There are two access patterns for collections. Both are fully typed when using the `Database` generic. Prefer the property-style access for better readability.
+
+### Access Patterns
+
+```typescript
+// 1. Property-style access (camelCase — auto-converted to snake_case slug)
+const { data: posts } = await rebase.data.posts.find();
+
+// 2. Collection method (explicit slug)
+const { data: posts } = await rebase.data.collection('posts').find();
+```
+
+### Available Operations
+
+| Method | Signature | Returns | Description |
+|--------|-----------|---------|-------------|
+| `find` | `find(params?)` | `{ data: Entity[], meta }` | List documents with filtering/pagination |
+| `findById` | `findById(id)` | `Entity \| undefined` | Get a single document by ID |
+| `create` | `create(data, id?)` | `Entity` | Create a new document |
+| `update` | `update(id, data)` | `Entity` | Update an existing document |
+| `delete` | `delete(id)` | `void` | Delete a document |
+| `count` | `count(params?)` | `number` | Count matching documents |
+
+### Examples
+
+```typescript
+// Create
+const post = await rebase.data.posts.create({
+    title: 'Hello World',
+    status: 'draft',
+    content: 'My first post',
+});
+
+// Read
+const post = await rebase.data.posts.findById('post-123');
+
+// Update
+const updated = await rebase.data.posts.update('post-123', {
+    status: 'published',
+});
+
+// Delete
+await rebase.data.posts.delete('post-123');
+
+// Count
+const total = await rebase.data.posts.count({
+    where: { status: 'eq.published' },
+});
+```
+
+### Response Format
+
+The `find()` method returns a response with data and pagination metadata:
+
+```typescript
+const response = await rebase.data.posts.find({ limit: 20, offset: 0 });
+
+// response.data  → Entity[]
+// response.meta  → { total: number, limit: number, offset: number, hasMore: boolean }
+```
+
+## Filtering, Sorting & Pagination
+
+There are two approaches to querying: **FindParams objects** and the **fluent QueryBuilder**.
+
+### Approach 1: FindParams Object
+
+Pass a params object directly to `.find()`:
+
+```typescript
+const result = await rebase.data.posts.find({
+    limit: 20,
+    offset: 0,
+    orderBy: 'createdAt:desc',
+    searchString: 'search term',
+    include: ['tags', 'author'],   // or ['*'] for all relations
+    where: {
+        status: 'eq.published',
+        price: 'gte.100',
+        category: 'in.(electronics,books)',
+    },
+});
+```
+
+### Filter Operators (String Syntax)
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equal | `'eq.published'` |
+| `neq` | Not equal | `'neq.draft'` |
+| `gt` | Greater than | `'gt.100'` |
+| `gte` | Greater than or equal | `'gte.100'` |
+| `lt` | Less than | `'lt.50'` |
+| `lte` | Less than or equal | `'lte.50'` |
+| `in` | In list | `'in.(electronics,books)'` |
+| `nin` | Not in list | `'nin.(archived,deleted)'` |
+| `cs` | Array contains | `'cs.tag1'` |
+| `csa` | Array contains any | `'csa.(tag1,tag2)'` |
+
+### Approach 2: Fluent QueryBuilder
+
+Chain methods for a more readable query API:
+
+```typescript
+const result = await rebase.data.posts
+    .where('status', '==', 'published')
+    .where('price', '>=', 100)
+    .orderBy('createdAt', 'desc')
+    .limit(20)
+    .offset(0)
+    .search('keyword')
+    .include('tags', 'author')
+    .find();
+```
+
+### Complex Logical Conditions
+
+Use `or`, `and`, and `cond` helpers for complex filters:
+
+```typescript
+import { or, and, cond } from '@rebasepro/client';
+
+const result = await rebase.data.posts
+    .where(or(
+        cond('status', '==', 'published'),
+        and(
+            cond('status', '==', 'draft'),
+            cond('authorId', '==', currentUserId)
+        )
+    ))
+    .find();
+```
+
+### QueryBuilder Methods
+
+| Method | Description |
+|--------|-------------|
+| `.where(field, op, value)` | Add a filter condition |
+| `.where(logicalCondition)` | Add complex `or`/`and`/`cond` filter |
+| `.orderBy(field, direction?)` | Sort results (`'asc'` or `'desc'`) |
+| `.limit(n)` | Limit number of results |
+| `.offset(n)` | Skip first `n` results |
+| `.search(term)` | Full-text search |
+| `.include(...relations)` | Include related entities |
+| `.find()` | Execute the query |
+| `.listen(callback, errorCallback?)` | Subscribe to realtime updates |
+
+## Authentication
+
+### Email / Password
+
+```typescript
+// Sign up
+await rebase.auth.signUp('user@example.com', 'password', 'Display Name');
+
+// Sign in
+await rebase.auth.signInWithEmail('user@example.com', 'password');
+
+// Sign out
+await rebase.auth.signOut();
+```
+
+### OAuth Providers
+
+Twelve providers are supported with dedicated methods:
+
+```typescript
+// Google (ID token or authorization code flow)
+await rebase.auth.signInWithGoogle({ idToken });
+await rebase.auth.signInWithGoogle({ code, redirectUri });
+
+// GitHub, Microsoft, Apple, Facebook, Twitter, Discord,
+// GitLab, Bitbucket, Slack, Spotify, LinkedIn
+await rebase.auth.signInWithGitHub(code, redirectUri);
+await rebase.auth.signInWithMicrosoft(code, redirectUri);
+await rebase.auth.signInWithApple(code, redirectUri);
+// ... same pattern for all providers
+
+// Generic OAuth (for custom providers)
+await rebase.auth.signInWithOAuth('custom-provider', payload);
+```
+
+### Session Management
+
+```typescript
+// Get current session
+const session = rebase.auth.getSession();
+
+// Get current user
+const user = await rebase.auth.getUser();
+
+// Refresh session manually
+await rebase.auth.refreshSession();
+
+// Update user profile
+await rebase.auth.updateUser({ displayName: 'New Name' });
+
+// List active sessions
+const sessions = await rebase.auth.getSessions();
+
+// Revoke sessions
+await rebase.auth.revokeSession(sessionId);
+await rebase.auth.revokeAllSessions();
+```
+
+### Password Management
+
+```typescript
+// Forgot password flow
+await rebase.auth.resetPasswordForEmail('user@example.com');
+await rebase.auth.resetPassword(token, newPassword);
+
+// Change password (while logged in)
+await rebase.auth.changePassword(oldPassword, newPassword);
+```
+
+### Email Verification
+
+```typescript
+await rebase.auth.sendVerificationEmail();
+await rebase.auth.verifyEmail(token);
+```
+
+### Auth State Listener
+
+```typescript
+const unsubscribe = rebase.auth.onAuthStateChange((event, session) => {
+    // event: 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'USER_UPDATED'
+    console.log('Auth event:', event);
+});
+
+// Clean up
+unsubscribe();
+```
+
+**Session behavior:**
+- Sessions are persisted to `localStorage` by default (configurable: `localStorage`, `memoryStorage`, `cookieStorage`)
+- Tokens auto-refresh 120 seconds before expiry
+- All requests automatically include the auth token
+- On 401 responses, the client auto-refreshes the session and retries the request
+
+## Realtime Subscriptions
+
+### Listen to Collection Changes
+
+```typescript
+// Via CollectionClient
+const unsubscribe = rebase.data.posts.listen(
+    { where: { status: 'published' }, limit: 50 },
+    (response) => {
+        // response: FindResponse with updated data
+        console.log('Updated posts:', response.data);
+    },
+    (error) => {
+        console.error('Subscription error:', error);
+    }
+);
+```
+
+### Listen to a Single Entity
+
+```typescript
+const unsubscribe = rebase.data.posts.listenById(
+    'post-123',
+    (entity) => {
+        // entity: Entity | undefined
+        console.log('Post updated:', entity);
+    },
+    (error) => {
+        console.error('Error:', error);
+    }
+);
+```
+
+### Listen via QueryBuilder
+
+```typescript
+const unsubscribe = rebase.data.posts
+    .where('status', '==', 'published')
+    .orderBy('createdAt', 'desc')
+    .limit(20)
+    .listen((response) => {
+        console.log('Realtime updates:', response.data);
+    });
+```
+
+### WebSocket Events
+
+```typescript
+rebase.ws?.on('connect', () => { console.log('Connected'); });
+rebase.ws?.on('disconnect', () => { console.log('Disconnected'); });
+rebase.ws?.on('reconnect', () => { console.log('Reconnected'); });
+rebase.ws?.on('error', (err) => { console.error('WS error:', err); });
+
+// Disconnect manually
+rebase.ws?.disconnect();
+```
+
+**Realtime features:**
+- Auto-reconnect with exponential backoff (max 5 attempts)
+- Subscription deduplication
+- Client-side entity caching with structural merge
+- Instant entity patches across subscriptions
+- Auto-authentication and re-authentication on token refresh
+
+## File Storage
+
+```typescript
+// Upload file
+const result = await rebase.storage.putObject({
+    file: fileBlob,        // File or Blob
+    key: 'path/to/file',   // Optional custom key
+    bucket: 'my-bucket',   // Optional bucket
+    metadata: { ... },     // Optional metadata
+});
+
+// Get signed download URL
+const { url, metadata } = await rebase.storage.getSignedUrl('path/to/file', 'bucket');
+
+// Download file
+const file = await rebase.storage.getObject('path/to/file', 'bucket');
+
+// Delete file
+await rebase.storage.deleteObject('path/to/file', 'bucket');
+
+// List files
+const { items, nextPageToken } = await rebase.storage.listObjects('prefix/', {
+    bucket: 'my-bucket',
+    maxResults: 100,
+    pageToken: 'next-page-token',
+});
+```
+
+## Custom Functions
+
+Invoke custom server-side functions defined in the backend:
+
+```typescript
+// Basic invocation
+const result = await rebase.functions.invoke<{ job: Job }>('extract-job', {
+    url: 'https://example.com/posting',
+    html: htmlContent,
+});
+
+// With additional options
+await rebase.functions.invoke('my-function', payload, {
+    method: 'GET',
+    path: 'sub-path/123',
+    headers: { 'X-Custom': 'value' },
+});
+```
+
+## Admin Operations
+
+> **IMPORTANT FOR AGENTS:** Admin operations require a service key or admin-level JWT token. These should only be used in server-side scripts or admin panels — never expose them in client-side code.
+
+```typescript
+// List users
+const users = await rebase.admin.listUsers();
+
+// Paginated user listing
+const result = await rebase.admin.listUsersPaginated({
+    search: 'john',
+    limit: 20,
+    offset: 0,
+    orderBy: 'createdAt',
+    orderDir: 'desc',
+});
+
+// CRUD operations
+const user = await rebase.admin.getUser(userId);
+const newUser = await rebase.admin.createUser({
+    email: 'new@example.com',
+    displayName: 'New User',
+    password: 'securePassword',
+    roles: ['editor'],
+});
+await rebase.admin.updateUser(userId, { displayName: 'Updated Name', roles: ['admin'] });
+await rebase.admin.deleteUser(userId);
+
+// Bootstrap (initial admin setup)
+await rebase.admin.bootstrap();
+```
+
+## Cron Jobs
+
+Manage scheduled background tasks from the client:
+
+```typescript
+// List all cron jobs
+const jobs = await rebase.cron.listJobs();
+
+// Get a specific job
+const job = await rebase.cron.getJob(jobId);
+
+// Trigger a job manually
+await rebase.cron.triggerJob(jobId);
+
+// Get job execution logs
+const logs = await rebase.cron.getJobLogs(jobId, { limit: 50 });
+
+// Enable/disable a job
+await rebase.cron.toggleJob(jobId, true);   // enable
+await rebase.cron.toggleJob(jobId, false);  // disable
+```
+
+## Generic Endpoint Call
+
+Call any custom API endpoint directly:
+
+```typescript
+const result = await rebase.call<MyResponseType>('/my-endpoint', payload);
+```
+
+## React Integration Example
+
+A common pattern for using the SDK in a React application:
+
+```typescript
+// src/client.ts
+import { createRebaseClient } from '@rebasepro/client';
+import type { Database } from './generated/sdk/database.types';
+
+const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:3001';
+export const rebase = createRebaseClient<Database>({ baseUrl: API_URL });
+```
+
+```typescript
+// src/hooks/useCollection.ts
+import { useState, useEffect } from 'react';
+import { rebase } from '../client';
+
+export function useCollection<T extends keyof Database>(
+    slug: T,
+    options?: { limit?: number; where?: Record<string, string> }
+) {
+    const [data, setData] = useState<Database[T]['Row'][]>([]);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        const unsubscribe = rebase.data.collection(slug).listen(
+            { limit: options?.limit, where: options?.where },
+            (response) => {
+                setData(response.data);
+                setLoading(false);
+            }
+        );
+        return unsubscribe;
+    }, [slug]);
+
+    return { data, loading };
+}
+```
+
+```typescript
+// src/hooks/useAuth.ts
+import { useState, useEffect } from 'react';
+import { rebase } from '../client';
+
+export function useAuth() {
+    const [user, setUser] = useState(null);
+
+    useEffect(() => {
+        const unsubscribe = rebase.auth.onAuthStateChange((event, session) => {
+            setUser(session?.user ?? null);
+        });
+        return unsubscribe;
+    }, []);
+
+    return {
+        user,
+        signIn: (email: string, password: string) =>
+            rebase.auth.signInWithEmail(email, password),
+        signUp: (email: string, password: string, name: string) =>
+            rebase.auth.signUp(email, password, name),
+        signOut: () => rebase.auth.signOut(),
+    };
+}
+```
+
+## References
+
+- **Documentation:** [rebase.pro/docs](https://rebase.pro/docs)
+- **GitHub:** [github.com/rebasepro/rebase](https://github.com/rebasepro/rebase)
+- **Client package source:** `packages/client/src/`
+- **SDK generator source:** `packages/sdk-generator/src/`
+- **QueryBuilder source:** `packages/common/src/data/query_builder.ts`
+- **SDK demo example:** `examples/sdk-demo/`