@wix/realtime 1.0.40 → 1.0.42

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.
@@ -3,7 +3,7 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
3
3
  /**
4
4
  * Publishes a message to a channel or resource.
5
5
  *
6
- * The method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
6
+ * The method publishes a message to all subscribers on the specified channel or resource. Channels and resources are independent, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
7
7
  *
8
8
  * > **Authentication**
9
9
  * >
@@ -35,7 +35,9 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
35
35
  * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
36
36
  * ```
37
37
  *
38
- * @param channel - Channel or resource to publish to.
38
+ * @param channel - Channel and optionally resource to publish to.
39
+ * @requiredField channel
39
40
  * @param payload - Message payload. Max: 10 KB.
41
+ * @requiredField payload
40
42
  */
41
43
  export declare const publish: MaybeContext<BuildRESTFunction<typeof publicPublish> & typeof publicPublish>;
@@ -6,7 +6,7 @@ const rest_modules_1 = require("@wix/sdk-runtime/rest-modules");
6
6
  /**
7
7
  * Publishes a message to a channel or resource.
8
8
  *
9
- * The method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
9
+ * The method publishes a message to all subscribers on the specified channel or resource. Channels and resources are independent, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
10
10
  *
11
11
  * > **Authentication**
12
12
  * >
@@ -38,7 +38,9 @@ const rest_modules_1 = require("@wix/sdk-runtime/rest-modules");
38
38
  * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
39
39
  * ```
40
40
  *
41
- * @param channel - Channel or resource to publish to.
41
+ * @param channel - Channel and optionally resource to publish to.
42
+ * @requiredField channel
42
43
  * @param payload - Message payload. Max: 10 KB.
44
+ * @requiredField payload
43
45
  */
44
46
  exports.publish = (0, rest_modules_1.createRESTModule)(publisher_public_js_1.publish);
@@ -45,7 +45,9 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
45
45
  * ```
46
46
  *
47
47
  * @param channel - Channel, and optionally resource, to subscribe to.
48
+ * @requiredField channel
48
49
  * @param messageHandler - Callback that runs whenever a message is published to the channel.
50
+ * @requiredField messageHandler
49
51
  * @param options - Lifecycle handlers for subscription events.
50
52
  */
51
53
  export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubscribe> & typeof publicSubscribe>;
@@ -88,5 +90,6 @@ export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubs
88
90
  * ```
89
91
  *
90
92
  * @param options - Unsubscribe information. You must specify `channel`, `subscriptionId`, or both.
93
+ * @requiredField options
91
94
  */
92
95
  export declare const unsubscribe: MaybeContext<BuildRESTFunction<typeof publicUnsubscribe> & typeof publicUnsubscribe>;
@@ -48,7 +48,9 @@ const rest_modules_1 = require("@wix/sdk-runtime/rest-modules");
48
48
  * ```
49
49
  *
50
50
  * @param channel - Channel, and optionally resource, to subscribe to.
51
+ * @requiredField channel
51
52
  * @param messageHandler - Callback that runs whenever a message is published to the channel.
53
+ * @requiredField messageHandler
52
54
  * @param options - Lifecycle handlers for subscription events.
53
55
  */
54
56
  exports.subscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.subscribe);
@@ -91,5 +93,6 @@ exports.subscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.
91
93
  * ```
92
94
  *
93
95
  * @param options - Unsubscribe information. You must specify `channel`, `subscriptionId`, or both.
96
+ * @requiredField options
94
97
  */
95
98
  exports.unsubscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.unsubscribe);
@@ -38,7 +38,7 @@
38
38
  "summary": [
39
39
  {
40
40
  "kind": "text",
41
- "text": "Publishes a message to a channel or resource.\n\nThe method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.\n\n> **Authentication**\n>\n> This method may require higher-level permissions than the caller has, based on their [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) and [roles and permissions](https://support.wix.com/en/article/roles-permissions-overview). In these cases, you can ensure the method is called with the required level of authorization by using [elevated permissions](https://dev.wix.com/docs/api-reference/articles/authentication/about-elevated-permissions).\n\n<!-- TODO: Check whether this API is relevant for headless projects. -->"
41
+ "text": "Publishes a message to a channel or resource.\n\nThe method publishes a message to all subscribers on the specified channel or resource. Channels and resources are independent, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.\n\n> **Authentication**\n>\n> This method may require higher-level permissions than the caller has, based on their [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) and [roles and permissions](https://support.wix.com/en/article/roles-permissions-overview). In these cases, you can ensure the method is called with the required level of authorization by using [elevated permissions](https://dev.wix.com/docs/api-reference/articles/authentication/about-elevated-permissions).\n\n<!-- TODO: Check whether this API is relevant for headless projects. -->"
42
42
  }
43
43
  ],
44
44
  "blockTags": [
@@ -67,6 +67,24 @@
67
67
  "text": "```ts\nimport { publisher } from '@wix/realtime';\nimport { createClient } from '@wix/sdk';\n\n// Import the auth strategy for the relevant access type\n// Import the relevant host module if needed\n\nconst client = createClient({\n modules: { publisher },\n // Include the auth strategy and host as relevant\n});\n\nawait client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });\n```"
68
68
  }
69
69
  ]
70
+ },
71
+ {
72
+ "tag": "@requiredField",
73
+ "content": [
74
+ {
75
+ "kind": "text",
76
+ "text": "channel"
77
+ }
78
+ ]
79
+ },
80
+ {
81
+ "tag": "@requiredField",
82
+ "content": [
83
+ {
84
+ "kind": "text",
85
+ "text": "payload"
86
+ }
87
+ ]
70
88
  }
71
89
  ]
72
90
  },
@@ -81,7 +99,7 @@
81
99
  "summary": [
82
100
  {
83
101
  "kind": "text",
84
- "text": "Channel or resource to publish to."
102
+ "text": "Channel and optionally resource to publish to."
85
103
  }
86
104
  ]
87
105
  },
