@rebasepro/types 0.12.0 → 0.12.1-canary.g181d0fe

package/dist/types/backend.d.ts

@@ -611,6 +611,25 @@ export interface BackendBootstrapper {
     ensureCollectionSchema?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
         applied: number;
     }>;
+    /**
+     * Apply the collections' row-level-security policies, additively and
+     * idempotently — the companion to {@link ensureCollectionSchema}.
+     *
+     * That method creates the tables; a table with RLS disabled and no policies
+     * is not servable, because authenticated requests run as a restricted role:
+     * a read with no `SELECT` policy returns nothing (a public collection
+     * answers 401) and a write with no `INSERT`/`UPDATE` policy is denied. The
+     * `db push` CLI applies these from the same collections, but it cannot reach
+     * a managed tenant's in-cluster database — the runtime, already connected,
+     * is the only thing that can.
+     *
+     * MUST be idempotent (re-run on every boot) and MUST NOT be destructive.
+     * Runs after auth initialization, because the generated policies call the
+     * `auth.*` helper functions and `CREATE POLICY` validates they exist.
+     */
+    ensureCollectionPolicies?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
+        applied: number;
+    }>;
     /**
      * Initialize WebSocket server for realtime operations.
      */

package/dist/types/cron.d.ts

@@ -26,6 +26,37 @@ export interface CronJobDefinition {
      * considered timed-out. Default: 300 (5 min).
      */
     timeoutSeconds?: number;
+    /**
+     * How far back to look, on startup, for a slot that elapsed while no
+     * instance was holding a timer for it. Off by default.
+     *
+     * The scheduler drives jobs with in-process `setTimeout` and computes the
+     * next slot from *now* on every boot, so a slot only fires if some instance
+     * happened to be alive and ticking when it came round. That is not a
+     * scale-to-zero problem: a platform that recycles containers — Cloud Run
+     * rotating an instance under `--min-instances 1`, a rolling deploy, a crash
+     * loop — drops any slot that falls inside the changeover, and the
+     * replacement schedules the slot *after* it. The run is skipped in silence.
+     *
+     * Set this to a window comfortably wider than a restart (a few minutes for
+     * a frequent job; an hour or more for a daily one) and startup will run a
+     * slot it finds unclaimed inside that window.
+     *
+     * Two deliberate limits:
+     *
+     * - **Only the most recent missed slot runs.** Booting after a six-hour
+     *   outage catches an hourly job up once, not six times. Catch-up exists to
+     *   stop a run going missing, not to replay history.
+     * - **A claims-capable store is required.** Catch-up is skipped entirely
+     *   when the store has no `tryClaimRun` (or no store is attached), because
+     *   the claim is the only thing that distinguishes "this slot never ran"
+     *   from "this slot already ran on the instance I am replacing". Without
+     *   it, an instance recycled every 30 minutes would re-run the same hourly
+     *   job every time it booted.
+     *
+     * @example catchUpWindowSeconds: 3600  // daily job: tolerate an hour of downtime
+     */
+    catchUpWindowSeconds?: number;
     /**
      * The handler function executed on each tick.
      * Receives a context object with the data driver and logger.

package/dist/types/database_adapter.d.ts

@@ -67,6 +67,32 @@ export interface DatabaseAdapter {
      * Initialize WebSocket server for realtime operations.
      */
     initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown): Promise<void> | void;
