lazypock 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -183,6 +183,96 @@ declare class HttpClient {
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T | null>;
 }
 
+interface RealtimeEvent {
+    event: string;
+    topic: string;
+    payload: Record<string, unknown>;
+}
+type RealtimeConnectOpts = {
+    /** WebSocket URL (e.g. ws://localhost:4000/socket/websocket) */
+    url: string;
+    /** Auth token to pass as query param */
+    token?: string;
+};
+/**
+ * Derive a WebSocket URL from an HTTP base URL.
+ * http://localhost:4000/api → ws://localhost:4000/socket/websocket
+ */
+declare function wsUrlFromBaseUrl(baseUrl: string): string;
+/**
+ * Phoenix Channel client for real-time collection subscriptions.
+ *
+ * Connects via WebSocket and subscribes to collection topics.
+ * Includes automatic reconnection with exponential backoff.
+ *
+ * @example
+ * ```ts
+ * const rt = new RealtimeService();
+ * rt.connect({ url: wsUrlFromBaseUrl('http://localhost:4000/api') });
+ * rt.subscribe('collection:posts', (e) => console.log(e));
+ * ```
+ */
+declare class RealtimeService {
+    private ws;
+    private refCounter;
+    private subscriptions;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private maxReconnectDelay;
+    onReconnect?: () => void;
+    onDisconnect?: () => void;
+    onError?: (err: Event) => void;
+    private url;
+    private token;
+    /** Whether the WebSocket is currently open. */
+    get isOpen(): boolean;
+    /**
+     * The most recently used WebSocket URL (set on {@link connect}).
+     * Useful for SDK convenience methods that auto-connect before subscribing.
+     */
+    get lastUrl(): string;
+    /** The auth token configured for this connection (set on connect). */
+    get lastToken(): string | undefined;
+    /**
+     * Set the socket URL. Useful before subscribing so the SDK can
+     * auto-connect on the first {@link subscribe}.
+     */
+    setUrl(url: string): void;
+    ensureConnected(): void;
+    connect(opts: RealtimeConnectOpts): void;
+    disconnect(): void;
+    /**
+     * Subscribe to a topic (e.g. "collection:posts" or "collection:posts:*").
+     * The backend Channel authorizes via listRule on join.
+     */
+    subscribe(topic: string, callback: (e: RealtimeEvent) => void): void;
+    /**
+     * Unsubscribe a specific callback from a topic.
+     */
+    unsubscribe(topic: string, callback?: (e: RealtimeEvent) => void): void;
+    private resubscribeAll;
+    private doConnect;
+    private handleMessage;
+    private joinTopic;
+    private nextRef;
+    private heartbeatInterval;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+}
+
+/**
+ * A realtime record-change event delivered to subscription callbacks.
+ * Mirrors PocketBase's RealtimeService result shape (`action` + `record`).
+ */
+interface RealtimeMessage {
+    action: "create" | "update" | "delete";
+    record: Record<string, unknown>;
+    topic?: string;
+}
+/** Subscription callback for a collection's realtime events. */
+type RealtimeCallback = (e: RealtimeMessage) => void;
 /**
  * Typed CRUD service for a single dynamic collection.
  * Get an instance via {@link LazypockClient.collection}.
@@ -193,8 +283,9 @@ declare class CollectionService<T = ApiRecord> {
     private http;
     private collectionName;
     private authStore?;
+    private realtime?;
     /** @internal */
-    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore);
+    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore, realtime?: RealtimeService);
     private encodeId;
     /**
      * List records with optional filter/sort/pagination.
@@ -255,6 +346,24 @@ declare class CollectionService<T = ApiRecord> {
      * ```
      */
     typed<TRecord = ApiRecord>(): CollectionService<TRecord>;
