@bunbase-ae/js 2.10.1 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunbase-ae/js",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "type": "module",
   "description": "TypeScript/JavaScript SDK for BunBase",
   "license": "UNLICENSED",

package/src/admin.ts

@@ -301,14 +301,25 @@ export interface ServerSettings {
   // storage tiers handled out-of-band (e.g. S3 versioning).
   backup_include_storage?: boolean;
   // Phase 2 (#350): when true, every backup also captures an AES-256-GCM
-  // encrypted bundle of secret env vars under `backup_env_passphrase`.
-  // Default false — opt-in. Passphrase loss is unrecoverable for the env
-  // restore path; DB+storage still restore without it.
+  // encrypted bundle of secret env vars. The passphrase used to encrypt the
+  // bundle is sourced from the `BACKUP_ENV_PASSPHRASE` environment variable
+  // on the BunBase host (see `backup_env_passphrase_source` below for the
+  // read-only set/unset indicator). Default false — opt-in. Passphrase loss
+  // is unrecoverable for the env restore path; DB+storage still restore
+  // without it.
   backup_include_env?: boolean;
-  // Operator-provided passphrase for `backup_include_env`. Must be at least
-  // 32 chars. Returned as the redacted sentinel ("********") on read once
-  // #379 lands.
+  /**
+   * @deprecated Removed in #402. The env-bundle passphrase is sourced from
+   * the `BACKUP_ENV_PASSPHRASE` environment variable only — never from
+   * `_settings`, never via this API. Setting this field via the admin API
+   * is silently ignored. Use `backup_env_passphrase_source` to read whether
+   * the env var is set on the BunBase host.
+   */
   backup_env_passphrase?: string;
+  // Read-only indicator (#402). `"env_set"` means BACKUP_ENV_PASSPHRASE is
+  // present in the BunBase host's process environment; `"env_unset"` means
+  // it is missing — encrypted env-bundle capture will skip with a warn log.
+  backup_env_passphrase_source?: "env_set" | "env_unset";
   server_timezone?: string;
   server_locale?: string;
   access_log_level?: "info" | "warn" | "error";
@@ -400,6 +411,24 @@ export interface StatsResponse {
   time_series: MinuteBucket[];
 }
 
+export interface TenantSummary {
+  tenant_id: string;
+  member_count: number;
+}
+
+export interface TenantMember {
+  user_id: string;
+  role: string;
+  created_at: number;
+}
+
+export interface AdminTenantMembership {
+  tenant_id: string;
+  user_id: string;
+  role: string;
+  created_at: number;
+}
+
 // ─── Sub-clients ──────────────────────────────────────────────────────────────
 
 class AdminUsersClient {
@@ -1129,6 +1158,58 @@ class AdminNamedQueriesClient {
   }
 }
 
+// Tenant membership management — surfaces the /api/v1/admin/tenants/* endpoints
+// added in v2.5.2 (#277/#323) so operators don't need to hand-roll fetch calls
+// to onboard a tenant member.
+class AdminTenantsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<TenantSummary[]> {
+    const res = await this.http.request<{ items: TenantSummary[] }>("GET", "/api/v1/admin/tenants");
+    return res.items;
+  }
+
+  async listMembers(tenantId: string): Promise<TenantMember[]> {
+    const res = await this.http.request<{ items: TenantMember[] }>(
+      "GET",
+      `/api/v1/admin/tenants/${encodeURIComponent(tenantId)}/members`,
+    );
+    return res.items;
+  }
+
+  async addMember(
+    tenantId: string,
+    params: { userId: string; role?: string },
+  ): Promise<AdminTenantMembership> {
+    const body: Record<string, unknown> = { user_id: params.userId };
+    if (params.role !== undefined) body.role = params.role;
+    return this.http.request<AdminTenantMembership>(
+      "POST",
+      `/api/v1/admin/tenants/${encodeURIComponent(tenantId)}/members`,
+      { body },
+    );
+  }
+
+  async setMemberRole(
+    tenantId: string,
+    userId: string,
+    role: string,
+  ): Promise<AdminTenantMembership> {
+    return this.http.request<AdminTenantMembership>(
+      "PATCH",
+      `/api/v1/admin/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}`,
+      { body: { role } },
+    );
+  }
+
+  async removeMember(tenantId: string, userId: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>(
+      "DELETE",
+      `/api/v1/admin/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}`,
+    );
+  }
+}
+
 // ─── Main AdminClient ─────────────────────────────────────────────────────────
 
 export class AdminClient {
@@ -1143,6 +1224,7 @@ export class AdminClient {
   readonly queries: AdminNamedQueriesClient;
   readonly logs: AdminLogsClient;
   readonly system: AdminSystemClient;
+  readonly tenants: AdminTenantsClient;
 
   constructor(http: HttpClient) {
     this.users = new AdminUsersClient(http);
@@ -1156,5 +1238,6 @@ export class AdminClient {
     this.queries = new AdminNamedQueriesClient(http);
     this.logs = new AdminLogsClient(http);
     this.system = new AdminSystemClient(http);
+    this.tenants = new AdminTenantsClient(http);
   }
 }

package/src/index.ts

@@ -7,6 +7,7 @@ export {
   type AdminRecord,
   type AdminSession,
   type AdminStoredFile,
+  type AdminTenantMembership,
   type AdminUser,
   type BackupDestinationConfig,
   type BackupFile,
@@ -38,6 +39,8 @@ export {
   type StatsResponse,
   type StorageBucket,
   type TemplateName,
+  type TenantMember,
+  type TenantSummary,
   type UpdateNamedQueryInput,
   type UpdateUserParams,
   type WebhookLogRow,

package/src/realtime.ts

@@ -88,6 +88,25 @@ export class RealtimeClient {
   private ws: WebSocket | null = null;
   // Map from channel key → { callbacks, options }
   private channels = new Map<string, ChannelState>();
+  // Reverse map: server-resolved topic → user-supplied channel key. Populated
+  // from the subscribe ack (`{ type: "ack", channel: <resolved-topic>,
+  // requestedChannel: <user-key> }`) so dispatch can translate the topic on
+  // incoming change messages back to the key the caller used. Without this,
+  // three of four subscribe shapes silently drop every event because the
+  // resolved topic differs from the user key:
+  //   - record:{collection}:{id}                  → record:{collection}:{id}                  (matches, unless tenant-scoped)
+  //   - record:{collection}:{id} (tenant-scoped)  → record:{collection}:tenant:{tid}:{id}
+  //   - collection:{name}:mine                    → collection:{name}:user:{uid}
+  //   - collection:{name} (tenant-scoped)         → collection:{name}:tenant:{tid}
+  //
+  // The earlier #408 fix paired acks to subscribes via a FIFO queue. That broke
+  // whenever the response stream wasn't 1:1 with the request stream — most
+  // notably when the server replied with `{ type: "error" }` to a subscribe
+  // (e.g. `tenant_required` for a tenant-scoped collection on a JWT without a
+  // tenant claim) or when an unsubscribe ack arrived in between. Both desync
+  // the queue permanently. Replacing FIFO pairing with an explicit
+  // `requestedChannel` echo makes correlation direct and stateless.
+  private resolvedTopicToKey = new Map<string, string>();
   private connected = false;
   private intentionalClose = false;
   private reconnectDelay = INITIAL_RECONNECT_MS;
@@ -281,6 +300,7 @@ export class RealtimeClient {
     this.ws = null;
     this.connected = false;
     this.connectionState = "disconnected";
+    this.resolvedTopicToKey.clear();
   }
 
   // ─── Internal ──────────────────────────────────────────────────────────────
@@ -291,6 +311,12 @@ export class RealtimeClient {
     state.callbacks.delete(callback);
     if (state.callbacks.size === 0) {
       this.channels.delete(channel);
+      // Drop any reverse-map entries that pointed at this user key — leaving
+      // stale rows would route a future event for a recycled topic to a
+      // deleted subscription.
+      for (const [topic, key] of this.resolvedTopicToKey) {
+        if (key === channel) this.resolvedTopicToKey.delete(topic);
+      }
       if (this.connected) this.send({ type: "unsubscribe", channel });
     }
   }
@@ -317,6 +343,9 @@ export class RealtimeClient {
     this.intentionalClose = false;
     this.connectionState = "connecting";
     this.sawSuccessfulSubscribe = false;
+    // Clear any stale reverse-topic mappings — the server will reissue acks
+    // for every channel we re-send in onopen below.
+    this.resolvedTopicToKey.clear();
     this.ws = new WebSocket(`${this.wsUrl}/realtime`);
 
     this.ws.onopen = () => {
@@ -360,10 +389,52 @@ export class RealtimeClient {
 
       // A subscribe ack proves we can actually hold a subscription on this
       // connection — reset the unauth-bailout state. (Auth-event acks flow
-      // through the "auth" branch below and carry no `channel` field.)
+      // through the "auth" branch below and carry no `channel` field;
+      // unsubscribe acks carry `channel` but no `requestedChannel`, so they
+      // don't disturb the reverse map.)
       if (msg.type === "ack" && (msg as { channel?: string }).channel) {
         this.sawSuccessfulSubscribe = true;
         this.unauthCloseTimestamps = [];
+        const ackChannel = (msg as unknown as { channel: string }).channel;
+        const requestedChannel = (msg as unknown as { requestedChannel?: string }).requestedChannel;
+        if (requestedChannel) {
+          // Direct correlation: the server echoed the user-supplied channel
+          // string back, so we can pair the resolved topic to the user key
+          // without any FIFO state.
+          this.resolvedTopicToKey.set(ackChannel, requestedChannel);
+        } else {
+          // Back-compat with older servers that don't echo requestedChannel:
+          // identity-map the resolved topic so dispatch still finds the
+          // channel when the user keyed by topic. Only the simple non-tenant
+          // `collection:{name}` shape works against an old server — that
+          // matches the pre-fix behavior, no regression here.
+          this.resolvedTopicToKey.set(ackChannel, ackChannel);
+        }
+        return;
+      }
+
+      // Subscribe-error: server returned `{ type: "error", requestedChannel }`
+      // for a subscribe that failed without closing the socket (e.g.
+      // `tenant_required`, `subscription_limit`, `invalid channel format`,
+      // RPC catch-all). Drop the channel from this.channels so the failed sub
+      // doesn't get re-sent on reconnect (where it would just fail again) and
+      // so a future subscribe of the same key starts clean. Surface to onError
+      // with channel context — currently the only way the caller can find out
+      // their subscribe didn't take.
+      if (msg.type === "error" && (msg as { requestedChannel?: string }).requestedChannel) {
+        const errMsg = msg as unknown as {
+          requestedChannel: string;
+          code?: string;
+          message?: string;
+        };
+        this.channels.delete(errMsg.requestedChannel);
+        for (const [topic, key] of this.resolvedTopicToKey) {
+          if (key === errMsg.requestedChannel) this.resolvedTopicToKey.delete(topic);
+        }
+        const summary = errMsg.code
+          ? `${errMsg.code}: ${errMsg.message ?? ""}`
+          : (errMsg.message ?? "subscribe failed");
+        this.onError?.(`Realtime subscribe failed for "${errMsg.requestedChannel}": ${summary}`);
         return;
       }
 
@@ -405,7 +476,16 @@ export class RealtimeClient {
       if (msg.type !== "change") return;
 
       const changeMsg = msg as ServerChangeMessage;
-      const state = this.channels.get(changeMsg.channel);
+      // Translate the server's resolved topic back to the user-supplied
+      // channel key before dispatching. Server fanout sets msg.channel to the
+      // topic the publish landed on (e.g. `collection:posts:user:U` for
+      // :mine, `record:posts:tenant:T:01ABC` for tenant-scoped record subs),
+      // which differs from the key the caller passed to subscribe(). Fall
+      // through to identity lookup for unmapped topics — keeps backwards
+      // compatibility with older servers and the simple non-tenant
+      // collection-channel case where the topic matches the user key.
+      const userKey = this.resolvedTopicToKey.get(changeMsg.channel) ?? changeMsg.channel;
+      const state = this.channels.get(userKey);
       if (!state) return;
 
       const realtimeEvent: RealtimeEvent = {