From e05710a035d61b4592ba1a442e97735ebb082de8 Mon Sep 17 00:00:00 2001 From: Karolina Zydek Date: Wed, 29 Jun 2022 15:48:11 +0200 Subject: [PATCH] Add info on APIs to hooks & add missing VSP fields to spec --- .../hooks/use-channel-members.stories.mdx | 8 +++-- .../stories/hooks/use-memberships.stories.mdx | 10 ++++--- .../hooks/use-user-memberships.stories.mdx | 10 ++++--- .../stories/introduction/payloads.stories.mdx | 29 ++++++++++++++++++- 4 files changed, 45 insertions(+), 12 deletions(-) diff --git a/lib/docs/stories/hooks/use-channel-members.stories.mdx b/lib/docs/stories/hooks/use-channel-members.stories.mdx index 5a904a799..e2b1b089e 100644 --- a/lib/docs/stories/hooks/use-channel-members.stories.mdx +++ b/lib/docs/stories/hooks/use-channel-members.stories.mdx @@ -4,16 +4,18 @@ import { Meta } from "@storybook/addon-docs/blocks"; # `useChannelMembers` -The hook returns a list of members in a channel. +The hook uses the [Metadata API](https://www.pubnub.com/docs/sdks/javascript/api-reference/objects#get-channel-memberships) for channel members. + +It returns a list of members in a given channel. The list will include user metadata for members that have additional metadata stored in the database. Pagination is handled internally. You can adjust the `limit` of returned members on a single call (max/default 100) and call a function returned by the hook to get another page of results. -This hook also sets up a listener that reacts to removals of already fetched members. Updates and +This hook also sets up a listener that reacts to removals of the already-fetched members. Updates and new memberships are not handled due to technical limitations. However, this behavior requires a -living subscription to the channel getting updated - this should be handled by the components. +living subscription for the channel to get updated - this should be handled by the components. ```js const [members, fetchPage, refetchChannelMembers, total, error] = useChannelMembers({ diff --git a/lib/docs/stories/hooks/use-memberships.stories.mdx b/lib/docs/stories/hooks/use-memberships.stories.mdx index 22f3b9f04..a7055718c 100644 --- a/lib/docs/stories/hooks/use-memberships.stories.mdx +++ b/lib/docs/stories/hooks/use-memberships.stories.mdx @@ -4,16 +4,18 @@ import { Meta } from "@storybook/addon-docs/blocks"; # `useMemberships` -Depending on the input arguments, the hook returns a list of members in a channel, or a list of +This hook uses the new [Memberships API](https://www.pubnub.com/docs/sdks/javascript/api-reference/memberships). + +Depending on the input arguments, the hook returns a list of members in a channel or a list of channels a given user is a member of. The list will include metadata for memberships that have additional metadata stored in the database. Pagination is handled internally. You can adjust the `limit` of returned memberships on a single call (max/default 100) and call a function returned by the hook to get another page of results. -This hook also sets up a listener that reacts to removals of already fetched memberships. Updates +This hook also sets up a listener that reacts to removals of the already-fetched memberships. Updates and new memberships are not handled due to technical limitations. However, this behavior requires a -living subscription to the channel getting updated - this should be handled by the components. +living subscription for the channel to get updated - this should be handled by the components. ```js const [users, fetchPage, refetchMemberships, total, error] = useMemberships({ @@ -61,6 +63,6 @@ return ( | :---------- | :---------------------------- | --------------------------------------------------------------------------------------------------------------- | | `array[0]` | UserEntity[] or SpaceEntity[] | List of returned memberships. | | `array[1] ` | Function | Function that can be called to fetch another page of members. | -| `array[2]` | Function | Function that can be called to completely reset the hook. This can be used in case of expected members updates. | +| `array[2]` | Function | Function that can be called to completely reset the hook. This can be used in case of expected updates of members. | | `array[3]` | Number | Total number of stored members. | | `array[4]` | Error | If there's an error fetching members, it will be available here. | diff --git a/lib/docs/stories/hooks/use-user-memberships.stories.mdx b/lib/docs/stories/hooks/use-user-memberships.stories.mdx index 299ec1cea..ee3e0d054 100644 --- a/lib/docs/stories/hooks/use-user-memberships.stories.mdx +++ b/lib/docs/stories/hooks/use-user-memberships.stories.mdx @@ -4,15 +4,17 @@ import { Meta } from "@storybook/addon-docs/blocks"; # `useUserMemberships` -The hook returns a list of channel memberships for a user. +The hook uses the [Metadata API](https://www.pubnub.com/docs/sdks/javascript/api-reference/objects#get-channel-members) for user memberships. + +It returns a list of channel memberships for a given user. This method doesn't return user's subscriptions. Pagination is handled internally. You can adjust -the `limit` of returned channes on a single call (max/default `100`) and call a function returned by +the `limit` of returned channels on a single call (max/default `100`) and call a function returned by the hook to get another page of results. -This hook also sets up a listener that reacts to removals of already fetched channels. Updates and +This hook also sets up a listener that reacts to removals of the already-fetched channels. Updates and new memberships are not handled due to technical limitations. However, this behavior requires a -living subscription to the user getting updated - this should be handled by the components. +living subscription for the user to get updated - this should be handled by the components. ```js const [channels, fetchPage, refetchMemberships, total, error] = useUserMemberships({ diff --git a/lib/docs/stories/introduction/payloads.stories.mdx b/lib/docs/stories/introduction/payloads.stories.mdx index 95dba2b86..901f2e166 100644 --- a/lib/docs/stories/introduction/payloads.stories.mdx +++ b/lib/docs/stories/introduction/payloads.stories.mdx @@ -44,6 +44,17 @@ Follow this schema for the user data in your apps: "description": "URL to a user avatar that you can display in the UI", "type": "string" }, + "type": { + "description": "Type of the user", + "type": "string", + "examples": ["default", "admin", "moderator"], + "default": "default" + }, + "status": { + "description": "Status of the user", + "type": "string", + "examples": ["default", "deleted"] + }, "custom": { "description": "Any additional payload information", "type": "object", @@ -63,7 +74,7 @@ Follow this schema for the user data in your apps: "type": "string" } }, - "required": ["id"] + "required": ["id", "type"] } ``` @@ -76,6 +87,8 @@ Example: "email": "jane.doe@example.com", "externalId": "some-external-user-id", "profileUrl": "https://randomuser.me/api/portraits/men/1.jpg", + "type": "default", + "status": "default", "custom": { "description": "Office Assistant" }, @@ -93,6 +106,7 @@ Follow this schema for the channel data in your apps: "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Channel", "description": "Channel in the chat application", + "type": "object", "properties": { "id": { "description": "Unique identifier for a channel", @@ -106,6 +120,17 @@ Follow this schema for the channel data in your apps: "description": "Description of the channel that you can display in the UI", "type": "string" }, + "type": { + "description": "Type of the channel", + "type": "string", + "examples": ["default", "group", "direct"], + "default": "default" + }, + "status": { + "description": "Status of the channel", + "type": "string", + "examples": ["default", "deleted"] + }, "custom": { "description": "Any additional payload information", "type": "object", @@ -136,6 +161,8 @@ Example: "id": "some-channel-id", "name": "Off-topic", "description": "Off-topic channel for random chatter and fun", + "type": "default", + "status": "default", "custom": { "profileUrl": "https://www.gravatar.com/avatar/149e60f311749f2a7c6515f7b34?s=256&d=identicon" },