@wix/realtime 1.0.23 → 1.0.24

package/dist/statics/docs-ts-model.json

@@ -2498,7 +2498,129 @@
     "packageName": "@wix/realtime",
     "symbolIdMap": {}
   },
-  "appendices": {},
+  "appendices": {
+    "/site": [
+      {
+        "type": "GUIDE",
+        "title": "Introduction",
+        "src": "# Introduction\n\n> **Note:** This API is only intended for use in [site development](https://dev.wix.com/docs/sdk/articles/get-started/about-site-development).\n\nUsing the Realtime API you can create channels and channel resources where messages\ncan be published. Site visitors who subscribe to a channel receive the\nmessages published to that channel. When a message is received you can handle the message any\nway you choose, such as displaying the contents of the message or changing the state\nof page elements depending on the contents of the message. You can also manage the\npermissions of who can read from specific channels.\n\nThe `@wix/realtime` module is used in conjunction with the [`@wix/site-realtime`](https://dev.wix.com/docs/sdk/frontend-modules/site-realtime/introduction) module.\n\nGet hands-on experience with the Realtime API on our [Hello Realtime](https://www.wix.com/velo/example/hello-realtime) example page.\n\nTypical uses of the Realtime API include implementing a messaging system or\nas an alternative to using a polling mechanism.\n\nThe Realtime API uses the following terminology:\n\n+ **Channel**: A specific channel on which messages are published. Each channel\n  has a unique name. Site visitors can subscribe to a channel to receive the \n  messages that are published on it. When site visitors subscribe to a channel, they do not \n  receive messages published to a resource on that same channel.\n+ **Channel resource**: A subchannel on which messages are published. Subchannels\n  can share a name with a channel and other subchannels, but they have a unique\n  resource ID. When site visitors subscribe to a channel resource, they do not \n  receive messages published to that same channel without a specified resource.\n  Channel resources inherit their parent channel's permissions, unless specified\n  otherwise.\n+ **Message**: A message published on a channel or channel resource. A message can\n  be of any type, such as a string, number, or object. Channel subscribers receive\n  the messages published on the channel.\n+ **Publish**: Sending a message over a channel or channel resource.\n+ **Subscribe**: A site visitor subscribes to receive the messages published on a \n  channel or channel resource.\n+ **Permissions router**: The permissions router is used to define the permissions\n  you want to grant to subscribers on channels and channel resources.\n+ **Permissions handler**: Handles a permissions check for a specific user on a \n  specific channel or channel resource.\n\nFor a tutorial on using the Realtime API, see \n[Sending Messages with the Realtime API](https://dev.wix.com/docs/develop-websites/articles/code-tutorials/wix-editor-elements/sending-messages-with-the-realtime-api).\n"
+      },
+      {
+        "type": "GUIDE",
+        "title": "Setup",
+        "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 [Wix 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 { site } from `@wix/realtime`;\n```"
+      }
+    ],
+    "/site/publish": [
+      {
+        "type": "EXAMPLE",
+        "title": "Publish to a channel",
+        "src": "import { site } from `@wix/realtime`;\n\n// ...\n\nconst channel = {\n  \"name\": \"recipes\",\n  \"resourceId\": \"9373b6bd-051e-4716-9591-91349cac8bd1\"\n};\n\nsite.publish(channel, \"Stay tuned for new recipes!\")\n  .then(() => {\n    // published\n  });"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Publish to a resource on a channel",
+        "src": "import { site } from `@wix/realtime`;\n\n// ...\n\nconst channel = {\n  \"name\": \"Work updates\"\n};\n\nconst message = {\n  \"subject\": \"Design review\",\n  \"description\": \"Meeting to review the latest widget design\"\n};\n\nconst user1 = // get ID of first user to publish to\nconst user2 = // get ID of second user to publish to\n\nconst options = {\n  \"users\" : [user1, user2],\n  \"includePublisher\": true\n};\n\nsite.publish(channel, message, options)\n  .then( () => {\n    // published\n  } );"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Publish to specific users on a channel and include publisher information",
+        "src": "/* Backend */\nimport { site } from `@wix/realtime`;\n\nexport function publishMessage(channel, message) {\n   return site.publish(channel, message);\n}\n\n/* Frontend */\nimport { realtime } from \"@wix/site-realtime\";\nimport { publishMessage } from 'backend/realtime';\n\nconst channelA = { name: 'a' };\nconst channelB = { name: 'b' };\nconst channelB1 = { name: 'b', resourceId: '1' };\nconst channelB2 = { name: 'b', resourceId: '2' };\n\n$w.onReady(function () {\n  subscribeToChannels();\n  setupPublishButtons();\n});\n\nfunction subscribeToChannels() {\n  realtime.subscribe(channelA, messageHandler);\n  realtime.subscribe(channelB, messageHandler);\n  realtime.subscribe(channelB1, messageHandler);\n  realtime.subscribe(channelB2, messageHandler);\n}\n\nfunction setupPublishButtons() {\n  $w('#publishButtonA').onClick(event => {\n    publish(event.target, channelA);\n  });\n\n  $w('#publishButtonB').onClick(event => {\n    publish(event.target, channelB);\n  });\n\n  $w('#publishButtonB1').onClick(event => {\n    publish(event.target, channelB1);\n  });\n\n  $w('#publishButtonB2').onClick(event => {\n    publish(event.target, channelB2);\n  });\n}\n\nasync function publish(button, channel) {\n  if ($w('#message').value) {\n    button.disable();\n    $w('#message').disable();\n\n    await publishMessage(channel, $w('#message').value);\n\n    $w('#message').value = undefined;\n    $w('#message').enable();\n    button.enable();\n  }\n}\n\nfunction messageHandler(message, channel) {\n  let textBoxId;\n\n  if (channel.name === 'a') {\n    textBoxId = '#receivedMessagesA';\n  } else { // Channel B - check resource ID\n    if (channel.resourceId === '1') {\n      textBoxId = '#receivedMessagesB1';\n    } else if (channel.resourceId === '2') {\n      textBoxId = '#receivedMessagesB2';\n    } else {\n      textBoxId = '#receivedMessagesB';\n    }\n  }\n\n  $w(textBoxId).value += (message.payload + '\\n');\n}"
+      }
+    ],
+    "/site/realtime_check_permission": [
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions for a channel based on subscriber type",
+        "src": "// In realtime-permissions.js\n\nexport function realtime_check_permission(channel, subscriber) {\n  // set default permissions\n  let permissions =  {\"read\": true};\n  \n  if(channel.name === \"MembersOnly\") {\n    if(subscriber.type === \"Member\"){\n      permissions.read = true; \n    }\n    else {\n      permissions.read = false;\n    }\n  }\n  \n  return permissions;\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions for a channel based on subscriber type using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default( (channel, subscriber) => {\n  return {\"read\": true};\n} );\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add(membersOnlyChannel, (channel, subscriber) => {\n  if(subscriber.type === \"Member\") {\n    return {\"read\": true};\n  }\n  else {\n    return {\"read\": false};\n  }\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel,subscriber);\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions based on user data",
+        "src": "// In realtime-permissions.js\n\nimport { members } from `wix-members-backend`;\n\nexport async function realtime_check_permission(channel, subscriber) {\n  // set default permissions\n  let permissions =  { \"read\": true };\n\n  if(channel.name === \"BobsOnly\") {\n    let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });\n    if(member.contactDetails.firstName === \"Bob\") {\n      permissions.read = true;\n    }\n    else {\n      permissions.read = false;\n    }\n  }\n  \n  return permissions;\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions based on user data using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { members } from `@wix/members`;\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default((channel, subscriber) => {\n  return {\"read\": true};\n});\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add( membersOnlyChannel, async (channel, subscriber) => {\n  let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });\n  \n  if(channel.resourceId === \"BobsOnly\") {\n    if(member.contactDetails.firstName === \"Bob\") {\n      return { \"read\": true };\n    }\n    else {\n      return { \"read\": false };\n    }\n  }\n  else {\n    return { \"read\": true };\n  }\n} );\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel, subscriber);\n}"
+      }
+    ],
+    "/site/permissionsRouter": [
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions for a channel based on subscriber type using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default( (channel, subscriber) => {\n  return {\"read\": true};\n} );\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add(membersOnlyChannel, (channel, subscriber) => {\n  if(subscriber.type === \"Member\") {\n    return {\"read\": true};\n  }\n  else {\n    return {\"read\": false};\n  }\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel,subscriber);\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions based on user data using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { members } from `@wix/members`;\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default((channel, subscriber) => {\n  return {\"read\": true};\n});\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add( membersOnlyChannel, async (channel, subscriber) => {\n  let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });\n  \n  if(channel.resourceId === \"BobsOnly\") {\n    if(member.contactDetails.firstName === \"Bob\") {\n      return { \"read\": true };\n    }\n    else {\n      return { \"read\": false };\n    }\n  }\n  else {\n    return { \"read\": true };\n  }\n} );\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel, subscriber);\n}"
+      }
+    ],
+    "/site/PermissionsRouter": [
+      {
+        "type": "GUIDE",
+        "title": "Introduction",
+        "src": "# Introduction\n\nUse the permissions router to define the permissions you want to grant to subscribers\non channels or channel resources. You can set permissions on the channel and channel\nresource level. If you do not define permissions for a particular channel resource,\nthat resource inherits the permissions of its parent channel.\n\nTypically you use the permissions router in the **realtime-permissions.js** file in\nyour site's backend to:\n\n+ Set default permissions for all channels and channel resources where no explicit\n  permissions are defined.\n+ Add permissions logic for specific channels or channel resources.\n+ Check the permissions for a specific subscriber on a specific channel.\n\n> **Note:** Although it is recommended, you do not need to use the permissions router to set permissions. You can also define all your permissions logic in the [`realtime_check_permission()`](https://dev.wix.com/docs/sdk/backend-modules/realtime/site/realtime-check-permission) function."
+      }
+    ],
+    "/site/PermissionsRouter/add": [
+      {
+        "type": "EXAMPLE",
+        "title": "Set a permissions handler for a specific channel",
+        "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} );"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions for a channel based on subscriber type using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default( (channel, subscriber) => {\n  return {\"read\": true};\n} );\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add(membersOnlyChannel, (channel, subscriber) => {\n  if(subscriber.type === \"Member\") {\n    return {\"read\": true};\n  }\n  else {\n    return {\"read\": false};\n  }\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel,subscriber);\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions based on user data using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { members } from `@wix/members`;\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default((channel, subscriber) => {\n  return {\"read\": true};\n});\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add( membersOnlyChannel, async (channel, subscriber) => {\n  let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });\n  \n  if(channel.resourceId === \"BobsOnly\") {\n    if(member.contactDetails.firstName === \"Bob\") {\n      return { \"read\": true };\n    }\n    else {\n      return { \"read\": false };\n    }\n  }\n  else {\n    return { \"read\": true };\n  }\n} );\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel, subscriber);\n}"
+      }
+    ],
+    "/site/PermissionsRouter/check": [
+      {
+        "type": "EXAMPLE",
+        "title": "Check permission for a subscriber to a channel",
+        "src": "// In realtime-permissions.js\n\nimport { site } from `@wix/realtime`;\n\n// ...\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel,subscriber);\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions for a channel based on subscriber type using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default( (channel, subscriber) => {\n  return {\"read\": true};\n} );\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add(membersOnlyChannel, (channel, subscriber) => {\n  if(subscriber.type === \"Member\") {\n    return {\"read\": true};\n  }\n  else {\n    return {\"read\": false};\n  }\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel,subscriber);\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions based on user data using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { members } from `@wix/members`;\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default((channel, subscriber) => {\n  return {\"read\": true};\n});\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add( membersOnlyChannel, async (channel, subscriber) => {\n  let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });\n  \n  if(channel.resourceId === \"BobsOnly\") {\n    if(member.contactDetails.firstName === \"Bob\") {\n      return { \"read\": true };\n    }\n    else {\n      return { \"read\": false };\n    }\n  }\n  else {\n    return { \"read\": true };\n  }\n} );\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel, subscriber);\n}"
+      }
+    ],
+    "/site/PermissionsRouter/default": [
+      {
+        "type": "EXAMPLE",
+        "title": "Set a default permissions handler",
+        "src": "// In realtime-permissions.js\n\nimport { site } from `@wix/realtime`;\n\n// ...\n\nsite.permissionsRouter.default( (channel, subscriber) => {\n  // return default permissions\n  return {\"read\": true};\n} );"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions for a channel based on subscriber type using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default( (channel, subscriber) => {\n  return {\"read\": true};\n} );\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add(membersOnlyChannel, (channel, subscriber) => {\n  if(subscriber.type === \"Member\") {\n    return {\"read\": true};\n  }\n  else {\n    return {\"read\": false};\n  }\n});\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel,subscriber);\n}"
+      },
+      {
+        "type": "EXAMPLE",
+        "title": "Grant permissions based on user data using the permissions router",
+        "src": "// In realtime-permissions.js\n\nimport { members } from `@wix/members`;\nimport { site } from `@wix/realtime`;\n\nsite.permissionsRouter.default((channel, subscriber) => {\n  return {\"read\": true};\n});\n\nconst membersOnlyChannel = {\"name\": \"MembersOnly\"};\n\nsite.permissionsRouter.add( membersOnlyChannel, async (channel, subscriber) => {\n  let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });\n  \n  if(channel.resourceId === \"BobsOnly\") {\n    if(member.contactDetails.firstName === \"Bob\") {\n      return { \"read\": true };\n    }\n    else {\n      return { \"read\": false };\n    }\n  }\n  else {\n    return { \"read\": true };\n  }\n} );\n\nexport function realtime_check_permission(channel, subscriber) {\n  return site.permissionsRouter.check(channel, subscriber);\n}"
+      }
+    ]
+  },
   "standaloneTypes": {},
   "metadata": {}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/realtime",
-  "version": "1.0.23",
+  "version": "1.0.24",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -51,7 +51,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && npm run docs",
-    "docs": "docs-ts-model --disableSources --entryPoint src/index.ts",
+    "docs": "docs-ts-model --config ./docs/cli-config.json",
     "test": "vitest run"
   },
   "wix": {
@@ -65,5 +65,5 @@
       "isRootPublicSdk": true
     }
   },
-  "falconPackageHash": "b0703d550c42219421881692c225661586900d2ab35c82a9b2cbd0bf"
+  "falconPackageHash": "ea641cc426acb611fabb0e9f13093b442c0f198efa57b83ff7b8c4a2"
 }