@rebasepro/types 0.4.0 → 0.6.0

package/README.md

@@ -1,242 +1,93 @@
-<p align="center">
-  <a href="https://rebase.pro">
-    <img src="https://rebase.pro/img/logo_small.png" width="240px" alt="Rebase logo" />
-  </a>
-</p>
+# @rebasepro/types
 
-<h1 align="center">Rebase</h1>
-<h3 align="center">The Open-Source Headless CMS & Admin Panel for Postgres</h3>
-<p align="center">
-  <strong>Ship production-ready backends and radically extensible back-office apps in minutes.</strong><br/>
-  Own your data, own your code. The absolute easiest way to build on PostgreSQL.
-</p>
+Shared TypeScript type definitions and interfaces for the Rebase ecosystem.
 
-<p align="center">
-  <a href="https://demo.rebase.pro">Live Demo</a> •
-  <a href="https://rebase.pro/docs">Documentation</a> •
-  <a href="https://rebase.pro/features">Features</a> •
-  <a href="https://github.com/rebasepro/rebase">GitHub</a> •
-  <a href="https://discord.gg/fxy7xsQm3m">Discord</a>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@rebasepro/core"><img src="https://img.shields.io/npm/v/@rebasepro/core.svg?style=flat-square&color=orange" alt="NPM Version" /></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-purple.svg?style=flat-square" alt="License: MIT" /></a>
-  <a href="https://www.npmjs.com/package/@rebasepro/core"><img src="https://img.shields.io/npm/dw/@rebasepro/core?style=flat-square&color=blue" alt="NPM Downloads" /></a>
-  <a href="https://discord.gg/fxy7xsQm3m"><img src="https://img.shields.io/discord/1013768502458470442?style=flat-square&logo=discord&logoColor=white&label=Discord" alt="Discord" /></a>
-</p>
-
-<br/>
-
-<p align="center">
-  <img src="https://rebase.pro/img/demo_products.png" width="800px" alt="Rebase Dashboard" />
-</p>
-
----
-
-## What is Rebase?
-
-Rebase is a **developer-first**, open-source headless CMS and admin panel framework built with **React** and **TypeScript**. It gives you a complete backend-as-a-service layer on top of PostgreSQL — including authentication, S3-compatible storage, a full admin UI, and auto-generated APIs — while letting you extend every layer with custom React components, serverless functions, and scripts.
-
-### ✨ Key Highlights
-
-- 🔓 **No Vendor Lock-in** — Self-host anywhere. Full control over your infrastructure, code, and database.
-- ⚡ **Instant Setup** — `npx @rebasepro/cli init` scaffolds a production-ready project in seconds.
-- 🗄️ **PostgreSQL First** — First-class Postgres support with Drizzle ORM, schema introspection, and automatic migrations.
-- 🧩 **Radical Extensibility** — Not constrained to pre-built widgets. If you can build it in React, you can build it in Rebase.
-- 🎨 **Premium UI** — Fast, accessible design system built on Tailwind CSS v4 and Radix UI.
-- 🤖 **AI-Ready** — MCP server for AI-assisted database management, plus data enhancement and insights plugins.
-
----
-
-## ⚡ Quick Start
-
-Scaffold a complete, self-hosted Rebase application connected to your database:
+## Installation
 
 ```bash
-npx @rebasepro/cli init my-rebase-app
+pnpm add @rebasepro/types
 ```
 
