@rebasepro/plugin-insights 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,115 @@
+# @rebasepro/plugin-insights
+
+Scorecard and KPI widget plugin for the Rebase admin panel.
+
+## Installation
+
+```bash
+pnpm add @rebasepro/plugin-insights
+```
+
+**Peer dependencies:** `react >= 19.0.0`, `react-dom >= 19.0.0`
+
+## What This Package Does
+
+This plugin injects data-driven scorecard widgets into the Rebase admin UI. You define insight definitions with custom `data()` callbacks — use the Rebase SDK, call a custom function, or hit any external API. The plugin handles caching, rendering, and slot injection.
+
+Widgets appear in three locations automatically:
+
+- **Home page header** — KPI overview cards via the `home.children.start` slot
+- **Collection list view** — Inline scorecards below the title, above the data list via `collection.insights`
+- **Home page cards** — Compact metrics auto-extracted from collection insights via `home.card.insight`
+
+Collection-level insights are the single source of truth: define once under `collections.<slug>`, and they render both in the collection view and on the home card.
+
+## Key Exports
+
+| Export | Type | Description |
+|---|---|---|
+| `useInsightsPlugin` | Hook | Creates the plugin from an `InsightsPluginConfig`. Returns a `RebasePlugin` |
+| `InsightsPluginConfig` | Type | Top-level config: `insights` (home + collections) and optional `cacheTTL` |
+| `InsightDefinition` | Type | Single insight: `id`, `title`, `data()` callback, `scorecard` config |
+| `InsightDataResult` | Type | Return type of `data()`: `{ rows: DataRow[] }` |
+| `DataRow` | Type | `Record<string, string \| number \| boolean \| null>` |
+| `ScorecardConfig` | Type | Field mapping for value, comparison, icon, dateRange |
+| `ScorecardFormat` | Type | Number formatting: style (decimal/currency/percent), notation, currency, decimals, showSign |
+| `InsightsProvider` | Component | React context provider (injected automatically by the plugin) |
+| `useInsightsEngine` | Hook | Access the insights engine from context (advanced) |
+| `InsightsCache` | Class | TTL-based cache for insight data (advanced) |
+| `useInsightsData` | Hook | Fetch and cache data for a specific insight (advanced) |
+| `InsightsScorecardView` | Component | Renders a scorecard from data + config (custom layouts) |
+| `InsightWidget` | Component | Single insight widget container (custom layouts) |
+| `InsightWidgetSkeleton` | Component | Loading placeholder for insight widgets |
+
+### `InsightsPluginConfig`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `insights.home` | `InsightDefinition[]` | — | Insights shown at the top of the home page |
+| `insights.collections` | `Record<string, InsightDefinition[]>` | — | Insights per collection slug |
+| `cacheTTL` | `number` | `60_000` | Cache TTL in milliseconds |
+
+### `ScorecardConfig`
+
+| Prop | Type | Description |
+|---|---|---|
+| `value.field` | `string` | Column name from data rows for the main value |
+| `value.format` | `ScorecardFormat` | Number formatting options |
+| `comparison.field` | `string` | Column name for comparison/delta value |
+| `comparison.format` | `ScorecardFormat` | Formatting for comparison |
+| `comparison.intent` | `"increase_is_good" \| "decrease_is_good"` | Controls green/red coloring |
+| `icon` | `string` | Icon key (e.g., `"shopping_cart"`) |
+| `dateRange` | `string` | Label text (e.g., `"Last 30 days"`) |
+
+## Quick Start
+
+```tsx
+import { useInsightsPlugin } from "@rebasepro/plugin-insights";
+
+const insightsPlugin = useInsightsPlugin({
+    cacheTTL: 120_000,
+    insights: {
+        home: [
+            {
+                id: "revenue",
+                title: "Revenue",
+                data: async () => {
+                    const res = await fetch("/api/analytics/revenue");
+                    return { rows: [await res.json()] };
+                },
+                scorecard: {
+                    value: { field: "total", format: { style: "currency", currency: "USD", notation: "compact" } },
+                    comparison: { field: "delta_pct", format: { style: "percent", decimals: 1 }, intent: "increase_is_good" },
+                    icon: "attach_money",
+                    dateRange: "Last 30 days"
+                }
+            }
+        ],
+        collections: {
+            orders: [
+                {
+                    id: "total_orders",
+                    title: "Total Orders",
+                    data: async () => {
+                        const count = await rebaseClient.data.orders.count();
+                        return { rows: [{ total: count }] };
+                    },
+                    scorecard: {
+                        value: { field: "total", format: { style: "decimal", notation: "compact" } },
+                        icon: "shopping_cart"
+                    }
+                }
+            ]
+        }
+    }
+});
+
+// Pass to your Rebase app:
+<RebaseFirebaseApp plugins={[insightsPlugin]} />
+```
+
+## Related Packages
+
+- `@rebasepro/core` — Core framework providing the plugin system
+- `@rebasepro/types` — Shared types (`RebasePlugin`, `SlotContribution`)
+- `@rebasepro/ui` — UI components used by insight widgets

package/dist/common/src/util/permissions.d.ts

