lazypock 0.8.4 → 0.9.0

package/README.md

@@ -329,10 +329,13 @@ PocketBase-style service for the collections themselves (admin):
 
 - `realtime.connect(opts)` — Connect to WebSocket
 - `realtime.disconnect()` — Disconnect
-- `realtime.subscribe(topic, callback)` — Low-level subscribe (topic like `collection:posts`)
+- `realtime.refresh()` — Reconnect with the current auth token (auto-called on auth change)
+- `realtime.setTokenProvider(fn)` — Register a token provider consulted at every connect
+- `realtime.subscribe(topic, callback, joinPayload?)` — Low-level subscribe (any topic, e.g. `collection:posts` or custom `chat:room1`)
 - `realtime.unsubscribe(topic, callback?)` — Low-level unsubscribe
-- `collection(name).subscribe(callback, recordId?)` — Subscribe to record changes; callback receives `{ action, record }`; returns unsubscribe fn
-- `collection(name).unsubscribe(recordId?)` — Unsubscribe from record changes
+- `realtime.unsubscribeByPrefix(prefix)` — Remove all subscriptions under a topic prefix
+- `collection(name).subscribe(topicOrCallback?, callback?, options?)` — PocketBase-style record subscription; callback receives `{ action, record }` (full record); returns unsubscribe fn
+- `collection(name).unsubscribe(topic?)` — Unsubscribe `'*'`, a record id, or all subscriptions
 
 ### CollectionService
 
@@ -346,8 +349,8 @@ Returned by `client.collection(name)`.
 - `create(data, options?)` — Create record
 - `update(id, data, options?)` — Update record
 - `delete(id, options?)` — Delete record
-- `subscribe(callback, recordId?)` — Subscribe to record changes (PocketBase-style)
-- `unsubscribe(recordId?)` — Unsubscribe
+- `subscribe(topicOrCallback?, callback?, options?)` — PocketBase-style: `subscribe(cb)`, `subscribe('*', cb)`, `subscribe('id', cb)`, or with `{ expand }` options (legacy `subscribe(cb, recordId)` still works)
+- `unsubscribe(topic?)` — `unsubscribe('*')` / `unsubscribe('id')` / `unsubscribe()` (all)
 - `authWithPassword(identity, password, options?)` — Login to this auth collection
 - `authRefresh(options?)` — Refresh token for this auth collection
 - `authMethods(options?)` — Get available auth methods
@@ -533,23 +536,56 @@ The SDK automatically refreshes expired auth tokens. When a token expires, the n
 
 ## Real-time Subscriptions
 
+### PocketBase-style `subscribe` / `unsubscribe`
+
+Collection subscriptions use the same argument order as PocketBase. The
+callback always receives the **full record** (all fields) — `select()`
+projections only affect `getList`/`getOne`, never subscriptions:
+
 ```typescript
-// Subscribe to all changes in a collection (PocketBase-style: callback-first)
+// Subscribe to all records (three equivalent forms)
 const off = client.collection('posts').subscribe((event) => {
   console.log(event.action); // 'create' | 'update' | 'delete'
-  console.log(event.record);
+  console.log(event.record); // full record — all fields
 });
+client.collection('posts').subscribe('*', (event) => { ... });
 
-// Subscribe to a specific record only
-client.collection('posts').subscribe((event) => { ... }, 'abc123');
+// Subscribe to a single record
+client.collection('posts').subscribe('RECORD_ID', (event) => { ... });
+
+// With options — forwarded to the server channel join payload
+// (available to onRealtimeSubscribeRequest hooks)
+client.collection('posts').subscribe('*', (event) => { ... }, {
+  expand: 'author',
+  customKey: 'any extra key is forwarded',
+});
 
 // Unsubscribe
-client.collection('posts').unsubscribe();
+client.collection('posts').unsubscribe('*'); // wildcard only
+client.collection('posts').unsubscribe('RECORD_ID'); // one record
+client.collection('posts').unsubscribe(); // everything in this collection
 
 // ...or call the returned unsubscribe function for one-shot listeners:
 off();
 ```
 