+    /**
+     * 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: RealtimeCallback, recordId?: string): () => void;
+    /**
+     * Unsubscribe all callbacks from this collection (or a specific record).
+     * @param recordId Optional record id; omitting it unsubs everything.
+     */
+    unsubscribe(recordId?: string): void;
     /**
      * Authenticate with email/password against this auth collection.
      * Stores the returned token and user model in the auth store.
@@ -277,70 +386,6 @@ declare class CollectionService<T = ApiRecord> {
     authMethods(options?: RequestOptions): Promise<Record<string, unknown> | null>;
 }
 
-interface RealtimeEvent {
-    event: string;
-    topic: string;
-    payload: Record<string, unknown>;
-}
-type RealtimeConnectOpts = {
-    /** WebSocket URL (e.g. ws://localhost:4000/socket/websocket) */
-    url: string;
-    /** Auth token to pass as query param */
-    token?: string;
-};
-/**
- * Derive a WebSocket URL from an HTTP base URL.
- * http://localhost:4000/api → ws://localhost:4000/socket/websocket
- */
-declare function wsUrlFromBaseUrl(baseUrl: string): string;
-/**
- * Phoenix Channel client for real-time collection subscriptions.
- *
- * Connects via WebSocket and subscribes to collection topics.
- * Includes automatic reconnection with exponential backoff.
- *
- * @example
- * ```ts
- * const rt = new RealtimeService();
- * rt.connect({ url: wsUrlFromBaseUrl('http://localhost:4000/api') });
- * rt.subscribe('collection:posts', (e) => console.log(e));
- * ```
- */
-declare class RealtimeService {
-    private ws;
-    private refCounter;
-    private subscriptions;
-    private reconnectTimer;
-    private reconnectAttempt;
-    private maxReconnectDelay;
-    onReconnect?: () => void;
-    onDisconnect?: () => void;
-    onError?: (err: Event) => void;
-    private url;
-    private token;
-    connect(opts: RealtimeConnectOpts): void;
-    disconnect(): void;
-    /**
-     * Subscribe to a topic (e.g. "collection:posts" or "collection:posts:*").
-     * The backend Channel authorizes via listRule on join.
-     */
-    subscribe(topic: string, callback: (e: RealtimeEvent) => void): void;
-    /**
-     * Unsubscribe a specific callback from a topic.
-     */
-    unsubscribe(topic: string, callback?: (e: RealtimeEvent) => void): void;
-    private resubscribeAll;
-    private doConnect;
-    private handleMessage;
-    private joinTopic;
-    private nextRef;
-    private heartbeatInterval;
-    private startHeartbeat;
-    private stopHeartbeat;
-    private scheduleReconnect;
-    private clearReconnectTimer;
-}
-
 /** Response shape from the server file endpoints */
 interface FileRecord {
     id: string;
@@ -693,4 +738,4 @@ declare class TypedClient<TCollections extends LazypockCollections = LazypockCol
  */
 declare function createClient<TCollections extends LazypockCollections = LazypockCollections>(options: LazypockClientOptions): TypedClient<TCollections>;
 
-export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CreateData, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, schemaFieldType, wsUrlFromBaseUrl };
+export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CreateData, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, schemaFieldType, wsUrlFromBaseUrl };

package/dist/index.d.ts

@@ -183,6 +183,96 @@ declare class HttpClient {
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T | null>;
 }
 
+interface RealtimeEvent {
+    event: string;
+    topic: string;
+    payload: Record<string, unknown>;
+}
+type RealtimeConnectOpts = {
+    /** WebSocket URL (e.g. ws://localhost:4000/socket/websocket) */
+    url: string;
+    /** Auth token to pass as query param */
+    token?: string;
+};
+/**
+ * Derive a WebSocket URL from an HTTP base URL.
+ * http://localhost:4000/api → ws://localhost:4000/socket/websocket
+ */
+declare function wsUrlFromBaseUrl(baseUrl: string): string;
+/**
+ * Phoenix Channel client for real-time collection subscriptions.
+ *
+ * Connects via WebSocket and subscribes to collection topics.
+ * Includes automatic reconnection with exponential backoff.
+ *
+ * @example
+ * ```ts
+ * const rt = new RealtimeService();
+ * rt.connect({ url: wsUrlFromBaseUrl('http://localhost:4000/api') });
+ * rt.subscribe('collection:posts', (e) => console.log(e));
+ * ```
+ */
+declare class RealtimeService {
+    private ws;
+    private refCounter;
+    private subscriptions;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private maxReconnectDelay;
+    onReconnect?: () => void;
+    onDisconnect?: () => void;
+    onError?: (err: Event) => void;
+    private url;
+    private token;
+    /** Whether the WebSocket is currently open. */
+    get isOpen(): boolean;
+    /**
+     * The most recently used WebSocket URL (set on {@link connect}).
+     * Useful for SDK convenience methods that auto-connect before subscribing.
+     */
+    get lastUrl(): string;
+    /** The auth token configured for this connection (set on connect). */
+    get lastToken(): string | undefined;
+    /**
+     * Set the socket URL. Useful before subscribing so the SDK can
+     * auto-connect on the first {@link subscribe}.
+     */
+    setUrl(url: string): void;
+    ensureConnected(): void;
+    connect(opts: RealtimeConnectOpts): void;
+    disconnect(): void;
+    /**
+     * Subscribe to a topic (e.g. "collection:posts" or "collection:posts:*").
+     * The backend Channel authorizes via listRule on join.
+     */
+    subscribe(topic: string, callback: (e: RealtimeEvent) => void): void;
+    /**
+     * Unsubscribe a specific callback from a topic.
+     */
+    unsubscribe(topic: string, callback?: (e: RealtimeEvent) => void): void;
+    private resubscribeAll;
+    private doConnect;
+    private handleMessage;
+    private joinTopic;
+    private nextRef;
+    private heartbeatInterval;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+}
+
+/**
+ * A realtime record-change event delivered to subscription callbacks.
+ * Mirrors PocketBase's RealtimeService result shape (`action` + `record`).
+ */
+interface RealtimeMessage {
+    action: "create" | "update" | "delete";
+    record: Record<string, unknown>;
+    topic?: string;
+}
+/** Subscription callback for a collection's realtime events. */
+type RealtimeCallback = (e: RealtimeMessage) => void;
 /**
  * Typed CRUD service for a single dynamic collection.
  * Get an instance via {@link LazypockClient.collection}.
@@ -193,8 +283,9 @@ declare class CollectionService<T = ApiRecord> {
     private http;
     private collectionName;
     private authStore?;
+    private realtime?;
     /** @internal */