@@ -1,6 +1,14 @@
-import { AuthController, Entity, EntityCollection, User } from "@rebasepro/types";
-export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
-export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>): boolean;
-export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
+import { Entity, EntityCollection, User } from "@rebasepro/types";
+/**
+ * Minimal auth context for permission checking.
+ * Only requires the user object — avoids forcing callers to construct
+ * a full AuthController just to check permissions.
+ */
+export interface AuthContext<USER extends User = User> {
+    user: USER | null;
+}
+export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
+export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>): boolean;
+export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;

package/dist/types/src/types/backend.d.ts

@@ -1,5 +1,6 @@
 import type { Entity } from "./entities";
 import type { EntityCollection, FilterValues, WhereFilterOp } from "./collections";
+import type { AuthAdapter } from "./auth_adapter";
 /**
  * Abstract database connection interface.
  * Represents a connection to any database system.
@@ -182,6 +183,24 @@ export interface RealtimeProvider {
      * Notify all relevant subscribers of an entity update
      */
     notifyEntityUpdate(path: string, entityId: string, entity: Entity | null, databaseId?: string): Promise<void>;
+    /**
+     * Called when the HTTP server is ready and listening.
+     * Useful for providers that need the server address for callbacks.
+     */
+    onServerReady?(serverInfo: {
+        port: number;
+        hostname?: string;
+    }): void;
+    /**
+     * Gracefully shut down the realtime provider.
+     * Called during server shutdown to clean up resources.
+     */
+    destroy?(): Promise<void>;
+    /**
+     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).
+     * Called during graceful shutdown before closing database connections.
+     */
+    stopListening?(): Promise<void>;
 }
 /**
  * Abstract collection registry interface.
@@ -464,6 +483,22 @@ export interface BackendBootstrapper {
      * (e.g., `"postgres"`, `"mongodb"`, `"mysql"`).
      */
     type: string;
+    /**
+     * Unique identifier for this bootstrapper instance.
+     * Used to register the driver in the driver registry.
+     * Defaults to `type` if not set.
+     */
+    id?: string;
+    /**
+     * Whether this bootstrapper provides the default driver.
+     * When true, the coordinator uses this driver as the primary one.
+     */
+    isDefault?: boolean;
+    /**
+     * Run database migrations for this driver.
+     * Called by the coordinator after all drivers are initialized.
+     */
+    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;
     /**
      * Create a DataDriver from the given config.
      * This is the only **required** method.
@@ -498,7 +533,7 @@ export interface BackendBootstrapper {
     /**
      * Initialize WebSocket server for realtime operations.
      */
-    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver").DataDriver, config?: unknown): Promise<void> | void;
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;
 }
 /**
  * Result of `BackendBootstrapper.initializeDriver()`.

package/dist/types/src/types/collections.d.ts

@@ -343,6 +343,23 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * Builder for the collection actions rendered in the toolbar
      */
     Actions?: ComponentRef<CollectionActionsProps>[];
+    /**
+     * The database table name for this collection.
+     * Automatically set for PostgreSQL collections.
+     * For non-SQL backends, this may be undefined.
+     */
+    table?: string;
+    /**
+     * Relations defined for this collection.
+     * Populated at normalization time from inline relation properties
+     * or explicit relation definitions.
+     */
+    relations?: Relation[];
+    /**
+     * Security rules for this collection (Row Level Security).
+     * When defined, the backend enforces access control policies.
+     */
+    securityRules?: SecurityRule[];
 }
 /**
  * A collection backed by PostgreSQL (or any SQL database).
@@ -436,7 +453,10 @@ export interface MongoDBCollection<M extends Record<string, unknown> = Record<st
  * @group Models
  */
 export type EntityCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = PostgresCollection<M, USER> | FirebaseCollection<M, USER> | MongoDBCollection<M, USER>;
-/** An EntityCollection that supports SQL-style relations (e.g. Postgres). */
+/**
+ * An EntityCollection that supports SQL-style relations (e.g. Postgres).
+ * @deprecated Use `EntityCollection` directly — `table`, `relations`, and `securityRules` are now on `BaseEntityCollection`.
+ */
 export type CollectionWithRelations<M extends Record<string, unknown> = Record<string, unknown>> = EntityCollection<M> & {
     table?: string;
     relations?: Relation[];

package/dist/types/src/types/properties.d.ts

@@ -641,14 +641,6 @@ export interface MapProperty extends BaseProperty {
      * Properties that are displayed when rendered as a preview
      */
     previewProperties?: string[];
-    /**
-     * Allow the user to add only some keys in this map.
-     * By default, all properties of the map have the corresponding field in
-     * the form view. Setting this flag to true allows to pick only some.
-     * Useful for map that can have a lot of sub-properties that may not be
-     * needed
-     */
-    pickOnlySomeKeys?: boolean;
     /**
      * Render this map as a key-value table that allows to use
      * arbitrary keys. You don't need to define the properties in this case.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/plugin-insights",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "main": "./dist/index.umd.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
@@ -16,9 +16,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/types": "0.4.0",
-    "@rebasepro/core": "0.4.0",
-    "@rebasepro/ui": "0.4.0"
+    "@rebasepro/core": "0.5.0",
+    "@rebasepro/types": "0.5.0",
+    "@rebasepro/ui": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=19.0.0",