@wix/comments-client

Comments Client

This is a client library that enables to interact with the generic Wix comments infrastructure.

Usage

Create a client.

const {client} = require('@wix/comments-client');

const commentsClient = client({
    contextToken: 'context-token-received-from-the-hosting-app',
    signedInstance: 'signed-instance-received-from-the-hosting-app',
    baseUrl: '/relative-to-document'  // optional, default: 'https://social.wix.com'
});

const comment = await client.get({
  commentId: 'comment-id'
});

API

CommentsClient.get(req: GetComment): Promise<Comment>

Get a single comment.

GetComment

interface GetComment {
    commentId?: (string | null);
}

CommentsClient.list(req: GetList): Promise<CommentsPage>

Get a list of comments or replies. Cursor should be provided as null to get the first page.

To list the next page of replies, take the Replies.nextCursor value and use it in cursorPaging.cursor.

Flatten to depth

In case a limited depth of comments -> replies are required, pagingContextSetup.flattenToDepth param can be used optionally when setting up a new pagination context.

I.e. Comment A

• Reply 1
  • Reply 2
    Comment B
• Reply 3

In case flattenToDepth=1 is provided, this hierarchy would be returned as Comment A

• Reply 1

All cursors will include this information

Getting comments "newest first"

In order to get the comments in newest first order, value ordering for ordering has to be set LATEST_FIRST

GetList

interface GetList {
    pagingContextSetup?: PagingContextSetup  // start a new pagination context
    cursorPaging?: CursorPaging;  // continue paging (as set up from pagingContextSetup)
    query?: CommentsQuery
}

interface PagingContextSetup {
    entityId?: string;
    flattenToDepth?: number;
    limit?: number;
    ordering: Ordering;
}

interface CommentsQuery {
    repliesToLoad: number;
}

enum Ordering {
  OLDEST_FIRST,
  LATEST_FIRST
}

CommentsClient.create(req: CreateComment): Promise<Comment>

Create a comment.

CreateComment

interface CreateComment {
    entityId?: string  // entityId
    comment: UpdateCommentEntity
}

CommentsClient.update(req: UpdateComment): Promise<Comment>

Update a comment.

UpdateComment

interface UpdateComment {
    commentId: string
    comment: UpdateCommentEntity
}

CommentsClient.createReply(req: CreateReply): Promise<Comment>

Create a comment reply.

CreateReply

interface CreateReply {
  commentOrReplyId: string,
  reply: UpdateCommentEntity
}

CommentsClient.delete(req: DeleteComment): Promise<CommentWithCommentsPage>

Delete a comment and optionally get a list of comments.

DeleteComment

interface DeleteComment {
    commentId: string,
    list?: GetList // optionally get an updated list of comments
}

CommentWithCommentsPage

interface CommentWithCommentsPage {
  comment: Comment
  commentsPage: CommentsPage | null
}

CommentsClient.uploadFile(req: UploadFile): Promise<Resource>

Upload a comment resource.

Example:

const resource = await commentsClient.uploadFile({
    file: fileInputElement.files[0]
});

UploadFile

interface UploadFile {
  file: Blob | File,
  name?: string
}

CommentsClient.report(req: ReportComment): Promise<Comment>

Report a comment.

ReportComment

interface ReportComment {
  commentId: string,
  reportType: ReportType
}

CommentsClient.getReported(req: GetReported): Promise<Reported>

Get reported summary for comment.

GetReported

interface GetReported {
  commentId: string
}

CommentsClient.queryProfiles(req: QueryProfiles): Promise<QueryProfilesResponse>

Query profiles.

QueryProfiles

interface QueryProfiles {
  searchText: string
  limit: number
}

interface QueryProfilesResponse {
  profiles: Profile[];
  nextCursor: string | null;
}

CommentsClient.listMoreProfiles(req: CursorPaging): Promise<QueryProfilesResponse>

List more profiles for the same query.

Message types

CommentsPage

interface CommentsPage {
    availableActions: Action[]
    total: number
    comments?: (Comment[] | null)
    cursor?: (string | null)
    nextCursor?: (string | null)
    previousCursor?: (string | null)
    remainingCount: number
    loggedInProfile: Profile | null
}

Comment

interface Comment {
  commentId: string
  containerId?: string
  comment: CommentEntity,
  reactions: Reactions,
  replies: Replies
  reported: Reported | null,
  createdAt: Date
  updatedAt: Date | null
  availableActions: Action[]
  createdBy: Profile
}

CommentEntity

interface CommentEntity {
    text: (Text | null);
    mentions?: (Mention[] | null);
    attachments?: (Resource[] | null);
}

UpdateCommentEntity

interface UpdateCommentEntity {
    text: (Text | null);
    mentions?: (UpdateMention[] | null);
    attachments?: (Resource[] | null);
}

interface UpdateMention {
    subjectId: string;
}

Reactions

interface Reactions {
    count: number;
}

Replies

interface Replies {
  count: number
  comments: Comment[]
  cursor?: string
  nextCursor?: string
  remainingCount: number
}

Reported

interface Reported {
  count: number | null
  reportedTypes?: ReportType[]
}

ReportType

enum ReportType {
  UnwantedContent = 'UNWANTED_CONTENT',
  Harassment = 'HARASSMENT',
  InappropriateContent = 'INAPPROPRIATE_CONTENT',
  HateSpeechOrGraphic = 'HATE_SPEECH_OR_GRAPHIC'
}

Action

enum Action {
  View = 'VIEW',
  AddComment = 'ADD_COMMENT',
  React = 'REACT',
  Unreact = 'UNREACT',
  Report = 'REPORT',
  Edit = 'EDIT',
  Delete = 'DELETE'
}

Resource

interface Resource {
    uri?: (string | null);
    id?: (string | null);
    mediaType?: (MediaType | null);
    pixelDimensions: PixelDimensions | null;
    mimeType: string | null;
}

MediaType

enum MediaType {
    ATTACHMENT = 'ATTACHMENT',
    IMAGE = 'IMAGE',
    VIDEO = 'VIDEO',
}

PixelDimensions

interface PixelDimensions {
  width: number;
  height: number;
}

Image

interface Text {
    contentType?: (ContentType | null);
    content?: (string | null);
}

Content Type

enum ContentType {
    PLAIN_TEXT = 'PLAIN_TEXT',
    DRAFTJS = 'DRAFTJS',
}

Mention

interface Mention {
    profile: Profile
}

Profile

interface Profile {
  id: string
  nickname: string
  imageUrl?: string
}

CursorPaging

interface CursorPaging {
    limit?: (number | null);
    cursor?: (string | null);
}