@rebasepro/types 0.20.0 → 0.21.0

package/dist/types/admin_block.d.ts

@@ -81,10 +81,15 @@ export declare function nestAdminCollectionKeys(collection: Record<string, unkno
 /**
  * {@link nestAdminKeysOf} for a property, applied to its children too.
  *
- * A map property carries `properties`, an array property carries `of`, and both
- * hold properties with `admin` blocks of their own. A flat `readOnly` left on a
- * child is as dead — and as fatal at the next boot — as one left on the parent,
- * so the walk goes all the way down.
+ * A map property carries `properties`, an array property carries `of`, and an
+ * array of typed blocks carries `oneOf.properties` — a record of properties like
+ * a map's. All of them hold properties with `admin` blocks of their own. A flat
+ * `readOnly` left on a child is as dead — and as fatal at the next boot — as one
+ * left on the parent, so the walk goes all the way down.
+ *
+ * `oneOf` was the container this walk did not know about, and it is the one the
+ * block-based collection templates are built out of: every block inside them
+ * kept its flat `markdown`, and the collection they created would not boot.
  *
  * @group Models
  */

package/dist/types/project_manifest.d.ts

@@ -88,7 +88,23 @@ export interface RebaseBackendAppConfig {
      * Default `Dockerfile`.
      */
     dockerfile?: string;
-    /** `runtime: "custom"` only. Build context relative to the root. Default `.`. */
+    /**
+     * `runtime: "custom"` only. Directory handed to `docker build` as the build
+     * context, relative to the directory holding `rebase.json`. Default `.`.
+     *
+     * The one path in this file allowed to point **above** the project. Every
+     * other one names something Rebase reads, and those must be inside the
+     * project or a bundle cannot carry them; this names something Rebase never
+     * opens. In a workspace repository it normally has to be the workspace root
+     * (`".."`), because the lockfile and sibling packages a Dockerfile copies do
+     * not live beside `rebase.json`.
+     *
+     * {@link RebaseBackendAppConfig.dockerfile} stays relative to `rebase.json`
+     * whatever this is — it names a file in this repository, and moving the
+     * context should not rewrite it. `rebase build` re-expresses it against the
+     * context when it prints the command, because `docker build -f` resolves
+     * against the working directory rather than the context.
+     */
     context?: string;
     /** `runtime: "custom"` only. Port the container listens on. Default 8080. */
     port?: number;
@@ -124,6 +140,30 @@ export interface RebaseStaticAppConfig {
      * static *site* generator emits real files for its routes anyway.
      */
     spa?: boolean;
+    /**
+     * Where this app mounts the Rebase CMS, as a URL path — the address you
+     * would type to reach it, not a path relative to `path`.
+     *
+     * The CMS is an ordinary React component in the developer's own app
+     * (`<RebaseCMS basePath="/admin">`), so its address is a *client-side
+     * route*: nothing on the server, in the bundle, or in the control plane can
+     * observe it. A project whose CMS sits at `/admin` inside a frontend that
+     * also serves a product at `/` is indistinguishable, from the outside, from
+     * one that has no CMS at all — which is exactly how a Rebase Cloud project
+     * came to have no discoverable admin URL anywhere in its console.
+     *
+     * Declaring it is the only way that fact travels. It is carried into the
+     * bundle manifest, recorded on the project's app row at deploy, and is what
+     * lets the console (and `rebase apps list`) offer a link straight to it.
+     *
+     * Must be `path` itself or something beneath it, since the app serving that
+     * URL is the one that has to answer for it. Absent means this app does not
+     * mount the CMS — the common case for a marketing site or a product app.
+     *
+     * @example "/" — the whole app is the CMS, as `rebase init` scaffolds it
+     * @example "/admin" — the CMS is one route of a larger app
+     */
+    cms?: string;
 }
 export type RebaseAppConfig = RebaseBackendAppConfig | RebaseStaticAppConfig;
 /**
@@ -215,7 +255,7 @@ export interface RebaseProjectManifest {
      * Repository-wide opt-out from anonymous CLI usage sharing.
      *
      * **Only `false` does anything.** It suppresses sharing for everyone who
-     * clones this repository, overriding each developer's own opt-in — an
+     * clones this repository, overriding each developer's own answer — an
      * organisation setting policy for work done on its behalf, the same shape
      * as a committed `.npmrc`.
      *
@@ -223,7 +263,7 @@ export interface RebaseProjectManifest {
      * quietly. This file is committed, so a `true` here would be one developer
      * answering a privacy question for every colleague who later clones the
      * repo — consent by proxy, which is the exact thing opt-in exists to
-     * prevent. Individuals opt in with `rebase telemetry enable`.
+     * prevent. Individuals answer at `rebase init`, or with `rebase telemetry enable` / `disable`.
      */
     telemetry?: boolean;
 }
@@ -341,6 +381,27 @@ export interface RebaseBundleStatic {
     dir: string;
     /** Serve `index.html` for unmatched paths under `path`. */
     spa: boolean;
+    /**
+     * The app's name in `rebase.json`.
+     *
+     * `dir` is `static/<name>` and has been since folding was written, so this
+     * is recoverable by string surgery — which is precisely why it is stated
+     * instead. A control plane reconciling app rows against this list has to
+     * match them by name, and a consumer that has to re-derive an identifier
+     * from a path is one refactor away from matching nothing and registering a
+     * duplicate app on every deploy.
+     *
+     * Optional because bundles built before this field exists do not carry it;
+     * a reader that needs a name falls back to the last segment of `dir`.
+     */
+    name?: string;
+    /**
+     * Where this app mounts the Rebase CMS, as a URL path.
+     *
+     * Copied from the app's declaration — see {@link RebaseStaticAppConfig.cms}
+     * for why a client-side route has to be declared to be knowable at all.
+     */
+    cms?: string;
 }
 /**
  * A native module found in the dependency closure.

package/dist/types/websockets.d.ts

@@ -109,6 +109,115 @@ export interface CollectionPatchMessage extends WebSocketMessage {
     /** See {@link WirePrimaryKeys}: how the subscriber finds {@link id} in its cache. */
     pks?: WirePrimaryKeys;
 }