-Configure your database in `.env`, then start everything:
-
-```bash
-cd my-rebase-app
-npm run dev
+## What This Package Does
+
+Provides the canonical type definitions used across all Rebase packages — both client-side and server-side. This is a **types-only** package with no runtime dependencies. Every other `@rebasepro/*` package depends on it.
+
+## Key Exports
+
+### Collection & Entity Types
+
+| Export | Description |
+|--------|-------------|
+| `EntityCollection` | Full collection definition (name, slug, properties, callbacks, security rules, views) |
+| `Property` | Union type for all property configurations (text, number, date, reference, array, map, etc.) |
+| `Entity` | Generic entity record type |
+| `EntityCallbacks` | Lifecycle hooks (`onPreSave`, `onSaveSuccess`, `onDelete`, etc.) |
+| `EntityValues` | Record of property values for an entity |
+| `SecurityRule` | RLS-style access control rule for a collection |
+
+### Backend & Driver Interfaces
+
+| Export | Description |
+|--------|-------------|
+| `DataDriver` | Abstract interface for database drivers (`fetchCollection`, `saveEntity`, `deleteEntity`, etc.) |
+| `DatabaseAdapter` | Pluggable database adapter interface (used by `server-core`) |
+| `BackendBootstrapper` | Lifecycle interface for initializing database drivers, auth, history, and realtime |
+| `DatabaseAdmin` | Admin operations interface (SQL execution, collection stats, table metadata) |
+| `RealtimeProvider` | Interface for realtime subscription providers |
+| `BackendConfig` / `BackendInstance` | Abstract backend configuration and instance types |
+| `HealthCheckResult` | Return type for health check operations |
+| `InitializedDriver` | Result of driver initialization (driver, realtime, registry, internals) |
+| `BootstrappedAuth` | Result of auth initialization (user service, role service, email service) |
+
+### Auth & User Types
+
+| Export | Description |
+|--------|-------------|
+| `AuthAdapter` | Pluggable auth adapter interface (for Clerk, Auth0, custom auth) |
+| `AuthController` | Client-side auth controller interface |
+| `RebaseUser` | User record type |
+| `Role` | Role definition type |
+
+### Controller Interfaces
+
+| Export | Description |
+|--------|-------------|
+| `RebaseClient` | Top-level client interface (data, auth, storage, email) |
+| `DataSourceDelegate` | Data operations interface for client-side data sources |
+| `StorageSource` | File storage interface |
+| `CollectionRegistryInterface` | Collection lookup and registration |
+| `NavigationController` | App navigation interface |
+
+### Other
+
+| Export | Description |
+|--------|-------------|
+| `CronJobDefinition` | Cron job configuration type |
+| `BackendHooks` | Server-side hooks for intercepting admin data |
+| `PluginConfig` | Plugin system types |
+| `WebSocketMessage` | WebSocket protocol message types |
+| `Locale` | Localization types |
+
+## Quick Start
+
+```typescript
+import type {
+  EntityCollection,
+  DataDriver,
+  DatabaseAdapter,
+  RebaseUser,
+  Property,
+} from "@rebasepro/types";
 ```
 
-Your admin panel is running at `http://localhost:5173` and the API at `http://localhost:3001`.
-
----
-
-## Features
-
-### 🏓 Full Admin Panel & CMS
-
-An incredibly fast, windowed spreadsheet view to manage your database with inline editing, real-time updates, filtering, sorting, and text search. Switch between multiple view modes:
-
-- **Spreadsheet table** — Inline editing, column reordering, drag-and-drop
-- **Card grid** — Visual overview with image previews
-- **List view** — Compact, scannable layout
-- **Custom views** — Build any React component as a collection view
-
-### 🔒 Typed Schema & Database Migrations
-
-Define your data models using pure TypeScript collections. Rebase automatically generates your Drizzle ORM schema, handles PostgreSQL migrations, and keeps your live database perfectly in sync using built-in tooling like `rebase doctor`.
-
-### 🔐 Authentication & Access Control
-
-Built-in authentication with multiple providers:
-
-- **Email/Password** — With password reset flow
-- **Google OAuth** — One-click sign-in
-- **Anonymous** — For guest access
-
-Granular **role-based access control (RBAC)** with customizable permissions per collection, field, and action.
-
-### 📦 S3-Compatible Storage
-
-Native S3-compatible file storage with:
-
-- Drag-and-drop uploads with progress tracking
-- Automatic image resizing and optimization
-- File metadata management
-- Storage browser in Studio
-
-### 🛠️ Studio — Developer Toolbox
-
-A full developer environment built into the admin panel:
-
-| Tool | Description |
-|---|---|
-| **SQL Editor** | Write and execute SQL queries directly against your database with schema-aware autocomplete |
-| **RLS Policy Editor** | Visual editor for PostgreSQL Row-Level Security policies |
-| **Schema Visualizer** | Interactive ER diagram of your database with relationship mapping |
-| **JS/TS Editor** | In-browser code editor for scripts and functions |
-| **API Explorer** | Browse and test your auto-generated REST API endpoints |
-| **Cron Jobs** | Schedule and monitor recurring tasks |
-| **Storage Browser** | Browse and manage files in your S3-compatible storage |
-
-### ⚡ Extensible API & Edge Functions
-
-Drop custom Hono routes or scheduled tasks into the `functions/` and `crons/` directories. Rebase auto-loads them with database access and JWT authentication middleware injected automatically.
-
-### 🧬 SDK Generator
-
-Auto-generate fully typed **TypeScript SDKs** from your collection definitions. Use them in any frontend, script, or service to interact with your Rebase backend with complete type safety.
-
-```bash
-npx @rebasepro/cli generate-sdk
-```
-
-### 🤖 MCP Server
-
-A built-in **Model Context Protocol** server that enables AI assistants to:
-
-- Query and manage your database schema
-- Create, read, update, and delete documents
-- Manage users and roles
-- Introspect your data model
-
-### 🔍 Schema Inference & Introspection
-
-Point Rebase at an existing PostgreSQL database and automatically generate collection definitions from your tables — including types, relations, validation constraints, and more.
-
-### 📥📤 Import & Export
-
-Import data from **CSV, JSON, and Excel** with an intuitive field mapper. Export your data in multiple formats with configurable column selection.
-
-### 🧩 Plugins
-
-Extend the admin experience with first-party plugins:
-
-- **Data Enhancement** — AI-powered field suggestions and auto-fill
-- **Insights** — Analytics dashboards and usage metrics
-
-### 📜 Standalone Scripting
-
-Write standalone data manipulation scripts that connect directly to your running backend using the `@rebasepro/client` SDK. The CLI persists the dev server URL to `.rebase-dev-url` for zero-config local development.
-
-### 🧩 Custom Views & React Extensibility
-
-Build entirely custom views — dashboards, previews, charts — and drop them into the main navigation or as entity-level tabs. Use built-in hooks to interact with Rebase's internal state.
-
----
-
-## 🛠️ Core Technologies
-
-Built entirely on modern, battle-tested web standards:
-
-| Technology | What we use it for |
-|---|---|
-| 💙 **TypeScript 5.x** | End-to-end type safety |
-| ⚛️ **React 19** | Component-driven UI |
-| 🌊 **Tailwind CSS v4** | Utility-first styling |
-| 🔌 **WebSockets** | Real-time synchronization |
-| 🗄️ **Drizzle ORM** | Type-safe SQL migrations and queries |
-| 🧱 **Radix UI** | Accessible UI primitives |
-| 📝 **TipTap v3** | Rich text editing |
-| 🌐 **Hono** | Ultrafast HTTP server framework |
-
----
-
-## 📦 Packages
-
-Rebase is structured as a modular monorepo — install only the layers you need:
-
-| Package | Description |
-|---|---|
-| `@rebasepro/types` | Core TypeScript type definitions |
-| `@rebasepro/utils` | Shared utility functions |
-| `@rebasepro/common` | Common modules shared across packages |
-| `@rebasepro/formex` | Lightweight form management library |
-| `@rebasepro/ui` | Standalone React component library (Tailwind + Radix) |
-| `@rebasepro/core` | Core CMS logic and controllers |
-| `@rebasepro/client` | Client-side data access layer |
-| `@rebasepro/client-postgresql` | PostgreSQL client adapter |
-| `@rebasepro/client-firebase` | Firebase/Firestore client adapter |
-| `@rebasepro/server-core` | Server framework and middleware (Hono) |
-| `@rebasepro/server-postgresql` | PostgreSQL server adapter with Drizzle |
-| `@rebasepro/server-mongodb` | MongoDB server adapter |
-| `@rebasepro/auth` | Authentication controllers and login views |
-| `@rebasepro/admin` | Full admin panel interface |
-| `@rebasepro/studio` | SQL editor, RLS editor, schema visualizer, API explorer |
-| `@rebasepro/cli` | CLI for project scaffolding and management |
-| `@rebasepro/sdk-generator` | TypeScript SDK code generation |
-| `@rebasepro/mcp-server` | MCP server for AI integrations |
-| `@rebasepro/schema-inference` | Database schema introspection and inference |
-| `@rebasepro/plugin-data-enhancement` | AI-powered data enhancement plugin |
-| `@rebasepro/plugin-insights` | Analytics and insights plugin |
-
----
-
-## 🎨 Standalone UI Library
-
-Rebase exposes its design system as a completely independent library. Fully typed, accessible, and customizable via Tailwind CSS v4:
-
-```bash
-npm install @rebasepro/ui
-```
-
----
-
-## Demo
-
-Explore a live interactive sandbox with all features — data resets periodically:
-
-**👉 [demo.rebase.pro](https://demo.rebase.pro)**
-
----
-
-## Support & Community
-
-- 📖 [Documentation](https://rebase.pro/docs)
-- 💬 [Discord Community](https://discord.gg/fxy7xsQm3m)
-- 🐛 [GitHub Issues](https://github.com/rebasepro/rebase/issues)
-- 📝 [Changelog](./CHANGELOG.md)
-
----
+## Related Packages
 
-## License
+Every `@rebasepro/*` package depends on this one. Key consumers:
 
-Rebase is open-source and licensed under the **MIT License**.
-See the full [License](https://github.com/rebasepro/rebase/blob/main/LICENSE) for details.
+| Package | Uses |
+|---------|------|
+| `@rebasepro/server-core` | `DataDriver`, `DatabaseAdapter`, `BackendBootstrapper`, `AuthAdapter` |
+| `@rebasepro/server-postgresql` | `BackendBootstrapper`, `InitializedDriver`, `RealtimeProvider` |
+| `@rebasepro/server-mongodb` | `BackendBootstrapper`, `DataDriver`, `EntityCollection` |
+| `@rebasepro/client` | `RebaseClient`, `DataSourceDelegate`, `StorageSource` |
+| `@rebasepro/admin` | `EntityCollection`, `Property`, `PluginConfig`, controller interfaces |

package/dist/controllers/client.d.ts

@@ -1,6 +1,8 @@
 import type { User } from "../users";
 import type { RebaseData } from "./data";
 import type { EmailService } from "./email";
+import type { StorageSource } from "./storage";
+import type { CronJobStatus, CronJobLogEntry } from "../types/cron";
 /**
  * Event type for authentication state changes
  */
