@guidelytech/sdk-core 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -1,19 +1,19 @@
 import * as _guidelytech_guide_runtime from '@guidelytech/guide-runtime';
 import { TargetingContext, PublishedGuide, ProjectTheme, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
-export { AgentEventsResponse, AgentOutcome, AgentToolCallInput, AgentTurnInput, AgentTurnRole, AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
+export { AgentEventsResponse, AgentOutcome, AgentToolCallInput, AgentTurnInput, AgentTurnRole, AppSnapshot, AutocaptureSettings, BugReportInput, BugReportResponse, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
 import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
 export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { AgentTurnInput } from '@guidelytech/shared/runtime';
-export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
-import { m as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, n as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-Bkw8ErmO.cjs';
-export { A as AgentTurnRedactor, E as EventQueue, b as EventQueueOptions, o as GuideStepInfo, d as GuidelyEnvironment, q as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, g as countsTowardThrottle, i as isExclusiveGuide, j as isFrequencyEligible, k as isThrottleEligible, l as isWithinSchedule, p as pruneLaunches } from './types-Bkw8ErmO.cjs';
+import { AgentTurnInput, ErrorLevelName, Breadcrumb, BugReportInput, BugReportResponse } from '@guidelytech/shared/runtime';
+export { Breadcrumb, CAPTURE_PARAM, ErrorFilterPattern, ErrorLevelName, ExceptionDetail } from '@guidelytech/shared/runtime';
+import { n as GuidelyOptions, d as GuidelyEnvironment, c as GuidelyAccount, a as ConsentState, o as CaptureContext, C as ChecklistProgressState, q as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './environment-D63OzdWf.cjs';
+export { A as AgentTurnRedactor, B as BreadcrumbHint, r as ErrorEvent, s as ErrorMonitoringOptions, E as EventQueue, b as EventQueueOptions, t as GuideStepInfo, u as GuidelyEventName, P as PersistedState, T as TraceSpan, v as TracingOptions, w as TransactionEvent, f as areMutuallyExclusive, g as countsTowardThrottle, i as environmentFromKey, j as isExclusiveGuide, k as isFrequencyEligible, l as isThrottleEligible, m as isWithinSchedule, p as pruneLaunches } from './environment-D63OzdWf.cjs';
 export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-DjZ2gwYa.cjs';
 export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-4EgpjK6Z.cjs';
 import './http-zOI8d2c2.cjs';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.15.0";
+declare const SDK_VERSION = "0.17.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -31,6 +31,8 @@ declare class GuidelyClient {
     /** Agent Analytics turns (agentConversation), in their own outbox. */
     private readonly agentTurns;
     private config;
+    /** The `environment` option as passed (the resolved one is in `options.environment`). */
+    private readonly envOption;
     private etag;
     private anonymousId;
     private user;
@@ -71,6 +73,11 @@ declare class GuidelyClient {
     private readonly exceptionThrottle;
     /** Exceptions seen before the config was loaded (reported once it is known whether the server accepts them). */
     private earlyExceptions;
+    /** The last exception this page reported, which bug reports link to by default. */
+    private lastExceptionId;
+    private bugReportDialog;
+    /** Tags, extra, contexts and breadcrumbs sent with every error (`setTag`, `addBreadcrumb`…). */
+    private readonly errorScope;
     private initialPageViewSent;
     private pageViewUrl;
     private pageLeft;
@@ -82,6 +89,8 @@ declare class GuidelyClient {
     private locale;
     /** Language each shown guide was rendered in; added to its events as `locale`. */
     private guideLocales;
+    /** Performance tracing (`tracing` option + the project's `performance` setting); see tracing.ts. */
+    private readonly tracer;
     constructor(options: GuidelyOptions);
     private createFlags;
     /** Loads config (cache first, then network), wires listeners and evaluates triggers. Idempotent. */
@@ -89,10 +98,15 @@ declare class GuidelyClient {
     /** Resolves once the client is ready (alias of `init()`). */
     ready(): Promise<void>;
     private bootstrap;
+    /** Environment guides and flags target: the `environment` option, else the one the loaded config names, else a guess from the key. */
+    get environment(): GuidelyEnvironment;
+    private useConfig;
     private fetchConfig;
     private wireListeners;
     /** Uncaught errors + unhandled rejections; attached before the config loads so boot errors are kept. */
     private wireErrorListeners;
+    /** An automatic breadcrumb, unless the `errors.breadcrumbs` option turns its kind off. */
+    private autoBreadcrumb;
     /** Re-fetches the published config and re-evaluates triggers. */
     refresh(): Promise<void>;
     /** Re-renders after a config change (refresh, or a config that arrived after start). */
@@ -112,6 +126,8 @@ declare class GuidelyClient {
     /** Updates consent at runtime (`granted` flushes buffered events; `denied` drops them). */
     setConsent(consent: ConsentState): void;
     private analyticsEnabled;
+    /** The host app's version (`appVersion` option), sent with every event and recording. */
+    private appVersion;
     private collectUrls;
     private enqueue;
     /** Tracks a custom event. Events drive `event` triggers, `advanceOn: "event"` steps and checklist tasks. */
@@ -154,10 +170,37 @@ declare class GuidelyClient {
     private captureGlobalException;
     /**
      * Reports a caught error as an `exception` event (`source: "manual"`, `handled: true`), grouped
-     * into an issue on the Errors page. Extra properties are attached to the occurrence. Needs the
-     * project's error tracking on (plus analytics + consent); `captureErrors: false` does not stop it.
+     * into an issue on the Errors page. The second argument takes Sentry's capture context (`tags`,
+     * `extra`, `level`, `fingerprint`, `contexts`, `user`); any other key is attached to the occurrence
+     * as a property. Needs the project's error tracking on (plus analytics + consent);
+     * `captureErrors: false` does not stop it. Returns the event id (empty when nothing is sent).
      */
-    captureException(error: unknown, properties?: Record<string, unknown>): void;
+    captureException(error: unknown, hint?: CaptureContext & Record<string, unknown>): string;
+    /** Reports a message (default level `info`) as its own issue, grouped by the message. */
+    captureMessage(message: string, level?: ErrorLevelName, hint?: CaptureContext): string;
+    private captureWith;
+    /** The `detail` of an error: scope, breadcrumbs, browser contexts and the `cause` chain. */
+    private errorDetail;
+    /** Adds a breadcrumb (sent with the next errors; the last 100 are kept). */
+    addBreadcrumb(crumb: Breadcrumb): void;
+    /** Tags every later error (searchable on the issue page). */
+    setTag(key: string, value: string | number | boolean | null | undefined): void;
+    setTags(tags: Record<string, string | number | boolean | null | undefined>): void;
+    /** Arbitrary data attached to every later error. */
+    setExtra(key: string, value: unknown): void;
+    setExtras(extras: Record<string, unknown>): void;
+    /** A named context (`setContext("cart", { items: 3 })`) on every later error; null removes it. */
+    setContext(name: string, context: Record<string, unknown> | null): void;
+    /**
+     * Sentry's `setUser`: identifies the user by `id` (like `identify`) and keeps `email` / `username`
+     * on their errors. `null` forgets the user (`reset()`).
+     */
+    setUser(user: {
+        id?: string | number;
+        email?: string;
+        username?: string;
+        [trait: string]: unknown;
+    } | null): void;
     private sendException;
     private maskSelector;
     private maskAllText;
@@ -252,6 +295,11 @@ declare class GuidelyClient {
     getGuides(): ReadonlyArray<PublishedGuide>;
     isGuideCompleted(idOrKey: string): boolean;
     openResourceCenter(): void;
+    /**
+     * Opens one help article: in Scout's Help tab when the messenger is on, otherwise in the resource
+     * center. Help-article links in guides (`#guidely-article:<id>`) call this.
+     */
+    openArticle(articleId: string): void;
     closeResourceCenter(): void;
     /** Opens the Scout messenger (when enabled for the project), optionally on a tab. */
     openMessenger(tab?: MessengerTab): void;
@@ -272,6 +320,19 @@ declare class GuidelyClient {
      * Does nothing when the project hasn't turned on Ideas.
      */
     openIdeas(requestId?: string): void;
+    /**
+     * Sends a bug report to Monitor → User feedback (Sentry's `captureFeedback`). It is linked to the visitor,
+     * this session's recording and, unless `associatedEventId` says otherwise, the last error this page
+     * reported. Resolves with the report's id; rejects when it can't be sent.
+     */
+    captureFeedback(input: BugReportInput, source?: "widget" | "api"): Promise<BugReportResponse>;
+    /** Opens the "Report a bug" dialog (message, name, email, a screenshot), which sends with captureFeedback. */
+    showBugReport(options?: {
+        message?: string;
+        name?: string;
+        email?: string;
+        title?: string;
+    }): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
     /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
@@ -507,4 +568,4 @@ declare const Guidely: {
     version: string;
 };
 
-export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, PROTOTYPE_CLOSE_MESSAGE, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, isAppUrl, matchPrototypeTestUrl, normalizeAppUrl, watchNavigation };
+export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, CaptureContext, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEnvironment, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, PROTOTYPE_CLOSE_MESSAGE, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, isAppUrl, matchPrototypeTestUrl, normalizeAppUrl, watchNavigation };

package/dist/index.d.ts

@@ -1,19 +1,19 @@
 import * as _guidelytech_guide_runtime from '@guidelytech/guide-runtime';
 import { TargetingContext, PublishedGuide, ProjectTheme, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
-export { AgentEventsResponse, AgentOutcome, AgentToolCallInput, AgentTurnInput, AgentTurnRole, AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
+export { AgentEventsResponse, AgentOutcome, AgentToolCallInput, AgentTurnInput, AgentTurnRole, AppSnapshot, AutocaptureSettings, BugReportInput, BugReportResponse, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
 import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
 export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { AgentTurnInput } from '@guidelytech/shared/runtime';
-export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
-import { m as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, n as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-Dy_uPu6S.js';
-export { A as AgentTurnRedactor, E as EventQueue, b as EventQueueOptions, o as GuideStepInfo, d as GuidelyEnvironment, q as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, g as countsTowardThrottle, i as isExclusiveGuide, j as isFrequencyEligible, k as isThrottleEligible, l as isWithinSchedule, p as pruneLaunches } from './types-Dy_uPu6S.js';
+import { AgentTurnInput, ErrorLevelName, Breadcrumb, BugReportInput, BugReportResponse } from '@guidelytech/shared/runtime';
+export { Breadcrumb, CAPTURE_PARAM, ErrorFilterPattern, ErrorLevelName, ExceptionDetail } from '@guidelytech/shared/runtime';
+import { n as GuidelyOptions, d as GuidelyEnvironment, c as GuidelyAccount, a as ConsentState, o as CaptureContext, C as ChecklistProgressState, q as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './environment-DAT4iYvZ.js';
+export { A as AgentTurnRedactor, B as BreadcrumbHint, r as ErrorEvent, s as ErrorMonitoringOptions, E as EventQueue, b as EventQueueOptions, t as GuideStepInfo, u as GuidelyEventName, P as PersistedState, T as TraceSpan, v as TracingOptions, w as TransactionEvent, f as areMutuallyExclusive, g as countsTowardThrottle, i as environmentFromKey, j as isExclusiveGuide, k as isFrequencyEligible, l as isThrottleEligible, m as isWithinSchedule, p as pruneLaunches } from './environment-DAT4iYvZ.js';
 export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-DjZ2gwYa.js';
 export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-C-4R56G0.js';
 import './http-BXys2d-j.js';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.15.0";
+declare const SDK_VERSION = "0.17.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -31,6 +31,8 @@ declare class GuidelyClient {
     /** Agent Analytics turns (agentConversation), in their own outbox. */
     private readonly agentTurns;
     private config;
+    /** The `environment` option as passed (the resolved one is in `options.environment`). */
+    private readonly envOption;
     private etag;
     private anonymousId;
     private user;
@@ -71,6 +73,11 @@ declare class GuidelyClient {
     private readonly exceptionThrottle;
     /** Exceptions seen before the config was loaded (reported once it is known whether the server accepts them). */
     private earlyExceptions;
+    /** The last exception this page reported, which bug reports link to by default. */
+    private lastExceptionId;
+    private bugReportDialog;
+    /** Tags, extra, contexts and breadcrumbs sent with every error (`setTag`, `addBreadcrumb`…). */
+    private readonly errorScope;
     private initialPageViewSent;
     private pageViewUrl;
     private pageLeft;
@@ -82,6 +89,8 @@ declare class GuidelyClient {
     private locale;
     /** Language each shown guide was rendered in; added to its events as `locale`. */
     private guideLocales;
+    /** Performance tracing (`tracing` option + the project's `performance` setting); see tracing.ts. */
+    private readonly tracer;
     constructor(options: GuidelyOptions);
     private createFlags;
     /** Loads config (cache first, then network), wires listeners and evaluates triggers. Idempotent. */
@@ -89,10 +98,15 @@ declare class GuidelyClient {
     /** Resolves once the client is ready (alias of `init()`). */
     ready(): Promise<void>;
     private bootstrap;
+    /** Environment guides and flags target: the `environment` option, else the one the loaded config names, else a guess from the key. */
+    get environment(): GuidelyEnvironment;
+    private useConfig;
     private fetchConfig;
     private wireListeners;
     /** Uncaught errors + unhandled rejections; attached before the config loads so boot errors are kept. */
     private wireErrorListeners;
+    /** An automatic breadcrumb, unless the `errors.breadcrumbs` option turns its kind off. */
+    private autoBreadcrumb;
     /** Re-fetches the published config and re-evaluates triggers. */
     refresh(): Promise<void>;
     /** Re-renders after a config change (refresh, or a config that arrived after start). */
@@ -112,6 +126,8 @@ declare class GuidelyClient {
     /** Updates consent at runtime (`granted` flushes buffered events; `denied` drops them). */
     setConsent(consent: ConsentState): void;
     private analyticsEnabled;
+    /** The host app's version (`appVersion` option), sent with every event and recording. */
+    private appVersion;
     private collectUrls;
     private enqueue;
     /** Tracks a custom event. Events drive `event` triggers, `advanceOn: "event"` steps and checklist tasks. */
@@ -154,10 +170,37 @@ declare class GuidelyClient {
     private captureGlobalException;
     /**
      * Reports a caught error as an `exception` event (`source: "manual"`, `handled: true`), grouped
-     * into an issue on the Errors page. Extra properties are attached to the occurrence. Needs the
-     * project's error tracking on (plus analytics + consent); `captureErrors: false` does not stop it.
+     * into an issue on the Errors page. The second argument takes Sentry's capture context (`tags`,
+     * `extra`, `level`, `fingerprint`, `contexts`, `user`); any other key is attached to the occurrence
+     * as a property. Needs the project's error tracking on (plus analytics + consent);
+     * `captureErrors: false` does not stop it. Returns the event id (empty when nothing is sent).
      */
-    captureException(error: unknown, properties?: Record<string, unknown>): void;
+    captureException(error: unknown, hint?: CaptureContext & Record<string, unknown>): string;
+    /** Reports a message (default level `info`) as its own issue, grouped by the message. */
+    captureMessage(message: string, level?: ErrorLevelName, hint?: CaptureContext): string;
+    private captureWith;
+    /** The `detail` of an error: scope, breadcrumbs, browser contexts and the `cause` chain. */
+    private errorDetail;
+    /** Adds a breadcrumb (sent with the next errors; the last 100 are kept). */
+    addBreadcrumb(crumb: Breadcrumb): void;
+    /** Tags every later error (searchable on the issue page). */
+    setTag(key: string, value: string | number | boolean | null | undefined): void;
+    setTags(tags: Record<string, string | number | boolean | null | undefined>): void;
+    /** Arbitrary data attached to every later error. */
+    setExtra(key: string, value: unknown): void;
+    setExtras(extras: Record<string, unknown>): void;
+    /** A named context (`setContext("cart", { items: 3 })`) on every later error; null removes it. */
+    setContext(name: string, context: Record<string, unknown> | null): void;
+    /**
+     * Sentry's `setUser`: identifies the user by `id` (like `identify`) and keeps `email` / `username`
+     * on their errors. `null` forgets the user (`reset()`).
+     */
+    setUser(user: {
+        id?: string | number;
+        email?: string;
+        username?: string;
+        [trait: string]: unknown;
+    } | null): void;
     private sendException;
     private maskSelector;
     private maskAllText;
@@ -252,6 +295,11 @@ declare class GuidelyClient {
     getGuides(): ReadonlyArray<PublishedGuide>;
     isGuideCompleted(idOrKey: string): boolean;
     openResourceCenter(): void;
+    /**
+     * Opens one help article: in Scout's Help tab when the messenger is on, otherwise in the resource
+     * center. Help-article links in guides (`#guidely-article:<id>`) call this.
+     */
+    openArticle(articleId: string): void;
     closeResourceCenter(): void;
     /** Opens the Scout messenger (when enabled for the project), optionally on a tab. */
     openMessenger(tab?: MessengerTab): void;
@@ -272,6 +320,19 @@ declare class GuidelyClient {
      * Does nothing when the project hasn't turned on Ideas.
      */
     openIdeas(requestId?: string): void;
+    /**
+     * Sends a bug report to Monitor → User feedback (Sentry's `captureFeedback`). It is linked to the visitor,
+     * this session's recording and, unless `associatedEventId` says otherwise, the last error this page
+     * reported. Resolves with the report's id; rejects when it can't be sent.
+     */
+    captureFeedback(input: BugReportInput, source?: "widget" | "api"): Promise<BugReportResponse>;
+    /** Opens the "Report a bug" dialog (message, name, email, a screenshot), which sends with captureFeedback. */
+    showBugReport(options?: {
+        message?: string;
+        name?: string;
+        email?: string;
+        title?: string;
+    }): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
     /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
@@ -507,4 +568,4 @@ declare const Guidely: {
     version: string;
 };
 
-export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, PROTOTYPE_CLOSE_MESSAGE, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, isAppUrl, matchPrototypeTestUrl, normalizeAppUrl, watchNavigation };
+export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, CaptureContext, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEnvironment, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, PROTOTYPE_CLOSE_MESSAGE, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, isAppUrl, matchPrototypeTestUrl, normalizeAppUrl, watchNavigation };