@@ -153,7 +171,7 @@
153
171
  "summary": [
154
172
  {
155
173
  "kind": "text",
156
- "text": "Publishes a message to a channel or resource.\n\nThe method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.\n\n> **Authentication**\n>\n> This method may require higher-level permissions than the caller has, based on their [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) and [roles and permissions](https://support.wix.com/en/article/roles-permissions-overview). In these cases, you can ensure the method is called with the required level of authorization by using [elevated permissions](https://dev.wix.com/docs/api-reference/articles/authentication/about-elevated-permissions).\n\n<!-- TODO: Check whether this API is relevant for headless projects. -->"
174
+ "text": "Publishes a message to a channel or resource.\n\nThe method publishes a message to all subscribers on the specified channel or resource. Channels and resources are independent, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.\n\n> **Authentication**\n>\n> This method may require higher-level permissions than the caller has, based on their [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) and [roles and permissions](https://support.wix.com/en/article/roles-permissions-overview). In these cases, you can ensure the method is called with the required level of authorization by using [elevated permissions](https://dev.wix.com/docs/api-reference/articles/authentication/about-elevated-permissions).\n\n<!-- TODO: Check whether this API is relevant for headless projects. -->"
157
175
  }
158
176
  ],
159
177
  "blockTags": [
@@ -182,6 +200,24 @@
182
200
  "text": "```ts\nimport { publisher } from '@wix/realtime';\nimport { createClient } from '@wix/sdk';\n\n// Import the auth strategy for the relevant access type\n// Import the relevant host module if needed\n\nconst client = createClient({\n modules: { publisher },\n // Include the auth strategy and host as relevant\n});\n\nawait client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });\n```"
183
201
  }
184
202
  ]
203
+ },
204
+ {
205
+ "tag": "@requiredField",
206
+ "content": [
207
+ {
208
+ "kind": "text",
209
+ "text": "channel"
210
+ }
211
+ ]
212
+ },
213
+ {
214
+ "tag": "@requiredField",
215
+ "content": [
216
+ {
217
+ "kind": "text",
218
+ "text": "payload"
219
+ }
220
+ ]
185
221
  }
186
222
  ]
187
223
  },
@@ -401,7 +437,15 @@
401
437
  "summary": [
402
438
  {
403
439
  "kind": "text",
404
- "text": "Checks permissions for a subscriber on a channel or resource.\n\nRuns the appropriate permissions handler to check whether the subscriber can receive messages on the specified channel or resource.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
440
+ "text": "Checks permissions for a subscriber on a channel or resource.\n\nRuns the appropriate permissions handler to check whether the subscriber can receive messages on the specified channel or resource. Call this method in the body of the ["
441
+ },
442
+ {
443
+ "kind": "code",
444
+ "text": "`realtime_check_permission()`"
445
+ },
446
+ {
447
+ "kind": "text",
448
+ "text": "](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/realtime-check-permission) hook.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
405
449
  }
406
450
  ],
407
451
  "blockTags": [
@@ -450,15 +494,6 @@
450
494
  }
451
495
  ]
452
496
  },
453
- {
454
- "tag": "@servicePath",
455
- "content": [
456
- {
457
- "kind": "text",
458
- "text": "wix-realtime-backend.ChannelPermissions"
459
- }
460
- ]
461
- },
462
497
  {
463
498
  "tag": "@servicePath",
464
499
  "content": [
@@ -562,7 +597,7 @@
562
597
  "summary": [
563
598
  {
564
599
  "kind": "text",
565
- "text": "Sets the default permissions handler.\n\nThe default handler runs when the specified channel or resource doesn't have an explicit handler. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
600
+ "text": "Sets the default permissions handler.\n\nThe default handler runs when no explicit handler is set for the channel. For resources, the handler runs when both the resource and its parent channel don't have one. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
566
601
  }
567
602
  ],
568
603
  "blockTags": [
@@ -701,15 +736,6 @@
701
736
  }
702
737
  ]
703
738
  },
704
- {
705
- "tag": "@servicePath",
706
- "content": [
707
- {
708
- "kind": "text",
709
- "text": "wix-realtime-backend.ChannelPermissions"
710
- }
711
- ]
712
- },
713
739
  {
714
740
  "tag": "@servicePath",
715
741
  "content": [
@@ -732,7 +758,7 @@
732
758
  "summary": [
733
759
  {
734
760
  "kind": "text",
735
- "text": "Channel or resource being checked."
761
+ "text": "Channel or resource to check."
736
762
  }
737
763
  ]
738
764
  },
@@ -753,7 +779,7 @@
753
779
  "summary": [
754
780
  {
755
781
  "kind": "text",
756
- "text": "Subscriber whose permissions are being checked."
782
+ "text": "Subscriber to check permissions for."
757
783
  }
758
784
  ]
759
785
  },
@@ -815,7 +841,7 @@
815
841
  "summary": [
816
842
  {
817
843
  "kind": "text",
818
- "text": "Sets a permissions handler for a specific channel or resource.\n\nAdding a handler to a channel without specifying a resource adds the handler to the channel and to all resources that don't have their own handler. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
844
+ "text": "Sets a permissions handler for a specific channel or resource.\n\nAdding a handler to a channel without specifying a resource applies the handler to the channel and to any of its resources that don't have their own handler. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
819
845
  }
820
846
  ],
821
847
  "blockTags": [
@@ -936,7 +962,15 @@
936
962
  "summary": [
937
963
  {
938
964
  "kind": "text",
939
- "text": "Checks permissions for a subscriber on a channel or resource.\n\nRuns the permissions handler appropriate for the subscriber on the specified channel or resource.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
965
+ "text": "Checks permissions for a subscriber on a channel or resource.\n\nRuns the appropriate permissions handler to check whether the subscriber can receive messages on the specified channel or resource. Call this method in the body of the ["
966
+ },
967
+ {
968
+ "kind": "code",
969
+ "text": "`realtime_check_permission()`"
970
+ },
971
+ {
972
+ "kind": "text",
973
+ "text": "](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/realtime-check-permission) hook.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
940
974
  }
941
975
  ],
942
976
  "blockTags": [
@@ -985,15 +1019,6 @@
985
1019
  }
986
1020
  ]
