@botim/mp-debug-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+import { EventType, EventLevel, ConsolePayload, NetworkPayload, ErrorPayload, CommandHandler, BotimConfig, ConsentInput, DeviceInfo } from './types.js';
+export { AttachRequest, AttachResponse, BotimEnv, BridgePayload, CommandAckPayload, CommandContext, CommandPollResponse, CommandRejectedPayload, CommandRequest, DebugEvent, DebugEventBase, ErrorSource, EventMeta, LifecycleEvent, LifecyclePayload, NetworkPhase, PerfPayload, SCHEMA_VERSION, SerializedValue, StreamFrame, UploadAck, UploadBatch } from './types.js';
+
+/**
+ * Errors that escape the SDK into host code.
+ *
+ * The SDK's no-throw invariant has exactly two carve-outs:
+ *  - `BotimConfigError` — thrown synchronously by `enableRemoteDebug` when the
+ *    resolved `BotimConfig` is missing or invalid. Prevents any I/O.
+ *  - `BotimConsentError` — thrown synchronously by `enableRemoteDebug` when
+ *    consent has not been granted in a `prod` build. Prevents any I/O.
+ *
+ * Both are intentionally synchronous and pre-installation: at the moment they
+ * fire, no globals have been wrapped, no listeners installed, no network sent.
+ */
+declare class BotimConfigError extends Error {
+    readonly name = "BotimConfigError";
+    readonly code: string;
+    readonly path?: string;
+    constructor(message: string, opts?: {
+        code: string;
+        path?: string;
+    });
+}
+declare class BotimConsentError extends Error {
+    readonly name = "BotimConsentError";
+    constructor(message: string);
+}
+
+/**
+ * Built-in commands registered automatically when `enableRemoteDebug` runs.
+ *
+ * Most are thin shells over host-supplied callbacks: the SDK has no business
+ * deciding what "reload" means in a given mini-program, so the host registers
+ * the callback and the SDK exposes a stable wire-level command name.
+ */
+
+interface BuiltinHostHooks {
+    /** Reload the mini-program. If absent, `reload` returns rejected. */
+    reload?: () => void | Promise<void>;
+    /** Return a JSON-serializable snapshot of host state. */
+    getState?: () => unknown | Promise<unknown>;
+    /** Apply a feature flag override. */
+    setFeatureFlag?: (key: string, value: unknown) => void | Promise<void>;
+    /**
+     * Capture a screenshot. Two return shapes are accepted:
+     *   - a raw base64 string  → assumed PNG (legacy form)
+     *   - `{ data, format }`   → format is one of 'png-base64' | 'jpeg-base64'
+     *     so the admin viewer can pick the right MIME for the data URL.
+     * The SDK enforces a 1 MB base64 cap regardless.
+     */
+    screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
+}
+type ScreenshotResult = string | {
+    data: string;
+    format?: 'png-base64' | 'jpeg-base64'
+    /**
+     * Self-contained HTML+CSS snapshot — `data` is a JSON string with
+     * the shape `{ html, viewport, url, capturedAt }`. Admin viewers
+     * render `html` inside a sandboxed `<iframe srcdoc>` so the result
+     * looks pixel-identical to the live page without any pixel encoding.
+     */
+     | 'html-snapshot';
+};
+
+/**
+ * Per-signature sliding-window event deduper.
+ *
+ * Without this, a `setInterval(() => undefined.foo, 16)` produces ~60
+ * `error` events per second; a flaky network endpoint in a tight retry
+ * loop can fire hundreds of `network` events per minute. The relay's hot
+ * retention is 24-48h — at those rates a single misbehaving session drowns
+ * out everything else, and the device's own ingest budget gets eaten by
+ * its own bug.
+ *
+ * Algorithm:
+ *   - Compute a stable signature for each event (type + key payload bits).
+ *   - First event with a given signature in a window: emit normally.
+ *   - Subsequent events with the same signature within `windowMs`: drop +
+ *     increment a counter.
+ *   - When the window closes (next same-signature event OR a periodic sweep),
+ *     emit ONE rollup event whose `meta.dedup` field carries the suppressed
+ *     count and the time range.
+ *
+ * Types are carried verbatim — a suppressed `error` produces an `error`-typed
+ * rollup with the same level. Admin UIs / agents detect rollups by checking
+ * `meta.dedup` rather than a separate event type, so no schema bump is needed.
+ *
+ * Default behaviour: enabled, 1000 ms window, applies to console / network /
+ * error events only. lifecycle / bridge / perf / command-* events bypass.
+ */
+
+interface DedupOptions {
+    /** Default true. Set false to disable deduping entirely. */
+    enabled?: boolean;
+    /** Sliding window per signature, in ms. Default 1000. */
+    windowMs?: number;
+    /** Hard cap on the number of tracked signatures. Default 500. Oldest entries evict on overflow. */
+    maxSignatures?: number;
+}
+interface SuppressionSummary {
+    signature: string;
+    type: EventType;
+    level: EventLevel;
+    /** Total suppressed (excludes the leading event that was emitted as a real event). */
+    count: number;
+    firstTs: number;
+    lastTs: number;
+    /** Human-readable label describing what was suppressed. */
+    label: string;
+    /** Original payload of the LAST suppressed occurrence — gives admins a
+     *  recent-state look at the thing that's been firing in a loop. */
+    examplePayload: ConsolePayload | NetworkPayload | ErrorPayload | unknown;
+}
+
+interface RedactionConfig {
+    headers?: string[];
+    bodyPatterns?: RegExp[];
+    maxBodyBytes?: number;
+}
+interface SamplingConfig {
+    console?: number;
+    network?: number;
+    lifecycle?: number;
+    bridge?: number;
+}
+interface AppInfo {
+    name: string;
+    version: string;
+    build?: string;
+}
+interface RemoteDebugOptions {
+    /** When false, returns a no-op handle and installs nothing. */
+    enabled?: boolean;
+    /** Relay base URL, e.g. "https://debug.botim.dev". */
+    endpoint: string;
+    /**
+     * Optional override for the app identity reported in events. When omitted
+     * the SDK falls back to `config.appName` / `config.appVersion` resolved by
+     * the Vite plugin from `botim.{env}.json`.
+     */
+    app?: AppInfo;
+    /**
+     * Build-time-resolved mini-program identity. In typical usage this is
+     * `botimConfig` imported from `virtual:botim/config` (provided by the
+     * `@botim/debug-sdk/vite` plugin). REQUIRED.
+     */
+    config: BotimConfig;
+    /**
+     * Consent for telemetry. Required in `prod`; implicit in non-prod builds.
+     */
+    consent?: ConsentInput;
+    /** Built-in command host hooks (reload, getState, screenshot, etc.). */
+    builtins?: BuiltinHostHooks;
+    device?: Partial<DeviceInfo>;
+    redact?: RedactionConfig;
+    sampling?: SamplingConfig;
+    /**
+     * Sliding-window per-signature dedup. Default: enabled with a 1 s window
+     * applied to console / network / error events. Set `false` to disable.
+     * Repetitive events (e.g., a render-loop error firing 60×/s) collapse
+     * into one leading event + a synthesized rollup event whose
+     * `meta.dedup.count` carries the suppressed total.
+     */
+    dedup?: DedupOptions | false;
+    flushIntervalMs?: number;
+    bufferSize?: number;
+    maxBatchSize?: number;
+    maxRetries?: number;
+    /** Called for transport-level errors. SDK never throws into app code. */
+    onError?: (err: unknown) => void;
+}
+interface RemoteDebugHandle {
+    readonly sid: string | null;
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+    /** Register a custom command handler. Idempotent on the name. */
+    registerCommand(name: string, handler: CommandHandler): void;
+    /** Remove a previously-registered command. Returns true if it existed. */
+    unregisterCommand(name: string): boolean;
+}
+declare const DEFAULT_REDACT_HEADERS: readonly string[];
+declare const DEFAULT_BODY_PATTERNS: readonly RegExp[];
+declare const DEFAULT_MAX_BODY_BYTES = 4096;
+/**
+ * How often the transport drains the buffer to the relay.
+ *
+ * 8 seconds is deliberately slow: this is a debug telemetry channel, not a
+ * realtime one. With a 200ms cadence, a busy session producing ~10 events/sec
+ * would make ~5 ingest POSTs/second, hammering the device's network stack
+ * and the relay's write path for no human-visible benefit (admins poll at
+ * 2s anyway, so end-to-end perceived latency is dominated by their poll).
+ *
+ * The timer fully drains the buffer per tick (multiple POSTs back-to-back if
+ * needed, each capped at maxBatchSize), so the only cost of the longer
+ * interval is up to 8s of potential delay before an event reaches the relay.
+ *
+ * Hosts can opt for tighter latency by setting `flushIntervalMs` explicitly.
+ */
+declare const DEFAULT_FLUSH_INTERVAL_MS = 8000;
+declare const DEFAULT_BUFFER_SIZE = 1000;
+declare const DEFAULT_MAX_BATCH_SIZE = 50;
+declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
+
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug };