@giosg/pub-sdk

TypeScript SDK and type definitions for the giosg Pub group chat API.

@giosg/pub-sdk wraps @giosg/realtime-sdk with typed methods for Pub channels, direct messages, messages, channel members, notification settings and conferences. Collections and resources are returned as RxJS Observables that stay up to date in real time, so UI components can simply subscribe to the data they need.

Installation

npm install @giosg/pub-sdk

@giosg/realtime-sdk and @giosg/types are installed as dependencies. The SDK uses RxJS 5 ([email protected]), the same version as @giosg/realtime-sdk.

Quick start

Create and authenticate a RealtimeSDK instance (see the @giosg/realtime-sdk documentation for authentication options) and pass it to BasePubSdk:

import "rxjs/add/operator/switchMap";
import "rxjs/add/operator/toArray";
import { RealtimeSDK } from "@giosg/realtime-sdk";
import { BasePubSdk, PubChannelUid } from "@giosg/pub-sdk";
import { OrganizationUid, UserUid } from "@giosg/types";

const sdk = new RealtimeSDK();
// ... set up authentication for `sdk` ...

const pub = new BasePubSdk(sdk);

const orgId = "<organization id>" as OrganizationUid;
const userId = "<user id>" as UserUid;
const channelId = "<channel id>" as PubChannelUid;

// List the channels the user has joined, kept up to date in real time.
// The outer Observable emits a new inner Observable whenever the collection changes.
pub
  .streamJoinedChannels(orgId, userId)
  .switchMap((channels) => channels.toArray())
  .subscribe((channels) => {
    channels.forEach((channel) => console.log(channel.name, channel.unread_message_count));
  });

// Send a message to a channel
await pub.postChannelMessage(orgId, channelId, {
  type: "user",
  body: { version: 3, chunks: [{ type: "text", text: "Hello!" }] },
});

API overview

All methods are on the BasePubSdk class. Method names follow these conventions:

• stream* returns an Observable that updates in real time. Collection methods return Observable<Observable<T>>; resource methods return Observable<T>.
• post*, patch*, delete*, create* and most get* methods return a Promise that resolves once the request completes.

Channels

| Method | Description | | --- | --- | | streamPublicChannels(orgId, ordering?) | Public channels of the organization | | streamChannel(orgId, channelId) | A single channel | | postPublicChannel(orgId, payload) | Create a public channel | | patchChannel(orgId, channelId, payload) | Update a channel | | deleteChannel(orgId, channelId) | Delete a channel | | streamJoinedChannels(orgId, userId, ordering?, isActive?) | Channels the user has joined, including unread counts and notification settings | | streamJoinedChannel(orgId, userId, channelId) | A single joined channel |

Direct messages

| Method | Description | | --- | --- | | streamUserDMChannels(orgId, userId, ordering?) | The user's direct message channels | | streamUserDMChannel(orgId, userId, channelId) | A single direct message channel | | postDMChannel(orgId, userId, payload) | Create a direct message channel |

Messages

| Method | Description | | --- | --- | | streamChannelMessages(orgId, channelId, ordering?) | Messages of a channel | | streamChannelMessage(orgId, channelId, messageId) | A single message | | postChannelMessage(orgId, channelId, payload) | Send a message | | patchChannelMessage(orgId, channelId, messageId, payload) | Edit a message | | deleteMessage(orgId, channelId, messageId) | Delete a message |

Channel members

| Method | Description | | --- | --- | | streamChannelMembers(orgId, channelId, ordering?) | Members of a channel | | streamChannelMember(orgId, channelId, memberId) | A single member | | postJoinChannel(orgId, channelId, userId) | Join a user to a channel | | patchChannelMember(orgId, channelId, memberId, payload) | Update a member | | patchLastSeenAtField(orgId, channelId, memberId) | Mark the channel as seen by the member | | deleteChannelMember(orgId, channelId, memberId) | Remove a member from a channel |

Notification settings

| Method | Description | | --- | --- | | streamChannelNotificationSettings(orgId, channelId, memberId) | A member's notification settings for a channel | | patchChannelNotificationSettings(orgId, channelId, memberId, payload) | Update a member's notification settings |

Conferences and live streams

| Method | Description | | --- | --- | | getConferences(orgId, userId) | The user's active conferences (returns a real-time collection Observable) | | getConferenceToken(orgId, channelId, context) | Get an access token for a channel's conference | | getLiveStreamConfig(orgId, channelId) | Get the live stream configuration of a conference | | createConferenceLiveStream(orgId, channelId, options) | Create a live stream for a conference | | createStreamSessionAction(orgId, channelId, action) | Perform an action on a live stream session | | getLiveStreamViewerCount(orgId, channelId) | Get the live stream's current viewer count |

Types

The package exports TypeScript types for the Pub API resources and payloads, including:

• Channels: PubChannel, JoinedPubChannel, ChannelPayload, DMChannelPayload, PubChannelUid
• Messages: PubMessage (a union of PubUserMessage, PubSystemMessage, PubDeletedMessage, PubCallRequestMessage, PubCallLeaveMessage and PubReportingMessage), PubMessagePayload, PubMessageBody (versions 1–3) and message chunk types such as TextChunk, ImageChunk and FileChunk
• Members: PubChannelMember, PubChannelMemberUid
• Notifications: NotificationSettings, NotificationSettingsPayload, NotificationMode
• Conferences: Conference, ConferenceTokenContext, ConferenceTokenResponse

Full type definitions ship with the package as .d.ts files.

Versioning

This package follows semantic versioning. Breaking API changes are released as new major versions.