987
1021
  },
988
- {
989
- "tag": "@servicePath",
990
- "content": [
991
- {
992
- "kind": "text",
993
- "text": "wix-realtime-backend.ChannelPermissions"
994
- }
995
- ]
996
- },
997
1022
  {
998
1023
  "tag": "@servicePath",
999
1024
  "content": [
@@ -1086,7 +1111,7 @@
1086
1111
  "summary": [
1087
1112
  {
1088
1113
  "kind": "text",
1089
- "text": "Sets the default permissions handler.\n\nThe default handler runs when the specified channel or resource doesn't have an explicit handler.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
1114
+ "text": "Sets the default permissions handler.\n\nThe default handler runs when no explicit handler is set for the channel. For resources, the handler runs when both the resource and its parent channel don't have one. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
1090
1115
  }
1091
1116
  ],
1092
1117
  "blockTags": [
@@ -1226,7 +1251,7 @@
1226
1251
  "summary": [
1227
1252
  {
1228
1253
  "kind": "text",
1229
- "text": "Resource ID.\n\nResources are isolated sub-channels in a channel. A subscriber listening to a resource doesn't receive messages published to the parent channel, and vice versa."
1254
+ "text": "Resource ID.\n\nResources are independent sub-channels in a channel. A subscriber listening to a resource doesn't receive messages published to the parent channel, and vice versa."
1230
1255
  }
1231
1256
  ]
1232
1257
  },
@@ -1729,7 +1754,15 @@
1729
1754
  "summary": [
1730
1755
  {
1731
1756
  "kind": "text",
1732
- "text": "Checks permissions for a subscriber on a channel or resource.\n\nThis hook runs automatically whenever a new subscription is attempted.\n\nSet up this hook as a named export in the **realtime-permissions.js** file in a site's backend.\n\nLearn more about [setting up permissions](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#setting-up-permissions)."
1757
+ "text": "Checks permissions for a subscriber on a channel or resource.\n\nThis hook runs automatically whenever a new subscription is attempted, including [re-subscriptions after reconnection](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction#business-solutions_realtime_realtime_subscriber_reconnection-and-message-sync). Permissions are checked once per subscription attempt. Changes to permissions don't affect active subscriptions until the subscriber reconnects.\n\nSet up this hook as a named export in the "
1758
+ },
1759
+ {
1760
+ "kind": "code",
1761
+ "text": "`realtime-permissions.js`"
1762
+ },
1763
+ {
1764
+ "kind": "text",
1765
+ "text": " file in a site's backend.\n\nCall the [Permissions Router](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction) to organize logic per channel and resource. You can include permissions logic directly in the hook body, but for most use cases, use the permissions router.\n\nLearn more about [setting up permissions](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction#setting-up-permissions)."
1733
1766
  }
1734
1767
  ],
1735
1768
  "blockTags": [
@@ -1954,6 +1987,24 @@
1954
1987
  "text": "```ts\nimport { createClient } from '@wix/sdk';\nimport { subscriber } from '@wix/realtime';\n\n// Import the auth strategy for the relevant access type\n// Import the relevant host module if needed\n\nconst client = createClient({\n modules: { subscriber },\n // Include the auth strategy and host as relevant\n});\n\nconst subscriptionId = client.subscriber.subscribe(\n { name: 'my-channel' },\n (message, channel) => {\n console.log('Received:', message.payload);\n },\n {\n onSubscribed: (id, isSynced) => console.log('Subscribed', id),\n onSubscriptionError: (error, id) => console.error('Error', error),\n },\n);\n```"
1955
1988
  }
1956
1989
  ]
1990
+ },
1991
+ {
1992
+ "tag": "@requiredField",
1993
+ "content": [
1994
+ {
1995
+ "kind": "text",
1996
+ "text": "channel"
1997
+ }
1998
+ ]
1999
+ },
2000
+ {
2001
+ "tag": "@requiredField",
2002
+ "content": [
2003
+ {
2004
+ "kind": "text",
2005
+ "text": "messageHandler"
2006
+ }
2007
+ ]
1957
2008
  }
1958
2009
  ]
1959
2010
  },
@@ -2084,6 +2135,24 @@
2084
2135
  "text": "```ts\nimport { createClient } from '@wix/sdk';\nimport { subscriber } from '@wix/realtime';\n\n// Import the auth strategy for the relevant access type\n// Import the relevant host module if needed\n\nconst client = createClient({\n modules: { subscriber },\n // Include the auth strategy and host as relevant\n});\n\nconst subscriptionId = client.subscriber.subscribe(\n { name: 'my-channel' },\n (message, channel) => {\n console.log('Received:', message.payload);\n },\n {\n onSubscribed: (id, isSynced) => console.log('Subscribed', id),\n onSubscriptionError: (error, id) => console.error('Error', error),\n },\n);\n```"
2085
2136
  }
2086
2137
  ]
2138
+ },
2139
+ {
2140
+ "tag": "@requiredField",
2141
+ "content": [
2142
+ {
2143
+ "kind": "text",
2144
+ "text": "channel"
2145
+ }
2146
+ ]
2147
+ },
2148
+ {
2149
+ "tag": "@requiredField",
2150
+ "content": [
2151
+ {
2152
+ "kind": "text",
2153
+ "text": "messageHandler"
2154
+ }
2155
+ ]
2087
2156
  }
2088
2157
  ]
2089
2158
  },
@@ -2179,6 +2248,15 @@
2179
2248
  "text": "```ts\nimport { subscriber } from '@wix/realtime';\nimport { createClient } from '@wix/sdk';\n\n// Import the auth strategy for the relevant access type\n// Import the relevant host module if needed\n\nconst client = createClient({\n modules: { subscriber },\n // Include the auth strategy and host as relevant\n});\n\n// Remove the specified subscription\nclient.subscriber.unsubscribe({ subscriptionId });\n\n// Remove all subscriptions from the specified channel\nclient.subscriber.unsubscribe({ channel: { name: 'my-channel' } });\n```"