+/**
+ * A presence roster, keyed by the server's client id.
+ *
+ * The id is per socket rather than per user: the same person in two tabs is two
+ * entries, and a reconnect replaces an entry rather than updating it. What the
+ * values hold is entirely the application's — the server stores and echoes back
+ * whatever `presence_track` was given, and never reads into it.
+ */
+export type PresenceState = Record<string, Record<string, unknown>>;
+/**
+ * Server → client: a message broadcast into a channel.
+ *
+ * The body is `payload`, inherited from {@link WebSocketMessage} — the server
+ * passes it through untouched, so its shape is the application's business. The
+ * sender is never sent its own broadcast back.
+ */
+export interface BroadcastMessage extends WebSocketMessage {
+    type: "broadcast";
+    channel: string;
+    /**
+     * The application-chosen event name. The only thing
+     * `channel.onBroadcast(event, …)` filters on; the server does not interpret
+     * it.
+     */
+    event: string;
+    /**
+     * Per-channel sequence number, present only on a channel the server has a
+     * retention rule for.
+     *
+     * Dense and monotonically increasing, so a client that remembers the last
+     * one it applied can name exactly where to resume from — see
+     * {@link ChannelHistoryMessage}. Absent on an ephemeral channel, where
+     * there is nothing to resume from and messages are delivered straight
+     * through.
+     */
+    seq?: number;
+}
+/**
+ * Server → client: the whole roster of a channel.
+ *
+ * Sent only in answer to a `presence_state` request. Joining does not push one,
+ * and a client that has just tracked itself is told only about its own join, so
+ * a client that waits for diffs alone believes it is the only one there until
+ * somebody else happens to move. This is why the SDK's `join()` asks for a
+ * roster rather than waiting to be given one.
+ */
+export interface PresenceStateMessage extends WebSocketMessage {
+    type: "presence_state";
+    channel: string;
+    /**
+     * Everyone currently tracked, this client included. Empty for a channel
+     * nobody is tracking presence in — an answer, not an omission.
+     */
+    presences: PresenceState;
+}
+/**
+ * Server → client: what moved in a channel's roster.
+ *
+ * Carries only the movement, never the roster, so a receiver maintains its own
+ * copy by applying these to what it already had (which is why it needs a
+ * {@link PresenceStateMessage} to start from).
+ */
+export interface PresenceDiffMessage extends WebSocketMessage {
+    type: "presence_diff";
+    channel: string;
+    /**
+     * Entries added or changed. A state update is a join over the same client
+     * id, since that is what a receiver has to do with it either way.
+     */
+    joins: PresenceState;
+    /**
+     * Entries removed — by `presence_untrack`, by a closed socket, or by the
+     * 30s expiry that reaps a client which stopped sending heartbeats.
+     *
+     * Keyed by client id like `joins`, and carrying each departing entry's last
+     * state rather than just its id: enough to say who left without having kept
+     * the roster.
+     */
+    leaves: PresenceState;
+}
+/**
+ * Server → client: a refusal about one channel.
+ *
+ * Channel frames are fire-and-forget — there is no pending request to reject
+ * and no subscription id to match — so a refused join, broadcast or history
+ * read is addressed by channel like any other channel frame. Without the
+ * `channel` field these fell through every branch of the client's message
+ * handler into a console warning, which is why it is the one thing that makes
+ * this a channel frame rather than a generic error.
+ *
+ * `type` is lowercase from the realtime service and uppercase from the socket
+ * gateway (auth, rate limiting). Both are sent; a client must accept both.
+ */
+export interface ChannelErrorMessage extends WebSocketMessage {
+    type: "error" | "ERROR";
+    channel: string;
+    /**
+     * The refusal. `error` is a bare string when there is no code, and
+     * `{ message, code }` when there is — `CHANNEL_FORBIDDEN`, `RATE_LIMITED`,
+     * `CHANNEL_HISTORY_READ_FAILED` / `_WRITE_FAILED`,
+     * `CHANNEL_BUS_PAYLOAD_TOO_LARGE`.
+     *
+     * The channel is echoed inside the envelope as well as beside it, for a
+     * reader that has only the payload.
+     */
+    payload?: WebSocketErrorPayload & {
+        channel?: string;
+    };
+}
 /**
  * One retained broadcast, as it travels on the wire.
  *
@@ -152,3 +261,14 @@ export interface ChannelHistoryMessage extends WebSocketMessage {
      */
     latestSeq?: number;
 }
+/**
+ * Every frame routed by channel name rather than by `requestId` or
+ * `subscriptionId`.
+ *
+ * A discriminated union: each member fixes `type` to a literal, so a `switch`
+ * over a value of this type narrows to the member and its fields. Narrowing
+ * *into* it is the part that needs a predicate — a frame arrives as a
+ * {@link WebSocketMessage}, whose `type` is a bare `string`, and a `string`
+ * discriminates nothing.
+ */
+export type ChannelMessage = BroadcastMessage | PresenceStateMessage | PresenceDiffMessage | ChannelHistoryMessage | ChannelErrorMessage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/types",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "keywords": [
     "rebase",