@wix/realtime 1.0.47 → 1.0.48
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/cjs/build/subscriber/subscriber.context.d.ts +2 -2
- package/cjs/build/subscriber/subscriber.context.js +2 -2
- package/dist/statics/docs-ts-model.json +17 -17
- package/es/build/subscriber/subscriber.context.d.ts +2 -2
- package/es/build/subscriber/subscriber.context.js +2 -2
- package/package.json +3 -3
|
@@ -7,7 +7,7 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
|
|
|
7
7
|
*
|
|
8
8
|
* Use the `options` parameter to register handlers that run whenever the subscription succeeds or generates an error. For some errors, the subscription is re-attempted automatically. The `onSubscribed()` handler runs on every successful re-subscription.
|
|
9
9
|
*
|
|
10
|
-
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/
|
|
10
|
+
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle).
|
|
11
11
|
*
|
|
12
12
|
* @example Subscribe to a channel
|
|
13
13
|
* ```ts
|
|
@@ -50,7 +50,7 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
|
|
|
50
50
|
* @requiredField channel
|
|
51
51
|
* @param messageHandler - Handler that runs whenever a message is published to the channel or resource.
|
|
52
52
|
* @requiredField messageHandler
|
|
53
|
-
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/
|
|
53
|
+
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle) for subscription events.
|
|
54
54
|
*/
|
|
55
55
|
export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubscribe> & typeof publicSubscribe>;
|
|
56
56
|
/**
|
|
@@ -10,7 +10,7 @@ const rest_modules_1 = require("@wix/sdk-runtime/rest-modules");
|
|
|
10
10
|
*
|
|
11
11
|
* Use the `options` parameter to register handlers that run whenever the subscription succeeds or generates an error. For some errors, the subscription is re-attempted automatically. The `onSubscribed()` handler runs on every successful re-subscription.
|
|
12
12
|
*
|
|
13
|
-
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/
|
|
13
|
+
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle).
|
|
14
14
|
*
|
|
15
15
|
* @example Subscribe to a channel
|
|
16
16
|
* ```ts
|
|
@@ -53,7 +53,7 @@ const rest_modules_1 = require("@wix/sdk-runtime/rest-modules");
|
|
|
53
53
|
* @requiredField channel
|
|
54
54
|
* @param messageHandler - Handler that runs whenever a message is published to the channel or resource.
|
|
55
55
|
* @requiredField messageHandler
|
|
56
|
-
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/
|
|
56
|
+
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle) for subscription events.
|
|
57
57
|
*/
|
|
58
58
|
exports.subscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.subscribe);
|
|
59
59
|
/**
|
|
@@ -331,7 +331,7 @@
|
|
|
331
331
|
"summary": [
|
|
332
332
|
{
|
|
333
333
|
"kind": "text",
|
|
334
|
-
"text": "Realtime permissions router.\n\nDefines which subscribers can receive messages on specific channels or resources. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/
|
|
334
|
+
"text": "Realtime permissions router.\n\nDefines which subscribers can receive messages on specific channels or resources. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
|
|
335
335
|
}
|
|
336
336
|
]
|
|
337
337
|
},
|
|
@@ -353,7 +353,7 @@
|
|
|
353
353
|
"summary": [
|
|
354
354
|
{
|
|
355
355
|
"kind": "text",
|
|
356
|
-
"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 all of its resources that don't have their own handler.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/
|
|
356
|
+
"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 all of its resources that don't have their own handler.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
|
|
357
357
|
}
|
|
358
358
|
],
|
|
359
359
|
"blockTags": [
|
|
@@ -491,7 +491,7 @@
|
|
|
491
491
|
},
|
|
492
492
|
{
|
|
493
493
|
"kind": "text",
|
|
494
|
-
"text": "](https://dev.wix.com/docs/sdk/
|
|
494
|
+
"text": "](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/realtime-check-permission) hook."
|
|
495
495
|
}
|
|
496
496
|
],
|
|
497
497
|
"blockTags": [
|
|
@@ -643,7 +643,7 @@
|
|
|
643
643
|
"summary": [
|
|
644
644
|
{
|
|
645
645
|
"kind": "text",
|
|
646
|
-
"text": "Sets the default permissions handler.\n\nThe default handler runs in the following cases:\n- When subscribing to a channel, when no explicit handler is set for that channel.\n- When subscribing to a resource, when no explicit handler is set for that resource or its parent channel.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/
|
|
646
|
+
"text": "Sets the default permissions handler.\n\nThe default handler runs in the following cases:\n- When subscribing to a channel, when no explicit handler is set for that channel.\n- When subscribing to a resource, when no explicit handler is set for that resource or its parent channel.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
|
|
647
647
|
}
|
|
648
648
|
],
|
|
649
649
|
"blockTags": [
|
|
@@ -887,7 +887,7 @@
|
|
|
887
887
|
"summary": [
|
|
888
888
|
{
|
|
889
889
|
"kind": "text",
|
|
890
|
-
"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 handlers. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/
|
|
890
|
+
"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 handlers. Learn more about [permission resolution](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
|
|
891
891
|
}
|
|
892
892
|
],
|
|
893
893
|
"blockTags": [
|
|
@@ -1016,7 +1016,7 @@
|
|
|
1016
1016
|
},
|
|
1017
1017
|
{
|
|
1018
1018
|
"kind": "text",
|
|
1019
|
-
"text": "](https://dev.wix.com/docs/sdk/
|
|
1019
|
+
"text": "](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/realtime-check-permission) hook.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
|
|
1020
1020
|
}
|
|
1021
1021
|
],
|
|
1022
1022
|
"blockTags": [
|
|
@@ -1157,7 +1157,7 @@
|
|
|
1157
1157
|
"summary": [
|
|
1158
1158
|
{
|
|
1159
1159
|
"kind": "text",
|
|
1160
|
-
"text": "Sets the default permissions handler.\n\nThe default handler runs in the following cases:\n- When subscribing to a channel, when no explicit handler is set for that channel.\n- When subscribing to a resource, when no explicit handler is set for that resource or its parent channel.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/
|
|
1160
|
+
"text": "Sets the default permissions handler.\n\nThe default handler runs in the following cases:\n- When subscribing to a channel, when no explicit handler is set for that channel.\n- When subscribing to a resource, when no explicit handler is set for that resource or its parent channel.\n\nLearn more about [permission resolution](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction#permission-resolution)."
|
|
1161
1161
|
}
|
|
1162
1162
|
],
|
|
1163
1163
|
"blockTags": [
|
|
@@ -1553,7 +1553,7 @@
|
|
|
1553
1553
|
"summary": [
|
|
1554
1554
|
{
|
|
1555
1555
|
"kind": "text",
|
|
1556
|
-
"text": "Realtime permissions router.\n\nDefines which subscribers can receive messages on specific channels or resources. Learn more about the [permissions router](https://dev.wix.com/docs/sdk/
|
|
1556
|
+
"text": "Realtime permissions router.\n\nDefines which subscribers can receive messages on specific channels or resources. Learn more about the [permissions router](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction)."
|
|
1557
1557
|
}
|
|
1558
1558
|
],
|
|
1559
1559
|
"blockTags": [
|
|
@@ -1808,7 +1808,7 @@
|
|
|
1808
1808
|
},
|
|
1809
1809
|
{
|
|
1810
1810
|
"kind": "text",
|
|
1811
|
-
"text": " file in a site's backend. The hook runs automatically whenever a new subscription is attempted, including [re-subscriptions after reconnection](https://dev.wix.com/docs/sdk/
|
|
1811
|
+
"text": " file in a site's backend. The hook runs automatically whenever a new subscription is attempted, including [re-subscriptions after reconnection](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_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\nCall ["
|
|
1812
1812
|
},
|
|
1813
1813
|
{
|
|
1814
1814
|
"kind": "code",
|
|
@@ -1816,7 +1816,7 @@
|
|
|
1816
1816
|
},
|
|
1817
1817
|
{
|
|
1818
1818
|
"kind": "text",
|
|
1819
|
-
"text": "](https://dev.wix.com/docs/sdk/
|
|
1819
|
+
"text": "](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/check) in the body of this hook to use the [Permissions Router](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction) to organize permissions logic. Alternatively, you can also include permissions logic directly in the hook body.\n\nLearn more about [setting up permissions](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction#setting-up-permissions)."
|
|
1820
1820
|
}
|
|
1821
1821
|
],
|
|
1822
1822
|
"blockTags": [
|
|
@@ -2012,7 +2012,7 @@
|
|
|
2012
2012
|
},
|
|
2013
2013
|
{
|
|
2014
2014
|
"kind": "text",
|
|
2015
|
-
"text": " handler runs on every successful re-subscription.\n\nLearn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/
|
|
2015
|
+
"text": " handler runs on every successful re-subscription.\n\nLearn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle)."
|
|
2016
2016
|
}
|
|
2017
2017
|
],
|
|
2018
2018
|
"blockTags": [
|
|
@@ -2117,7 +2117,7 @@
|
|
|
2117
2117
|
"summary": [
|
|
2118
2118
|
{
|
|
2119
2119
|
"kind": "text",
|
|
2120
|
-
"text": "[Lifecycle handlers](https://dev.wix.com/docs/sdk/
|
|
2120
|
+
"text": "[Lifecycle handlers](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle) for subscription events."
|
|
2121
2121
|
}
|
|
2122
2122
|
]
|
|
2123
2123
|
},
|
|
@@ -2160,7 +2160,7 @@
|
|
|
2160
2160
|
},
|
|
2161
2161
|
{
|
|
2162
2162
|
"kind": "text",
|
|
2163
|
-
"text": " handler runs on every successful re-subscription.\n\nLearn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/
|
|
2163
|
+
"text": " handler runs on every successful re-subscription.\n\nLearn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle)."
|
|
2164
2164
|
}
|
|
2165
2165
|
],
|
|
2166
2166
|
"blockTags": [
|
|
@@ -3808,7 +3808,7 @@
|
|
|
3808
3808
|
{
|
|
3809
3809
|
"type": "GUIDE",
|
|
3810
3810
|
"title": "Introduction",
|
|
3811
|
-
"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/
|
|
3811
|
+
"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/core-modules/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/core-modules/realtime/realtime/introduction).\n\nWith the Publisher API, you can:\n\n- Publish messages to a channel or resource.\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/core-modules/realtime/realtime/subscriber/introduction)\n- [Site API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/introduction)\n- [Permissions Router API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction)\n\n@sdk_package_setup\n"
|
|
3812
3812
|
},
|
|
3813
3813
|
{
|
|
3814
3814
|
"type": "GUIDE",
|
|
@@ -3820,7 +3820,7 @@
|
|
|
3820
3820
|
{
|
|
3821
3821
|
"type": "GUIDE",
|
|
3822
3822
|
"title": "Introduction",
|
|
3823
|
-
"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/
|
|
3823
|
+
"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/core-modules/realtime/realtime/introduction#channels-and-channel-resources) to receive messages in real time. Subscribers with suitable permissions instantly receive messages sent by a publisher. 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/core-modules/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/core-modules/realtime/realtime/subscriber/unsubscribe) at a later time.\n\nYou can register lifecycle handlers to respond when the subscription succeeds or fails:\n\n- The [`onSubscribed` handler](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/subscribe) runs on every successful connection, including [automatic re-connections](#reconnection-and-message-sync) attempted after network interruptions.\n- The [`onSubscriptionError` handler](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/subscribe) runs whenever an [error occurs](#subscription-errors).\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/core-modules/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` parameters that indicate the error type and whether the client is automatically trying to reconnect.\n\nLearn more about how the [`subscribe()`](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/subscribe) method handles subscription errors.\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## Before you begin\n\nIt's important to note the following points before starting to code:\n\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- Subscriptions don't persist across sessions. Closing a browser tab removes all its subscriptions.\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/core-modules/realtime/realtime/publisher/introduction)\n- [Site API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/introduction)\n- [Permissions Router API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction)\n\n@sdk_package_setup\n"
|
|
3824
3824
|
},
|
|
3825
3825
|
{
|
|
3826
3826
|
"type": "GUIDE",
|
|
@@ -3832,7 +3832,7 @@
|
|
|
3832
3832
|
{
|
|
3833
3833
|
"type": "GUIDE",
|
|
3834
3834
|
"title": "Introduction",
|
|
3835
|
-
"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/
|
|
3835
|
+
"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/core-modules/realtime/realtime/introduction). It determines which [subscribers](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction) can receive messages on specific [channels and resources](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction#channels-and-channel-resources).\n\nWith the Site API, you can:\n\n- Use the [permissions router](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction) to organize permission logic per channel or resource.\n- Control subscriber access using the [`realtime_check_permission` hook](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/realtime-check-permission).\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 Wix user can receive messages. Use the [permissions router](https://dev.wix.com/docs/sdk/core-modules/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/core-modules/realtime/realtime/introduction)\n- [Permissions Router API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/introduction)\n- [Subscriber API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction)\n- [Publisher API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/publisher/introduction)\n\n@sdk_package_setup\n"
|
|
3836
3836
|
},
|
|
3837
3837
|
{
|
|
3838
3838
|
"type": "GUIDE",
|
|
@@ -3895,7 +3895,7 @@
|
|
|
3895
3895
|
{
|
|
3896
3896
|
"type": "GUIDE",
|
|
3897
3897
|
"title": "Introduction",
|
|
3898
|
-
"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/
|
|
3898
|
+
"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/core-modules/realtime/realtime/site/realtime-check-permission).\n\nLearn more about the [Site API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/introduction) and the [Realtime APIs](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction).\n\nWith the Permissions Router API, you can:\n\n- [Add a handler](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/add) for a specific channel or resource.\n- [Set a default handler](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/default) for channels that don't have explicit handlers.\n- [Check](https://dev.wix.com/docs/sdk/core-modules/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. Use [`add()`](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/permissions-router/add) for specific channels or resources, and [`default()`](https://dev.wix.com/docs/sdk/core-modules/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()` in the body of the hook 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/core-modules/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/core-modules/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/core-modules/realtime/realtime/subscriber/introduction#core-modules_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/core-modules/realtime/realtime/introduction)\n- [Site API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/site/introduction)\n- [Subscriber API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction)\n- [Publisher API](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/publisher/introduction)\n\n@sdk_package_setup\n"
|
|
3899
3899
|
}
|
|
3900
3900
|
],
|
|
3901
3901
|
"/site/PermissionsRouter/add": [
|
|
@@ -7,7 +7,7 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
|
|
|
7
7
|
*
|
|
8
8
|
* Use the `options` parameter to register handlers that run whenever the subscription succeeds or generates an error. For some errors, the subscription is re-attempted automatically. The `onSubscribed()` handler runs on every successful re-subscription.
|
|
9
9
|
*
|
|
10
|
-
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/
|
|
10
|
+
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle).
|
|
11
11
|
*
|
|
12
12
|
* @example Subscribe to a channel
|
|
13
13
|
* ```ts
|
|
@@ -50,7 +50,7 @@ import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
|
|
|
50
50
|
* @requiredField channel
|
|
51
51
|
* @param messageHandler - Handler that runs whenever a message is published to the channel or resource.
|
|
52
52
|
* @requiredField messageHandler
|
|
53
|
-
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/
|
|
53
|
+
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle) for subscription events.
|
|
54
54
|
*/
|
|
55
55
|
export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubscribe> & typeof publicSubscribe>;
|
|
56
56
|
/**
|
|
@@ -7,7 +7,7 @@ import { createRESTModule } from '@wix/sdk-runtime/rest-modules';
|
|
|
7
7
|
*
|
|
8
8
|
* Use the `options` parameter to register handlers that run whenever the subscription succeeds or generates an error. For some errors, the subscription is re-attempted automatically. The `onSubscribed()` handler runs on every successful re-subscription.
|
|
9
9
|
*
|
|
10
|
-
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/
|
|
10
|
+
* Learn more about the [subscription lifecycle](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle).
|
|
11
11
|
*
|
|
12
12
|
* @example Subscribe to a channel
|
|
13
13
|
* ```ts
|
|
@@ -50,7 +50,7 @@ import { createRESTModule } from '@wix/sdk-runtime/rest-modules';
|
|
|
50
50
|
* @requiredField channel
|
|
51
51
|
* @param messageHandler - Handler that runs whenever a message is published to the channel or resource.
|
|
52
52
|
* @requiredField messageHandler
|
|
53
|
-
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/
|
|
53
|
+
* @param options - [Lifecycle handlers](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction#core-modules_realtime_realtime_subscriber_subscription-lifecycle) for subscription events.
|
|
54
54
|
*/
|
|
55
55
|
export const subscribe = /*#__PURE__*/ createRESTModule(publicSubscribe);
|
|
56
56
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wix/realtime",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.48",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"registry": "https://registry.npmjs.org/",
|
|
6
6
|
"access": "public"
|
|
@@ -48,7 +48,7 @@
|
|
|
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.
|
|
51
|
+
"@wix/sdk_realtime_site": "1.0.37",
|
|
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": "
|
|
75
|
+
"falconPackageHash": "4197eb852efdac39391b2b37c71c645dab2c0d1c66b63d83eecda3ae"
|
|
76
76
|
}
|