@rebasepro/server-postgresql 0.0.1-canary.4d4fb3e

package/dist/server-postgresql/src/services/realtimeService.d.ts

@@ -0,0 +1,186 @@
+import { WebSocket } from "ws";
+import { EventEmitter } from "events";
+import { Entity, DataDriver, WebSocketMessage } from "@rebasepro/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { RealtimeProvider, CollectionSubscriptionConfig, EntitySubscriptionConfig } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Auth context stored per-subscription so real-time refetches respect RLS.
+ * Mirrors the session variables set by PostgresBackendDriver.withAuth().
+ */
+export interface SubscriptionAuthContext {
+    userId: string;
+    roles: string[];
+}
+/**
+ * PostgreSQL-specific realtime service.
+ * Handles WebSocket connections and subscriptions for real-time entity updates.
+ *
+ * Implements the RealtimeProvider interface for database abstraction.
+ */
+export declare class RealtimeService extends EventEmitter implements RealtimeProvider {
+    private db;
+    private registry;
+    private clients;
+    private entityService;
+    private _subscriptions;
+    private subscriptionCallbacks;
+    private driver?;
+    /** Unique identifier for this process instance, used to skip own notifications. */
+    private readonly instanceId;
+    /** Dedicated pg.Client for LISTEN (outside the Drizzle pool). */
+    private listenClient?;
+    /** Connection string used for reconnecting the LISTEN client. */
+    private listenConnectionString?;
+    /** Whether cross-instance broadcasting is active. */
+    private broadcasting;
+    /** Reconnection timer handle. */
+    private reconnectTimer?;
+    /** Debounce timers for collection refetches to prevent refetch storms. */
+    private refetchTimers;
+    /** Debounce window (ms) for coalescing rapid entity updates into a single correctness refetch. */
+    private static readonly REFETCH_DEBOUNCE_MS;
+    constructor(db: NodePgDatabase<any>, registry: PostgresCollectionRegistry);
+    /** Whether to emit verbose debug logs (disabled in production). */
+    private static readonly DEBUG;
+    private debugLog;
+    setDataDriver(driver: DataDriver): void;
+    get subscriptions(): Map<string, {
+        clientId: string;
+        type: "collection" | "entity";
+        path: string;
+        entityId?: string | number;
+        collectionRequest?: {
+            filter?: Record<string, unknown>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            startAfter?: Record<string, unknown>;
+            databaseId?: string;
+            searchString?: string;
+        };
+        authContext?: SubscriptionAuthContext;
+    }>;
+    registerDataDriverSubscription(subscriptionId: string, subscription: {
+        clientId: string;
+        type: "collection" | "entity";
+        path: string;
+        entityId?: string | number;
+        collectionRequest?: {
+            filter?: Record<string, unknown>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            startAfter?: Record<string, unknown>;
+            databaseId?: string;
+            searchString?: string;
+        };
+        authContext?: SubscriptionAuthContext;
+    }): void;
+    addSubscriptionCallback(subscriptionId: string, callback: (data: Entity[] | Entity | null) => void): void;
+    removeSubscriptionCallback(subscriptionId: string): void;
+    /**
+     * Subscribe to collection changes (RealtimeProvider interface)
+     */
+    subscribeToCollection(subscriptionId: string, config: CollectionSubscriptionConfig, callback?: (entities: Entity[]) => void): void;
+    /**
+     * Subscribe to single entity changes (RealtimeProvider interface)
+     */
+    subscribeToEntity(subscriptionId: string, config: EntitySubscriptionConfig, callback?: (entity: Entity | null) => void): void;
+    /**
+     * Unsubscribe from a subscription (RealtimeProvider interface)
+     */
+    unsubscribe(subscriptionId: string): void;
+    addClient(clientId: string, ws: WebSocket): void;
+    handleClientMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext): Promise<void>;
+    removeClient(clientId: string): Promise<void>;
+    private handleMessage;
+    private handleCollectionSubscription;
+    private handleEntitySubscription;
+    private handleUnsubscribe;
+    /**
+     * Enhanced notification method that handles nested relation updates.
+     * @param broadcast When true (default), also sends a pg_notify so other instances
+     *                  pick up the change. Set to false when handling an incoming
+     *                  cross-instance notification to avoid infinite loops.
+     */
+    notifyEntityUpdate(path: string, entityId: string, entity: Entity | null, databaseId?: string, broadcast?: boolean): Promise<void>;
+    /**
+     * Notify subscriptions for a specific path
+     */
+    private notifyPathUpdate;
+    /**
+     * Debounce a collection refetch for a WebSocket subscription.
+     * Coalesces rapid entity mutations into a single database query.
+     */
+    private debouncedCollectionRefetch;
+    /**
+     * Debounce a collection refetch for a DataDriver callback subscription.
+     */
+    private debouncedDriverRefetch;
+    /**
+     * Fetch a collection with optional RLS auth context.
+     * When authContext is provided, the fetch runs inside a transaction
+     * with set_config calls so PostgreSQL RLS policies are enforced.
+     */
+    private fetchCollectionWithAuth;
+    /**
+     * Debounce an entity refetch for a WebSocket subscription.
+     */
+    private debouncedEntityRefetch;
+    /**
+     * Debounce an entity refetch for a Driver callback subscription.
+     */
+    private debouncedEntityDriverRefetch;
+    /**
+     * Fetch a single entity with optional RLS auth context.
+     */
+    private fetchEntityWithAuth;
+    private sendCollectionUpdate;
+    private sendEntityUpdate;
+    /**
+     * Send a lightweight entity-level patch to a collection subscriber.
+     * The client can merge this into its cached data for instant feedback.
+     */
+    private sendCollectionEntityPatch;
+    private sendError;
+    private sendMessage;
+    /**
+     * Extract parent paths from a nested path like "posts/70/tags"
+     * Returns ["posts", "posts/70"] for the example above
+     */
+    private getParentPaths;
+    /**
+     * Enable cross-instance realtime broadcasting via Postgres LISTEN/NOTIFY.
+     * Creates a dedicated pg.Client (outside the Drizzle pool) that stays
+     * connected and listens for change notifications from other instances.
+     *
+     * This is an **optional** feature — if never called, the backend operates
+     * in single-instance mode (the default, perfectly fine for most setups).
+     *
+     * @param connectionString Raw Postgres connection string for the LISTEN client.
+     */
+    startListening(connectionString: string): Promise<void>;
+    /**
+     * Stop listening and clean up the dedicated LISTEN connection.
+     */
+    stopListening(): Promise<void>;
+    /**
+     * Broadcast a change notification to other instances via pg_notify.
+     * Uses the main Drizzle connection (pooled) — NOT the LISTEN client.
+     */
+    private broadcastChange;
+    /**
+     * Create and connect the dedicated LISTEN client with auto-reconnect.
+     */
+    private connectListenClient;
+    /**
+     * Schedule a reconnection attempt with a fixed 3s delay.
+     */
+    private scheduleReconnect;
+}
+/**
+ * Alias for RealtimeService for consistent naming with other database implementations.
+ * This allows code to use PostgresRealtimeProvider alongside future MongoRealtimeProvider, etc.
+ */
+export declare const PostgresRealtimeProvider: typeof RealtimeService;

package/dist/server-postgresql/src/utils/drizzle-conditions.d.ts

@@ -0,0 +1,116 @@
+import { SQL } from "drizzle-orm";
+import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
+import { FilterValues, WhereFilterOp, Relation } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/** Drizzle dynamic query builder — accepts innerJoin + where chaining */
+export interface DrizzleDynamicQuery {
+    innerJoin(table: PgTable<any>, condition: SQL): this;
+    where(condition: SQL | undefined): this;
+    limit(limit: number): this;
+}
+/**
+ * Unified condition builder for Drizzle/PostgreSQL queries.
+ *
+ * This class uses static methods and satisfies the ConditionBuilderStatic<SQL> type.
+ * It translates Rebase filter conditions to Drizzle SQL conditions.
+ *
+ * @example
+ * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;
+ */
+export declare class DrizzleConditionBuilder {
+    /**
+     * Build filter conditions from FilterValues
+     */
+    static buildFilterConditions<M extends Record<string, any>>(filter: FilterValues<Extract<keyof M, string>>, table: PgTable<any>, collectionPath: string): SQL[];
+    /**
+     * Build a single filter condition for a specific operator and value
+     */
+    static buildSingleFilterCondition(column: AnyPgColumn, op: WhereFilterOp, value: unknown): SQL | null;
+    /**
+     * Build relation-based conditions for different relation types
+     */
+    static buildRelationConditions(relation: Relation, parentEntityId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry): {
+        joinConditions: {
+            table: PgTable<any>;
+            condition: SQL;
+        }[];
+        whereConditions: SQL[];
+    };
+    /**
+     * Build conditions for join path relations
+     */
+    private static buildJoinPathConditions;
+    /**
+     * Build a single join condition between tables
+     */
+    private static buildSingleJoinCondition;
+    /**
+     * Try to build a junction table join when direct foreign key relationship is not found
+     */
+    private static tryBuildJunctionJoin;
+    /**
+     * Build conditions for junction table (many-to-many) relations
+     */
+    private static buildJunctionTableConditions;
+    /**
+     * Build conditions for inverse junction table (many-to-many) relations
+     */
+    private static buildInverseJunctionTableConditions;
+    /**
+     * Build conditions for simple relations (owning/inverse without join paths)
+     */
+    private static buildSimpleRelationCondition;
+    /**
+     * Combine multiple conditions with AND operator
+     */
+    static combineConditionsWithAnd(conditions: SQL[]): SQL | undefined;
+    /**
+     * Combine multiple conditions with OR operator
+     */
+    static combineConditionsWithOr(conditions: SQL[]): SQL | undefined;
+    /**
+     * Build search conditions for text fields
+     */
+    static buildSearchConditions(searchString: string, properties: Record<string, any>, table: PgTable<any>): SQL[];
+    /**
+     * Build a unique field check condition
+     */
+    static buildUniqueFieldCondition(fieldColumn: AnyPgColumn, value: unknown, idColumn?: AnyPgColumn, excludeId?: string | number): SQL[];
+    /**
+     * Build relation-based query with joins and conditions
+     */
+    static buildRelationQuery<T extends DrizzleDynamicQuery>(baseQuery: T, relation: Relation, parentEntityId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
+    /**
+     * Build count query for relations with proper joins and conditions
+     */
+    static buildRelationCountQuery<T extends DrizzleDynamicQuery>(baseCountQuery: T, relation: Relation, parentEntityId: string | number, targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
+    /**
+     * Build join path conditions for count queries
+     */
+    private static buildJoinPathCountQuery;
+    /**
+     * Build junction table conditions for count queries
+     */
+    private static buildJunctionCountQuery;
+    /**
+     * Build inverse junction table conditions for count queries
+     */
+    private static buildInverseJunctionCountQuery;
+    /**
+     * Helper method to extract table names from columns
+     */
+    static getTableNamesFromColumns(columns: string | string[]): string[];
+    /**
+     * Helper method to extract column names from columns
+     */
+    static getColumnNamesFromColumns(columns: string | string[]): string[];
+    /**
+     * Find the corresponding junction table for an inverse many-to-many relation
+     */
+    private static findCorrespondingJunctionTable;
+}
+/**
+ * Alias for DrizzleConditionBuilder for consistent naming with other database implementations.
+ * This allows code to use PostgresConditionBuilder alongside future MongoConditionBuilder, etc.
+ */
+export declare const PostgresConditionBuilder: typeof DrizzleConditionBuilder;

package/dist/server-postgresql/src/websocket.d.ts

@@ -0,0 +1,5 @@
+import { RealtimeService } from "./services/realtimeService";
+import { PostgresBackendDriver } from "./PostgresBackendDriver";
+import { Server } from "http";
+import { AuthConfig } from "@rebasepro/server-core";
+export declare function createPostgresWebSocket(server: Server, realtimeService: RealtimeService, driver: PostgresBackendDriver, authConfig?: AuthConfig): void;

package/dist/types/src/controllers/analytics_controller.d.ts

@@ -0,0 +1,7 @@
+export type AnalyticsController = {
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: AnalyticsEvent, data?: object) => void;
+};
+export type AnalyticsEvent = "entity_click" | "entity_click_from_reference" | "reference_selection_clear" | "reference_selection_toggle" | "reference_selected_single" | "reference_selection_new_entity" | "edit_entity_clicked" | "entity_edited" | "new_entity_click" | "new_entity_saved" | "copy_entity_click" | "entity_copied" | "single_delete_dialog_open" | "multiple_delete_dialog_open" | "single_entity_deleted" | "multiple_entities_deleted" | "drawer_navigate_to_home" | "drawer_navigate_to_collection" | "drawer_navigate_to_view" | "home_navigate_to_collection" | "home_favorite_navigate_to_collection" | "home_navigate_to_view" | "home_navigate_to_admin_view" | "home_favorite_navigate_to_view" | "home_move_card" | "home_move_group" | "home_drop_new_group" | "collection_inline_editing" | "view_mode_changed" | "kanban_card_moved" | "kanban_column_reorder" | "kanban_property_changed" | "kanban_new_entity_in_column" | "kanban_backfill_order" | "card_view_entity_click" | "unmapped_event";

package/dist/types/src/controllers/auth.d.ts

@@ -0,0 +1,117 @@
+import { StorageSource } from "./storage";
+import { Role, User } from "../users";
+import { RebaseData } from "./data";
+/**
+ * Capabilities advertised by an auth provider.
+ * UI components use this to show/hide features dynamically
+ * (e.g. password reset, registration, session management).
+ * @group Hooks and utilities
+ */
+export interface AuthCapabilities {
+    emailPasswordLogin?: boolean;
+    googleLogin?: boolean;
+    registration?: boolean;
+    passwordReset?: boolean;
+    sessionManagement?: boolean;
+    profileUpdate?: boolean;
+    emailVerification?: boolean;
+}
+/**
+ * Controller for retrieving the logged user or performing auth related operations.
+ * Note that if you are implementing your AuthController, you probably will want
+ * to do it as the result of a hook.
+ * @group Hooks and utilities
+ */
+export type AuthController<USER extends User = User, ExtraData = unknown> = {
+    /**
+     * The user currently logged in
+     * The values can be: the user object, null if they skipped login
+     */
+    user: USER | null;
+    /**
+     * Initial loading flag. It is used not to display the login screen
+     * when the app first loads, and it has not been checked whether the user
+     * is logged in or not.
+     */
+    initialLoading?: boolean;
+    /**
+     * Loading flag. It is used to display a loading screen when the user is
+     * logging in or out.
+     */
+    authLoading: boolean;
+    /**
+     * Sign out
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Error initializing the authentication
+     */
+    authError?: unknown;
+    /**
+     * Error dispatched by the auth provider
+     */
+    authProviderError?: unknown;
+    /**
+     * You can use this method to retrieve the auth token for the current user.
+     */
+    getAuthToken: () => Promise<string>;
+    /**
+     * Has the user skipped the login process
+     */
+    loginSkipped: boolean;
+    extra: ExtraData;
+    setExtra: (extra: ExtraData) => void;
+    setUser?(user: USER | null): void;
+    setUserRoles?(roles: Role[]): void;
+    /**
+     * Capabilities advertised by the auth provider.
+     * UI components use this to feature-detect what the backend supports.
+     */
+    capabilities?: AuthCapabilities;
+};
+/**
+ * Extended auth controller with common optional auth methods.
+ * Backend implementations (Rebase backend, Firebase, Supabase, etc.)
+ * extend this with their own backend-specific extras.
+ * @group Hooks and utilities
+ */
+export interface AuthControllerExtended<USER extends User = User, ExtraData = unknown> extends AuthController<USER, ExtraData> {
+    /** Login with email and password */
+    emailPasswordLogin?(email: string, password: string): Promise<void>;
+    /** Login with a Google ID token or trigger Google popup */
+    googleLogin?(idToken: string): Promise<void>;
+    /** Register a new user */
+    register?(email: string, password: string, displayName?: string): Promise<void>;
+    /** Skip login (for anonymous access if enabled) */
+    skipLogin?(): void;
+    /** Request password reset email */
+    forgotPassword?(email: string): Promise<void>;
+    /** Reset password using a token */
+    resetPassword?(token: string, password: string): Promise<void>;
+    /** Change password for the authenticated user */
+    changePassword?(oldPassword: string, newPassword: string): Promise<void>;
+    /** Update user profile */
+    updateProfile?(displayName?: string, photoURL?: string): Promise<USER>;
+}
+/**
+ * Implement this function to allow access to specific users.
+ * @group Hooks and utilities
+ */
+export type Authenticator<USER extends User = User> = (props: {
+    /**
+     * Logged-in user or null
+     */
+    user: USER | null;
+    /**
+     * AuthController
+     */
+    authController: AuthController<USER>;
+    /**
+     * Unified data access API
+     */
+    data: RebaseData;
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+}) => boolean | Promise<boolean>;

package/dist/types/src/controllers/client.d.ts

@@ -0,0 +1,58 @@
+import { User } from "../users";
+import { RebaseData } from "./data";
+/**
+ * Event type for authentication state changes
+ */
+export type AuthChangeEvent = 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'USER_UPDATED';
+/**
+ * Standard session interface representing an authenticated state
+ */
+export interface RebaseSession {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    user: User;
+}
+import { StorageSource } from "./storage";
+/**
+ * Unified Authentication Client Interface
+ * Pure functional SDK interface, decoupled from UI and React hooks
+ */
+export interface AuthClient {
+    /**
+     * Get the current user from the server or cache
+     */
+    getUser(): Promise<User | null>;
+    /**
+     * Get the currently active session
+     */
+    getSession(): RebaseSession | null;
+    /**
+     * Sign out the current user and clear local session
+     */
+    signOut(): Promise<void>;
+    /**
+     * Subscribe to authentication state changes
+     */
+    onAuthStateChange(callback: (event: AuthChangeEvent, session: RebaseSession | null) => void): () => void;
+    /**
+     * Manually refresh the session token
+     */
+    refreshSession(): Promise<RebaseSession>;
+    [key: string]: any;
+}
+/**
+ * Overarching abstraction that unites Data, Auth, and Storage.
+ * Adapters for Supabase or Firebase simply need to implement this interface.
+ */
+export interface RebaseClient<DB = any> {
+    /** Unified Data access layer */
+    data: RebaseData;
+    /** Unified Authentication layer */
+    auth: AuthClient;
+    /** Unified Storage layer */
+    storage?: StorageSource;
+    /** Optional admin panel specific tasks */
+    admin?: any;
+    [key: string]: any;
+}

package/dist/types/src/controllers/collection_registry.d.ts

@@ -0,0 +1,44 @@
+import { EntityCollection, EntityReference } from "../types";
+/**
+ * Controller that provides access to the registered entity collections.
+ * @group Models
+ */
+export type CollectionRegistryController<EC extends EntityCollection = EntityCollection<any>> = {
+    /**
+     * List of the mapped collections in the CMS.
+     * Each entry relates to a collection in the root database.
+     * Each of the navigation entries in this field
+     * generates an entry in the main menu.
+     */
+    collections?: EntityCollection[];
+    /**
+     * Is the registry ready to be used
+     */
+    initialised: boolean;
+    /**
+     * Get the collection configuration for a given path.
+     * The collection is resolved from the given path or alias.
+     */
+    getCollection: (slugOrPath: string, includeUserOverride?: boolean) => EC | undefined;
+    /**
+     * Get the raw, un-normalized collection configuration.
+     * This bypasses the `CollectionRegistry` normalization (such as injecting `relation` instances).
+     * This is strictly for the Visual Editor to manipulate AST code without persisting runtime state.
+     */
+    getRawCollection: (slugOrPath: string) => EC | undefined;
+    /**
+     * Retrieve all the related parent references for a given path
+     * @param path
+     */
+    getParentReferencesFromPath: (path: string) => EntityReference[];
+    /**
+     * Retrieve all the related parent collection ids for a given path
+     * @param path
+     */
+    getParentCollectionIds: (path: string) => string[];
+    /**
+     * Resolve paths from a list of ids
+     * @param ids
+     */
+    convertIdsToPaths: (ids: string[]) => string[];
+};

package/dist/types/src/controllers/customization_controller.d.ts

@@ -0,0 +1,54 @@
+import React from "react";
+import { EntityLinkBuilder, Locale, EntityAction, EntityCustomView, RebasePlugin, PropertyConfig, SlotContribution } from "../types";
+export type CustomizationController = {
+    /**
+     * Builder for generating utility links for entities
+     */
+    entityLinkBuilder?: EntityLinkBuilder;
+    /**
+     * Use plugins to modify the behaviour of the CMS.
+     */
+    plugins?: RebasePlugin[];
+    /**
+     * Pre-merged slots from plugins + direct slot contributions.
+     */
+    resolvedSlots: SlotContribution[];
+    /**
+     * List of additional custom views for entities.
+     * You can use the key to reference the custom view in
+     * the `entityViews` prop of a collection.
+     *
+     * You can also define an entity view from the UI.
+     */
+    entityViews?: EntityCustomView[];
+    /**
+     * List of actions that can be performed on entities.
+     * These actions are displayed in the entity view and in the collection view.
+     * You can later reuse these actions in the `entityActions` prop of a collection,
+     * by specifying the `key` of the action.
+     */
+    entityActions?: EntityAction[];
+    /**
+     * Format of the dates in the CMS.
+     * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
+     */
+    dateTimeFormat?: string;
+    /**
+     * Locale of the CMS, currently only affecting dates
+     */
+    locale?: Locale;
+    /**
+     * Record of custom form fields to be used in the CMS.
+     * You can use the key to reference the custom field in
+     * 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;
+        }>;
+    };
+};