@wix/auto_sdk_seo_keyword-research 1.0.0

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

@@ -0,0 +1,672 @@
+import { NonNullablePaths } from '@wix/sdk-types';
+
+/**
+ * A keyword research item is one target keyword in a site's content plan,
+ * together with the search data behind it and the page it belongs to.
+ *
+ * The content plan pipeline generates a set of these for a site. A site owner
+ * can then refine them, and the blog post briefs are built from the result.
+ *
+ * Items are grouped into clusters. Each site page has one main keyword, marked
+ * by `primary`, and the other keywords in that cluster support it.
+ */
+interface KeywordResearch {
+    /**
+     * Keyword research item ID.
+     * @format GUID
+     * @readonly
+     */
+    _id?: string | null;
+    /**
+     * The keyword itself.
+     *
+     * An update is rejected if the new keyword is longer than 80 characters, or
+     * if it duplicates another keyword in the same research.
+     * @maxLength 1000
+     */
+    keyword?: string | null;
+    /**
+     * ID of the site page the keyword is assigned to.
+     * @maxLength 1000
+     */
+    pageId?: string | null;
+    /**
+     * Type of the site page the keyword is assigned to, such as a static
+     * page or a blog post.
+     * @maxLength 1000
+     */
+    itemType?: string | null;
+    /**
+     * URL of the site page the keyword is assigned to.
+     * @maxLength 1000
+     */
+    pageUrl?: string | null;
+    /**
+     * How hard it is to rank for the keyword, on a scale where a higher
+     * number means more competition.
+     *
+     * Recalculated when `keyword` changes, even if you don't name this field
+     * in the field mask.
+     */
+    competition?: number | null;
+    /**
+     * Estimated number of searches for the keyword per month.
+     *
+     * Recalculated when `keyword` changes, even if you don't name this field
+     * in the field mask.
+     */
+    searchVolume?: number | null;
+    /**
+     * Whether the site page this keyword is assigned to has been deleted.
+     *
+     * A keyword assigned to a deleted page stays in the research.
+     */
+    pageDeleted?: boolean | null;
+    /**
+     * Whether this keyword is the main keyword for its page.
+     *
+     * A page has a single main keyword, and the other keywords in its cluster
+     * support it.
+     */
+    primary?: boolean | null;
+    /**
+     * Name of the cluster that groups this keyword with the others covering
+     * the same topic.
+     * @maxLength 1000
+     */
+    clusterName?: string | null;
+}
+interface GetKeywordResearchItemsByPageIdRequest {
+    /**
+     * ID of the page to retrieve keywords for. Required.
+     * @maxLength 1000
+     */
+    pageId?: string;
+    /**
+     * Type of the page. Required. Must match a stored item type.
+     * Unmatched value returns NOT_FOUND unless a main keyword was already set.
+     * @maxLength 1000
+     */
+    itemType?: string;
+    /**
+     * Optional. The handler currently resolves the site's latest keyword
+     * research and does not read this field. Kept for future use: when the
+     * handler is updated to support per-flow lookups, callers will be able to
+     * target a specific flow's research instead of always getting the latest.
+     * @format GUID
+     */
+    contentPlanFlowId?: string | null;
+}
+interface GetKeywordResearchItemsByPageIdResponse {
+    /**
+     * keywords related to the page
+     * @maxSize 1000
+     */
+    keywordResearchItems?: KeywordResearch[];
+    /**
+     * id of the main keyword for this page
+     * @format GUID
+     */
+    mainKeywordId?: string | null;
+}
+interface ListKeywordResearchItemsRequest {
+    /**
+     * Reserved for future use.
+     *
+     * This method currently resolves the site's most recent keyword research,
+     * and this field is ignored.
+     * @format GUID
+     */
+    contentPlanFlowId?: string | null;
+    /**
+     * Cursor paging. Omit for the first page.
+     *
+     * Omit this object entirely to return every item in a single response.
+     */
+    paging?: CursorPaging;
+}
+interface CursorPaging {
+    /**
+     * Max items per page. Default 50, max 100.
+     * @max 100
+     */
+    limit?: number | null;
+    /**
+     * Cursor from a previous response. Omit for the first page.
+     * @maxLength 16000
+     */
+    cursor?: string | null;
+}
+interface ListKeywordResearchItemsResponse {
+    /**
+     * Retrieved keyword research items.
+     * @maxSize 1000
+     */
+    keywordResearchItems?: KeywordResearch[];
+    /**
+     * ID of the keyword research these items belong to.
+     *
+     * Send this ID when you update an item. Compare it across reads to detect
+     * that a newer generation replaced the research.
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+    /**
+     * Whether this research has been edited.
+     *
+     * `false` means the research is exactly as the content plan generated it,
+     * so the next edit copies it onto a new `keywordResearchId`.
+     */
+    createdByUser?: boolean | null;
+    /**
+     * ID of the main keyword for each page, keyed by page ID.
+     *
+     * Built from the site's full item set, so on a paged response it can name
+     * items that aren't in `keywordResearchItems`.
+     */
+    mainKeywordMap?: Record<string, string>;
+    /** Paging metadata. */
+    pagingMetadata?: CursorPagingMetadata;
+}
+interface CursorPagingMetadata {
+    /** Items returned in this page. */
+    count?: number | null;
+    /** Cursors for next/previous page. */
+    cursors?: Cursors;
+    /** Whether there are more pages. */
+    hasNext?: boolean | null;
+}
+interface Cursors {
+    /**
+     * Cursor for the next page.
+     * @maxLength 16000
+     */
+    next?: string | null;
+    /**
+     * Cursor for the previous page.
+     * @maxLength 16000
+     */
+    prev?: string | null;
+}
+/** Deprecated alias request. Same fields as ListKeywordResearchItemsRequest. */
+interface GetKeywordResearchItemsRequest {
+    /**
+     * Deprecated. Ignored by the handler.
+     * @format GUID
+     */
+    contentPlanFlowId?: string | null;
+    /** Cursor paging. */
+    paging?: CursorPaging;
+}
+/** Deprecated alias response. Same fields as ListKeywordResearchItemsResponse. */
+interface GetKeywordResearchItemsResponse {
+    /**
+     * Keyword research items.
+     * @maxSize 1000
+     */
+    keywordResearchItems?: KeywordResearch[];
+    /**
+     * ID of the keyword research.
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+    /** Whether the research was user-created. */
+    createdByUser?: boolean | null;
+    /** Main keyword IDs by page ID. */
+    mainKeywordMap?: Record<string, string>;
+    /** Paging metadata. */
+    pagingMetadata?: CursorPagingMetadata;
+}
+interface GetDraftKeywordResearchItemsRequest {
+    /**
+     * id of the content plan flow this keyword research belongs to
+     * @format GUID
+     */
+    contentPlanFlowId?: string | null;
+}
+interface GetDraftKeywordResearchItemsResponse {
+    /**
+     * keyword research items
+     * @maxSize 1000
+     */
+    keywordResearchItems?: KeywordResearch[];
+    /**
+     * id of the keyword research that was returned
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+    /** whether the keyword research was created by the user */
+    createdByUser?: boolean | null;
+    /** map of ids of the main keywords by page id */
+    mainKeywordMap?: Record<string, string>;
+}
+interface UpdateKeywordResearchItemsRequest {
+    /**
+     * updated keyword research items
+     * @maxSize 1000
+     */
+    updatedItems?: UpdatedKeywordResearch[];
+    /**
+     * deleted keyword research items
+     * @maxSize 1000
+     */
+    deletedItems?: DeletedKeywordResearch[];
+    /**
+     * added keyword research items
+     * @maxSize 1000
+     */
+    addedItems?: AddedKeywordResearch[];
+    /**
+     * id of the keyword research to be updated
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+}
+interface UpdatedKeywordResearch {
+    /**
+     * ID of the keyword research item to update.
+     * @format GUID
+     */
+    _id?: string | null;
+    /**
+     * New keyword.
+     *
+     * Rejected if it's longer than 80 characters, or if it duplicates another
+     * keyword in the same research. Changing it also refreshes the item's
+     * `searchVolume` and `competition`.
+     * @maxLength 1000
+     */
+    keyword?: string | null;
+    /**
+     * Whether to make this item its page's main keyword.
+     *
+     * Set to `true` to promote it. `false` and omitting the field both leave
+     * the current main keyword unchanged, so this field can't demote one.
+     */
+    mainKeyword?: boolean | null;
+}
+interface DeletedKeywordResearch {
+    /**
+     * ID of the keyword research item to delete.
+     * @format GUID
+     */
+    _id?: string | null;
+}
+interface AddedKeywordResearch {
+    /**
+     * keyword of the keyword research item
+     * @maxLength 1000
+     */
+    keyword?: string | null;
+    /**
+     * page id the keyword relates to
+     * @maxLength 1000
+     */
+    pageId?: string | null;
+    /** is the keyword the main keyword for it's page */
+    mainKeyword?: boolean | null;
+}
+interface UpdateKeywordResearchItemsResponse {
+    /**
+     * keyword research items
+     * @maxSize 1000
+     */
+    keywordResearchItems?: KeywordResearch[];
+    /**
+     * id of the keyword research that was returned
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+    /** whether the keyword research was created by the user */
+    createdByUser?: boolean | null;
+    /** map of ids of the main keywords by page id */
+    mainKeywordMap?: Record<string, string>;
+}
+interface UpdateKeywordResearchItemRequest {
+    /**
+     * ID of the keyword research the item belongs to.
+     *
+     * Use the `keywordResearchId` from your most recent read or write.
+     * @format GUID
+     */
+    keywordResearchId: string | null;
+    /** Keyword research item to update. */
+    item: UpdatedKeywordResearch;
+    /**
+     * Fields to update.
+     *
+     * Must name at least one of `keyword` or `mainKeyword`, the only writable
+     * fields. An omitted or empty mask is rejected.
+     */
+    fieldMask: string[];
+}
+interface UpdateKeywordResearchItemResponse {
+    /** Updated keyword research item. */
+    keywordResearchItem?: KeywordResearch;
+    /**
+     * ID of the keyword research holding the updated item.
+     *
+     * This can differ from the ID you sent, because the first edit to
+     * generated research copies it. Use this value for your next write.
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+}
+interface BulkUpdateKeywordResearchItemsRequest {
+    /**
+     * ID of the keyword research the items belong to.
+     *
+     * Use the `keywordResearchId` from your most recent read or write.
+     * @format GUID
+     */
+    keywordResearchId: string | null;
+    /**
+     * Keyword research items to update.
+     *
+     * Each item ID must appear at most once. The research holds at most 30
+     * keywords once the update is applied.
+     * @minSize 1
+     * @maxSize 1000
+     */
+    items?: UpdatedKeywordResearch[];
+}
+interface BulkUpdateKeywordResearchItemsResponse {
+    /**
+     * Result for each entry, correlated by `itemMetadata.originalIndex`.
+     * @maxSize 1000
+     */
+    results?: BulkKeywordResearchItemResult[];
+    /** How many entries succeeded and how many failed. */
+    bulkActionMetadata?: BulkActionMetadata;
+    /**
+     * The full set of keyword research items after the update.
+     * @maxSize 1000
+     */
+    keywordResearchItems?: KeywordResearch[];
+    /**
+     * ID of the keyword research holding the updated items.
+     *
+     * This can differ from the ID you sent, because the first edit to
+     * generated research copies it. Use this value for your next write.
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+    /** ID of the main keyword for each page, keyed by page ID. */
+    mainKeywordMap?: Record<string, string>;
+}
+interface ItemMetadata {
+    /**
+     * Item ID. Should always be available, unless it's impossible (for example, when failing to create an item).
+     * @maxLength 100
+     */
+    _id?: string | null;
+    /** Index of the item within the request array. Allows for correlation between request and response items. */
+    originalIndex?: number;
+    /** Whether the requested action was successful for this item. When `false`, the `error` field is populated. */
+    success?: boolean;
+    /** Details about the error in case of failure. */
+    error?: ApplicationError;
+}
+interface ApplicationError {
+    /** Error code. */
+    code?: string;
+    /** Description of the error. */
+    description?: string;
+    /** Data related to the error. */
+    data?: Record<string, any> | null;
+}
+interface BulkKeywordResearchItemResult {
+    /** Success/failure and error detail for this entry. */
+    itemMetadata?: ItemMetadata;
+}
+interface BulkActionMetadata {
+    /** Number of items that were successfully processed. */
+    totalSuccesses?: number;
+    /** Number of items that couldn't be processed. */
+    totalFailures?: number;
+    /** Number of failures without details because detailed failure threshold was exceeded. */
+    undetailedFailures?: number;
+}
+interface RevertKeywordResearchRequest {
+    /**
+     * id of the keyword research to revert
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+}
+interface RevertKeywordResearchResponse {
+    /**
+     * keyword research items
+     * @maxSize 1000
+     */
+    keywordResearchItems?: KeywordResearch[];
+    /**
+     * id of the keyword research that was returned
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+}
+interface DistributeKeywordsToPagesRequest {
+    /**
+     * Keywords to distribute
+     * @maxSize 1000
+     * @maxLength 1000
+     */
+    keywords?: string[];
+    /**
+     * Page essences to match keywords to
+     * @maxSize 1000
+     */
+    pageEssences?: PageEssenceInput[];
+    /**
+     * Embedding dimensions (e.g., "256", "512", "1024", "3072")
+     * @maxLength 4
+     */
+    dimensions?: string | null;
+    /** Similarity threshold (default 0.5) */
+    similarityThreshold?: number | null;
+}
+interface PageEssenceInput {
+    /**
+     * Page name
+     * @maxLength 1000
+     */
+    pageName?: string;
+    /**
+     * Page ID
+     * @maxLength 1000
+     */
+    pageId?: string;
+    /**
+     * Page essence (semantic summary)
+     * @maxLength 1000
+     */
+    pageEssence?: string;
+    /** Is homepage */
+    homepage?: boolean;
+}
+interface DistributeKeywordsToPagesResponse {
+    /**
+     * Distributed keywords with their assigned pages
+     * @maxSize 1000
+     */
+    distributedKeywords?: DistributedKeyword[];
+}
+interface DistributedKeyword {
+    /**
+     * The keyword
+     * @maxLength 1000
+     */
+    keyword?: string;
+    /**
+     * The assigned page ID
+     * @maxLength 1000
+     */
+    pageId?: string;
+    /** The similarity score */
+    score?: number;
+}
+/**
+ * Retrieves the keyword research behind the site's current content plan.
+ *
+ * Returns the research produced by the last completed generation. Research
+ * from a generation that's still running, or that failed, isn't readable.
+ * Poll Get Content Plan Flow until its status is `SUCCESS`, then call this
+ * method.
+ *
+ * The result is scoped to the site rather than to a flow. This method
+ * always returns the site's most recent research and can't target an
+ * earlier one. If another generation finishes between your trigger and this
+ * read, you receive the newer research instead. Compare `keywordResearchId`
+ * across reads to detect that the research was replaced.
+ *
+ * Omit `paging` to return every item in a single response. When `paging` is
+ * present, `limit` accepts 1 to 100 and defaults to 50.
+ *
+ * A site with no keyword research returns a not found error rather than an
+ * empty list.
+ * @public
+ * @documentationMaturity preview
+ * @permissionId promote:seo:v1:content_plan_keyword_research:list_keyword_research_items
+ * @applicableIdentity APP
+ * @fqn wix.promote.seo.content.plan.v1.KeywordResearchServiceV1.ListKeywordResearchItems
+ */
+declare function listKeywordResearchItems(options?: ListKeywordResearchItemsOptions): Promise<NonNullablePaths<ListKeywordResearchItemsResponse, `keywordResearchItems`, 2>>;
+interface ListKeywordResearchItemsOptions {
+    /**
+     * Reserved for future use.
+     *
+     * This method currently resolves the site's most recent keyword research,
+     * and this field is ignored.
+     * @format GUID
+     */
+    contentPlanFlowId?: string | null;
+    /**
+     * Cursor paging. Omit for the first page.
+     *
+     * Omit this object entirely to return every item in a single response.
+     */
+    paging?: CursorPaging;
+}
+/**
+ * Updates a keyword research item.
+ *
+ * `fieldMask` is required and must name at least one of `keyword` or
+ * `mainKeyword`. Those are the only writable fields, and an omitted or
+ * empty mask is rejected rather than treated as a request to write
+ * everything.
+ *
+ * `mainKeyword` only promotes. Set it to `true` to make the item its page's
+ * main keyword. Setting it to `false`, or leaving it out, changes nothing,
+ * so a main keyword can't be demoted with this method.
+ *
+ * This method updates an item that already exists. It can't add or delete a
+ * keyword.
+ *
+ * The first write to AI-generated research copies that research instead of
+ * changing it, so the response can carry a different `keywordResearchId`.
+ * Always send the ID from the most recent response on your next write.
+ * Sending the original ID again copies the research again.
+ *
+ * Changing `keyword` also refreshes that item's `searchVolume` and
+ * `competition`, even though the mask doesn't name them.
+ *
+ * Edits don't survive a later generation. A generation that completes after
+ * your edit produces fresh research that replaces the edited copy in every
+ * read.
+ *
+ * To update multiple keyword research items in a single API call, call
+ * [Bulk Update Keyword Research Items](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/bulk-update-keyword-research-items).
+ * @param _id - ID of the keyword research item to update.
+ * @param keywordResearchId - ID of the keyword research the item belongs to.
+ *
+ * Use the `keywordResearchId` from your most recent read or write.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField _id
+ * @requiredField keywordResearchId
+ * @requiredField options
+ * @requiredField options.fieldMask
+ * @requiredField options.item
+ * @permissionId promote:seo:v1:content_plan_keyword_research:update_keyword_research_item
+ * @applicableIdentity APP
+ * @fqn wix.promote.seo.content.plan.v1.KeywordResearchServiceV1.UpdateKeywordResearchItem
+ */
+declare function updateKeywordResearchItem(_id: string, keywordResearchId: string, options: NonNullablePaths<UpdateKeywordResearchItemOptions, `fieldMask` | `item`, 2>): Promise<UpdateKeywordResearchItemResponse>;
+interface UpdateKeywordResearchItemOptions {
+    item: {
+        /**
+         * ID of the keyword research item to update.
+         * @format GUID
+         */
+        _id?: string | null;
+        /**
+         * New keyword.
+         *
+         * Rejected if it's longer than 80 characters, or if it duplicates another
+         * keyword in the same research. Changing it also refreshes the item's
+         * `searchVolume` and `competition`.
+         * @maxLength 1000
+         */
+        keyword?: string | null;
+        /**
+         * Whether to make this item its page's main keyword.
+         *
+         * Set to `true` to promote it. `false` and omitting the field both leave
+         * the current main keyword unchanged, so this field can't demote one.
+         */
+        mainKeyword?: boolean | null;
+    };
+    /**
+     * Fields to update.
+     *
+     * Must name at least one of `keyword` or `mainKeyword`, the only writable
+     * fields. An omitted or empty mask is rejected.
+     */
+    fieldMask: string[];
+}
+/**
+ * Updates multiple keyword research items.
+ *
+ * This method has no field mask and writes every field present on each
+ * entry. `keyword` and `mainKeyword` remain the only writable fields, and
+ * `mainKeyword` only promotes, as it does for a single item. Repeating an
+ * item ID within one call is rejected.
+ *
+ * Validation runs across the whole request before anything is written, so a
+ * problem rejects the entire call rather than failing one entry. Every
+ * returned entry therefore reports success.
+ *
+ * A keyword research holds at most 30 keywords, counted after the update.
+ * That limit is reached well before the request's own item limit.
+ *
+ * This method copies AI-generated research the same way a single-item
+ * update does, so send the `keywordResearchId` from the response on your
+ * next write. Edits don't survive a later generation.
+ *
+ * To update a single keyword research item, call
+ * [Update Keyword Research Item](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/update-keyword-research-item).
+ * @param keywordResearchId - ID of the keyword research the items belong to.
+ *
+ * Use the `keywordResearchId` from your most recent read or write.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField keywordResearchId
+ * @permissionId promote:seo:v1:content_plan_keyword_research:bulk_update_keyword_research_items
+ * @applicableIdentity APP
+ * @fqn wix.promote.seo.content.plan.v1.KeywordResearchServiceV1.BulkUpdateKeywordResearchItems
+ */
+declare function bulkUpdateKeywordResearchItems(keywordResearchId: string, options?: BulkUpdateKeywordResearchItemsOptions): Promise<NonNullablePaths<BulkUpdateKeywordResearchItemsResponse, `results` | `results.${number}.itemMetadata.originalIndex` | `results.${number}.itemMetadata.success` | `results.${number}.itemMetadata.error.code` | `results.${number}.itemMetadata.error.description` | `bulkActionMetadata.totalSuccesses` | `bulkActionMetadata.totalFailures` | `bulkActionMetadata.undetailedFailures` | `keywordResearchItems`, 6>>;
+interface BulkUpdateKeywordResearchItemsOptions {
+    /**
+     * Keyword research items to update.
+     *
+     * Each item ID must appear at most once. The research holds at most 30
+     * keywords once the update is applied.
+     * @minSize 1
+     * @maxSize 1000
+     */
+    items?: UpdatedKeywordResearch[];
+}
+
+export { type AddedKeywordResearch, type ApplicationError, type BulkActionMetadata, type BulkKeywordResearchItemResult, type BulkUpdateKeywordResearchItemsOptions, type BulkUpdateKeywordResearchItemsRequest, type BulkUpdateKeywordResearchItemsResponse, type CursorPaging, type CursorPagingMetadata, type Cursors, type DeletedKeywordResearch, type DistributeKeywordsToPagesRequest, type DistributeKeywordsToPagesResponse, type DistributedKeyword, type GetDraftKeywordResearchItemsRequest, type GetDraftKeywordResearchItemsResponse, type GetKeywordResearchItemsByPageIdRequest, type GetKeywordResearchItemsByPageIdResponse, type GetKeywordResearchItemsRequest, type GetKeywordResearchItemsResponse, type ItemMetadata, type KeywordResearch, type ListKeywordResearchItemsOptions, type ListKeywordResearchItemsRequest, type ListKeywordResearchItemsResponse, type PageEssenceInput, type RevertKeywordResearchRequest, type RevertKeywordResearchResponse, type UpdateKeywordResearchItemOptions, type UpdateKeywordResearchItemRequest, type UpdateKeywordResearchItemResponse, type UpdateKeywordResearchItemsRequest, type UpdateKeywordResearchItemsResponse, type UpdatedKeywordResearch, bulkUpdateKeywordResearchItems, listKeywordResearchItems, updateKeywordResearchItem };