@wix/auto_sdk_comments_votes 1.0.0 → 1.0.2

package/build/cjs/index.typings.d.ts

@@ -4,53 +4,56 @@ import { QuerySpec, Query, NonNullablePaths } from '@wix/sdk-types';
 /** An upvote or downvote cast by one identity on a resource in an app context. */
 interface Vote {
     /**
-     * Vote resource ID
+     * ID of the resource receiving the vote. For comments, this is the comment ID.
      * @maxLength 128
      */
     resourceId?: string;
     /**
-     * Resource fully qualified domain name
+     * Entity type receiving the vote. For comments, this is `wix.comments.v2.comment`.
      * @maxLength 300
      */
     resourceFqdn?: string;
     /**
-     * Vote ID
+     * Vote ID.
      * @format GUID
      * @readonly
      */
     voteId?: string;
     /**
-     * Type of vote
+     * Vote type.
      * @readonly
      */
     type?: TypeWithLiterals;
     /**
-     * Vote author
+     * Identity that cast the vote.
      * @readonly
      */
     createdBy?: SocialIdentity;
     /**
-     * Vote created date
+     * Date and time the vote was created.
      * @readonly
      */
     _createdDate?: Date | null;
     /**
-     * Vote updated date
+     * Date and time the vote was updated.
      * @readonly
      */
     _updatedDate?: Date | null;
-    /** Vote context, defining where the vote belongs to */
+    /** App and context containing the resource. */
     context?: VoteContext;
     /**
-     * Vote revision
+     * Revision number, which increments when the vote is updated.
      * @readonly
      */
     revision?: string;
 }
-/** Type of vote */
+/** Vote type. */
 declare enum Type {
+    /** Unknown vote type. */
     UNKNOWN = "UNKNOWN",
+    /** Vote in favor of the resource. */
     UPVOTE = "UPVOTE",
+    /** Vote against the resource. */
     DOWNVOTE = "DOWNVOTE"
 }
 /** @enumType */