+The legacy callback-first form (`subscribe(cb, recordId)`) still works.
+`headers` in the options object is accepted for PocketBase signature
+compatibility but is not sent over the WebSocket.
+
+### Auth tokens are attached automatically
+
+The WebSocket automatically uses the current auth token (`authStore.token`)
+and **reconnects when auth changes** (login / logout / token refresh) — so
+subscriptions to rule-protected collections and admin channels work without
+any manual socket management:
+
+```typescript
+await client.login('admin@example.com', 'secret');
+// The socket reconnects with the new token; existing subscriptions re-join.
+client.collection('private_feed').subscribe('*', (e) => { ... });
+```
+
 ### Anonymous / rule-based realtime
 
 Realtime subscriptions honor your API **and list rules** — matching PocketBase
@@ -565,6 +601,20 @@ const off = client.collection('public_feed').subscribe((e) => {
 });
 ```
 
+### Custom channels
+
+Any topic string can be subscribed to via the low-level realtime service
+(PocketBase behavior — anonymous joins allowed, broadcasts come from the
+server side):
+
+```typescript
+// Subscribe to an arbitrary topic
+const off = client.realtime.subscribe('chat:room1', (event) => {
+  console.log(event.event, event.payload);
+});
+off(); // or client.realtime.unsubscribe('chat:room1');
+```
+
 
 ## Releasing (automatic)
 

package/dist/index.cjs

@@ -817,25 +817,24 @@ var CollectionService = class _CollectionService {
     derived.fieldsPreset = this.fieldsPreset;
     return derived;
   }
-  // ── Realtime Subscriptions (PocketBase-style) ──
-  /**
-   * Subscribe to realtime changes for this collection.
-   * The event's `action` is one of `"create" | "update" | "delete"`.
-   *
-   * Access is governed by the collection's `listRule` (PocketBase semantics):
-   * public collections allow anonymous subscriptions; other collections
-   * require a matching logged-in user or superuser.
-   *
-   * @param callback Received on every record change.
-   * @param recordId Optional — subscribe to a single record instead of `*`.
-   * @returns A function that unsubscribes this callback.
-   */
-  subscribe(callback, recordId) {
+  subscribe(topicOrCallback, maybeCallback, options) {
     if (!this.realtime) {
       console.warn("[lazypock] No realtime service configured.");
       return () => {
       };
     }
+    let recordId;
+    let callback;
+    let joinPayload;
+    if (typeof topicOrCallback === "function") {
+      callback = topicOrCallback;
+      if (typeof maybeCallback === "string") recordId = maybeCallback;
+    } else {
+      callback = maybeCallback;
+      recordId = topicOrCallback === "*" ? void 0 : topicOrCallback;
+      const { headers: _ignored, ...rest } = options ?? {};
+      if (Object.keys(rest).length > 0) joinPayload = rest;
+    }
     const topic = "collection:" + this.collectionName + (recordId ? ":" + recordId : "");
     const handler = (raw) => {
       const record = raw.payload?.["record"] ?? {};
@@ -846,15 +845,23 @@ var CollectionService = class _CollectionService {
       });
     };
     this.realtime.ensureConnected();
-    this.realtime.subscribe(topic, handler);
+    this.realtime.subscribe(topic, handler, joinPayload);
     return () => this.realtime?.unsubscribe(topic, handler);
   }
   /**
-   * Unsubscribe all callbacks from this collection (or a specific record).
-   * @param recordId Optional record id; omitting it unsubs everything.
+   * Unsubscribe from realtime changes (PocketBase-compatible):
+   *   - `unsubscribe()` — remove **all** subscriptions of this collection
+   *   - `unsubscribe('*')` — remove wildcard subscriptions
+   *   - `unsubscribe('RECORD_ID')` — remove that record's subscriptions
    */
   unsubscribe(recordId) {
-    const topic = "collection:" + this.collectionName + (recordId ? ":" + recordId : "");
+    if (recordId === void 0) {
+      this.realtime?.unsubscribeByPrefix(
+        "collection:" + this.collectionName
+      );
+      return;
+    }
+    const topic = "collection:" + this.collectionName + (recordId === "*" ? "" : ":" + recordId);
     this.realtime?.unsubscribe(topic);
   }
   // ── Auth Collection Methods ──
@@ -921,6 +928,7 @@ var RealtimeService = class {
     this.reconnectAttempt = 0;
     this.maxReconnectDelay = 5e3;
     this.url = "";
+    this.tokenProvider = null;
     // ── Heartbeat ──
     this.heartbeatInterval = null;
   }
@@ -946,6 +954,32 @@ var RealtimeService = class {
   setUrl(url) {
     this.url = url;
   }
+  /**
+   * Register a token provider consulted at every (re)connect.
+   * When set, it takes precedence over the token passed to {@link connect}.
+   */
+  setTokenProvider(provider) {
+    this.tokenProvider = provider;
+  }
+  /**
+   * Reconnect the socket immediately with the current token.
+   * Called by the SDK when auth changes (login/logout/token refresh) so
+   * private-channel joins are authorized with the new credentials. No-op
+   * when the socket has never been opened and nothing is subscribed.
+   */
+  refresh() {
+    if (typeof WebSocket === "undefined") return;
+    if (!this.ws && this.subscriptions.size === 0) return;
+    this.clearReconnectTimer();
+    const ws = this.ws;
+    this.ws = null;
+    if (ws) {
+      ws.onclose = null;
+      ws.close();
+    }
+    this.reconnectAttempt = 0;
+    this.doConnect();
+  }
   /*
    * Ensure the socket is connected, then subscribe.
    * Used by collection-level convenience wrappers so a connection is opened
@@ -969,15 +1003,30 @@ var RealtimeService = class {
     this.ws = null;
   }
   /**
-   * Subscribe to a topic (e.g. "collection:posts" or "collection:posts:*").
+   * Subscribe to a topic (e.g. "collection:posts" or "custom:chat-room").
    * The backend Channel authorizes via listRule on join.
+   *
+   * @param joinPayload Optional payload forwarded with the channel join
+   * (available to the server's join callback / hooks, e.g. `expand`).
    */
-  subscribe(topic, callback) {
+  subscribe(topic, callback, joinPayload) {
     const subs = this.subscriptions.get(topic) || [];
-    subs.push({ topic, callback });
+    subs.push({ topic, callback, joinPayload });
     this.subscriptions.set(topic, subs);
     if (this.ws?.readyState === WebSocket.OPEN) {
-      this.joinTopic(topic);
+      this.joinTopic(topic, joinPayload);
+    }
+  }
+  /**
+   * Remove all subscriptions for topics under `prefix` (the topic itself or
+   * any topic starting with `prefix + ":"`). Used by collection-level
+   * `unsubscribe()` to drop every subscription of a collection.
+   */
+  unsubscribeByPrefix(prefix) {
+    for (const topic of [...this.subscriptions.keys()]) {
+      if (topic === prefix || topic.startsWith(prefix + ":")) {
+        this.subscriptions.delete(topic);
+      }
     }
   }
   /**
@@ -996,9 +1045,14 @@ var RealtimeService = class {
     }
   }
   resubscribeAll() {
-    for (const topic of this.subscriptions.keys()) {
-      if (this.ws?.readyState === WebSocket.OPEN) {
-        this.joinTopic(topic);
+    const seen = /* @__PURE__ */ new Set();
+    for (const entries of this.subscriptions.values()) {
+      for (const entry of entries) {
+        if (seen.has(entry.topic)) continue;
+        seen.add(entry.topic);
+        if (this.ws?.readyState === WebSocket.OPEN) {
+          this.joinTopic(entry.topic, entry.joinPayload);
+        }
       }
     }
   }
@@ -1010,8 +1064,9 @@ var RealtimeService = class {
       return;
     }
     let url = this.url;
-    if (this.token) {
-      url += (url.includes("?") ? "&" : "?") + "token=" + encodeURIComponent(this.token);
+    const token = this.tokenProvider ? this.tokenProvider() : this.token;
+    if (token) {
+      url += (url.includes("?") ? "&" : "?") + "token=" + encodeURIComponent(token);
     }
     this.ws = new WebSocket(url);
     this.ws.onopen = () => {
@@ -1058,12 +1113,12 @@ var RealtimeService = class {
       }
     }
   }
-  joinTopic(topic) {
+  joinTopic(topic, joinPayload) {
     const ref = this.nextRef();
     const msg = JSON.stringify({
       topic,
       event: "phx_join",
-      payload: {},
+      payload: joinPayload ?? {},
       ref
     });
     this.ws?.send(msg);
@@ -1635,6 +1690,9 @@ var LazypockClient = class {
     if (!options.realtime) {
       this.realtime.setUrl(wsUrlFromBaseUrl(baseUrl));
     }
+    this.realtime.setTokenProvider(() => this.authStore.token);
+    this.authStore.onChange(() => this.realtime.refresh());
+    this.authReady.then(() => this.realtime.refresh());
     this.files = new FilesService(this.http);
     this.collections = new CollectionsService(this.http, this.realtime);
     if (options.types?.schemas) {