@@ -14,7 +16,6 @@ export interface RebaseSession {
     expiresAt: number;
     user: User;
 }
-import type { StorageSource } from "./storage";
 /**
  * Unified Authentication Client Interface
  * Pure functional SDK interface, decoupled from UI and React hooks
@@ -111,8 +112,65 @@ export interface AdminAPI {
     }>;
 }
 /**
- * Overarching abstraction that unites Data, Auth, Storage, and Email.
- * Adapters for Supabase or Firebase simply need to implement this interface.
+ * Client-side Cron job management interface.
+ * @group Cron
+ */
+export interface CronAPI {
+    listJobs(): Promise<{
+        jobs: CronJobStatus[];
+    }>;
+    getJob(jobId: string): Promise<{
+        job: CronJobStatus;
+    }>;
+    triggerJob(jobId: string): Promise<{
+        log: CronJobLogEntry;
+        job: CronJobStatus;
+    }>;
+    getJobLogs(jobId: string, options?: {
+        limit?: number;
+    }): Promise<{
+        logs: CronJobLogEntry[];
+    }>;
+    toggleJob(jobId: string, enabled: boolean): Promise<{
+        job: CronJobStatus;
+    }>;
+}
+/**
+ * Options for invoking a custom backend function.
+ * @group Functions
+ */
+export interface FunctionInvokeOptions {
+    /** HTTP method — defaults to `"POST"`. */
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Sub-path appended after the function name. */
+    path?: string;
+    /** Extra headers merged into the request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Client interface for invoking custom backend functions.
+ * @group Functions
+ */
+export interface FunctionsAPI {
+    /**
+     * Invoke a custom backend function by name.
+     *
+     * @typeParam T - Expected shape of the response payload.
+     * @param name    - Function name (filename without extension, e.g. `"extract-job"`).
+     * @param payload - Optional JSON-serialisable body sent as POST.
+     * @param options - Optional overrides (method, sub-path, headers).
+     */
+    invoke<T = unknown>(name: string, payload?: unknown, options?: FunctionInvokeOptions): Promise<T>;
+}
+/**
+ * The single, canonical Rebase client interface.
+ *
+ * Used everywhere: the server-side `rebase` singleton, the SDK's
+ * `createRebaseClient()`, React context, cron job context, etc.
+ *
+ * Core fields (`data`, `auth`) are always present. Everything else
+ * is optional — which capabilities are populated depends on the
+ * runtime environment and adapter.
  */
 export interface RebaseClient<DB = unknown> {
     /** Unified Data access layer */
@@ -123,43 +181,32 @@ export interface RebaseClient<DB = unknown> {
     storage?: StorageSource;
     /**
      * Server-side email service.
-     *
-     * Available when SMTP (or a custom `sendEmail` function) is configured
-     * in the backend auth config. `undefined` when email is not configured.
-     *
-     * > **Note:** This is only available on the server-side `rebase` singleton.
-     * > The client-side SDK does not include an email service.
+     * Available when SMTP or a custom `sendEmail` function is configured.
      */
     email?: EmailService;
     /** Admin API for user management */
     admin?: AdminAPI;
-    /**
-     * The base HTTP URL of the backend server.
-     * Exposed by the SDK client (`@rebasepro/client`) and used to auto-derive
-     * the `ApiConfigProvider` URL.
-     */
+    /** Cron job management API */
+    cron?: CronAPI;
+    /** Custom backend functions API */
+    functions?: FunctionsAPI;
+    /** Base HTTP URL of the backend server */
     baseUrl?: string;
-    /**
-     * WebSocket client for realtime subscriptions and admin capabilities.
-     * Exposed by the SDK client (`@rebasepro/client`). The shape is intentionally
-     * left as `unknown` in the base interface — callers should narrow via feature
-     * detection (e.g. `typeof ws.executeSql === "function"`).
-     */
+    /** WebSocket client for realtime subscriptions */
     ws?: unknown;
+    /** Set the auth token for subsequent requests */
+    setToken?(token: string | null): void;
+    /** Set a function that lazily resolves the auth token */
+    setAuthTokenGetter?(getter: () => Promise<string | null>): void;
+    /** Set handler called when a request returns 401 */
+    setOnUnauthorized?(handler: () => Promise<boolean>): void;
+    /** Resolve the current auth token */
+    resolveToken?(): Promise<string | null>;
+    /** Make a raw HTTP call to the backend */
+    call?<T = unknown>(endpoint: string, payload?: unknown): Promise<T>;
     /**
      * Execute raw SQL against the database.
-     *
-     * Only available server-side when the backend uses a SQL database
-     * (PostgreSQL, MySQL, etc.). `undefined` for document databases
-     * (MongoDB, Firestore) and on the client-side SDK.
-     *
-     * @example
-     * ```typescript
-     * // In a cron job or custom function:
-     * if (ctx.client.sql) {
-     *     const rows = await ctx.client.sql("SELECT count(*) FROM orders");
-     * }
-     * ```
+     * Only available server-side with a SQL database.
      */
     sql?(query: string, options?: {
         database?: string;

package/dist/controllers/customization_controller.d.ts

@@ -1,4 +1,3 @@
-import React from "react";
 import type { EntityLinkBuilder } from "../types/entity_link_builder";
 import type { Locale } from "../types/locales";
 import type { EntityAction } from "../types/entity_actions";
@@ -6,6 +5,7 @@ import type { EntityCustomView } from "../types/entity_views";
 import type { RebasePlugin } from "../types/plugins";
 import type { PropertyConfig } from "../types/property_config";
 import type { SlotContribution } from "../types/slots";
+import type { ComponentOverrideMap } from "../types/component_overrides";
 export type CustomizationController = {
     /**
      * Builder for generating utility links for entities
@@ -49,12 +49,13 @@ export type CustomizationController = {
      * the `propertyConfig` prop of a property in a collection.
      */
     propertyConfigs: Record<string, PropertyConfig>;
-    components?: {
-        /**
-         * Component to render when a reference is missing
-         */
-        missingReference?: React.ComponentType<{
-            path: string;
-        }>;
-    };
+    /**
+     * Global component overrides. Keys are component names from
+     * {@link OverridableComponentName}. Values replace the default
+     * implementation everywhere in the app.
+     *
+     * Collection-scoped overrides (set on individual collections)
+     * take precedence over global overrides.
+     */
+    components?: ComponentOverrideMap;
 };