@guidelytech/shared 0.2.0 → 0.4.0

package/dist/runtime.d.ts

@@ -15,9 +15,70 @@ declare function stripOrigin(url: string): string;
 /** Safe regexp construction with a length cap to limit ReDoS exposure. */
 declare function safeRegExp(source: string, flags?: string): RegExp | null;
 
+/**
+ * Cross-platform helpers shared by the web SDK, the React Native SDK and (as a reference for) the
+ * native iOS/Android SDKs. Zod-free so it can ship in runtime bundles.
+ */
+/** Platforms a guide can be delivered to. */
+declare const PLATFORMS: readonly ["web", "ios", "android"];
+type Platform = (typeof PLATFORMS)[number];
+/** Guides published before platforms existed have no `platforms` field and are web-only. */
+declare const DEFAULT_PLATFORMS: Platform[];
+/** Platforms a guide config targets (missing field → web only). */
+declare function guidePlatforms(config: {
+    platforms?: readonly string[] | null;
+}): string[];
+declare function supportsPlatform(config: {
+    platforms?: readonly string[] | null;
+}, platform: string): boolean;
+/** Attribute web apps put on elements to share a target id with their mobile apps. */
+declare const GUIDELY_ID_ATTRIBUTE = "data-guidely-id";
+/**
+ * Extracts a Guidely target id from a trigger / advance / checklist value so the same guide works on
+ * web and mobile. Accepts a bare id (`new-deal`), `#new-deal`, or `[data-guidely-id="new-deal"]`
+ * (also `data-testid` / `data-tour`). Returns null for selectors that cannot name a single id.
+ */
+declare function guidelyIdFromSelector(value: string | null | undefined): string | null;
+/**
+ * Mobile SDKs have screens instead of URLs. URL-based features (URL patterns, `url_match` triggers,
+ * multi-page steps, `url_visited` checklist tasks) match against the screen path `/<ScreenName>`.
+ */
+declare function screenPath(screen: string | null | undefined): string;
+/**
+ * Compares dotted version strings numerically (`2.10.0` > `2.9.3`). Non-numeric parts compare as
+ * strings; a missing part counts as 0 (`2.1` == `2.1.0`). Returns -1, 0 or 1, or null when either
+ * side is empty.
+ */
+declare function compareVersions(a: unknown, b: unknown): -1 | 0 | 1 | null;
+
+/**
+ * Pure checklist / survey logic shared by every renderer (web runtime, React Native, and the
+ * reference for the native SDKs). Zod-free; uses structural types so it stays in the runtime entry.
+ */
+type SurveyAnswer = string | number | boolean | string[];
+type SurveyAnswers = Record<string, SurveyAnswer>;
+interface ShowWhen {
+    questionId: string;
+    op: "equals" | "lte" | "gte" | "in";
+    value: string | number | string[];
+}
+/** Evaluates a question's `showWhen` condition against current answers. */
+declare function isQuestionVisible(q: {
+    showWhen?: ShowWhen;
+}, answers: SurveyAnswers): boolean;
+/** Are all required tasks done? */
+declare function isChecklistComplete(config: {
+    tasks: Array<{
+        id: string;
+        required: boolean;
+    }>;
+}, progress: {
+    completedTaskIds: string[];
+}): boolean;
+
 declare const RULE_OPERATORS: readonly ["equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "exists", "not_exists", "gt", "gte", "lt", "lte", "in", "not_in", "regex", "is_true", "is_false", "before", "after"];
 type RuleOperator = (typeof RULE_OPERATORS)[number];
-declare const RULE_FIELDS: readonly ["user.attribute", "account.attribute", "user.role", "user.plan", "url.path", "url.full", "url.query", "device.type", "device.browser", "device.os", "visitor.firstVisit", "visitor.returning", "event.seen", "guide.completed", "guide.dismissed", "guide.seen", "checklist.completed", "audience.member", "datetime.now", "datetime.dayOfWeek", "datetime.hour", "rollout.percentage", "environment", "locale"];
+declare const RULE_FIELDS: readonly ["user.attribute", "account.attribute", "user.role", "user.plan", "url.path", "url.full", "url.query", "device.type", "device.browser", "device.os", "visitor.firstVisit", "visitor.returning", "event.seen", "guide.completed", "guide.dismissed", "guide.seen", "checklist.completed", "audience.member", "datetime.now", "datetime.dayOfWeek", "datetime.hour", "rollout.percentage", "environment", "locale", "app.platform", "app.screen", "app.version"];
 type RuleField = (typeof RULE_FIELDS)[number];
 interface Rule {
     id: string;
@@ -61,6 +122,12 @@ interface TargetingContext {
     now: Date;
     environment: string;
     locale?: string;
+    /** `web`, `ios` or `android`. Missing means web. */
+    platform?: string;
+    /** Current screen name (mobile SDKs; set via `screen()`). */
+    screen?: string;
+    /** Host app version (mobile SDKs), e.g. `2.4.1`. */
+    appVersion?: string;
     /** Salt for rollout (guide id). Set per guide before evaluating. */
     rolloutSalt?: string;
 }
@@ -77,4 +144,126 @@ declare const SENSITIVE_PROPERTY_PATTERN: RegExp;
 declare const MAX_PROPERTY_BYTES: number;
 declare function sanitizeProperties(props: Record<string, unknown> | undefined): Record<string, unknown>;
 
-export { MAX_PROPERTY_BYTES, RULE_FIELDS, RULE_OPERATORS, type Rule, type RuleField, type RuleGroup, type RuleOperator, SENSITIVE_PROPERTY_PATTERN, SERVER_ASSISTED_FIELDS, type TargetingContext, clamp, compare, describeRule, emptyRuleGroup, evaluateRule, evaluateRules, fnv1a, getPath, isPlainObject, isRuleGroup, matchUrlPattern, randomId, rolloutBucket, safeRegExp, sanitizeProperties, slugify, stripOrigin };
+/** One parsed stack frame. `file` is the script URL (or path) as the browser reported it. */
+interface StackFrame {
+    fn?: string;
+    file?: string;
+    line?: number;
+    col?: number;
+}
+/** Properties carried by an `exception` event (see `docs/product-analytics.md`). */
+interface ExceptionProperties {
+    type: string;
+    message: string;
+    frames: StackFrame[];
+    /** `onerror` | `unhandledrejection` | `manual` (captureException) | `console`. */
+    source?: string;
+    handled?: boolean;
+    /** App version or commit (SDK option `release`); selects the matching uploaded source maps. */
+    release?: string;
+    /** Set by the server at ingestion; groups occurrences into an issue. */
+    fingerprint?: string;
+}
+declare const MAX_STACK_FRAMES = 30;
+/** Parses `Error.stack` from V8, SpiderMonkey and JavaScriptCore into frames (innermost first). */
+declare function parseStack(stack: string | undefined | null, max?: number): StackFrame[];
+/** Replaces volatile parts of a message (numbers, ids, quoted values) so repeats group together. */
+declare function normalizeErrorMessage(message: string): string;
+/** Strips origin, query, hash and build hashes (`main.3f2a1b9c.js` → `main.js`) from a script URL. */
+declare function normalizeFrameFile(file: string | undefined): string;
+/** Source map upload limits (`POST /api/v1/sourcemaps/upload`). */
+declare const SOURCEMAP_MAX_FILE_BYTES: number;
+declare const SOURCEMAP_MAX_FILES_PER_UPLOAD = 200;
+/**
+ * Stable issue key for an exception: error type + normalised message + the innermost frame that
+ * has a file (path without build hash + function name, or its original source + name when a source
+ * map resolved it). Line/column numbers are left out because they change with every deploy of a
+ * minified bundle.
+ */
+declare function fingerprintError(input: {
+    type?: string;
+    message?: string;
+    frames?: StackFrame[];
+    original?: {
+        source: string;
+        name?: string | null;
+    } | null;
+}): string;
+
+/** rrweb plugin name for network events in recordings (event type 6, `data.plugin`). */
+declare const NETWORK_PLUGIN = "guidely/network@1";
+/** Request kinds, from `fetch`/`XMLHttpRequest` patching or `PerformanceResourceTiming.initiatorType`. */
+type NetworkRequestType = "fetch" | "xhr" | "websocket" | "document" | "script" | "stylesheet" | "image" | "font" | "media" | "beacon" | "other";
+/**
+ * One network request in a recording: the payload of an rrweb plugin event
+ * `{ type: 6, data: { plugin: NETWORK_PLUGIN, payload: NetworkPluginPayload } }`, batched.
+ * Times are epoch milliseconds (same clock as rrweb event timestamps).
+ *
+ * A WebSocket is a request with `type: "websocket"` and `method: "GET"`, emitted when it opens
+ * (`startTime`) and again, with the same `id`, when it closes (`endTime`, `closeCode`, `closeReason`,
+ * totals in `messages`). Its frames are `WebSocketMessage`s referencing that `id`.
+ */
+interface NetworkRequest {
+    /** Stable id within the recording. */
+    id: string;
+    type: NetworkRequestType;
+    method: string;
+    /** Absolute URL; values of sensitive-looking query parameters replaced with `[redacted]`. */
+    url: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    /** HTTP status; 0 for network errors / blocked / aborted. Absent when the browser doesn't expose it. */
+    status?: number;
+    /** Set for failed requests: network error, abort or timeout message. */
+    error?: string;
+    /** Encoded bytes transferred / decoded response size, when known. */
+    transferSize?: number;
+    responseSize?: number;
+    /** Only when `recordNetworkPayloads` is on; sensitive headers are `[redacted]`. */
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    /** Text/JSON bodies, ≤10KB, sensitive JSON fields masked; `[binary]` / `[truncated]` markers otherwise. */
+    requestBody?: string;
+    responseBody?: string;
+    /** WebSocket only: negotiated subprotocol, close details, and frame totals (all frames, including ones not recorded). */
+    protocol?: string;
+    closeCode?: number;
+    closeReason?: string;
+    messages?: {
+        sent: number;
+        received: number;
+        sentBytes: number;
+        receivedBytes: number;
+        recorded: number;
+    };
+}
+/** One WebSocket frame. At most `WS_MAX_MESSAGES_PER_SOCKET` are recorded per connection per page load. */
+interface WebSocketMessage {
+    /** The `NetworkRequest.id` of the connection. */
+    socketId: string;
+    dir: "send" | "recv";
+    time: number;
+    /** Bytes (UTF-8 length for text frames). */
+    size: number;
+    binary?: boolean;
+    /** Only with `recordNetworkPayloads`: text ≤ 2KB (JSON with sensitive keys masked), else `[truncated]`; binary frames are `[binary <n> B]`. */
+    data?: string;
+}
+interface NetworkPluginPayload {
+    requests?: NetworkRequest[];
+    messages?: WebSocketMessage[];
+    /** Requests/frames dropped since the previous payload because a cap was reached. */
+    dropped?: {
+        requests?: number;
+        messages?: number;
+    };
+}
+declare const WS_MAX_MESSAGES_PER_SOCKET = 200;
+declare const WS_MAX_MESSAGE_BYTES = 2048;
+/** Header names always replaced with `[redacted]` when payload capture is on. */
+declare const SENSITIVE_HEADER_PATTERN: RegExp;
+/** Query parameter and JSON field names whose values are redacted. */
+declare const SENSITIVE_PARAM_PATTERN: RegExp;
+
+export { DEFAULT_PLATFORMS, type ExceptionProperties, GUIDELY_ID_ATTRIBUTE, MAX_PROPERTY_BYTES, MAX_STACK_FRAMES, NETWORK_PLUGIN, type NetworkPluginPayload, type NetworkRequest, type NetworkRequestType, PLATFORMS, type Platform, RULE_FIELDS, RULE_OPERATORS, type Rule, type RuleField, type RuleGroup, type RuleOperator, SENSITIVE_HEADER_PATTERN, SENSITIVE_PARAM_PATTERN, SENSITIVE_PROPERTY_PATTERN, SERVER_ASSISTED_FIELDS, SOURCEMAP_MAX_FILES_PER_UPLOAD, SOURCEMAP_MAX_FILE_BYTES, type ShowWhen, type StackFrame, type SurveyAnswer, type SurveyAnswers, type TargetingContext, WS_MAX_MESSAGES_PER_SOCKET, WS_MAX_MESSAGE_BYTES, type WebSocketMessage, clamp, compare, compareVersions, describeRule, emptyRuleGroup, evaluateRule, evaluateRules, fingerprintError, fnv1a, getPath, guidePlatforms, guidelyIdFromSelector, isChecklistComplete, isPlainObject, isQuestionVisible, isRuleGroup, matchUrlPattern, normalizeErrorMessage, normalizeFrameFile, parseStack, randomId, rolloutBucket, safeRegExp, sanitizeProperties, screenPath, slugify, stripOrigin, supportsPlatform };

package/dist/runtime.js

@@ -1,49 +1,93 @@
 import {
+  DEFAULT_PLATFORMS,
+  GUIDELY_ID_ATTRIBUTE,
   MAX_PROPERTY_BYTES,
+  MAX_STACK_FRAMES,
+  NETWORK_PLUGIN,
+  PLATFORMS,
   RULE_FIELDS,
   RULE_OPERATORS,
+  SENSITIVE_HEADER_PATTERN,
+  SENSITIVE_PARAM_PATTERN,
   SENSITIVE_PROPERTY_PATTERN,
   SERVER_ASSISTED_FIELDS,
+  SOURCEMAP_MAX_FILES_PER_UPLOAD,
+  SOURCEMAP_MAX_FILE_BYTES,
+  WS_MAX_MESSAGES_PER_SOCKET,
+  WS_MAX_MESSAGE_BYTES,
   clamp,
   compare,
+  compareVersions,
   describeRule,
   emptyRuleGroup,
   evaluateRule,
   evaluateRules,
+  fingerprintError,
   fnv1a,
   getPath,
+  guidePlatforms,
+  guidelyIdFromSelector,
+  isChecklistComplete,
   isPlainObject,
+  isQuestionVisible,
   isRuleGroup,
   matchUrlPattern,
+  normalizeErrorMessage,
+  normalizeFrameFile,
+  parseStack,
   randomId,
   rolloutBucket,
   safeRegExp,
   sanitizeProperties,
+  screenPath,
   slugify,
-  stripOrigin
-} from "./chunk-OFBIZEM5.js";
+  stripOrigin,
+  supportsPlatform
+} from "./chunk-QUKMOTT4.js";
 export {
+  DEFAULT_PLATFORMS,
+  GUIDELY_ID_ATTRIBUTE,
   MAX_PROPERTY_BYTES,
+  MAX_STACK_FRAMES,
+  NETWORK_PLUGIN,
+  PLATFORMS,
   RULE_FIELDS,
   RULE_OPERATORS,
+  SENSITIVE_HEADER_PATTERN,
+  SENSITIVE_PARAM_PATTERN,
   SENSITIVE_PROPERTY_PATTERN,
   SERVER_ASSISTED_FIELDS,
+  SOURCEMAP_MAX_FILES_PER_UPLOAD,
+  SOURCEMAP_MAX_FILE_BYTES,
+  WS_MAX_MESSAGES_PER_SOCKET,
+  WS_MAX_MESSAGE_BYTES,
   clamp,
   compare,
+  compareVersions,
   describeRule,
   emptyRuleGroup,
   evaluateRule,
   evaluateRules,
+  fingerprintError,
   fnv1a,
   getPath,
+  guidePlatforms,
+  guidelyIdFromSelector,
+  isChecklistComplete,
   isPlainObject,
+  isQuestionVisible,
   isRuleGroup,
   matchUrlPattern,
+  normalizeErrorMessage,
+  normalizeFrameFile,
+  parseStack,
   randomId,
   rolloutBucket,
   safeRegExp,
   sanitizeProperties,
+  screenPath,
   slugify,
-  stripOrigin
+  stripOrigin,
+  supportsPlatform
 };
 //# sourceMappingURL=runtime.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidelytech/shared",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shared schemas, types and pure utilities for Guidely",
   "license": "MIT",
   "type": "module",