@wix/auto_sdk_seo_content-plan-flows 1.0.0

package/build/es/index.typings.d.mts

@@ -0,0 +1,531 @@
+import { NonNullablePaths } from '@wix/sdk-types';
+
+/**
+ * A content plan flow tracks the generation of an SEO content plan for a site.
+ *
+ * A content plan is a set of blog post briefs built from the site's pages, its
+ * business category, and real search volume data. Generating one takes several
+ * minutes, so the flow runs asynchronously and reports its progress in `status`.
+ *
+ * A flow doesn't run to completion on its own. It stops at `KEYWORD_RESEARCH`
+ * and waits for a call to Create Content Plan before it continues.
+ */
+interface ContentPlanFlow {
+    /**
+     * Content plan flow ID.
+     * @format GUID
+     * @readonly
+     */
+    _id?: string | null;
+    /**
+     * Date and time the content plan flow was created.
+     * @maxLength 100
+     */
+    createdAt?: string | null;
+    /**
+     * Date and time the content plan flow was updated.
+     * @maxLength 100
+     */
+    updatedAt?: string | null;
+    /**
+     * Current status of the content plan flow.
+     *
+     * The status advances on its own as generation progresses, except at
+     * `KEYWORD_RESEARCH`, where the flow waits for a call to Create Content
+     * Plan.
+     */
+    status?: StatusWithLiterals;
+    /**
+     * What started the content plan flow. Flows started by an app are
+     * recorded as `AGENT`.
+     * @maxLength 100
+     */
+    origin?: string | null;
+    /**
+     * ID of the site content summary the flow produced.
+     * @format GUID
+     */
+    summaryId?: string | null;
+    /**
+     * ID of the keyword research the flow produced.
+     *
+     * Available once `status` is `KEYWORD_RESEARCH` or later.
+     * @format GUID
+     */
+    keywordResearchId?: string | null;
+}
+declare enum Status {
+    /** The flow is created and the generation pipeline is starting. */
+    CREATED = "CREATED",
+    /** The site's existing content is being summarized. */
+    SITE_SUMMARY = "SITE_SUMMARY",
+    /**
+     * Keyword research is complete and the flow is waiting. Call Create
+     * Content Plan to generate the blog post briefs and continue the flow.
+     */
+    KEYWORD_RESEARCH = "KEYWORD_RESEARCH",
+    /** Blog post briefs are being generated from the keyword research. */
+    CONTENT_PLAN = "CONTENT_PLAN",
+    /**
+     * Generation is complete. Retrieve the results with List Blog Post
+     * Candidates and List Keyword Research Items.
+     */
+    SUCCESS = "SUCCESS",
+    /** Generation failed. Trigger a flow to try again. */
+    FAIL = "FAIL",
+    /**
+     * The site is missing business information that keyword research
+     * requires. The flow resumes automatically once the information is
+     * added to the site.
+     */
+    PENDING_REQUIREMENTS = "PENDING_REQUIREMENTS",
+    /** The flow was canceled and can't be resumed. */
+    CANCELED = "CANCELED",
+    /** The site's pages are being analyzed. */
+    SITE_ANALYSIS = "SITE_ANALYSIS"
+}
+/** @enumType */
+type StatusWithLiterals = Status | 'CREATED' | 'SITE_SUMMARY' | 'KEYWORD_RESEARCH' | 'CONTENT_PLAN' | 'SUCCESS' | 'FAIL' | 'PENDING_REQUIREMENTS' | 'CANCELED' | 'SITE_ANALYSIS';
+interface GetContentPlanFlowRequest {
+    /**
+     * ID of the content plan flow to retrieve.
+     *
+     * Omit to retrieve the site's most recent successful flow.
+     * @format GUID
+     */
+    contentPlanFlowId: string | null;
+}
+interface GetContentPlanFlowResponse {
+    /** Retrieved content plan flow. */
+    contentPlanFlow?: ContentPlanFlow;
+}
+interface TriggerContentPlanGenerationFlowRequest {
+}
+interface TriggerContentPlanGenerationFlowResponse {
+    /**
+     * ID of the content plan flow that was created.
+     *
+     * Poll Get Content Plan Flow with this ID to follow the flow's progress.
+     * @format GUID
+     */
+    contentPlanFlowId?: string | null;
+}
+interface ExecuteActionRequest {
+    /**
+     * the execution id
+     * @format GUID
+     */
+    executionId?: string;
+    /**
+     * the action id
+     * @maxLength 1000
+     */
+    actionId?: string;
+    /** item data - if relevant */
+    item?: ItemData;
+    /** whether to reset the current content of the action */
+    reset?: boolean;
+}
+interface ItemData extends ItemDataPayloadDataOneOf {
+    blogData?: BlogData;
+    /**
+     * id
+     * @maxLength 1000
+     */
+    _id?: string;
+    /**
+     * type
+     * @maxLength 1000
+     */
+    type?: string;
+}
+/** @oneof */
+interface ItemDataPayloadDataOneOf {
+    blogData?: BlogData;
+}
+interface BlogData {
+    /**
+     * prompt
+     * @maxLength 10000
+     */
+    prompt?: string;
+}
+interface ExecuteActionResponse {
+    /** Whether the suggestion succeeded */
+    success?: boolean;
+    /** Whether the operation is async */
+    async?: boolean;
+    /**
+     * Optional internal message
+     * @maxLength 1000
+     */
+    message?: string;
+    /** Optional display message */
+    displayMessage?: DisplayMessage;
+    /** The payload of the action, also the suggestion itself. */
+    payload?: ActionPayload;
+    /** Total action cost in microcents (1 microcent = $0.00001). If omitted or zero, PMA uses configured credit cost. */
+    costInMicrocents?: number | null;
+}
+interface DisplayMessage {
+    /**
+     * Message to show to the user
+     * @maxLength 1000
+     */
+    message?: string;
+    /** Optional call to action */
+    cta?: ActionCta;
+}
+interface ActionCta {
+    /**
+     * CTA title
+     * @maxLength 1000
+     */
+    title?: string;
+    /**
+     * CTA URL
+     * @maxLength 1000
+     */
+    url?: string;
+}
+interface ActionPayload {
+    /**
+     * Description of the suggestion
+     * @maxLength 1000
+     */
+    description?: string;
+    /**
+     * Optional motivation for the suggestion
+     * @maxLength 1000
+     */
+    motivation?: string;
+    /** Optional entity being suggested */
+    entity?: Entity;
+    /**
+     * Optional changes suggested
+     * @maxSize 100
+     */
+    changes?: Change[];
+    /**
+     * Optional items suggested
+     * @maxSize 100
+     */
+    items?: Item[];
+    /** Optional preview link */
+    previewLink?: ActionCta;
+}
+interface Entity {
+    /**
+     * Entity ID
+     * @maxLength 100
+     */
+    _id?: string;
+    /**
+     * Optional entity name
+     * @maxLength 1000
+     */
+    name?: string;
+}
+interface Change {
+    /**
+     * Change ID
+     * @maxLength 100
+     */
+    _id?: string;
+    /**
+     * Change title
+     * @maxLength 1000
+     */
+    title?: string;
+    /**
+     * The resulting state after the change
+     * @maxLength 1000
+     */
+    after?: string;
+    /**
+     * Optional description
+     * @maxLength 1000
+     */
+    description?: string;
+    /**
+     * Optional state before the change
+     * @maxLength 1000
+     */
+    before?: string;
+    /** Optional: is this a suggestion or a confirmed change */
+    isSuggestion?: boolean;
+    /**
+     * Optional type of change
+     * @maxLength 100
+     */
+    type?: string;
+}
+interface Item {
+    /**
+     * Item ID
+     * @maxLength 100
+     */
+    _id?: string;
+    /**
+     * Item title
+     * @maxLength 1000
+     */
+    title?: string;
+    /**
+     * Optional description
+     * @maxLength 1000
+     */
+    description?: string;
+    /**
+     * Optional images
+     * @maxSize 100
+     * @maxLength 1000
+     */
+    images?: string[];
+    /** Optional preview link */
+    previewLink?: ActionCta;
+    /**
+     * Optional motivation for suggesting this item
+     * @maxLength 1000
+     */
+    motivation?: string;
+    /** Data */
+    data?: Record<string, any> | null;
+    /**
+     * The content plan item id which this item created by
+     * @maxLength 100
+     */
+    contentPlanItemId?: string;
+    /** scheduled date */
+    scheduledDate?: Date | null;
+}
+interface CancelContentPlanFlowRequest {
+    /**
+     * ID of the content plan flow to cancel.
+     * @format GUID
+     */
+    contentPlanFlowId: string | null;
+}
+interface CancelContentPlanFlowResponse {
+}
+interface DomainEvent extends DomainEventBodyOneOf {
+    createdEvent?: EntityCreatedEvent;
+    updatedEvent?: EntityUpdatedEvent;
+    deletedEvent?: EntityDeletedEvent;
+    actionEvent?: ActionEvent;
+    /** Event ID. With this ID you can easily spot duplicated events and ignore them. */
+    _id?: string;
+    /**
+     * Fully Qualified Domain Name of an entity. This is a unique identifier assigned to the API main business entities.
+     * For example, `wix.stores.catalog.product`, `wix.bookings.session`, `wix.payments.transaction`.
+     */
+    entityFqdn?: string;
+    /**
+     * Event action name, placed at the top level to make it easier for users to dispatch messages.
+     * For example: `created`/`updated`/`deleted`/`started`/`completed`/`email_opened`.
+     */
+    slug?: string;
+    /** ID of the entity associated with the event. */
+    entityId?: string;
+    /** Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example, `2020-04-26T13:57:50.699Z`. */
+    eventTime?: Date | null;
+    /**
+     * Whether the event was triggered as a result of a privacy regulation application
+     * (for example, GDPR).
+     */
+    triggeredByAnonymizeRequest?: boolean | null;
+    /** If present, indicates the action that triggered the event. */
+    originatedFrom?: string | null;
+    /**
+     * A sequence number that indicates the order of updates to an entity. For example, if an entity was updated at `16:00` and then again at `16:01`, the second update will always have a higher sequence number.
+     * You can use this number to make sure you're handling updates in the right order. Just save the latest sequence number on your end and compare it to the one in each new message. If the new message has an older (lower) number, you can safely ignore it.
+     */
+    entityEventSequence?: string | null;
+}
+/** @oneof */
+interface DomainEventBodyOneOf {
+    createdEvent?: EntityCreatedEvent;
+    updatedEvent?: EntityUpdatedEvent;
+    deletedEvent?: EntityDeletedEvent;
+    actionEvent?: ActionEvent;
+}
+interface EntityCreatedEvent {
+    entity?: string;
+}
+interface RestoreInfo {
+    deletedDate?: Date | null;
+}
+interface EntityUpdatedEvent {
+    /**
+     * Since platformized APIs only expose PATCH and not PUT we can't assume that the fields sent from the client are the actual diff.
+     * This means that to generate a list of changed fields (as opposed to sent fields) one needs to traverse both objects.
+     * We don't want to impose this on all developers and so we leave this traversal to the notification recipients which need it.
+     */
+    currentEntity?: string;
+}
+interface EntityDeletedEvent {
+    /** Entity that was deleted. */
+    deletedEntity?: string | null;
+}
+interface ActionEvent {
+    body?: string;
+}
+interface MessageEnvelope {
+    /**
+     * App instance ID.
+     * @format GUID
+     */
+    instanceId?: string | null;
+    /**
+     * Event type.
+     * @maxLength 150
+     */
+    eventType?: string;
+    /** The identification type and identity data. */
+    identity?: IdentificationData;
+    /** Stringify payload. */
+    data?: string;
+    /** Details related to the account */
+    accountInfo?: AccountInfo;
+}
+interface IdentificationData extends IdentificationDataIdOneOf {
+    /**
+     * ID of a site visitor that has not logged in to the site.
+     * @format GUID
+     */
+    anonymousVisitorId?: string;
+    /**
+     * ID of a site visitor that has logged in to the site.
+     * @format GUID
+     */
+    memberId?: string;
+    /**
+     * ID of a Wix user (site owner, contributor, etc.).
+     * @format GUID
+     */
+    wixUserId?: string;
+    /**
+     * ID of an app.
+     * @format GUID
+     */
+    appId?: string;
+    /** @readonly */
+    identityType?: WebhookIdentityTypeWithLiterals;
+}
+/** @oneof */
+interface IdentificationDataIdOneOf {
+    /**
+     * ID of a site visitor that has not logged in to the site.
+     * @format GUID
+     */
+    anonymousVisitorId?: string;
+    /**
+     * ID of a site visitor that has logged in to the site.
+     * @format GUID
+     */
+    memberId?: string;
+    /**
+     * ID of a Wix user (site owner, contributor, etc.).
+     * @format GUID
+     */
+    wixUserId?: string;
+    /**
+     * ID of an app.
+     * @format GUID
+     */
+    appId?: string;
+}
+declare enum WebhookIdentityType {
+    UNKNOWN = "UNKNOWN",
+    ANONYMOUS_VISITOR = "ANONYMOUS_VISITOR",
+    MEMBER = "MEMBER",
+    WIX_USER = "WIX_USER",
+    APP = "APP"
+}
+/** @enumType */
+type WebhookIdentityTypeWithLiterals = WebhookIdentityType | 'UNKNOWN' | 'ANONYMOUS_VISITOR' | 'MEMBER' | 'WIX_USER' | 'APP';
+interface AccountInfo {
+    /**
+     * ID of the Wix account associated with the event.
+     * @format GUID
+     */
+    accountId?: string | null;
+    /**
+     * ID of the parent Wix account. Only included when accountId belongs to a child account.
+     * @format GUID
+     */
+    parentAccountId?: string | null;
+    /**
+     * ID of the Wix site associated with the event. Only included when the event is tied to a specific site.
+     * @format GUID
+     */
+    siteId?: string | null;
+}
+/**
+ * Retrieves a content plan flow.
+ *
+ * While a flow is generating, poll this method with the
+ * `contentPlanFlowId` returned by Trigger Content Plan Generation Flow to
+ * follow the flow's progress.
+ *
+ * Omit `contentPlanFlowId` to retrieve the site's most recent successful
+ * flow. This is useful for picking up a content plan that was generated in
+ * the site dashboard. A flow that's still running is never returned this
+ * way, and a site with no successful flow returns a not found error.
+ * @param contentPlanFlowId - ID of the content plan flow to retrieve.
+ *
+ * Omit to retrieve the site's most recent successful flow.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField contentPlanFlowId
+ * @permissionId promote:seo:v1:content_plan_content_plan_flow:get_content_plan_flow
+ * @applicableIdentity APP
+ * @fqn wix.promote.seo.content.plan.v1.ContentPlanFlowServiceV1.GetContentPlanFlow
+ */
+declare function getContentPlanFlow(contentPlanFlowId: string): Promise<NonNullablePaths<GetContentPlanFlowResponse, `contentPlanFlow.status`, 3>>;
+/**
+ * Creates and starts a content plan flow for a site.
+ *
+ * Generation runs asynchronously and takes several minutes. This method
+ * returns a `contentPlanFlowId` as soon as the flow is created, before any
+ * content is generated. Poll Get Content Plan Flow with that ID to follow
+ * the flow's progress.
+ *
+ * A successful response means the flow was created, not that generation
+ * succeeded. Check `status` rather than relying on the response alone.
+ *
+ * The flow stops at `KEYWORD_RESEARCH` and waits. Call Create Content Plan
+ * to generate the blog post briefs and let the flow continue to `SUCCESS`.
+ *
+ * A failed flow is retried automatically, and each retry creates a separate
+ * flow with its own ID. The original flow keeps its `FAIL` status, so call
+ * Get Content Plan Flow without an ID to retrieve the site's most recent
+ * successful flow.
+ * @public
+ * @documentationMaturity preview
+ * @permissionId promote:seo:v1:content_plan_content_plan_flow:trigger_content_plan_generation_flow
+ * @applicableIdentity APP
+ * @fqn wix.promote.seo.content.plan.v1.ContentPlanFlowServiceV1.TriggerContentPlanGenerationFlow
+ */
+declare function triggerContentPlanGenerationFlow(): Promise<TriggerContentPlanGenerationFlowResponse>;
+/**
+ * Cancels a content plan flow.
+ *
+ * Cancellation is permanent. A canceled flow can't be resumed or restarted,
+ * and the keyword research linked to it is canceled with it. To generate a
+ * content plan afterwards, call Trigger Content Plan Generation Flow to
+ * start a flow.
+ *
+ * Calling this method on a flow that's already canceled succeeds and
+ * changes nothing.
+ * @param contentPlanFlowId - ID of the content plan flow to cancel.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField contentPlanFlowId
+ * @permissionId promote:seo:v1:content_plan_content_plan_flow:cancel_content_plan_flow
+ * @applicableIdentity APP
+ * @fqn wix.promote.seo.content.plan.v1.ContentPlanFlowServiceV1.CancelContentPlanFlow
+ */
+declare function cancelContentPlanFlow(contentPlanFlowId: string): Promise<void>;
+
+export { type AccountInfo, type ActionCta, type ActionEvent, type ActionPayload, type BlogData, type CancelContentPlanFlowRequest, type CancelContentPlanFlowResponse, type Change, type ContentPlanFlow, type DisplayMessage, type DomainEvent, type DomainEventBodyOneOf, type Entity, type EntityCreatedEvent, type EntityDeletedEvent, type EntityUpdatedEvent, type ExecuteActionRequest, type ExecuteActionResponse, type GetContentPlanFlowRequest, type GetContentPlanFlowResponse, type IdentificationData, type IdentificationDataIdOneOf, type Item, type ItemData, type ItemDataPayloadDataOneOf, type MessageEnvelope, type RestoreInfo, Status, type StatusWithLiterals, type TriggerContentPlanGenerationFlowRequest, type TriggerContentPlanGenerationFlowResponse, WebhookIdentityType, type WebhookIdentityTypeWithLiterals, cancelContentPlanFlow, getContentPlanFlow, triggerContentPlanGenerationFlow };