+    /**
+     * Bring the database's collection tables up to date, additively — the boot
+     * companion to `db push`. See `BackendBootstrapper.ensureCollectionSchema`
+     * for the contract (create-only; never drop, narrow, or rewrite).
+     *
+     * Optional, and MUST be forwarded by any wrapper that turns this adapter
+     * into a `BackendBootstrapper`: the runtime calls it through the bootstrapper
+     * at boot, and a wrapper that silently omits it leaves a managed tenant
+     * 500ing every data route with no create step ever having run.
+     */
+    ensureCollectionSchema?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
+        applied: number;
+    }>;
+    /**
+     * Apply the collections' RLS policies (ENABLE ROW LEVEL SECURITY + the
+     * `securityRules` compiled to `CREATE POLICY`) — the boot companion to the
+     * policy half of `db push`. Idempotent; see
+     * `BackendBootstrapper.ensureCollectionPolicies`.
+     *
+     * Same forwarding requirement as `ensureCollectionSchema`: without the
+     * policies, tables exist but every user-context read is denied (a public
+     * collection answers 401).
+     */
+    ensureCollectionPolicies?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
+        applied: number;
+    }>;
     /**
      * Return admin capabilities for this database (SQL editor, schema browser, branching).
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.12.1-canary.g181d0fe",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -39,14 +39,14 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.2",
     "@types/object-hash": "^3.0.6",
     "@types/react-measure": "^2.0.12",
     "hono": "^4.12.27",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11",
+    "ts-jest": "^29.4.12",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.1.5"
   },
   "peerDependencies": {
     "hono": "^4.12.27"

package/src/controllers/client.ts

@@ -94,6 +94,21 @@ export interface AuthClient {
      * Manually refresh the session token
      */
     refreshSession(): Promise<RebaseSession>;
+
+    /**
+     * Whether a session could exist that this client has not loaded yet.
+     *
+     * `false` means the only way this client can hold a session is an explicit
+     * sign-in during this page's lifetime: it neither persists sessions nor
+     * carries an httpOnly auth cookie, so there is nothing on disk or in the
+     * browser to restore from. A caller that would otherwise probe the server
+     * — `getUser()` on mount, say — can skip it, because the answer is already
+     * known and the request can only ever fail.
+     *
+     * Optional so that alternative {@link AuthClient} implementations need not
+     * supply it; treat a missing implementation as "unknown, go ahead and ask".
+     */
+    canRestoreSession?: () => boolean;
 }
 
 // ─── Admin API ───────────────────────────────────────────────────────────────