-    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore);
+    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore, realtime?: RealtimeService);
     private encodeId;
     /**
      * List records with optional filter/sort/pagination.
@@ -255,6 +346,24 @@ declare class CollectionService<T = ApiRecord> {
      * ```
      */
     typed<TRecord = ApiRecord>(): CollectionService<TRecord>;
+    /**
+     * 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: RealtimeCallback, recordId?: string): () => void;
+    /**
+     * Unsubscribe all callbacks from this collection (or a specific record).
+     * @param recordId Optional record id; omitting it unsubs everything.
+     */
+    unsubscribe(recordId?: string): void;
     /**
      * Authenticate with email/password against this auth collection.
      * Stores the returned token and user model in the auth store.
@@ -277,70 +386,6 @@ declare class CollectionService<T = ApiRecord> {
     authMethods(options?: RequestOptions): Promise<Record<string, unknown> | null>;
 }
 
-interface RealtimeEvent {
-    event: string;
-    topic: string;
-    payload: Record<string, unknown>;
-}
-type RealtimeConnectOpts = {
-    /** WebSocket URL (e.g. ws://localhost:4000/socket/websocket) */
-    url: string;
-    /** Auth token to pass as query param */
-    token?: string;
-};
-/**
- * Derive a WebSocket URL from an HTTP base URL.
- * http://localhost:4000/api → ws://localhost:4000/socket/websocket
- */
-declare function wsUrlFromBaseUrl(baseUrl: string): string;
-/**
- * Phoenix Channel client for real-time collection subscriptions.
- *
- * Connects via WebSocket and subscribes to collection topics.
- * Includes automatic reconnection with exponential backoff.
- *
- * @example
- * ```ts
- * const rt = new RealtimeService();
- * rt.connect({ url: wsUrlFromBaseUrl('http://localhost:4000/api') });
- * rt.subscribe('collection:posts', (e) => console.log(e));
- * ```
- */
-declare class RealtimeService {
-    private ws;
-    private refCounter;
-    private subscriptions;
-    private reconnectTimer;
-    private reconnectAttempt;
-    private maxReconnectDelay;
-    onReconnect?: () => void;
-    onDisconnect?: () => void;
-    onError?: (err: Event) => void;
-    private url;
-    private token;
-    connect(opts: RealtimeConnectOpts): void;
-    disconnect(): void;
-    /**
-     * Subscribe to a topic (e.g. "collection:posts" or "collection:posts:*").
-     * The backend Channel authorizes via listRule on join.
-     */
-    subscribe(topic: string, callback: (e: RealtimeEvent) => void): void;
-    /**
-     * Unsubscribe a specific callback from a topic.
-     */
-    unsubscribe(topic: string, callback?: (e: RealtimeEvent) => void): void;
-    private resubscribeAll;
-    private doConnect;
-    private handleMessage;
-    private joinTopic;
-    private nextRef;
-    private heartbeatInterval;
-    private startHeartbeat;
-    private stopHeartbeat;
-    private scheduleReconnect;
-    private clearReconnectTimer;
-}
-
 /** Response shape from the server file endpoints */
 interface FileRecord {
     id: string;
@@ -693,4 +738,4 @@ declare class TypedClient<TCollections extends LazypockCollections = LazypockCol
  */
 declare function createClient<TCollections extends LazypockCollections = LazypockCollections>(options: LazypockClientOptions): TypedClient<TCollections>;
 
-export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CreateData, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, schemaFieldType, wsUrlFromBaseUrl };
+export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CreateData, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, schemaFieldType, wsUrlFromBaseUrl };

package/dist/index.global.js