2180
2249
  }
2181
2250
  ]
2251
+ },
2252
+ {
2253
+ "tag": "@requiredField",
2254
+ "content": [
2255
+ {
2256
+ "kind": "text",
2257
+ "text": "options"
2258
+ }
2259
+ ]
2182
2260
  }
2183
2261
  ]
2184
2262
  },
@@ -2281,6 +2359,15 @@
2281
2359
  "text": "```ts\nimport { subscriber } from '@wix/realtime';\nimport { createClient } from '@wix/sdk';\n\n// Import the auth strategy for the relevant access type\n// Import the relevant host module if needed\n\nconst client = createClient({\n modules: { subscriber },\n // Include the auth strategy and host as relevant\n});\n\n// Remove the specified subscription\nclient.subscriber.unsubscribe({ subscriptionId });\n\n// Remove all subscriptions from the specified channel\nclient.subscriber.unsubscribe({ channel: { name: 'my-channel' } });\n```"
2282
2360
  }
2283
2361
  ]
2362
+ },
2363
+ {
2364
+ "tag": "@requiredField",
2365
+ "content": [
2366
+ {
2367
+ "kind": "text",
2368
+ "text": "options"
2369
+ }
2370
+ ]
2284
2371
  }
2285
2372
  ]
2286
2373
  },
@@ -3493,32 +3580,35 @@
3493
3580
  "symbolIdMap": {}
3494
3581
  },