@@ -72,20 +75,20 @@ declare enum IdentityType {
 type IdentityTypeWithLiterals = IdentityType | 'ANONYMOUS' | 'MEMBER' | 'USER' | 'SERVICE' | 'MEMBER_GROUP';
 interface VoteContext {
     /**
-     * Context ID
+     * ID of the context containing the resource.
      * @maxLength 128
      */
     contextId?: string;
-    /** Context type */
+    /** Type used by the app to identify the context. */
     contextType?: string | null;
     /**
-     * Vote app ID
+     * ID of the app that owns the context.
      * @format GUID
      * @readonly
      */
     appDefId?: string;
     /**
-     * MetaSite ID
+     * Site ID.
      * @format GUID
      * @readonly
      */
@@ -93,27 +96,27 @@ interface VoteContext {
 }
 interface UpvoteRequest {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string;
     /**
-     * resource identifier for vote be cast on
+     * ID of the resource receiving the vote. For a comment, specify the comment ID.
      * @maxLength 128
      */
     resourceId: string;
     /**
-     * resource name
+     * Entity type receiving the vote. For comments, specify `wix.comments.v2.comment`.
      * @maxLength 300
      */
     resourceFqdn: string;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData;
 }
 /**
  * Identifies the app and context containing the resource.
- * When provided, contextData takes precedence over the deprecated contextToken.
+ * When provided, `contextData` takes precedence over the deprecated `contextToken`.
  */
 interface ContextData {
     /**
@@ -130,55 +133,55 @@ interface ContextData {
     contextType?: string | null;
 }
 interface UpvoteResponse {
-    /** created vote */
+    /** Vote cast or updated. */
     vote?: Vote;
 }
 interface ContextResourceVoteChange {
     /**
-     * Resource ID
+     * ID of the resource receiving the vote.
      * @maxLength 128
      */
     resourceId?: string;
     /**
-     * Resource fully qualified domain name
+     * Entity type receiving the vote. For comments, this is `wix.comments.v2.comment`.
      * @maxLength 300
      */
     resourceFqdn?: string;
-    /** Score of votes */
+    /** Net score: upvote count minus downvote count. */
     score?: number;
-    /** Upvote count */
+    /** Number of upvotes. */
     upvoteCount?: number;
-    /** Downvote count */
+    /** Number of downvotes. */
     downvoteCount?: number;
-    /** Vote context */
+    /** App and context containing the resource. */
     context?: VoteContext;
 }
 interface VoteCast {
-    /** Vote */
+    /** Vote associated with the event. */
     vote?: Vote;
 }
 interface DownvoteRequest {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string;
     /**
-     * resource identifier for vote be cast on
+     * ID of the resource receiving the vote. For a comment, specify the comment ID.
      * @maxLength 128
      */
     resourceId: string;
     /**
-     * resource name
+     * Entity type receiving the vote. For comments, specify `wix.comments.v2.comment`.
      * @maxLength 300
      */
     resourceFqdn: string;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData;
 }
 interface DownvoteResponse {
-    /** created vote */
+    /** Vote cast or updated. */
     vote?: Vote;
 }
 interface UpdateVoteRequest {
@@ -191,34 +194,34 @@ interface UpdateVoteResponse {
 }
 interface RemoveVoteRequest {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string;
-    /** id of the vote which will be deleted */
+    /** ID of the vote to remove. */
     voteId: string;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData;
 }
 interface RemoveVoteResponse {
-    /** removed vote */
+    /** Vote removed. */
     vote?: Vote;
 }
 interface VoteDeleted {
-    /** Vote */
+    /** Vote associated with the event. */
     vote?: Vote;
 }
 interface QueryVotesRequest {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string;
-    /** query request. Filter supports only "resourceId" field. Fields and Fieldset are not supported */
+    /** Query options. Filter by `resourceId`. Field projection and fieldsets aren't supported. */
     query?: QueryV2;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData;
 }
 interface QueryV2 extends QueryV2PagingMethodOneOf {
@@ -298,9 +301,9 @@ interface CursorPaging {
     cursor?: string | null;
 }
 interface QueryVotesResponse {
-    /** matching votes */
+    /** Votes matching the query. */
     votes?: Vote[];
-    /** paging metadata. Only contains cursors */
+    /** Paging metadata containing cursors for retrieving additional results. */
     paging?: PagingMetadataV2;
 }
 interface PagingMetadataV2 {
@@ -646,7 +649,9 @@ interface VoteContextResourceVoteChangeEnvelope {
     data: ContextResourceVoteChange;
     metadata: EventMetadata;
 }
-/** @webhook
+/**
+ * Triggered when a vote changes the totals for a resource.
+ * @webhook
  * @eventType wix.comments.v1.vote_context_resource_vote_change
  * @serviceIdentifier com.wixpress.comments.Votes
  * @slug context_resource_vote_change
@@ -657,7 +662,9 @@ interface VoteCastEnvelope {
     data: VoteCast;
     metadata: EventMetadata;
 }
-/** @webhook
+/**
+ * Triggered when an upvote or downvote is cast, including changes to an existing vote.
+ * @webhook
  * @eventType wix.comments.v1.vote_vote_cast
  * @serviceIdentifier com.wixpress.comments.Votes
  * @slug vote_cast
@@ -668,7 +675,9 @@ interface VoteDeletedEnvelope {
     data: VoteDeleted;
     metadata: EventMetadata;
 }
-/** @webhook
+/**
+ * Triggered when a vote is removed.
+ * @webhook
  * @eventType wix.comments.v1.vote_vote_deleted
  * @serviceIdentifier com.wixpress.comments.Votes
  * @slug vote_deleted
@@ -677,115 +686,135 @@ interface VoteDeletedEnvelope {
 declare function onVoteDeleted(handler: (event: VoteDeletedEnvelope) => void | Promise<void>): void;
 /**
  * Casts an upvote on a resource for the current identity.
- * Changes an existing downvote to an upvote. Repeating an upvote does not remove it.
- * Provide contextData for the app and context. Context voting permissions apply.
- * Authorization is enforced by the service for the current identity and context.
+ *
+ * Changes the current identity's existing downvote to an upvote.
+ * Repeating the same vote doesn't remove it. To clear a vote, call
+ * [Remove Vote](https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/comments/vote-v1/remove-vote).
+ * Specify the resource's app and context in `contextData`. Voting must be enabled for that context.
  * @public
  * @documentationMaturity preview
  * @requiredField options.resourceFqdn
  * @requiredField options.resourceId
+ * @permissionId comments:v1:vote:upvote
  * @fqn com.wixpress.comments.Votes.Upvote
  */
-declare function upvote(options?: NonNullablePaths<UpvoteOptions, `resourceFqdn` | `resourceId`, 2>): Promise<NonNullablePaths<UpvoteResponse, `vote.resourceId` | `vote.resourceFqdn` | `vote.voteId` | `vote.type` | `vote.createdBy.identityId` | `vote.createdBy.identityType` | `vote.context.contextId` | `vote.context.appDefId` | `vote.context.metaSiteId` | `vote.revision`, 4> & {
+declare function upvote(options?: NonNullablePaths<UpvoteOptions, `resourceFqdn` | `resourceId`, 0>): Promise<NonNullablePaths<UpvoteResponse, `vote.resourceId` | `vote.resourceFqdn` | `vote.voteId` | `vote.type` | `vote.createdBy.identityId` | `vote.createdBy.identityType` | `vote.context.contextId` | `vote.context.appDefId` | `vote.context.metaSiteId` | `vote.revision`, 2> & {
     __applicationErrorsType?: UpvoteApplicationErrors;
 }>;
 interface UpvoteOptions {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string;
     /**
-     * resource identifier for vote be cast on
+     * ID of the resource receiving the vote. For a comment, specify the comment ID.
      * @maxLength 128
      */
     resourceId: string;
     /**
-     * resource name
+     * Entity type receiving the vote. For comments, specify `wix.comments.v2.comment`.
      * @maxLength 300
      */
     resourceFqdn: string;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData;
 }
 /**
  * Casts a downvote on a resource for the current identity.
- * Changes an existing upvote to a downvote. Use RemoveVote to clear a vote.
- * Provide contextData for the app and context. Context voting permissions apply.
- * Authorization is enforced by the service for the current identity and context.
+ *
+ * Changes the current identity's existing upvote to a downvote.
+ * Repeating the same vote doesn't remove it. To clear a vote, call
+ * [Remove Vote](https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/comments/vote-v1/remove-vote).
+ * Specify the resource's app and context in `contextData`. Voting must be enabled for that context.
  * @public
  * @documentationMaturity preview
  * @requiredField options.resourceFqdn
  * @requiredField options.resourceId
+ * @permissionId comments:v1:vote:downvote
  * @fqn com.wixpress.comments.Votes.Downvote
  */
-declare function downvote(options?: NonNullablePaths<DownvoteOptions, `resourceFqdn` | `resourceId`, 2>): Promise<NonNullablePaths<DownvoteResponse, `vote.resourceId` | `vote.resourceFqdn` | `vote.voteId` | `vote.type` | `vote.createdBy.identityId` | `vote.createdBy.identityType` | `vote.context.contextId` | `vote.context.appDefId` | `vote.context.metaSiteId` | `vote.revision`, 4> & {
+declare function downvote(options?: NonNullablePaths<DownvoteOptions, `resourceFqdn` | `resourceId`, 0>): Promise<NonNullablePaths<DownvoteResponse, `vote.resourceId` | `vote.resourceFqdn` | `vote.voteId` | `vote.type` | `vote.createdBy.identityId` | `vote.createdBy.identityType` | `vote.context.contextId` | `vote.context.appDefId` | `vote.context.metaSiteId` | `vote.revision`, 2> & {
     __applicationErrorsType?: DownvoteApplicationErrors;
 }>;
 interface DownvoteOptions {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string;
     /**
-     * resource identifier for vote be cast on
+     * ID of the resource receiving the vote. For a comment, specify the comment ID.
      * @maxLength 128
      */
     resourceId: string;
     /**
-     * resource name
+     * Entity type receiving the vote. For comments, specify `wix.comments.v2.comment`.
      * @maxLength 300
      */
     resourceFqdn: string;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData;
 }
 /**
- * Removes the current identity's vote in the specified context and returns it.
- * Obtain voteId from a vote response or QueryVotes. A repeated removal can fail.
- * Authorization is enforced by the service for the current identity and context.
- * @param voteId - id of the vote which will be deleted
+ * Removes the current identity's vote and returns the removed vote.
+ *
+ * Specify the `voteId` returned by a vote response or
+ * [Query Votes](https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/comments/vote-v1/query-votes) and the same `contextData` used to cast the vote.
+ * A repeated removal fails when the vote no longer exists.
+ * @param voteId - ID of the vote to remove.
  * @public
  * @documentationMaturity preview
  * @requiredField voteId
+ * @permissionId comments:v1:vote:remove_vote
  * @fqn com.wixpress.comments.Votes.RemoveVote
  */
-declare function removeVote(voteId: string, options?: RemoveVoteOptions): Promise<NonNullablePaths<RemoveVoteResponse, `vote.resourceId` | `vote.resourceFqdn` | `vote.voteId` | `vote.type` | `vote.createdBy.identityId` | `vote.createdBy.identityType` | `vote.context.contextId` | `vote.context.appDefId` | `vote.context.metaSiteId` | `vote.revision`, 4> & {
+declare function removeVote(voteId: string, options?: RemoveVoteOptions): Promise<NonNullablePaths<RemoveVoteResponse, `vote.resourceId` | `vote.resourceFqdn` | `vote.voteId` | `vote.type` | `vote.createdBy.identityId` | `vote.createdBy.identityType` | `vote.context.contextId` | `vote.context.appDefId` | `vote.context.metaSiteId` | `vote.revision`, 2> & {
     __applicationErrorsType?: RemoveVoteApplicationErrors;
 }>;
 interface RemoveVoteOptions {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData;
 }
 /**
- * Retrieves votes in the specified app and context.
- * Visitor and member callers receive only their own votes. Application callers
- * can query all votes only when granted WIX_COMMENTS.VOTE_QUERY.
- * Filter on resourceId, including $in for a batch of comment IDs.
- * Continue with query.cursorPaging.cursor from paging.cursors.next.
- * Authorization is enforced by the service for the current identity and context.
+ * Retrieves a list of votes, given the provided paging and filtering.
+ *
+ * Visitor and member callers receive their own votes in the specified app and context.
+ * Authorized application callers can retrieve votes from multiple identities in that context.
+ * Filter by `resourceId`, using `$in` to retrieve votes for multiple comment IDs.
+ * Results don't include comments without a matching vote.
+ *
+ * Specify `query.cursorPaging.limit` to control the page size. To retrieve the next page,
+ * set `query.cursorPaging.cursor` to the returned `paging.cursors.next` and keep the same context.
+ * Offset paging and field projection aren't supported. Don't depend on a particular result order.
+ *
+ * To learn about working with Query methods, see
+ * [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language) and
+ * [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging).
+ * Retain the permission checked by RequestContextResolver for app identities.
  * @public
  * @documentationMaturity preview
+ * @permissionId WIX_COMMENTS.VOTE_QUERY
+ * @applicableIdentity APP
  * @fqn com.wixpress.comments.Votes.QueryVotes
  */
 declare function queryVotes(options?: QueryVotesOptions): VotesQueryBuilder;
 interface QueryVotesOptions {
     /**
-     * context token to be passed
+     * Legacy context token. Use `contextData` instead.
      * @deprecated
      * @replacedBy context_data
      */
     contextToken?: string | undefined;
-    /** context data */
+    /** App and context containing the resource. */
     contextData?: ContextData | undefined;
 }
 interface QueryCursorResult {
@@ -830,7 +859,7 @@ interface VotesQueryBuilder {
  * @fqn com.wixpress.comments.Votes.QueryVotes
  * @requiredField query
  */
-declare function typedQueryVotes(query: VoteQuery, options?: QueryVotesOptions): Promise<NonNullablePaths<QueryVotesResponse, `votes` | `votes.${number}.resourceId` | `votes.${number}.resourceFqdn` | `votes.${number}.voteId` | `votes.${number}.type` | `votes.${number}.createdBy.identityId` | `votes.${number}.createdBy.identityType` | `votes.${number}.context.contextId` | `votes.${number}.context.appDefId` | `votes.${number}.context.metaSiteId` | `votes.${number}.revision`, 5> & {
+declare function typedQueryVotes(query: VoteQuery, options?: QueryVotesOptions): Promise<NonNullablePaths<QueryVotesResponse, `votes` | `votes.${number}.resourceId` | `votes.${number}.resourceFqdn` | `votes.${number}.voteId` | `votes.${number}.type` | `votes.${number}.createdBy.identityId` | `votes.${number}.createdBy.identityType` | `votes.${number}.context.contextId` | `votes.${number}.context.appDefId` | `votes.${number}.context.metaSiteId` | `votes.${number}.revision`, 3> & {
     __applicationErrorsType?: QueryVotesApplicationErrors;
 }>;
 interface VoteQuerySpec extends QuerySpec {