@@ -321,6 +336,17 @@ export interface RebaseClient<DB = unknown> {
     /** Base HTTP URL of the backend server */
     baseUrl?: string;
 
+    /**
+     * The path every API route is mounted under, appended to {@link baseUrl}.
+     *
+     * `"/api"` unless the backend was configured with a different `basePath`
+     * and the client told to match. Exposed because code that builds a URL by
+     * hand — rather than going through the client's own methods — otherwise has
+     * to guess, and guessing `/api` is wrong for exactly the projects that set
+     * the option.
+     */
+    apiPath?: string;
+
     /** WebSocket client for realtime subscriptions */
     ws?: RebaseWebSocket;
 
@@ -439,6 +465,17 @@ export interface RebaseBrowserClient<DB = unknown> {
     /** Base HTTP URL of the backend server */
     baseUrl?: string;
 
+    /**
+     * The path every API route is mounted under, appended to {@link baseUrl}.
+     *
+     * `"/api"` unless the backend was configured with a different `basePath`
+     * and the client told to match. Exposed because code that builds a URL by
+     * hand — rather than going through the client's own methods — otherwise has
+     * to guess, and guessing `/api` is wrong for exactly the projects that set
+     * the option.
+     */
+    apiPath?: string;
+
     /** WebSocket client for realtime subscriptions */
     ws?: RebaseWebSocket;
 

package/src/types/backend.ts

@@ -798,6 +798,28 @@ export interface BackendBootstrapper {
         log?: (message: string) => void
     ): Promise<{ applied: number }>;
 
+    /**
+     * Apply the collections' row-level-security policies, additively and
+     * idempotently — the companion to {@link ensureCollectionSchema}.
+     *
+     * That method creates the tables; a table with RLS disabled and no policies
+     * is not servable, because authenticated requests run as a restricted role:
+     * a read with no `SELECT` policy returns nothing (a public collection
+     * answers 401) and a write with no `INSERT`/`UPDATE` policy is denied. The
+     * `db push` CLI applies these from the same collections, but it cannot reach
+     * a managed tenant's in-cluster database — the runtime, already connected,
+     * is the only thing that can.
+     *
+     * MUST be idempotent (re-run on every boot) and MUST NOT be destructive.
+     * Runs after auth initialization, because the generated policies call the
+     * `auth.*` helper functions and `CREATE POLICY` validates they exist.
+     */
+    ensureCollectionPolicies?(
+        collections: unknown[],
+        driverResult: InitializedDriver,
+        log?: (message: string) => void
+    ): Promise<{ applied: number }>;
+
     /**
      * Initialize WebSocket server for realtime operations.
      */

package/src/types/cron.ts

@@ -38,6 +38,38 @@ export interface CronJobDefinition {
      */
     timeoutSeconds?: number;
 
+    /**
+     * How far back to look, on startup, for a slot that elapsed while no
+     * instance was holding a timer for it. Off by default.
+     *
+     * The scheduler drives jobs with in-process `setTimeout` and computes the
+     * next slot from *now* on every boot, so a slot only fires if some instance
+     * happened to be alive and ticking when it came round. That is not a
+     * scale-to-zero problem: a platform that recycles containers — Cloud Run
+     * rotating an instance under `--min-instances 1`, a rolling deploy, a crash
+     * loop — drops any slot that falls inside the changeover, and the
+     * replacement schedules the slot *after* it. The run is skipped in silence.
+     *
+     * Set this to a window comfortably wider than a restart (a few minutes for
+     * a frequent job; an hour or more for a daily one) and startup will run a
+     * slot it finds unclaimed inside that window.
+     *
+     * Two deliberate limits:
+     *
+     * - **Only the most recent missed slot runs.** Booting after a six-hour
+     *   outage catches an hourly job up once, not six times. Catch-up exists to
+     *   stop a run going missing, not to replay history.
+     * - **A claims-capable store is required.** Catch-up is skipped entirely
+     *   when the store has no `tryClaimRun` (or no store is attached), because
+     *   the claim is the only thing that distinguishes "this slot never ran"
+     *   from "this slot already ran on the instance I am replacing". Without
+     *   it, an instance recycled every 30 minutes would re-run the same hourly
+     *   job every time it booted.
+     *
+     * @example catchUpWindowSeconds: 3600  // daily job: tolerate an hour of downtime
+     */
+    catchUpWindowSeconds?: number;
+
     /**
      * The handler function executed on each tick.
      * Receives a context object with the data driver and logger.

package/src/types/database_adapter.ts

@@ -90,6 +90,38 @@ export interface DatabaseAdapter {
         config?: unknown,
     ): Promise<void> | void;
 
+    /**
+     * Bring the database's collection tables up to date, additively — the boot
+     * companion to `db push`. See `BackendBootstrapper.ensureCollectionSchema`
+     * for the contract (create-only; never drop, narrow, or rewrite).
+     *
+     * Optional, and MUST be forwarded by any wrapper that turns this adapter
+     * into a `BackendBootstrapper`: the runtime calls it through the bootstrapper
+     * at boot, and a wrapper that silently omits it leaves a managed tenant
+     * 500ing every data route with no create step ever having run.
+     */
+    ensureCollectionSchema?(
+        collections: unknown[],
+        driverResult: InitializedDriver,
+        log?: (message: string) => void,
+    ): Promise<{ applied: number }>;
+
+    /**
+     * Apply the collections' RLS policies (ENABLE ROW LEVEL SECURITY + the
+     * `securityRules` compiled to `CREATE POLICY`) — the boot companion to the
+     * policy half of `db push`. Idempotent; see
+     * `BackendBootstrapper.ensureCollectionPolicies`.
+     *
+     * Same forwarding requirement as `ensureCollectionSchema`: without the
+     * policies, tables exist but every user-context read is denied (a public
+     * collection answers 401).
+     */
+    ensureCollectionPolicies?(
+        collections: unknown[],
+        driverResult: InitializedDriver,
+        log?: (message: string) => void,
+    ): Promise<{ applied: number }>;
+
     /**
      * Return admin capabilities for this database (SQL editor, schema browser, branching).
      */