3495
3582
  "appendices": {
3496
- "/": [
3583
+ "/publisher": [
3497
3584
  {
3498
3585
  "type": "GUIDE",
3499
3586
  "title": "Introduction",
3500
- "src": "---\narticleType: intro\n---\n\n# About the Realtime APIs\n\nThe Realtime APIs let you send and receive messages between a site backend and connected clients in real time. When a backend service publishes messages to a channel, clients subscribed to that channel receive them instantly.\n\nWith the Realtime APIs, you can:\n\n- Publish messages from the backend to channels and channel resources.\n- Subscribe to channels and resources to receive messages on connected clients.\n- Control which subscribers receive messages on specific channels or channel resources.\n\nThe Realtime APIs consist of the following modules that work together:\n\n- [**Publisher**](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/publisher/introduction): Backend module that sends messages to channels.\n- [**Site**](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction): Backend module that manages subscriber permissions.\n- [**Subscriber**](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction): Client module that listens to channels and receives messages.\n\n## How the modules work together\n\nThe Publisher sends a message to a channel or channel resource. The Site module checks whether each subscriber has permission to listen on that channel. Subscribers that have the appropriate permissions receive the message in real time.\n\nA typical flow looks like this:\n\n1. Define permissions in the **realtime-permissions.js** in the site's backend using the [Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction).\n2. A client subscribes to a channel or channel resource using the [Subscriber API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction).\n3. The [`realtime_check_permission`](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/realtime-check-permission) hook checks the subscriber's permissions.\n4. The [Publisher](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/publisher/introduction) publishes a message to the channel.\n5. The subscriber receives the message.\n\n## Channels and channel resources\n\nChannels are the mechanism by which publishers send messages to subscribers. Each channel has a unique name and can contain resources that act as sub-channels. Clients can subscribe to a channel or resource. When a publisher sends a message, subscribers receive the messages instantly if they have the appropriate permissions.\n\nChannels and resources are strictly isolated: subscribing to a channel doesn't include messages published to a resource on that channel, and subscribing to a resource doesn't include messages published to the parent channel.\n\n## Publisher\n\nThe [Publisher API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/publisher/introduction) is a backend module that sends messages to subscribers listening to the specified channel or resource.\n\n## Site\n\nThe [Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction) controls subscriber permissions. It determines which subscribers can receive messages on specific channels and resources.\n\nLearn more about [permissions in the Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction).\n\n## Subscribers\n\nA subscriber is a client that listens to a channel or resource. When a message is published to a channel or resource, all subscribers with [the appropriate permissions](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction) receive the message. \n\nYou can set up dedicated handlers for incoming messages, subscription successes, and subscription failures.\n\nLearn more about the [Subscriber API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction).\n\n\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- Messages are ephemeral. They don't persist across sessions.\n- When previewing the site, `read` permissions are always `true`.\n<!-- TODO: Document channel/subscription limits per site/app. -->\n\n<!-- ## Use cases\n\n- [Send notifications to connected clients](ADDLINK).\n- [Broadcast data updates in real time](ADDLINK).\n- [Push state changes to a live dashboard](ADDLINK). -->\n\n## Terminology\n\n- **Channel**: Named broadcast channel that publishers send messages to and subscribers listen on.\n- **Resource**: Isolated sub-channel in a channel. Messages on a resource are isolated from messages on its parent channel.\n- **Message**: Data published to a channel or resource.\n- **Publisher**: Service that sends messages to subscribers.\n- **Subscriber**: Client that listens for messages on a channel or resource.\n- **Subscription**: Active connection between a subscriber and a channel or resource, identified by a subscription ID.\n\n"
3501
- }
3502
- ],
3503
- "/publisher": [
3587
+ "src": "---\narticleType: intro\n---\n\n# About the Publisher API\n\nThe Publisher API is a backend module for sending messages to [channels and resources](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction#channels-and-channel-resources). Subscribers with suitable permissions receive these messages instantly. Channels and resources are independent, so messages sent to a channel aren't delivered to a resource, and vice versa.\n\nLearn more [about the Realtime APIs](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction).\n\n<!-- TODO check that elevation note appears in method description -->\n<!-- TODO: Check whether this API is relevant for headless projects. -->\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- Messages don't persist across tab sessions. Closing the browser tab or window closes the connection.\n- Messages aren't queued. When no subscribers are listening, the message is dropped.\n\n<!-- ## Use cases\n\n- [Send notifications to connected clients](ADDLINK).\n- [Broadcast data updates in real time](ADDLINK).\n- [Push state changes to a live dashboard](ADDLINK). -->\n\n## See also\n\n- [Subscriber API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction)\n- [Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction)\n- [Permissions Router API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction)\n\n@sdk_package_setup\n"
3588
+ },
3504
3589
  {
3505
3590
  "type": "GUIDE",
3506
- "title": "Introduction",
3507
- "src": "---\narticleType: intro\n---\n\n# About the Publisher API\n\nThe Publisher API is a backend module for sending messages to [channels and resources](ADDLINK). [Subscribers](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction) with suitable [permissions](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction) receive these messages instantly. Channels and resources are isolated, so messages sent to a channel are not published to a resource, and vice versa.\n\nLearn more [about the Realtime APIs](ADDLINK).\n\n<!-- TODO check that elevation note appears in method description -->\n<!-- TODO: Check whether this API is relevant for headless projects. -->\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- Messages aren't queued. When no subscribers are listening, the message is dropped.\n- Messages don't persist across sessions.\n\n<!-- ## Use cases\n\n- [Send notifications to connected clients](ADDLINK).\n- [Broadcast data updates in real time](ADDLINK).\n- [Push state changes to a live dashboard](ADDLINK). -->\n\n@sdk_package_setup\n"
3591
+ "title": "Setup",
3592
+ "src": "# Setup\n\n@package_metadata:@wix/realtime\n\nTo use the Realtime API, install the `@wix/realtime` package.\n\n#### Install the package\n\nFollow the installation instructions for your development environment.\n\n| Development environment | Installation method |\n| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Wix sites (editor or IDE) | Use the [package manager](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |\n| Wix sites (local IDE) | Run `wix install @wix/realtime` using the [CLI](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli). |\n\n#### Import the package\n\nTo import the package in your code:\n\n```js\nimport { publisher } from '@wix/realtime';\n```\n"
3508
3593
  }
3509
3594
  ],
3510
3595
  "/subscriber": [
3511
3596
  {
3512
3597
  "type": "GUIDE",
3513
3598
  "title": "Introduction",
3514
- "src": "---\narticleType: intro\n---\n\n# About the Subscriber API\n\nThe Subscriber API allows users to subscribe to [channels and resources](ADDLINK). When a [publisher](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/publisher/introduction) sends messages, subscribers with suitable permissions receive them in real time. Channels and resources are isolated, so messages sent to a channel aren't published to a resource, and vice versa.\n\nLearn more [about the Realtime APIs](ADDLINK).\n\nWith the Subscriber API, you can:\n\n- Subscribe or unsubscribe from a channel or resource.\n- Respond to subscription successes, connection errors, and incoming messages with dedicated handlers.\n\n## Subscription lifecycle\n\nWhile subscribing is asynchronous, the `subscribe()` method returns a subscription ID immediately, but the connection is established in the background. Subscribers can use the subscription ID to [unsubscribe](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/unsubscribe) at a later time. \n\nYou can register lifecycle handlers to respond when the subscription succeeds or fails. The [`onSubscribed` handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) runs on every successful connection, including automatic re-subscriptions attempted after network interruptions. The [`onSubscriptionError` handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) runs whenever an error occurs.\n\n### Unsubscribing\n\nYou can unsubscribe in the following ways:\n\n- By `subscriptionId`: Removes a single subscription.\n- By `channel`: Removes all subscriptions to that channel or resource.\n- By both: Removes the specific subscription, verifying it matches the specified channel or resource. If it doesn't, the subscription isn't removed.\n\nWhen the last subscription on a connection is removed, the connection closes automatically.\n\n## Reconnection and message sync\n\nIf the connection drops, the client automatically attempts to reconnect and re-subscribe. When subscribing or re-subscribing, the `isSynced` parameter of the `onSubscribed()` hook indicates whether all missed messages were successfully restored, or whether manual the subscriber needs to take further action. \n\nLearn more about [subscribing](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) to a channel or resource.\n\n<!-- TODO: Document server-side buffer limits for message replay. -->\n\n## Subscription errors\n\nSubscription errors are caused by the subscription being rejected or by connection failures. Each error includes `errorCode` and `recoverable` properties that indicate the error type and whether the client is automatically retrying.\n\nLearn more about how the [`subscribe()`](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) method handles subscription errors.\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- Subscriptions are ephemeral. They don't persist across sessions.\n- Closing a browser tab removes all its subscriptions.\n- Permissions are checked when a subscription is first established. When a subscriber doesn't have `read` permission on the channel, their subscription fails.\n<!-- TODO: Document channel/subscription limits per site/app. -->\n\n<!-- ## Use cases\n\n- [Send notifications to connected clients](ADDLINK).\n- [Broadcast data updates in real time](ADDLINK).\n- [Push state changes to a live dashboard](ADDLINK). -->\n\n## Terminology\n\n- **Subscription**: An active connection between a client and a channel or resource, identified by a subscription ID.\n- **Subscription ID**: A unique identifier returned by `subscribe()`. Use it to unsubscribe or track lifecycle events.\n\n@sdk_package_setup\n"
3599
+ "src": "---\narticleType: intro\n---\n\n# About the Subscriber API\n\nThe Subscriber API lets clients subscribe to [channels and resources](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction#channels-and-channel-resources). When a publisher sends messages, subscribers with suitable permissions receive them in real time. Channels and resources are independent, so messages sent to a channel aren't published to a resource, and vice versa.\n\nLearn more [about the Realtime APIs](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction).\n\nWith the Subscriber API, you can:\n\n- Subscribe or unsubscribe from a channel or resource.\n- Respond to subscription successes, connection errors, and incoming messages with dedicated handlers.\n\n## Subscription lifecycle\n\nThe `subscribe()` method returns a subscription ID immediately, but the connection is established in the background. Subscribers can use the subscription ID to [unsubscribe](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/unsubscribe) at a later time.\n\nYou can register lifecycle handlers to respond when the subscription succeeds or fails. The [`onSubscribed` handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) runs on every successful connection, including automatic re-subscriptions attempted after network interruptions. The [`onSubscriptionError` handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) runs whenever an error occurs.\n\n### Unsubscribing\n\nYou can unsubscribe in the following ways:\n\n- By `subscriptionId`: Removes a single subscription.\n<!-- TODO: Confirm with dev that unsubscribing by channel doesn't affect resource subscriptions, and vice versa. Item 2.13-->\n- By `channel`: Removes all subscriptions that match the specified channel and resource exactly. Unsubscribing from a channel doesn't affect subscriptions to resources on that channel, and vice versa.\n- By both: Removes the specific subscription, verifying it matches the specified channel or resource. If it doesn't, the subscription isn't removed.\n\nWhen the last subscription on a connection is removed, the connection closes automatically.\n\n## Reconnection and message sync\n\nIf the connection drops, the client automatically attempts to reconnect and re-subscribe. When subscribing or re-subscribing, the `isSynced` parameter of the `onSubscribed()` handler indicates whether all missed messages were successfully restored, or whether the subscriber needs to take further action.\n\nLearn more about [subscribing](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) to a channel or resource.\n\n<!-- TODO: Document backend buffer limits for message replay. -->\n\n## Subscription errors\n\nSubscription errors occur when a subscription is rejected or when the connection fails. Each error includes `errorCode` and `recoverable` properties that indicate the error type and whether the client is automatically retrying.\n\nLearn more about how the [`subscribe()`](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/subscribe) method handles subscription errors.\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- Subscriptions don't persist across sessions.\n- Closing a browser tab removes all its subscriptions.\n- The Realtime SDK checks permissions when a subscription is first established. When a subscriber doesn't have `read` permission on the channel, the subscription fails.\n<!-- TODO: Document channel/subscription limits per site/app. -->\n\n<!-- ## Use cases\n\n- [Send notifications to connected clients](ADDLINK).\n- [Broadcast data updates in real time](ADDLINK).\n- [Push state changes to a live dashboard](ADDLINK). -->\n\n## See also\n\n- [Publisher API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/publisher/introduction)\n- [Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction)\n- [Permissions Router API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction)\n\n@sdk_package_setup\n"
3600
+ },
3601
+ {
3602
+ "type": "GUIDE",
3603
+ "title": "Setup",
3604
+ "src": "# Setup\n\n@package_metadata:@wix/realtime\n\nTo use the Realtime API, install the `@wix/realtime` package.\n\n#### Install the package\n\nFollow the installation instructions for your development environment.\n\n| Development environment | Installation method |\n| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Wix sites (editor or IDE) | Use the [package manager](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |\n| Wix sites (local IDE) | Run `wix install @wix/realtime` using the [CLI](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli). |\n\n#### Import the package\n\nTo import the package in your code:\n\n```js\nimport { subscriber } from '@wix/realtime';\n```\n"
3515
3605
  }
3516
3606
  ],
3517
3607
  "/site": [
3518
3608
  {
3519
3609
  "type": "GUIDE",
3520
3610
  "title": "Introduction",
3521
- "src": "---\narticleType: intro\n---\n\n# About the Site API\n\nThe Site API lets you control subscriber permissions for the [Realtime APIs](ADDLINK). It determines which [subscribers](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction) can receive messages on specific [channels and resources](ADDLINK).\n\nTo define permissions, set up the [`realtime_check_permission` hook](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/realtime-check-permission) in the **realtime-permissions.js** file in a site's backend. You can include all permissions logic directly in the hook, or use the [permissions router](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction) to organize permissions logic per channel and resource.\n\nWith the Site API, you can:\n\n- Define the `realtime_check_permission` hook to control subscriber access.\n- Use the [permissions router](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction) to organize permission logic per channel or resource.\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- In Wix Studio, you must create a **realtime-permissions.js** file in a site's backend, even if the `realtime_check_permission` isn't defined. Without the file, subscriptions fail.\n- When the `realtime_check_permission` hook isn't defined, all subscribers receive the default permissions of `{\"read\": true}`.\n- When previewing a site, `read` permissions are always `true`.\n- Learn more about [permissions in the realtime SDK](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction).\n\n<!-- ## Use cases\n\n- [Restrict channels to logged-in members](ADDLINK). -->\n\n@sdk_package_setup"
3611
+ "src": "---\narticleType: intro\n---\n\n# About the Site API\n\nThe Site API lets you control subscriber permissions for the [Realtime APIs](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction). It determines which [subscribers](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction) can receive messages on specific [channels and resources](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction#channels-and-channel-resources).\n\nWith the Site API, you can:\n\n- Define the [`realtime_check_permission` hook](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/realtime-check-permission) in the `realtime-permissions.js` file in a site's backend to control subscriber access.\n- Use the [permissions router](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction) to organize permission logic per channel or resource.\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- In Wix Studio, you must create a `realtime-permissions.js` file in a site's backend, even if `realtime_check_permission` isn't defined. Without the file, subscriptions fail.\n- When the `realtime_check_permission` hook isn't defined, all subscribers receive the default permissions of `{\"read\": true}`.\n- When previewing a site, `read` permissions are always `true`.\n\n## Use cases\n\nRestrict a channel so only the site owner can receive messages. Use the [permissions router](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction) to add a handler that checks `subscriber.type`:\n\n```js\nimport { site } from \"@wix/realtime\";\nconst { permissionsRouter } = site;\n\npermissionsRouter.add({ name: \"owner-only\" }, (channel, subscriber) => {\n return { read: subscriber.type === \"USER\" };\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n return permissionsRouter.check(channel, subscriber);\n}\n```\n\n## See also\n\n- [Realtime APIs](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction)\n- [Permissions Router API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction)\n- [Subscriber API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction)\n- [Publisher API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/publisher/introduction)\n\n@sdk_package_setup\n"
3522
3612
  },
3523
3613
  {
3524
3614
  "type": "GUIDE",
@@ -3581,14 +3671,14 @@
3581
3671
  {
3582
3672
  "type": "GUIDE",
3583
3673
  "title": "Introduction",
3584
- "src": "---\narticleType: intro\n---\n\n# About the Permissions Router API\n\nThe Permissions Router API is a utility for organizing channel permission logic. The router lets you set up a default permissions handler as well as handlers specific to channels or resources.\n\n> **Note**: Alternatively, you can include permissions logic in the [`realtime_check_permission()` hook](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/introduction).\n\nLearn more about the [Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction) and the [Realtime APIs](ADDLINK).\n\nWith the Permissions Router API, you can:\n\n- [Add a handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/add) for a specific channel or resource.\n- [Set a default handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/default) for channels that don't have explicit handlers.\n- [Check](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/check) subscriber permissions.\n\n## Setting up permissions\n\nTo set up permissions:\n\n1. Create a **realtime-permissions.js** file in a site's backend.\n2. Export a `realtime_check_permission` hook. This hook runs automatically whenever a subscription is attempted.\n3. In the hook body, call `permissionsRouter.check()` to evaluate the subscriber's permissions based on the handlers you've registered.\n\n```js\nimport { permissionsRouter } from '@wix/realtime';\n\npermissionsRouter.default((channel, subscriber) => {\n return { read: true };\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n return permissionsRouter.check(channel, subscriber);\n}\n```\n\n## Permission resolution\n\nPermissions can be set at the channel level or the resource level. They determine whether subscribers can receive messages published to that channel or resource.\n\nPermissions follow a cascading pattern:\n\n- When the specified resource [doesn't have a permissions handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/add), the handler for its parent channel runs.\n- When the specified or parent channel doesn't have a permissions handler, the [default permissions handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/default) runs.\n- When no default handler is set, all subscribers receive the default permissions of `{ \"read\": true }`.\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- You must create a **realtime-permissions.js** file in a site's backend. Without it, all subscriptions fail in Wix Studio.\n- When the `realtime_check_permission` hook isn't defined, all subscribers receive the default permissions of `{\"read\": true}`.\n- When previewing a site, `read` permissions are always `true`.\n\n<!-- ## Use cases\n\n- [Restrict channels to logged-in members](ADDLINK). -->\n\n@sdk_package_setup"
3674
+ "src": "---\narticleType: intro\n---\n\n# About the Permissions Router API\n\nThe Permissions Router API is a utility for organizing channel permission logic. The router lets you set up a default permissions handler as well as handlers specific to channels or resources.\n\n> **Note:** Alternatively, you can include permissions logic directly in the [`realtime_check_permission()` hook](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/realtime-check-permission).\n\nLearn more about the [Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction) and the [Realtime APIs](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction).\n\nWith the Permissions Router API, you can:\n\n- [Add a handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/add) for a specific channel or resource.\n- [Set a default handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/default) for channels that don't have explicit handlers.\n- [Check](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/check) subscriber permissions.\n\n## Setting up permissions\n\nTo set up permissions using the router:\n\n1. Create a `realtime-permissions.js` file in a site's backend.\n2. Import the `permissionsRouter`:\n\n ```js\n import { site } from \"@wix/realtime\";\n const { permissionsRouter } = site;\n ```\n\n3. Define permission handlers using [`add()`](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/add) for specific channels or resources, and [`default()`](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/default) for a default fallback handler:\n\n ```js\n // Set a default handler that grants read access to all subscribers\n permissionsRouter.default((channel, subscriber) => {\n return { read: true };\n });\n\n // Restrict a specific channel to logged-in members\n permissionsRouter.add({ name: \"members-only\" }, (channel, subscriber) => {\n return { read: subscriber.type === \"MEMBER\" };\n });\n ```\n\n4. Export the `realtime_check_permission` hook and call `check()` to delegate to the router:\n\n ```js\n export function realtime_check_permission(channel, subscriber) {\n return permissionsRouter.check(channel, subscriber);\n }\n ```\n\n## Permission resolution\n\nPermissions can be set at the channel level or the resource level. They determine whether subscribers can receive messages published to that channel or resource.\n\nPermissions follow a cascading pattern:\n\n- When a resource [doesn't have a permissions handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/add), the handler for its parent channel runs.\n- When the parent channel doesn't have a permissions handler, the [default permissions handler](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/permissions-router/default) runs.\n- When no default handler is set, all subscribers receive the default permissions of `{ \"read\": true }`.\n\n> **Note:** Permissions are checked once per subscription attempt, including [re-subscriptions after reconnection](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction#business-solutions_realtime_realtime_subscriber_reconnection-and-message-sync). Changes to permissions don't affect active subscriptions until the subscriber reconnects.\n\n## Before you begin\n\nIt's important to note the following points before starting to code:\n\n- You must create a `realtime-permissions.js` file in a site's backend, even if you don't define any custom permissions. Without it, all subscriptions fail in Wix Studio.\n- When the `realtime_check_permission` hook isn't defined, all subscribers receive the default permissions of `{\"read\": true}`.\n- When previewing a site, `read` permissions are always `true`.\n\n## Use cases\n\nRestrict the `announcements` channel so only logged-in members can receive messages. All other channels remain open to everyone:\n\n```js\nimport { site } from \"@wix/realtime\";\nconst { permissionsRouter } = site;\n\n// Only logged-in members can listen to announcements\npermissionsRouter.add({ name: \"announcements\" }, (channel, subscriber) => {\n return { read: subscriber.type === \"MEMBER\" };\n});\n\n// All other channels are open to everyone\npermissionsRouter.default((channel, subscriber) => {\n return { read: true };\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n return permissionsRouter.check(channel, subscriber);\n}\n```\n\n## See also\n\n- [Realtime APIs](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/introduction)\n- [Site API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/site/introduction)\n- [Subscriber API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/subscriber/introduction)\n- [Publisher API](https://dev.wix.com/docs/sdk/business-solutions/realtime/realtime/publisher/introduction)\n\n@sdk_package_setup\n"
3585
3675
  }
3586
3676
  ],
3587
3677
  "/site/PermissionsRouter/add": [
3588
3678
  {
3589
3679
  "type": "EXAMPLE",
3590
3680
  "title": "Set a permissions handler for a specific channel",
3591
- "src": "// In realtime-permissions.js\n\nimport { site } from \"@wix/realtime\";\n\n// ...\n\nconst adminAnnouncements = {\"name\": \"announcements\"}\n\nsite.permissionsRouter.add( adminAnnouncements, (channel, subscriber) => {\n // add permissions check logic and return\n // permissions for announcements channel\n if(subscriber.type === \"Admin\") {\n return {\"read\": true};\n }\n else {\n return {\"read\": true};\n }\n} );"
3681
+ "src": "// In realtime-permissions.js\n\nimport { site } from \"@wix/realtime\";\nconst { permissionsRouter } = site;\n\n// Only the site owner can listen to announcements\npermissionsRouter.add({ name: \"announcements\" }, (channel, subscriber) => {\n return { read: subscriber.type === \"USER\" };\n});\n\n// Export the hook and delegate to the router\nexport function realtime_check_permission(channel, subscriber) {\n return permissionsRouter.check(channel, subscriber);\n}\n"
3592
3682
  },
3593
3683
  {
3594
3684
  "type": "EXAMPLE",
@@ -3,7 +3,7 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
3
3
  /**
4
4
  * Publishes a message to a channel or resource.
5
5
  *
6
- * The method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
6
+ * The method publishes a message to all subscribers on the specified channel or resource. Channels and resources are independent, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
7
7
  *
8
8
  * > **Authentication**
9
9
  * >
@@ -35,7 +35,9 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
35
35
  * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
36
36
  * ```
37
37
  *
38
- * @param channel - Channel or resource to publish to.
38
+ * @param channel - Channel and optionally resource to publish to.
39
+ * @requiredField channel
39
40
  * @param payload - Message payload. Max: 10 KB.
41
+ * @requiredField payload
40
42
  */
41
43
  export declare const publish: MaybeContext<BuildRESTFunction<typeof publicPublish> & typeof publicPublish>;
@@ -3,7 +3,7 @@ import { createRESTModule } from '@wix/sdk-runtime/rest-modules';
3
3
  /**
4
4
  * Publishes a message to a channel or resource.
5
5
  *
6
- * The method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
6
+ * The method publishes a message to all subscribers on the specified channel or resource. Channels and resources are independent, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
7
7
  *
8
8
  * > **Authentication**
9
9
  * >
@@ -35,7 +35,9 @@ import { createRESTModule } from '@wix/sdk-runtime/rest-modules';
35
35
  * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
36
36
  * ```
37
37
  *
38
- * @param channel - Channel or resource to publish to.
38
+ * @param channel - Channel and optionally resource to publish to.
39
+ * @requiredField channel
39
40
  * @param payload - Message payload. Max: 10 KB.
41
+ * @requiredField payload
40
42
  */
41
43
  export const publish = /*#__PURE__*/ createRESTModule(publicPublish);
@@ -45,7 +45,9 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
45
45
  * ```
46
46
  *
47
47
  * @param channel - Channel, and optionally resource, to subscribe to.
48
+ * @requiredField channel
48
49
  * @param messageHandler - Callback that runs whenever a message is published to the channel.
50
+ * @requiredField messageHandler
49
51
  * @param options - Lifecycle handlers for subscription events.
50
52
  */
51
53
  export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubscribe> & typeof publicSubscribe>;
@@ -88,5 +90,6 @@ export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubs
88
90
  * ```
89
91
  *
90
92
  * @param options - Unsubscribe information. You must specify `channel`, `subscriptionId`, or both.
93
+ * @requiredField options
91
94
  */
92
95
  export declare const unsubscribe: MaybeContext<BuildRESTFunction<typeof publicUnsubscribe> & typeof publicUnsubscribe>;
@@ -45,7 +45,9 @@ import { createRESTModule } from '@wix/sdk-runtime/rest-modules';
45
45
  * ```
46
46
  *
47
47
  * @param channel - Channel, and optionally resource, to subscribe to.
48
+ * @requiredField channel
48
49
  * @param messageHandler - Callback that runs whenever a message is published to the channel.
50
+ * @requiredField messageHandler
49
51
  * @param options - Lifecycle handlers for subscription events.
50
52
  */
51
53
  export const subscribe = /*#__PURE__*/ createRESTModule(publicSubscribe);
@@ -88,5 +90,6 @@ export const subscribe = /*#__PURE__*/ createRESTModule(publicSubscribe);
88
90
  * ```
89
91
  *
90
92
  * @param options - Unsubscribe information. You must specify `channel`, `subscriptionId`, or both.
93
+ * @requiredField options
91
94
  */
92
95
  export const unsubscribe = /*#__PURE__*/ createRESTModule(publicUnsubscribe);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wix/realtime",
3
- "version": "1.0.40",
3
+ "version": "1.0.42",
4
4
  "publishConfig": {
5
5
  "registry": "https://registry.npmjs.org/",
6
6
  "access": "public"
@@ -44,11 +44,11 @@
44
44
  "@wix/auto_sdk_duplexer_publisher": "^1.0.10",
45
45
  "@wix/auto_sdk_duplexer_realtime-permissions-provider": "^1.0.0",
46
46
  "@wix/duplexer-js": "^2.0.6",
47
- "@wix/realtime-common": "1.0.15",
47
+ "@wix/realtime-common": "1.0.16",
48
48
  "@wix/sdk": "^1.21.4",
49
49
  "@wix/sdk-runtime": "^1.0.9",
50
50
  "@wix/sdk-types": "^1.17.5",
51
- "@wix/sdk_realtime_site": "1.0.31",
51
+ "@wix/sdk_realtime_site": "1.0.33",
52
52
  "uuid": "^11.1.0"
53
53
  },
54
54
  "devDependencies": {
@@ -72,5 +72,5 @@
72
72
  "isRootPublicSdk": true
73
73
  }
74
74
  },
75
- "falconPackageHash": "00192eae4fb863495ba7cb35954ffb6f00076bbd32c605132020be11"
75
+ "falconPackageHash": "ca93cf2cc64db9484a449a2efa0b3d4db52d6eb2ccd663d29dda93f2"
76
76
  }