@supacloud/js 0.45.4 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/REALTIME.md ADDED
@@ -0,0 +1,84 @@
1
+ # SupaCloud Realtime Adapter
2
+
3
+ `@supacloud/js/realtime` provides a pluggable, standard-compliant Realtime Channel facade that fully mimics the syntax and ergonomics of `@supabase/supabase-js`.
4
+
5
+ It allows decoupling client application code from backend real-time protocols (Phoenix Channel, Centrifugo, lightweight WebSocket brokers, or SSE) without altering client syntax.
6
+
7
+ ---
8
+
9
+ ## 1. Features
10
+
11
+ - **100% Supabase-compatible channel API**:
12
+ - `channel.on('postgres_changes', filter, callback)`
13
+ - `channel.on('broadcast', filter, callback)`
14
+ - `channel.on('presence', filter, callback)`
15
+ - `channel.subscribe(callback)`
16
+ - `channel.send(broadcast)`
17
+ - `channel.track(payload)` / `channel.untrack()`
18
+ - `channel.presenceState()`
19
+ - **Custom Transport Interface**:
20
+ - Implement `RealtimeTransport` to direct messages through any broker or backend service.
21
+ - Built-in `MemoryRealtimeTransport` for zero-setup local testing and single-node in-memory event dispatch.
22
+ - **Client-side Filter Matching**:
23
+ - Evaluates standard Supabase filter strings (`id=eq.1`, `status=neq.deleted`, `score=gte.10`, `role=in.(admin,editor)`) locally.
24
+
25
+ ---
26
+
27
+ ## 2. Basic Usage
28
+
29
+ ```typescript
30
+ import { createRealtimeAdapter } from "@supacloud/js/realtime";
31
+
32
+ const realtime = createRealtimeAdapter();
33
+
34
+ const channel = realtime.channel("room-1")
35
+ .on(
36
+ "postgres_changes",
37
+ { event: "*", schema: "public", table: "messages" },
38
+ (payload) => {
39
+ console.log("Postgres change:", payload.new);
40
+ }
41
+ )
42
+ .on("broadcast", { event: "cursor" }, ({ payload }) => {
43
+ console.log("Cursor position:", payload);
44
+ })
45
+ .on("presence", { event: "sync" }, () => {
46
+ console.log("Online users:", channel.presenceState());
47
+ })
48
+ .subscribe((status) => {
49
+ if (status === "SUBSCRIBED") {
50
+ console.log("Connected to channel");
51
+ }
52
+ });
53
+
54
+ // Broadcast
55
+ await channel.send({
56
+ type: "broadcast",
57
+ event: "cursor",
58
+ payload: { x: 100, y: 250 },
59
+ });
60
+
61
+ // Presence
62
+ await channel.track({ username: "alice", online_at: new Date().toISOString() });
63
+ ```
64
+
65
+ ---
66
+
67
+ ## 3. Integration with `createSupaCloudClient`
68
+
69
+ When instantiating the main platform client, an optional `realtimeTransport` can be supplied to override the default transport:
70
+
71
+ ```typescript
72
+ import { createSupaCloudClient } from "@supacloud/js";
73
+ import { MemoryRealtimeTransport } from "@supacloud/js/realtime";
74
+
75
+ const client = createSupaCloudClient({
76
+ supabase,
77
+ managementApiUrl: "https://api.example.com",
78
+ projectRef: "default",
79
+ realtimeTransport: new MemoryRealtimeTransport(),
80
+ });
81
+
82
+ // Returns the adapted RealtimeChannel instance
83
+ const channel = client.channel("room-1");
84
+ ```
package/dist/index.cjs CHANGED
@@ -39,6 +39,7 @@ var __export = (target, all) => {
39
39
  // src/index.ts
40
40
  var exports_src = {};
41
41
  __export(exports_src, {
42
+ MemoryRealtimeTransport: () => MemoryRealtimeTransport,
42
43
  SupaCloudApiError: () => SupaCloudApiError,
43
44
  SupaCloudArtifactLinkError: () => SupaCloudArtifactLinkError,
44
45
  SupaCloudArtifactReadError: () => SupaCloudArtifactReadError,
@@ -53,6 +54,7 @@ __export(exports_src, {
53
54
  SupaCloudOAuthServerError: () => SupaCloudOAuthServerError,
54
55
  SupaCloudProcedureError: () => SupaCloudProcedureError,
55
56
  SupaCloudQueueError: () => SupaCloudQueueError,
57
+ SupaCloudRealtimeChannel: () => SupaCloudRealtimeChannel,
56
58
  SupaCloudTaskAuthenticationError: () => SupaCloudTaskAuthenticationError,
57
59
  SupaCloudTaskDecodeError: () => SupaCloudTaskDecoderError,
58
60
  SupaCloudTaskDecoderError: () => SupaCloudTaskDecoderError,
@@ -73,6 +75,7 @@ __export(exports_src, {
73
75
  createProcedureClient: () => createProcedureClient,
74
76
  createQueryAdapter: () => createQueryAdapter,
75
77
  createQueryKey: () => createQueryKey,
78
+ createRealtimeAdapter: () => createRealtimeAdapter,
76
79
  createSupaCloudApiFetch: () => createSupaCloudApiFetch,
77
80
  createSupaCloudArtifactFetch: () => createSupaCloudArtifactFetch,
78
81
  createSupaCloudClient: () => createSupaCloudClient,
@@ -88,7 +91,8 @@ __export(exports_src, {
88
91
  isSupaCloudProcedureError: () => isSupaCloudProcedureError,
89
92
  isSupaCloudProcedureErrorCode: () => isSupaCloudProcedureErrorCode,
90
93
  isSupaCloudProcedureHttpError: () => isSupaCloudProcedureHttpError,
91
- isSupaCloudProcedureTransportError: () => isSupaCloudProcedureTransportError
94
+ isSupaCloudProcedureTransportError: () => isSupaCloudProcedureTransportError,
95
+ matchesPostgresFilter: () => matchesPostgresFilter
92
96
  });
93
97
  module.exports = __toCommonJS(exports_src);
94
98
  var import_supabase_js2 = require("@supabase/supabase-js");
@@ -2401,6 +2405,392 @@ class SupaCloudOAuthServerClient {
2401
2405
  }
2402
2406
  }
2403
2407
 
2408
+ // src/realtime.ts
2409
+ function matchesPostgresFilter(filterStr, record) {
2410
+ if (!filterStr || !filterStr.trim())
2411
+ return true;
2412
+ const eqIdx = filterStr.indexOf("=");
2413
+ if (eqIdx === -1)
2414
+ return true;
2415
+ const col = filterStr.substring(0, eqIdx).trim();
2416
+ const rest = filterStr.substring(eqIdx + 1).trim();
2417
+ const dotIdx = rest.indexOf(".");
2418
+ if (dotIdx === -1)
2419
+ return true;
2420
+ const op = rest.substring(0, dotIdx).trim().toLowerCase();
2421
+ const rawVal = rest.substring(dotIdx + 1).trim();
2422
+ const val = record[col];
2423
+ const strVal = val === null || val === undefined ? "" : String(val);
2424
+ switch (op) {
2425
+ case "eq":
2426
+ return strVal === rawVal;
2427
+ case "neq":
2428
+ return strVal !== rawVal;
2429
+ case "gt": {
2430
+ const nVal = Number(val);
2431
+ const nTarget = Number(rawVal);
2432
+ return !isNaN(nVal) && !isNaN(nTarget) ? nVal > nTarget : strVal > rawVal;
2433
+ }
2434
+ case "gte": {
2435
+ const nVal = Number(val);
2436
+ const nTarget = Number(rawVal);
2437
+ return !isNaN(nVal) && !isNaN(nTarget) ? nVal >= nTarget : strVal >= rawVal;
2438
+ }
2439
+ case "lt": {
2440
+ const nVal = Number(val);
2441
+ const nTarget = Number(rawVal);
2442
+ return !isNaN(nVal) && !isNaN(nTarget) ? nVal < nTarget : strVal < rawVal;
2443
+ }
2444
+ case "lte": {
2445
+ const nVal = Number(val);
2446
+ const nTarget = Number(rawVal);
2447
+ return !isNaN(nVal) && !isNaN(nTarget) ? nVal <= nTarget : strVal <= rawVal;
2448
+ }
2449
+ case "in": {
2450
+ const inner = rawVal.replace(/^\(|\)$/g, "");
2451
+ const items = inner.split(",").map((s) => s.trim());
2452
+ return items.includes(strVal);
2453
+ }
2454
+ default:
2455
+ return true;
2456
+ }
2457
+ }
2458
+
2459
+ class MemoryRealtimeTransport {
2460
+ subscribers = new Map;
2461
+ connected = true;
2462
+ connect() {
2463
+ this.connected = true;
2464
+ }
2465
+ disconnect() {
2466
+ this.connected = false;
2467
+ }
2468
+ isConnected() {
2469
+ return this.connected;
2470
+ }
2471
+ send(message) {
2472
+ if (!this.connected)
2473
+ return;
2474
+ const targets = this.subscribers.get(message.topic);
2475
+ if (!targets)
2476
+ return;
2477
+ for (const callback of targets) {
2478
+ try {
2479
+ callback(message);
2480
+ } catch {}
2481
+ }
2482
+ }
2483
+ subscribe(topic, onMessage) {
2484
+ let set = this.subscribers.get(topic);
2485
+ if (!set) {
2486
+ set = new Set;
2487
+ this.subscribers.set(topic, set);
2488
+ }
2489
+ set.add(onMessage);
2490
+ return () => {
2491
+ const current = this.subscribers.get(topic);
2492
+ if (current) {
2493
+ current.delete(onMessage);
2494
+ if (current.size === 0) {
2495
+ this.subscribers.delete(topic);
2496
+ }
2497
+ }
2498
+ };
2499
+ }
2500
+ clear() {
2501
+ this.subscribers.clear();
2502
+ }
2503
+ }
2504
+
2505
+ class SupaCloudRealtimeChannel {
2506
+ topic;
2507
+ config;
2508
+ transport;
2509
+ channelStatus = "CLOSED";
2510
+ statusCallbacks = [];
2511
+ postgresCallbacks = [];
2512
+ broadcastCallbacks = [];
2513
+ presenceCallbacks = [];
2514
+ presences = {};
2515
+ presenceKey;
2516
+ localPresenceRef;
2517
+ transportUnsubscribe = null;
2518
+ subscriptionTimer = null;
2519
+ constructor(topic, transport, config = {}) {
2520
+ this.topic = topic;
2521
+ this.transport = transport;
2522
+ this.config = config;
2523
+ this.presenceKey = config.presence?.key ?? (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `sub_${Math.random().toString(36).substring(2, 10)}`);
2524
+ this.localPresenceRef = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `ref_${Math.random().toString(36).substring(2, 10)}`;
2525
+ }
2526
+ get state() {
2527
+ return this.channelStatus;
2528
+ }
2529
+ on(type, filter, callback) {
2530
+ if (type === "postgres_changes") {
2531
+ this.postgresCallbacks.push({
2532
+ filter,
2533
+ callback
2534
+ });
2535
+ } else if (type === "broadcast") {
2536
+ const evt = String(filter.event ?? "*");
2537
+ this.broadcastCallbacks.push({
2538
+ event: evt,
2539
+ callback
2540
+ });
2541
+ } else if (type === "presence") {
2542
+ const evt = filter.event ?? "sync";
2543
+ this.presenceCallbacks.push({
2544
+ event: evt,
2545
+ callback
2546
+ });
2547
+ }
2548
+ return this;
2549
+ }
2550
+ subscribe(callback, timeoutMs = 1e4) {
2551
+ if (callback) {
2552
+ this.statusCallbacks.push(callback);
2553
+ }
2554
+ if (this.channelStatus === "SUBSCRIBED") {
2555
+ if (callback)
2556
+ callback("SUBSCRIBED");
2557
+ return this;
2558
+ }
2559
+ if (this.transport.connect) {
2560
+ Promise.resolve(this.transport.connect()).catch((err) => {
2561
+ this.emitStatus("ERRORED", err instanceof Error ? err : new Error(String(err)));
2562
+ });
2563
+ }
2564
+ if (timeoutMs > 0) {
2565
+ this.subscriptionTimer = setTimeout(() => {
2566
+ if (this.channelStatus !== "SUBSCRIBED" && this.channelStatus !== "CLOSED") {
2567
+ this.emitStatus("TIMED_OUT", new Error(`Subscription timed out after ${timeoutMs}ms`));
2568
+ }
2569
+ }, timeoutMs);
2570
+ }
2571
+ this.transportUnsubscribe = this.transport.subscribe(this.topic, (message) => {
2572
+ this.handleIncomingMessage(message);
2573
+ });
2574
+ if (this.subscriptionTimer) {
2575
+ clearTimeout(this.subscriptionTimer);
2576
+ this.subscriptionTimer = null;
2577
+ }
2578
+ this.emitStatus("SUBSCRIBED");
2579
+ return this;
2580
+ }
2581
+ async unsubscribe() {
2582
+ if (this.subscriptionTimer) {
2583
+ clearTimeout(this.subscriptionTimer);
2584
+ this.subscriptionTimer = null;
2585
+ }
2586
+ if (this.transportUnsubscribe) {
2587
+ this.transportUnsubscribe();
2588
+ this.transportUnsubscribe = null;
2589
+ }
2590
+ await this.untrack();
2591
+ this.emitStatus("CLOSED");
2592
+ return "ok";
2593
+ }
2594
+ async send(args) {
2595
+ if (this.channelStatus === "CLOSED") {
2596
+ return "error";
2597
+ }
2598
+ const message = {
2599
+ topic: this.topic,
2600
+ event: "broadcast",
2601
+ payload: {
2602
+ type: "broadcast",
2603
+ event: args.event,
2604
+ payload: args.payload,
2605
+ __sender: this.localPresenceRef
2606
+ }
2607
+ };
2608
+ try {
2609
+ await this.transport.send(message);
2610
+ return "ok";
2611
+ } catch {
2612
+ return "error";
2613
+ }
2614
+ }
2615
+ async track(payload) {
2616
+ if (this.channelStatus === "CLOSED")
2617
+ return "error";
2618
+ const entry = {
2619
+ presence_ref: this.localPresenceRef,
2620
+ ...payload
2621
+ };
2622
+ const message = {
2623
+ topic: this.topic,
2624
+ event: "presence_join",
2625
+ payload: {
2626
+ key: this.presenceKey,
2627
+ current: [entry]
2628
+ }
2629
+ };
2630
+ try {
2631
+ await this.transport.send(message);
2632
+ const prev = this.presences[this.presenceKey] ?? [];
2633
+ const updated = [
2634
+ ...prev.filter((p) => p.presence_ref !== this.localPresenceRef),
2635
+ entry
2636
+ ];
2637
+ this.presences[this.presenceKey] = updated;
2638
+ this.dispatchPresence("join", {
2639
+ key: this.presenceKey,
2640
+ currentPresences: updated,
2641
+ newPresences: [entry]
2642
+ });
2643
+ this.dispatchPresence("sync", this.presences);
2644
+ return "ok";
2645
+ } catch {
2646
+ return "error";
2647
+ }
2648
+ }
2649
+ async untrack() {
2650
+ const prev = this.presences[this.presenceKey];
2651
+ if (!prev || prev.length === 0)
2652
+ return "ok";
2653
+ const left = prev.filter((p) => p.presence_ref === this.localPresenceRef);
2654
+ if (left.length === 0)
2655
+ return "ok";
2656
+ const remaining = prev.filter((p) => p.presence_ref !== this.localPresenceRef);
2657
+ if (remaining.length === 0) {
2658
+ delete this.presences[this.presenceKey];
2659
+ } else {
2660
+ this.presences[this.presenceKey] = remaining;
2661
+ }
2662
+ const message = {
2663
+ topic: this.topic,
2664
+ event: "presence_leave",
2665
+ payload: {
2666
+ key: this.presenceKey,
2667
+ left
2668
+ }
2669
+ };
2670
+ try {
2671
+ await this.transport.send(message);
2672
+ } catch {}
2673
+ this.dispatchPresence("leave", {
2674
+ key: this.presenceKey,
2675
+ currentPresences: remaining,
2676
+ leftPresences: left
2677
+ });
2678
+ this.dispatchPresence("sync", this.presences);
2679
+ return "ok";
2680
+ }
2681
+ presenceState() {
2682
+ return this.presences;
2683
+ }
2684
+ emitStatus(status, err) {
2685
+ this.channelStatus = status;
2686
+ for (const cb of this.statusCallbacks) {
2687
+ try {
2688
+ cb(status, err);
2689
+ } catch {}
2690
+ }
2691
+ }
2692
+ handleIncomingMessage(message) {
2693
+ const { event, payload } = message;
2694
+ if (event === "postgres_changes") {
2695
+ this.dispatchPostgresChange(payload);
2696
+ } else if (event === "broadcast") {
2697
+ const sender = payload.__sender;
2698
+ if (sender === this.localPresenceRef && !this.config.broadcast?.self) {
2699
+ return;
2700
+ }
2701
+ const bPayload = payload.payload !== undefined ? payload.payload : payload;
2702
+ const bEvent = String(payload.event ?? "*");
2703
+ this.dispatchBroadcast(bEvent, bPayload);
2704
+ } else if (event === "presence_join") {
2705
+ const key = String(payload.key ?? "");
2706
+ const incoming = payload.current ?? [];
2707
+ const prev = this.presences[key] ?? [];
2708
+ const updated = [
2709
+ ...prev.filter((p) => !incoming.some((i) => i.presence_ref === p.presence_ref)),
2710
+ ...incoming
2711
+ ];
2712
+ this.presences[key] = updated;
2713
+ this.dispatchPresence("join", {
2714
+ key,
2715
+ currentPresences: updated,
2716
+ newPresences: incoming
2717
+ });
2718
+ this.dispatchPresence("sync", this.presences);
2719
+ } else if (event === "presence_leave") {
2720
+ const key = String(payload.key ?? "");
2721
+ const left = payload.left ?? [];
2722
+ const prev = this.presences[key] ?? [];
2723
+ const remaining = prev.filter((p) => !left.some((l) => l.presence_ref === p.presence_ref));
2724
+ if (remaining.length === 0) {
2725
+ delete this.presences[key];
2726
+ } else {
2727
+ this.presences[key] = remaining;
2728
+ }
2729
+ this.dispatchPresence("leave", {
2730
+ key,
2731
+ currentPresences: remaining,
2732
+ leftPresences: left
2733
+ });
2734
+ this.dispatchPresence("sync", this.presences);
2735
+ }
2736
+ }
2737
+ dispatchPostgresChange(payload) {
2738
+ if (!payload || !payload.schema || !payload.table || !payload.eventType)
2739
+ return;
2740
+ for (const { filter, callback } of this.postgresCallbacks) {
2741
+ if (filter.schema !== "*" && filter.schema.toLowerCase() !== payload.schema.toLowerCase()) {
2742
+ continue;
2743
+ }
2744
+ if (filter.table && filter.table !== "*" && filter.table.toLowerCase() !== payload.table.toLowerCase()) {
2745
+ continue;
2746
+ }
2747
+ if (filter.event !== "*" && filter.event.toUpperCase() !== payload.eventType.toUpperCase()) {
2748
+ continue;
2749
+ }
2750
+ const recordToMatch = payload.eventType === "DELETE" ? payload.old : payload.new;
2751
+ if (recordToMatch && !matchesPostgresFilter(filter.filter, recordToMatch)) {
2752
+ continue;
2753
+ }
2754
+ try {
2755
+ callback(payload);
2756
+ } catch {}
2757
+ }
2758
+ }
2759
+ dispatchBroadcast(event, payload) {
2760
+ for (const listener of this.broadcastCallbacks) {
2761
+ if (listener.event === "*" || listener.event === event) {
2762
+ try {
2763
+ listener.callback({
2764
+ type: "broadcast",
2765
+ event,
2766
+ payload
2767
+ });
2768
+ } catch {}
2769
+ }
2770
+ }
2771
+ }
2772
+ dispatchPresence(event, payload) {
2773
+ for (const listener of this.presenceCallbacks) {
2774
+ if (listener.event === event) {
2775
+ try {
2776
+ listener.callback(payload);
2777
+ } catch {}
2778
+ }
2779
+ }
2780
+ }
2781
+ }
2782
+ function createRealtimeAdapter(options = {}) {
2783
+ const transport = options.transport ?? new MemoryRealtimeTransport;
2784
+ return {
2785
+ channel(topic, config) {
2786
+ return new SupaCloudRealtimeChannel(topic, transport, config);
2787
+ },
2788
+ get transport() {
2789
+ return transport;
2790
+ }
2791
+ };
2792
+ }
2793
+
2404
2794
  // node_modules/@supacloud/query/dist/index.js
2405
2795
  async function invalidateByTags(queryClient, tags, keyPrefix) {
2406
2796
  const targetTags = Array.isArray(tags) ? tags : [tags];
@@ -3771,9 +4161,9 @@ function captureTaskSubscribeOptions(options) {
3771
4161
  if (typeof captured.onUpdate !== "function" || captured.onStateChange !== undefined && typeof captured.onStateChange !== "function" || captured.onError !== undefined && typeof captured.onError !== "function" || captured.stopOnTerminal !== undefined && typeof captured.stopOnTerminal !== "boolean") {
3772
4162
  throw new Error("Invalid task subscription options");
3773
4163
  }
3774
- const realtime = captureTaskRealtimeSource(captured.realtime);
3775
- if (realtime)
3776
- captured.realtime = realtime;
4164
+ const realtime2 = captureTaskRealtimeSource(captured.realtime);
4165
+ if (realtime2)
4166
+ captured.realtime = realtime2;
3777
4167
  return captured;
3778
4168
  }
3779
4169
  function normalizeTaskSnapshot(task, taskId, projectRef, decoder) {
@@ -4091,7 +4481,7 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
4091
4481
  subscribeInternal(taskId, options, decoder) {
4092
4482
  taskId = captureTaskId(taskId);
4093
4483
  options = captureTaskSubscribeOptions(options);
4094
- const realtime = captureTaskRealtimeSource(options.realtime);
4484
+ const realtime2 = captureTaskRealtimeSource(options.realtime);
4095
4485
  const projectRef = this.options.projectRef;
4096
4486
  let closed = false;
4097
4487
  let channel = null;
@@ -4248,14 +4638,14 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
4248
4638
  close();
4249
4639
  }
4250
4640
  };
4251
- if (!realtime) {
4641
+ if (!realtime2) {
4252
4642
  startPolling();
4253
4643
  return subscription;
4254
4644
  }
4255
4645
  channel = this.options.supabase.channel(`supacloud-task:${this.options.projectRef}:${taskId}`).on("postgres_changes", {
4256
4646
  event: "*",
4257
- schema: realtime.schema,
4258
- table: realtime.table,
4647
+ schema: realtime2.schema,
4648
+ table: realtime2.table,
4259
4649
  filter: `id=eq.${taskId}`
4260
4650
  }, (payload) => {
4261
4651
  const next = payload.new && Object.keys(payload.new).length > 0 ? payload.new : payload.old;
@@ -4481,11 +4871,22 @@ class SupaCloudQueuesClient extends SupaCloudManagementClient {
4481
4871
  await this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${encodeURIComponent(queueName)}`, "DELETE", undefined, decodeVoid);
4482
4872
  }
4483
4873
  }
4874
+ function openSupabaseChannel(supabase, topic, config) {
4875
+ if (!config)
4876
+ return supabase.channel(topic);
4877
+ return supabase.channel(topic, {
4878
+ config: {
4879
+ ...config.broadcast ? { broadcast: config.broadcast } : {},
4880
+ ...config.presence ? { presence: config.presence } : {}
4881
+ }
4882
+ });
4883
+ }
4484
4884
  function createSupaCloudClient(options) {
4485
4885
  const normalized = {
4486
4886
  ...options,
4487
4887
  managementApiUrl: normalizeBaseUrl(options.managementApiUrl),
4488
4888
  pollingIntervalMs: options.pollingIntervalMs ?? 3000,
4889
+ realtimeTransport: options.realtimeTransport ?? null,
4489
4890
  getAccessToken: options.getAccessToken ?? (() => defaultAccessTokenResolver(options.supabase))
4490
4891
  };
4491
4892
  const tasks = new SupaCloudTasksClient(normalized);
@@ -4495,6 +4896,10 @@ function createSupaCloudClient(options) {
4495
4896
  const workflows2 = new SupaCloudWorkflowsClient(options.supabase);
4496
4897
  const commands2 = new SupaCloudCommandsClient(options.supabase);
4497
4898
  const artifacts2 = new SupaCloudArtifactsClient(options.supabase);
4899
+ const realtime2 = createRealtimeAdapter({
4900
+ transport: options.realtimeTransport ?? undefined,
4901
+ projectRef: normalized.projectRef
4902
+ });
4498
4903
  const instance = {
4499
4904
  supabase: options.supabase,
4500
4905
  projectRef: normalized.projectRef,
@@ -4508,6 +4913,8 @@ function createSupaCloudClient(options) {
4508
4913
  commands: commands2,
4509
4914
  artifacts: artifacts2,
4510
4915
  queues,
4916
+ realtime: realtime2,
4917
+ channel: (topic, config) => options.realtimeTransport ? realtime2.channel(topic, config) : openSupabaseChannel(options.supabase, topic, config),
4511
4918
  queue: (name) => new SupaCloudQueueClient(normalized, name),
4512
4919
  functions: {
4513
4920
  invokeBackground: (functionName, submitOptions) => tasks.submit(functionName, submitOptions)
package/dist/index.d.cts CHANGED
@@ -6,6 +6,7 @@ import { SupaCloudApiError } from "./api-error.cjs";
6
6
  import { type FetchTransport } from "./bounded-rpc-fetch.cjs";
7
7
  import { SupaCloudOAuthClientsClient } from "./oauth-clients.cjs";
8
8
  import { SupaCloudOAuthServerClient } from "./oauth-server.cjs";
9
+ import { type RealtimeChannelConfig, type RealtimeTransport, type SupaCloudRealtimeChannel } from "./realtime.cjs";
9
10
  import { type ProcedureSource, type ProceduresOf, type QueryAdapterOptions } from "@supacloud/query";
10
11
  export { createProcedureClient, createQueryAdapter, createQueryKey, invalidateByTags, type QueryAdapter, type QueryAdapterOptions, } from "@supacloud/query";
11
12
  import { type SupaCloudQueueJson, type SupaCloudQueueMessage, type SupaCloudQueueSendResult, type SupaCloudQueueIdempotentSendResult, type SupaCloudQueueMutationResult } from "./queue-rpc.cjs";
@@ -23,6 +24,7 @@ export { createSupaCloudApiFetch, type SupaCloudApiFetchOptions, } from "./api-f
23
24
  export { createSupaCloudProcedureClient, SupaCloudProcedureError, isSupaCloudProcedureError, isSupaCloudProcedureErrorCode, isSupaCloudProcedureHttpError, isSupaCloudProcedureTransportError, type SupaCloudGeneratedClientConfig, type SupaCloudGeneratedClientFactory, type SupaCloudGeneratedClientOptions, type SupaCloudProcedureClient, type SupaCloudProcedureClientOptions, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-client.cjs";
24
25
  export * from "./commands.cjs";
25
26
  export * from "./artifacts.cjs";
27
+ export * from "./realtime.cjs";
26
28
  export type SupaCloudTaskStatus = "pending" | "leased" | "running" | "retry_scheduled" | "succeeded" | "failed" | "dead_lettered" | "cancelled" | "queued" | "processing" | "completed";
27
29
  export type SupaCloudTaskLogEntry = {
28
30
  timestamp: string;
@@ -226,6 +228,7 @@ export type SupaCloudClientOptions<TClient extends SupabaseClient = SupabaseClie
226
228
  projectRef: string;
227
229
  getAccessToken?: () => Promise<string | null> | string | null;
228
230
  pollingIntervalMs?: number;
231
+ realtimeTransport?: RealtimeTransport | null;
229
232
  };
230
233
  export declare class SupaCloudTaskSubmitError extends Error {
231
234
  readonly code = "TASK_SUBMIT_UNCONFIRMED";
@@ -365,6 +368,8 @@ export declare function createSupaCloudClient<TClient extends SupabaseClient = S
365
368
  commands: SupaCloudCommandsClient<TClient>;
366
369
  artifacts: SupaCloudArtifactsClient<TClient>;
367
370
  queues: SupaCloudQueuesClient<TClient>;
371
+ realtime: import("./realtime.cjs").SupaCloudRealtimeAdapter;
372
+ channel: (topic: string, config?: RealtimeChannelConfig) => SupaCloudRealtimeChannel;
368
373
  queue: (name: string) => SupaCloudQueueClient<TClient>;
369
374
  functions: {
370
375
  invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt<unknown>>;
@@ -384,6 +389,8 @@ export declare function createSupaCloudClient<TClient extends SupabaseClient = S
384
389
  commands: SupaCloudCommandsClient<TClient>;
385
390
  artifacts: SupaCloudArtifactsClient<TClient>;
386
391
  queues: SupaCloudQueuesClient<TClient>;
392
+ realtime: import("./realtime.cjs").SupaCloudRealtimeAdapter;
393
+ channel: (topic: string, config?: RealtimeChannelConfig) => SupaCloudRealtimeChannel;
387
394
  queue: (name: string) => SupaCloudQueueClient<TClient>;
388
395
  functions: {
389
396
  invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt<unknown>>;
package/dist/index.d.mts CHANGED
@@ -6,6 +6,7 @@ import { SupaCloudApiError } from "./api-error.mjs";
6
6
  import { type FetchTransport } from "./bounded-rpc-fetch.mjs";
7
7
  import { SupaCloudOAuthClientsClient } from "./oauth-clients.mjs";
8
8
  import { SupaCloudOAuthServerClient } from "./oauth-server.mjs";
9
+ import { type RealtimeChannelConfig, type RealtimeTransport, type SupaCloudRealtimeChannel } from "./realtime.mjs";
9
10
  import { type ProcedureSource, type ProceduresOf, type QueryAdapterOptions } from "@supacloud/query";
10
11
  export { createProcedureClient, createQueryAdapter, createQueryKey, invalidateByTags, type QueryAdapter, type QueryAdapterOptions, } from "@supacloud/query";
11
12
  import { type SupaCloudQueueJson, type SupaCloudQueueMessage, type SupaCloudQueueSendResult, type SupaCloudQueueIdempotentSendResult, type SupaCloudQueueMutationResult } from "./queue-rpc.mjs";
@@ -23,6 +24,7 @@ export { createSupaCloudApiFetch, type SupaCloudApiFetchOptions, } from "./api-f
23
24
  export { createSupaCloudProcedureClient, SupaCloudProcedureError, isSupaCloudProcedureError, isSupaCloudProcedureErrorCode, isSupaCloudProcedureHttpError, isSupaCloudProcedureTransportError, type SupaCloudGeneratedClientConfig, type SupaCloudGeneratedClientFactory, type SupaCloudGeneratedClientOptions, type SupaCloudProcedureClient, type SupaCloudProcedureClientOptions, type SupaCloudProcedureErrorCode, type SupaCloudProcedureErrorOptions, } from "./procedure-client.mjs";
24
25
  export * from "./commands.mjs";
25
26
  export * from "./artifacts.mjs";
27
+ export * from "./realtime.mjs";
26
28
  export type SupaCloudTaskStatus = "pending" | "leased" | "running" | "retry_scheduled" | "succeeded" | "failed" | "dead_lettered" | "cancelled" | "queued" | "processing" | "completed";
27
29
  export type SupaCloudTaskLogEntry = {
28
30
  timestamp: string;
@@ -226,6 +228,7 @@ export type SupaCloudClientOptions<TClient extends SupabaseClient = SupabaseClie
226
228
  projectRef: string;
227
229
  getAccessToken?: () => Promise<string | null> | string | null;
228
230
  pollingIntervalMs?: number;
231
+ realtimeTransport?: RealtimeTransport | null;
229
232
  };
230
233
  export declare class SupaCloudTaskSubmitError extends Error {
231
234
  readonly code = "TASK_SUBMIT_UNCONFIRMED";
@@ -365,6 +368,8 @@ export declare function createSupaCloudClient<TClient extends SupabaseClient = S
365
368
  commands: SupaCloudCommandsClient<TClient>;
366
369
  artifacts: SupaCloudArtifactsClient<TClient>;
367
370
  queues: SupaCloudQueuesClient<TClient>;
371
+ realtime: import("./realtime.mjs").SupaCloudRealtimeAdapter;
372
+ channel: (topic: string, config?: RealtimeChannelConfig) => SupaCloudRealtimeChannel;
368
373
  queue: (name: string) => SupaCloudQueueClient<TClient>;
369
374
  functions: {
370
375
  invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt<unknown>>;
@@ -384,6 +389,8 @@ export declare function createSupaCloudClient<TClient extends SupabaseClient = S
384
389
  commands: SupaCloudCommandsClient<TClient>;
385
390
  artifacts: SupaCloudArtifactsClient<TClient>;
386
391
  queues: SupaCloudQueuesClient<TClient>;
392
+ realtime: import("./realtime.mjs").SupaCloudRealtimeAdapter;
393
+ channel: (topic: string, config?: RealtimeChannelConfig) => SupaCloudRealtimeChannel;
387
394
  queue: (name: string) => SupaCloudQueueClient<TClient>;
388
395
  functions: {
389
396
  invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt<unknown>>;