@@ -329,12 +329,25 @@ var Lazypock = (() => {
   };
 
   // src/collection.ts
+  function normalizeAction(event, rawAction) {
+    if (typeof rawAction === "string") {
+      const a = rawAction.toLowerCase();
+      if (a === "create" || a === "update" || a === "delete") {
+        return a;
+      }
+    }
+    if (event === "record_change") return "update";
+    if (event === "create" || event === "record_create") return "create";
+    if (event === "delete" || event === "record_delete") return "delete";
+    return "update";
+  }
   var CollectionService = class {
     /** @internal */
-    constructor(http, collectionName, authStore) {
+    constructor(http, collectionName, authStore, realtime) {
       this.http = http;
       this.collectionName = collectionName;
       this.authStore = authStore;
+      this.realtime = realtime;
     }
     encodeId(id) {
       return encodeURIComponent(id);
@@ -406,10 +419,7 @@ var Lazypock = (() => {
      * Useful for constructing `expand` query parameters.
      */
     async expandFields(options) {
-      const data = await this.http.get(
-        "/collections/" + this.encodeId(this.collectionName),
-        options
-      );
+      const data = await this.http.get("/collections/" + this.encodeId(this.collectionName), options);
       if (!data?.fields) return null;
       return data.fields.filter((f) => f.type === "relation" && f.options?.collection).map((f) => ({
         field: f.name,
@@ -436,6 +446,46 @@ var Lazypock = (() => {
     typed() {
       return this;
     }
+    // ── 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) {
+      if (!this.realtime) {
+        console.warn("[lazypock] No realtime service configured.");
+        return () => {
+        };
+      }
+      const topic = "collection:" + this.collectionName + (recordId ? ":" + recordId : "");
+      const handler = (raw) => {
+        const record = raw.payload?.["record"] ?? {};
+        callback({
+          action: normalizeAction(raw.event, raw.payload?.["action"]),
+          record,
+          topic: raw.topic
+        });
+      };
+      this.realtime.ensureConnected();
+      this.realtime.subscribe(topic, handler);
+      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(recordId) {
+      const topic = "collection:" + this.collectionName + (recordId ? ":" + recordId : "");
+      this.realtime?.unsubscribe(topic);
+    }
     // ── Auth Collection Methods ──
     /**
      * Authenticate with email/password against this auth collection.
@@ -472,6 +522,7 @@ var Lazypock = (() => {
     /**
      * Get available auth methods for this collection.
      */
+    // ── end Realtime ──
     async authMethods(options) {
       return this.http.get(
         "/" + this.encodeId(this.collectionName) + "/auth-methods",
@@ -502,6 +553,39 @@ var Lazypock = (() => {
       // ── Heartbeat ──
       this.heartbeatInterval = null;
     }
+    /** Whether the WebSocket is currently open. */
+    get isOpen() {
+      return this.ws?.readyState === WebSocket.OPEN;
+    }
+    /**
+     * The most recently used WebSocket URL (set on {@link connect}).
+     * Useful for SDK convenience methods that auto-connect before subscribing.
+     */
+    get lastUrl() {
+      return this.url;
+    }
+    /** The auth token configured for this connection (set on connect). */
+    get lastToken() {
+      return this.token;
+    }
+    /**
+     * Set the socket URL. Useful before subscribing so the SDK can
+     * auto-connect on the first {@link subscribe}.
+     */
+    setUrl(url) {
+      this.url = url;
+    }
+    /*
+     * Ensure the socket is connected, then subscribe.
+     * Used by collection-level convenience wrappers so a connection is opened
+     * automatically on the first subscribe (matching PocketBase behaviour —
+     * works for anonymous/public collections too).
+     */
+    ensureConnected() {
+      if (this.isOpen || !this.url) return;
+      if (typeof WebSocket === "undefined") return;
+      this.doConnect();
+    }
     connect(opts) {
       this.url = opts.url;
       this.token = opts.token;
@@ -918,6 +1002,9 @@ ${opts.body}
       this.authStore = options.authStore ?? new AuthStore(options.storage ?? memoryStorage);
       this.http = new HttpClient(baseUrl, this.authStore);
       this.realtime = options.realtime ?? new RealtimeService();
+      if (!options.realtime) {
+        this.realtime.setUrl(wsUrlFromBaseUrl(baseUrl));
+      }
       this.files = new FilesService(this.http);
       if (options.types?.schemas) {
         this.schemaByName = new Map(
@@ -939,7 +1026,12 @@ ${opts.body}
     collection(name) {
       let svc = this.collectionCache.get(name);
       if (!svc) {
-        svc = new CollectionService(this.http, name, this.authStore);
+        svc = new CollectionService(
+          this.http,
+          name,
+          this.authStore,
+          this.realtime
+        );
         this.collectionCache.set(name, svc);
       }
       return svc;