@guidelytech/shared 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -1523,6 +1523,8 @@ type GuideConfig = z.infer<typeof GuideConfigSchema>;
 type GuideConfigInput = z.input<typeof GuideConfigSchema>;
 declare function defaultGuideConfig(kind: GuideKind): GuideConfig;
 declare function defaultStep(type: StepType, overrides?: Partial<GuideStepInput>): GuideStep;
+/** Buttons to show for a step; "back" buttons are hidden when there is no previous step to return to. */
+declare function visibleButtons(step: GuideStep, canGoBack: boolean): GuideStep["buttons"];
 /** Validation beyond Zod shape: returns human-readable problems that block publishing. */
 interface ValidationIssue {
     level: "error" | "warning";
@@ -1565,13 +1567,13 @@ declare const ProjectThemeSchema: z.ZodObject<{
     brandName?: string | undefined;
 }>;
 
-declare const EVENT_NAMES: readonly ["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "custom", "page_view", "identify"];
+declare const EVENT_NAMES: readonly ["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "messenger_opened", "conversation_started", "conversation_handed_off", "scout_answered", "custom", "page_view", "identify"];
 type EventName = (typeof EVENT_NAMES)[number];
 declare const GUIDE_LIFECYCLE_EVENTS: readonly ["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned"];
 /** Event as produced by the SDK and accepted by POST /api/v1/sdk/events */
 declare const SdkEventSchema: z.ZodObject<{
     eventId: z.ZodString;
-    name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "custom", "page_view", "identify"]>;
+    name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "messenger_opened", "conversation_started", "conversation_handed_off", "scout_answered", "custom", "page_view", "identify"]>;
     /** For `custom` events: the application-defined name. */
     customName: z.ZodOptional<z.ZodString>;
     occurredAt: z.ZodString;
@@ -1587,7 +1589,7 @@ declare const SdkEventSchema: z.ZodObject<{
     properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     eventId: string;
-    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
     occurredAt: string;
     anonymousId: string;
     url?: string | undefined;
@@ -1602,7 +1604,7 @@ declare const SdkEventSchema: z.ZodObject<{
     properties?: Record<string, unknown> | undefined;
 }, {
     eventId: string;
-    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
     occurredAt: string;
     anonymousId: string;
     url?: string | undefined;
@@ -1620,7 +1622,7 @@ type SdkEvent = z.infer<typeof SdkEventSchema>;
 declare const EventBatchSchema: z.ZodObject<{
     events: z.ZodArray<z.ZodObject<{
         eventId: z.ZodString;
-        name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "custom", "page_view", "identify"]>;
+        name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "messenger_opened", "conversation_started", "conversation_handed_off", "scout_answered", "custom", "page_view", "identify"]>;
         /** For `custom` events: the application-defined name. */
         customName: z.ZodOptional<z.ZodString>;
         occurredAt: z.ZodString;
@@ -1636,7 +1638,7 @@ declare const EventBatchSchema: z.ZodObject<{
         properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1651,7 +1653,7 @@ declare const EventBatchSchema: z.ZodObject<{
         properties?: Record<string, unknown> | undefined;
     }, {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1679,7 +1681,7 @@ declare const EventBatchSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     events: {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1701,7 +1703,7 @@ declare const EventBatchSchema: z.ZodObject<{
 }, {
     events: {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1723,6 +1725,156 @@ declare const EventBatchSchema: z.ZodObject<{
 }>;
 type EventBatch = z.infer<typeof EventBatchSchema>;
 
+/** Messenger settings delivered to the SDK in `SdkConfigResponse.messenger`. */
+interface MessengerConfig {
+    enabled: boolean;
+    /** Display name of the AI agent ("Scout"). */
+    name: string;
+    greeting: string;
+    /** Scout answers with AI; when false every conversation goes to the team inbox. */
+    aiAvailable: boolean;
+    handoffEnabled: boolean;
+    launcher: {
+        position: "bottom-right" | "bottom-left";
+    };
+}
+declare const MESSAGE_AUTHORS: readonly ["user", "scout", "agent", "system"];
+type MessageAuthor = (typeof MESSAGE_AUTHORS)[number];
+type ConversationStatus = "bot" | "open" | "closed";
+interface MessengerCitation {
+    articleId: string;
+    title: string;
+}
+interface MessengerSuggestedGuide {
+    key: string;
+    name: string;
+}
+interface MessengerMessage {
+    id: string;
+    author: MessageAuthor;
+    /** Team member name for `agent` messages. */
+    authorName?: string | null;
+    body: string;
+    citations: MessengerCitation[];
+    suggestedGuides: MessengerSuggestedGuide[];
+    status: "pending" | "complete" | "failed";
+    createdAt: string;
+}
+interface MessengerConversation {
+    id: string;
+    status: ConversationStatus;
+    subject: string;
+    lastMessageAt: string;
+    lastMessagePreview: string;
+    unread: number;
+    rating: number | null;
+}
+declare const MAX_MESSAGE_LENGTH = 4000;
+declare const StartConversationSchema: z.ZodObject<{
+    anonymousId: z.ZodString;
+    userId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    message: z.ZodString;
+    pageUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    anonymousId: string;
+    userId?: string | null | undefined;
+    pageUrl?: string | undefined;
+}, {
+    message: string;
+    anonymousId: string;
+    userId?: string | null | undefined;
+    pageUrl?: string | undefined;
+}>;
+type StartConversationRequest = z.infer<typeof StartConversationSchema>;
+interface StartConversationResponse {
+    conversation: MessengerConversation;
+    /** Secret that authorises this browser to read and post in the conversation. Store it; it is not shown again. */
+    token: string;
+    messages: MessengerMessage[];
+}
+declare const ConversationLookupSchema: z.ZodObject<{
+    tokens: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    tokens: string[];
+}, {
+    tokens: string[];
+}>;
+interface ConversationLookupResponse {
+    conversations: Array<MessengerConversation & {
+        token: string;
+    }>;
+}
+declare const PostMessageSchema: z.ZodObject<{
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+}, {
+    message: string;
+}>;
+declare const ConversationRatingSchema: z.ZodObject<{
+    rating: z.ZodNumber;
+    comment: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    rating: number;
+    comment?: string | undefined;
+}, {
+    rating: number;
+    comment?: string | undefined;
+}>;
+interface ConversationMessagesResponse {
+    conversation: MessengerConversation;
+    messages: MessengerMessage[];
+}
+/**
+ * Server-sent events streamed by `POST /sdk/conversations` and `POST /sdk/conversations/:id/messages`
+ * while Scout replies. `conversation` (start only) carries the new conversation and its token, `message`
+ * each stored message, `delta` reply text as it is generated, and `done` the final stored message.
+ */
+type ScoutStreamEvent = {
+    event: "conversation";
+    data: StartConversationResponse;
+} | {
+    event: "message";
+    data: MessengerMessage;
+} | {
+    event: "delta";
+    data: {
+        messageId: string;
+        text: string;
+    };
+} | {
+    event: "done";
+    data: {
+        message: MessengerMessage;
+        conversation: MessengerConversation;
+    };
+} | {
+    event: "error";
+    data: {
+        message: string;
+    };
+};
+/** Article list entry for the messenger Help tab (bodies are fetched on demand). */
+interface SdkArticleSummary {
+    id: string;
+    slug: string;
+    title: string;
+    summary: string;
+    collectionId: string | null;
+    externalUrl: string | null;
+    updatedAt: string;
+}
+interface SdkArticlesResponse {
+    collections: Array<{
+        id: string;
+        name: string;
+        description: string;
+        order: number;
+    }>;
+    articles: SdkArticleSummary[];
+}
+
 /** A published guide as delivered to the SDK. Draft-only data (author, notes) is never included. */
 interface PublishedGuide {
     id: string;
@@ -1739,6 +1891,8 @@ interface ResourceCenterArticle {
     title: string;
     summary: string;
     body: string;
+    /** True when `body` was left out of the config to keep it small; fetch it from `GET /sdk/articles/:id`. */
+    bodyOmitted?: boolean;
     collectionId?: string | null;
     externalUrl?: string | null;
     updatedAt: string;
@@ -1778,6 +1932,8 @@ interface SdkConfigResponse {
     theme: z.infer<typeof ProjectThemeSchema>;
     guides: PublishedGuide[];
     resourceCenter: ResourceCenterConfig | null;
+    /** Scout messenger; absent from servers that predate it. */
+    messenger?: MessengerConfig | null;
     settings: {
         analyticsEnabled: boolean;
         collectUrls: boolean;
@@ -1991,6 +2147,20 @@ declare const AuthoringPickSchema: z.ZodObject<{
     } | undefined;
 }>;
 type AuthoringPick = z.infer<typeof AuthoringPickSchema>;
+/**
+ * Static, script-free copy of the page an authoring session is connected to. The SDK posts it to
+ * the dashboard (never to the API) so the editor canvas can show the customer's real app.
+ */
+interface AppSnapshot {
+    /** Full HTML document (doctype included) with scripts and Guidely UI removed and a `<base>` pointing at `url`. */
+    html: string;
+    url: string;
+    title: string;
+    /** Viewport the snapshot was taken at, in CSS pixels. */
+    width: number;
+    height: number;
+    capturedAt: string;
+}
 interface AuthoringSessionInfo {
     id: string;
     projectId: string;
@@ -3181,6 +3351,6 @@ declare function templateConfig(id: string): {
 } | null;
 
 declare const SDK_API_VERSION = "v1";
-declare const SHARED_VERSION = "0.1.0";
+declare const SHARED_VERSION = "0.2.1";
 
-export { ADVANCE_ON, type ApiError, type Appearance, AppearanceSchema, type AuthoringPick, AuthoringPickSchema, type AuthoringSessionInfo, BUTTON_ACTIONS, ButtonSchema, type ChecklistConfig, ChecklistConfigSchema, type ChecklistProgressRequest, ChecklistProgressRequestSchema, type ChecklistTask, ChecklistTaskSchema, EVENT_NAMES, type EventBatch, EventBatchSchema, type EventName, type FrequencyConfig, FrequencySchema, GUIDE_KINDS, GUIDE_LIFECYCLE_EVENTS, GUIDE_STATUSES, GUIDE_TEMPLATES, type GuideConfig, type GuideConfigInput, GuideConfigSchema, type GuideKind, GuideStateUpdateSchema, type GuideStatus, type GuideStep, type GuideStepInput, type GuideTemplate, type IdentifyRequest, IdentifyRequestSchema, type IdentifyResponse, PLACEMENTS, type Placement, type ProjectTheme, ProjectThemeSchema, type PublishedGuide, PublishedGuideSchema, type ResourceCenterArticle, type ResourceCenterConfig, Rule, RuleGroup, RuleGroupSchema, RuleSchema, SDK_API_VERSION, SELECTOR_KINDS, SHARED_VERSION, STEP_TYPES, SURVEY_QUESTION_TYPES, type SdkConfigResponse, type SdkEvent, SdkEventSchema, type SelectorStrategy, SelectorStrategySchema, StepBranchSchema, type StepButton, StepSchema, type StepTarget, type StepType, type SurveyConfig, SurveyConfigSchema, type SurveyQuestion, SurveyQuestionSchema, type SurveyResponseRequest, SurveyResponseRequestSchema, TRIGGER_TYPES, TargetSchema, type TriggerConfig, TriggerSchema, type ValidationIssue, defaultGuideConfig, defaultStep, templateConfig, validateGuideConfig };
+export { ADVANCE_ON, type ApiError, type AppSnapshot, type Appearance, AppearanceSchema, type AuthoringPick, AuthoringPickSchema, type AuthoringSessionInfo, BUTTON_ACTIONS, ButtonSchema, type ChecklistConfig, ChecklistConfigSchema, type ChecklistProgressRequest, ChecklistProgressRequestSchema, type ChecklistTask, ChecklistTaskSchema, type ConversationLookupResponse, ConversationLookupSchema, type ConversationMessagesResponse, ConversationRatingSchema, type ConversationStatus, EVENT_NAMES, type EventBatch, EventBatchSchema, type EventName, type FrequencyConfig, FrequencySchema, GUIDE_KINDS, GUIDE_LIFECYCLE_EVENTS, GUIDE_STATUSES, GUIDE_TEMPLATES, type GuideConfig, type GuideConfigInput, GuideConfigSchema, type GuideKind, GuideStateUpdateSchema, type GuideStatus, type GuideStep, type GuideStepInput, type GuideTemplate, type IdentifyRequest, IdentifyRequestSchema, type IdentifyResponse, MAX_MESSAGE_LENGTH, MESSAGE_AUTHORS, type MessageAuthor, type MessengerCitation, type MessengerConfig, type MessengerConversation, type MessengerMessage, type MessengerSuggestedGuide, PLACEMENTS, type Placement, PostMessageSchema, type ProjectTheme, ProjectThemeSchema, type PublishedGuide, PublishedGuideSchema, type ResourceCenterArticle, type ResourceCenterConfig, Rule, RuleGroup, RuleGroupSchema, RuleSchema, SDK_API_VERSION, SELECTOR_KINDS, SHARED_VERSION, STEP_TYPES, SURVEY_QUESTION_TYPES, type ScoutStreamEvent, type SdkArticleSummary, type SdkArticlesResponse, type SdkConfigResponse, type SdkEvent, SdkEventSchema, type SelectorStrategy, SelectorStrategySchema, type StartConversationRequest, type StartConversationResponse, StartConversationSchema, StepBranchSchema, type StepButton, StepSchema, type StepTarget, type StepType, type SurveyConfig, SurveyConfigSchema, type SurveyQuestion, SurveyQuestionSchema, type SurveyResponseRequest, SurveyResponseRequestSchema, TRIGGER_TYPES, TargetSchema, type TriggerConfig, TriggerSchema, type ValidationIssue, defaultGuideConfig, defaultStep, templateConfig, validateGuideConfig, visibleButtons };

package/dist/index.d.ts

@@ -1523,6 +1523,8 @@ type GuideConfig = z.infer<typeof GuideConfigSchema>;
 type GuideConfigInput = z.input<typeof GuideConfigSchema>;
 declare function defaultGuideConfig(kind: GuideKind): GuideConfig;
 declare function defaultStep(type: StepType, overrides?: Partial<GuideStepInput>): GuideStep;
+/** Buttons to show for a step; "back" buttons are hidden when there is no previous step to return to. */
+declare function visibleButtons(step: GuideStep, canGoBack: boolean): GuideStep["buttons"];
 /** Validation beyond Zod shape: returns human-readable problems that block publishing. */
 interface ValidationIssue {
     level: "error" | "warning";
@@ -1565,13 +1567,13 @@ declare const ProjectThemeSchema: z.ZodObject<{
     brandName?: string | undefined;
 }>;
 
-declare const EVENT_NAMES: readonly ["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "custom", "page_view", "identify"];
+declare const EVENT_NAMES: readonly ["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "messenger_opened", "conversation_started", "conversation_handed_off", "scout_answered", "custom", "page_view", "identify"];
 type EventName = (typeof EVENT_NAMES)[number];
 declare const GUIDE_LIFECYCLE_EVENTS: readonly ["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned"];
 /** Event as produced by the SDK and accepted by POST /api/v1/sdk/events */
 declare const SdkEventSchema: z.ZodObject<{
     eventId: z.ZodString;
-    name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "custom", "page_view", "identify"]>;
+    name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "messenger_opened", "conversation_started", "conversation_handed_off", "scout_answered", "custom", "page_view", "identify"]>;
     /** For `custom` events: the application-defined name. */
     customName: z.ZodOptional<z.ZodString>;
     occurredAt: z.ZodString;
@@ -1587,7 +1589,7 @@ declare const SdkEventSchema: z.ZodObject<{
     properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     eventId: string;
-    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
     occurredAt: string;
     anonymousId: string;
     url?: string | undefined;
@@ -1602,7 +1604,7 @@ declare const SdkEventSchema: z.ZodObject<{
     properties?: Record<string, unknown> | undefined;
 }, {
     eventId: string;
-    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+    name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
     occurredAt: string;
     anonymousId: string;
     url?: string | undefined;
@@ -1620,7 +1622,7 @@ type SdkEvent = z.infer<typeof SdkEventSchema>;
 declare const EventBatchSchema: z.ZodObject<{
     events: z.ZodArray<z.ZodObject<{
         eventId: z.ZodString;
-        name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "custom", "page_view", "identify"]>;
+        name: z.ZodEnum<["guide_viewed", "guide_started", "step_viewed", "step_completed", "guide_completed", "guide_skipped", "guide_dismissed", "guide_abandoned", "checklist_task_completed", "checklist_completed", "checklist_dismissed", "survey_displayed", "survey_submitted", "survey_dismissed", "resource_center_opened", "article_viewed", "messenger_opened", "conversation_started", "conversation_handed_off", "scout_answered", "custom", "page_view", "identify"]>;
         /** For `custom` events: the application-defined name. */
         customName: z.ZodOptional<z.ZodString>;
         occurredAt: z.ZodString;
@@ -1636,7 +1638,7 @@ declare const EventBatchSchema: z.ZodObject<{
         properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1651,7 +1653,7 @@ declare const EventBatchSchema: z.ZodObject<{
         properties?: Record<string, unknown> | undefined;
     }, {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1679,7 +1681,7 @@ declare const EventBatchSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     events: {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1701,7 +1703,7 @@ declare const EventBatchSchema: z.ZodObject<{
 }, {
     events: {
         eventId: string;
-        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "page_view" | "identify";
+        name: "custom" | "guide_completed" | "guide_viewed" | "guide_started" | "step_viewed" | "step_completed" | "guide_skipped" | "guide_dismissed" | "guide_abandoned" | "checklist_task_completed" | "checklist_completed" | "checklist_dismissed" | "survey_displayed" | "survey_submitted" | "survey_dismissed" | "resource_center_opened" | "article_viewed" | "messenger_opened" | "conversation_started" | "conversation_handed_off" | "scout_answered" | "page_view" | "identify";
         occurredAt: string;
         anonymousId: string;
         url?: string | undefined;
@@ -1723,6 +1725,156 @@ declare const EventBatchSchema: z.ZodObject<{
 }>;
 type EventBatch = z.infer<typeof EventBatchSchema>;
 
+/** Messenger settings delivered to the SDK in `SdkConfigResponse.messenger`. */
+interface MessengerConfig {
+    enabled: boolean;
+    /** Display name of the AI agent ("Scout"). */
+    name: string;
+    greeting: string;
+    /** Scout answers with AI; when false every conversation goes to the team inbox. */
+    aiAvailable: boolean;
+    handoffEnabled: boolean;
+    launcher: {
+        position: "bottom-right" | "bottom-left";
+    };
+}
+declare const MESSAGE_AUTHORS: readonly ["user", "scout", "agent", "system"];
+type MessageAuthor = (typeof MESSAGE_AUTHORS)[number];
+type ConversationStatus = "bot" | "open" | "closed";
+interface MessengerCitation {
+    articleId: string;
+    title: string;
+}
+interface MessengerSuggestedGuide {
+    key: string;
+    name: string;
+}
+interface MessengerMessage {
+    id: string;
+    author: MessageAuthor;
+    /** Team member name for `agent` messages. */
+    authorName?: string | null;
+    body: string;
+    citations: MessengerCitation[];
+    suggestedGuides: MessengerSuggestedGuide[];
+    status: "pending" | "complete" | "failed";
+    createdAt: string;
+}
+interface MessengerConversation {
+    id: string;
+    status: ConversationStatus;
+    subject: string;
+    lastMessageAt: string;
+    lastMessagePreview: string;
+    unread: number;
+    rating: number | null;
+}
+declare const MAX_MESSAGE_LENGTH = 4000;
+declare const StartConversationSchema: z.ZodObject<{
+    anonymousId: z.ZodString;
+    userId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    message: z.ZodString;
+    pageUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    anonymousId: string;
+    userId?: string | null | undefined;
+    pageUrl?: string | undefined;
+}, {
+    message: string;
+    anonymousId: string;
+    userId?: string | null | undefined;
+    pageUrl?: string | undefined;
+}>;
+type StartConversationRequest = z.infer<typeof StartConversationSchema>;
+interface StartConversationResponse {
+    conversation: MessengerConversation;
+    /** Secret that authorises this browser to read and post in the conversation. Store it; it is not shown again. */
+    token: string;
+    messages: MessengerMessage[];
+}
+declare const ConversationLookupSchema: z.ZodObject<{
+    tokens: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    tokens: string[];
+}, {
+    tokens: string[];
+}>;
+interface ConversationLookupResponse {
+    conversations: Array<MessengerConversation & {
+        token: string;
+    }>;
+}
+declare const PostMessageSchema: z.ZodObject<{
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+}, {
+    message: string;
+}>;
+declare const ConversationRatingSchema: z.ZodObject<{
+    rating: z.ZodNumber;
+    comment: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    rating: number;
+    comment?: string | undefined;
+}, {
+    rating: number;
+    comment?: string | undefined;
+}>;
+interface ConversationMessagesResponse {
+    conversation: MessengerConversation;
+    messages: MessengerMessage[];
+}
+/**
+ * Server-sent events streamed by `POST /sdk/conversations` and `POST /sdk/conversations/:id/messages`
+ * while Scout replies. `conversation` (start only) carries the new conversation and its token, `message`
+ * each stored message, `delta` reply text as it is generated, and `done` the final stored message.
+ */
+type ScoutStreamEvent = {
+    event: "conversation";
+    data: StartConversationResponse;
+} | {
+    event: "message";
+    data: MessengerMessage;
+} | {
+    event: "delta";
+    data: {
+        messageId: string;
+        text: string;
+    };
+} | {
+    event: "done";
+    data: {
+        message: MessengerMessage;
+        conversation: MessengerConversation;
+    };
+} | {
+    event: "error";
+    data: {
+        message: string;
+    };
+};
+/** Article list entry for the messenger Help tab (bodies are fetched on demand). */
+interface SdkArticleSummary {
+    id: string;
+    slug: string;
+    title: string;
+    summary: string;
+    collectionId: string | null;
+    externalUrl: string | null;
+    updatedAt: string;
+}
+interface SdkArticlesResponse {
+    collections: Array<{
+        id: string;
+        name: string;
+        description: string;
+        order: number;
+    }>;
+    articles: SdkArticleSummary[];
+}
+
 /** A published guide as delivered to the SDK. Draft-only data (author, notes) is never included. */
 interface PublishedGuide {
     id: string;
@@ -1739,6 +1891,8 @@ interface ResourceCenterArticle {
     title: string;
     summary: string;
     body: string;
+    /** True when `body` was left out of the config to keep it small; fetch it from `GET /sdk/articles/:id`. */
+    bodyOmitted?: boolean;
     collectionId?: string | null;
     externalUrl?: string | null;
     updatedAt: string;
@@ -1778,6 +1932,8 @@ interface SdkConfigResponse {
     theme: z.infer<typeof ProjectThemeSchema>;
     guides: PublishedGuide[];
     resourceCenter: ResourceCenterConfig | null;
+    /** Scout messenger; absent from servers that predate it. */
+    messenger?: MessengerConfig | null;
     settings: {
         analyticsEnabled: boolean;
         collectUrls: boolean;
@@ -1991,6 +2147,20 @@ declare const AuthoringPickSchema: z.ZodObject<{
     } | undefined;
 }>;
 type AuthoringPick = z.infer<typeof AuthoringPickSchema>;
+/**
+ * Static, script-free copy of the page an authoring session is connected to. The SDK posts it to
+ * the dashboard (never to the API) so the editor canvas can show the customer's real app.
+ */
+interface AppSnapshot {
+    /** Full HTML document (doctype included) with scripts and Guidely UI removed and a `<base>` pointing at `url`. */
+    html: string;
+    url: string;
+    title: string;
+    /** Viewport the snapshot was taken at, in CSS pixels. */
+    width: number;
+    height: number;
+    capturedAt: string;
+}
 interface AuthoringSessionInfo {
     id: string;
     projectId: string;
@@ -3181,6 +3351,6 @@ declare function templateConfig(id: string): {
 } | null;
 
 declare const SDK_API_VERSION = "v1";
-declare const SHARED_VERSION = "0.1.0";
+declare const SHARED_VERSION = "0.2.1";
 
-export { ADVANCE_ON, type ApiError, type Appearance, AppearanceSchema, type AuthoringPick, AuthoringPickSchema, type AuthoringSessionInfo, BUTTON_ACTIONS, ButtonSchema, type ChecklistConfig, ChecklistConfigSchema, type ChecklistProgressRequest, ChecklistProgressRequestSchema, type ChecklistTask, ChecklistTaskSchema, EVENT_NAMES, type EventBatch, EventBatchSchema, type EventName, type FrequencyConfig, FrequencySchema, GUIDE_KINDS, GUIDE_LIFECYCLE_EVENTS, GUIDE_STATUSES, GUIDE_TEMPLATES, type GuideConfig, type GuideConfigInput, GuideConfigSchema, type GuideKind, GuideStateUpdateSchema, type GuideStatus, type GuideStep, type GuideStepInput, type GuideTemplate, type IdentifyRequest, IdentifyRequestSchema, type IdentifyResponse, PLACEMENTS, type Placement, type ProjectTheme, ProjectThemeSchema, type PublishedGuide, PublishedGuideSchema, type ResourceCenterArticle, type ResourceCenterConfig, Rule, RuleGroup, RuleGroupSchema, RuleSchema, SDK_API_VERSION, SELECTOR_KINDS, SHARED_VERSION, STEP_TYPES, SURVEY_QUESTION_TYPES, type SdkConfigResponse, type SdkEvent, SdkEventSchema, type SelectorStrategy, SelectorStrategySchema, StepBranchSchema, type StepButton, StepSchema, type StepTarget, type StepType, type SurveyConfig, SurveyConfigSchema, type SurveyQuestion, SurveyQuestionSchema, type SurveyResponseRequest, SurveyResponseRequestSchema, TRIGGER_TYPES, TargetSchema, type TriggerConfig, TriggerSchema, type ValidationIssue, defaultGuideConfig, defaultStep, templateConfig, validateGuideConfig };
+export { ADVANCE_ON, type ApiError, type AppSnapshot, type Appearance, AppearanceSchema, type AuthoringPick, AuthoringPickSchema, type AuthoringSessionInfo, BUTTON_ACTIONS, ButtonSchema, type ChecklistConfig, ChecklistConfigSchema, type ChecklistProgressRequest, ChecklistProgressRequestSchema, type ChecklistTask, ChecklistTaskSchema, type ConversationLookupResponse, ConversationLookupSchema, type ConversationMessagesResponse, ConversationRatingSchema, type ConversationStatus, EVENT_NAMES, type EventBatch, EventBatchSchema, type EventName, type FrequencyConfig, FrequencySchema, GUIDE_KINDS, GUIDE_LIFECYCLE_EVENTS, GUIDE_STATUSES, GUIDE_TEMPLATES, type GuideConfig, type GuideConfigInput, GuideConfigSchema, type GuideKind, GuideStateUpdateSchema, type GuideStatus, type GuideStep, type GuideStepInput, type GuideTemplate, type IdentifyRequest, IdentifyRequestSchema, type IdentifyResponse, MAX_MESSAGE_LENGTH, MESSAGE_AUTHORS, type MessageAuthor, type MessengerCitation, type MessengerConfig, type MessengerConversation, type MessengerMessage, type MessengerSuggestedGuide, PLACEMENTS, type Placement, PostMessageSchema, type ProjectTheme, ProjectThemeSchema, type PublishedGuide, PublishedGuideSchema, type ResourceCenterArticle, type ResourceCenterConfig, Rule, RuleGroup, RuleGroupSchema, RuleSchema, SDK_API_VERSION, SELECTOR_KINDS, SHARED_VERSION, STEP_TYPES, SURVEY_QUESTION_TYPES, type ScoutStreamEvent, type SdkArticleSummary, type SdkArticlesResponse, type SdkConfigResponse, type SdkEvent, SdkEventSchema, type SelectorStrategy, SelectorStrategySchema, type StartConversationRequest, type StartConversationResponse, StartConversationSchema, StepBranchSchema, type StepButton, StepSchema, type StepTarget, type StepType, type SurveyConfig, SurveyConfigSchema, type SurveyQuestion, SurveyQuestionSchema, type SurveyResponseRequest, SurveyResponseRequestSchema, TRIGGER_TYPES, TargetSchema, type TriggerConfig, TriggerSchema, type ValidationIssue, defaultGuideConfig, defaultStep, templateConfig, validateGuideConfig, visibleButtons };