remote-webview-debugger 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,368 @@
+declare const AGENT_EN: {
+  missingParam: (name: string) => string;
+  notString: (name: string) => string;
+  unknownMethod: (method: string) => string;
+  needLevel: (level: string) => string;
+  takenOver: string;
+  userDenied: string;
+  confirmBusy: string;
+  unknownModifier: (m: string) => string;
+  unknownKey: (key: string) => string;
+  refNotInSnapshot: (ref: string) => string;
+  refDetached: (ref: string) => string;
+  queryNeedsCriteria: string;
+  noSuchRecord: (seq: string) => string;
+  noSuchSession: (id: string) => string;
+  noSessionLog: string;
+  sessionLogUnavailable: string;
+  readOnly: (tag: string) => string;
+  isSelect: (tag: string) => string;
+  notFillable: (tag: string) => string;
+  notSelect: (tag: string) => string;
+  singleSelect: string;
+  noSuchOption: (value: string, choices: string[]) => string;
+  optionDisabled: (value: string) => string;
+  badUrl: (url: string) => string;
+  httpOnly: string;
+  textAppearTimeout: (text: string) => string;
+  textGoneTimeout: (text: string) => string;
+  badFunction: (message: string) => string;
+  notAFunction: string;
+  elementDetached: (tag: string) => string;
+  notActionable: (tag: string, reason: string) => string;
+  notVisible: (tag: string) => string;
+  reasonMoving: string;
+  reasonOffscreen: string;
+  reasonObscured: (tag: string, ref: string) => string;
+  overlayHeader: string;
+  overlayMask: (tag: string, coverage: number, ref: string) => string;
+  overlayLayer: (tag: string, text: string, coverage: number, ref: string) => string;
+  reasonHidden: string;
+  reasonDisabled: string;
+  storageUnavailable: (area: string) => string;
+  badStorageArea: string;
+  requestFailed: string;
+  noSuchRequest: (id: string) => string;
+  netFailed: (what: string, error: string) => string;
+  wsFailed: (url: string) => string;
+  tapped: (role: string, text: string) => string;
+  tappedTag: (role: string, tag: string) => string;
+  roles: {
+    [role: string]: string;
+  };
+  element: string;
+};
+type AgentText = typeof AGENT_EN;
+declare const USER_EN: {
+  quote: (name: string) => string;
+  click: (target: string) => string;
+  enterActivate: (target: string) => string;
+  enterSubmit: (target: string) => string;
+};
+type UserText = typeof USER_EN;
+type Level = 'observe' | 'interact' | 'advanced';
+type LevelText = {
+  observe: string;
+  interact: string;
+  advanced: string;
+};
+declare const ui: {
+  /** Levels in the floating window (auto-allow). */
+  levels: LevelText;
+  /** Levels in the attach dialog: what each choice adds. */
+  attachLevels: LevelText;
+  state: {
+    none: string;
+    observe: string;
+    agent: string;
+    user: string;
+  };
+  link: {
+    connecting: string;
+    online: string;
+    offline: string;
+  };
+  connecting: string;
+  helpPending: string;
+  copy: string;
+  copied: string;
+  noteHelp: string;
+  noteAuto: string;
+  noteShare: string;
+  help: string;
+  cancelHelp: string;
+  collapse: string;
+  deviceCode: string;
+  barViewing: string;
+  barAgent: string;
+  barUser: string;
+  connectedFor: (time: string) => string;
+  takeover: string;
+  handback: string;
+  end: string;
+  autoTitle: string;
+  autoOn: (level: string) => string;
+  autoOff: string;
+  lockTitle: string;
+  lockOn: string;
+  lockOff: string;
+  lockedToast: string;
+  unlockedToast: string;
+  autoOffToast: string;
+  autoDialogTitle: string;
+  autoDialogText: string;
+  turnOn: string;
+  cancel: string;
+  autoOnToast: (level: string) => string;
+  countdown: (seconds: number) => string;
+  agentName: string;
+  autoAllowedToast: (agent: string, level: string) => string;
+  attachTitle: string;
+  attachText: (agent: string) => string;
+  confirmTitle: string;
+  confirmText: (action: string) => string;
+  allow: string;
+  deny: string;
+};
+type UiMessages = typeof ui;
+type AgentMessages = AgentText;
+type ActionMessages = UserText;
+interface Messages {
+  ui: UiMessages;
+  action: ActionMessages;
+  agent: AgentMessages;
+}
+/** Optional at every level; functions stay whole. */
+type DeepPartial<T> = T extends ((...args: never[]) => unknown) ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]>; } : T;
+/** A complete language pack, like the built-in ones. */
+interface Locale extends Messages {
+  /** BCP 47 tag: 'en', 'zh-TW', 'pt'… */
+  id: string;
+  /** The language's own name: 'Deutsch', '日本語'. */
+  name: string;
+  dir?: 'ltr' | 'rtl';
+}
+/** A pack for registerLocale(): anything left out comes from its fallback languages. */
+interface LocalePack extends DeepPartial<Messages> {
+  id: string;
+  name?: string;
+  dir?: 'ltr' | 'rtl';
+}
+/** Messages to override, per language tag: { en: { ui: { help: 'Contact support' } } }. */
+type MessageOverrides = {
+  [lang: string]: DeepPartial<Messages>;
+};
+/** Add language packs (or replace one with the same id). Pages that already chose that language switch to it. */
+export declare function registerLocale(pack: LocalePack | LocalePack[]): void;
+type ControlState = 'none' | 'observe' | 'agent' | 'user';
+/**
+ * run({ style }): each field sets one --rwd-* custom property on #__rwd (see
+ * VARS). Colors take any CSS color; lengths a number of px or a CSS length.
+ */
+interface StyleOptions {
+  /** --rwd-accent-rgb: buttons, switches, the agent's pointer and the edge glow. */
+  accent?: string;
+  /** --rwd-danger-rgb: the End button. */
+  danger?: string;
+  /** --rwd-warning-rgb: help, the user-in-control state. */
+  warning?: string;
+  /** --rwd-success-rgb: online dot, copied. */
+  success?: string;
+  /** --rwd-font */
+  font?: string;
+  /** --rwd-font-mono: device code, tags. */
+  monoFont?: string;
+  /** --rwd-radius: floating window (dialog +2px, task card −2px, smaller parts follow). */
+  radius?: number | string;
+  /** --rwd-button-radius: pill-shaped buttons and toasts. */
+  buttonRadius?: number | string;
+  /** --rwd-z-index of the whole UI (default 2147483647). */
+  zIndex?: number;
+  /** --rwd-bar-bottom: bottom bar distance from the bottom safe area (default 14px). */
+  barBottom?: number | string;
+  /** --rwd-task-top: task card distance from the top safe area (default 10px). */
+  taskTop?: number | string;
+  /** --rwd-toast-bottom: toast distance from the bottom safe area (default 84px). */
+  toastBottom?: number | string;
+  /** Where the idle pill starts until the user drags it: the screen edge and the height (0 top … 1 bottom). */
+  pill?: {
+    side?: 'left' | 'right';
+    top?: number;
+  };
+}
+interface AttachPending {
+  kind: 'attach';
+  requestId: string;
+  agent: {
+    name: string;
+    keyHint: string | null;
+  };
+  levels: Level[];
+  expiresAt: number;
+}
+interface ConfirmPending {
+  kind: 'confirm';
+  requestId: string;
+  action: string;
+  expiresAt: number;
+}
+type LinkState = 'connecting' | 'online' | 'polling' | 'stopped' | 'rejected' | 'quota';
+interface ErudaOptions {
+  /** Show Remote Debugger as a tab inside eruda instead of the floating window. Default true. */
+  dock?: boolean;
+  /** Load eruda when the page has none (the latest release by default) and init it. Default false. */
+  load?: boolean;
+  /** Script URL for `load`. */
+  src?: string;
+  /** Name of the eruda tab. */
+  name?: string;
+}
+interface ErudaRemote {
+  dock?: boolean;
+  load?: boolean;
+}
+export declare const version: string;
+export interface RunOptions {
+  userId?: string | null;
+  deviceId?: string;
+  helpButton?: boolean;
+  app?: {
+    name: string;
+    version: string;
+  } | null;
+  /**
+   * Secret chosen by a native host (iOS/Android) when it injects the SDK.
+   * Enables nativeControl() so the app can offer its own takeover / handback /
+   * end buttons. Page scripts never see it.
+   */
+  nativeKey?: string;
+  /**
+   * deviceToken the gateway issued to this deviceId (status().deviceToken),
+   * kept by the native host: localStorage is per origin.
+   */
+  deviceToken?: string;
+  /**
+   * The native host shows the attach / confirm questions itself: no page
+   * dialog; it reads status().pending and answers with nativeDecide().
+   */
+  nativeApproval?: boolean;
+  /**
+   * Work with eruda: `true` (or `{ dock: true }`) shows Remote Debugger as a
+   * tab inside eruda instead of the floating window; `load: true` loads the
+   * latest eruda when the page has none. Off by default; the project policy
+   * can turn it on remotely, these options win field by field.
+   */
+  eruda?: boolean | ErudaOptions;
+  /**
+   * Lock the page while an agent is attached (default true). The user can
+   * still change it in the floating window.
+   */
+  lockScreen?: boolean;
+  /** Our UI's look: 'auto' (default) follows the page background, 'system' the OS, or fixed 'light' / 'dark'. */
+  theme?: 'auto' | 'system' | 'light' | 'dark';
+  /**
+   * Colors, fonts, radii, z-index and positions of our UI, as --rwd-* CSS
+   * custom properties (pages can also set those in their own CSS).
+   */
+  style?: StyleOptions;
+  /**
+   * Language of the UI the phone user sees (pill, bottom bar, dialogs…): a
+   * language tag such as 'ja' or 'pt-BR'. Default: the browser's languages.
+   * Either way the first one with a pack wins, falling back tag by tag
+   * (zh-HK → zh-TW → zh) and finally to English. Built in: en, zh, zh-TW,
+   * fr, es, ru, ar, ja, ko, de, pt. What the agent reads follows the gateway
+   * (welcome.agentLang).
+   */
+  lang?: string;
+  /** Extra language packs, registered before the language is picked (see registerLocale). */
+  locales?: LocalePack[];
+  /** Messages to override per language: { en: { ui: { help: 'Contact support' } } }. */
+  messages?: MessageOverrides;
+  /**
+   * Requests left out of what the agent sees in the network list and the
+   * timeline (still recorded): URL substrings, `*` wildcards or /regex/,
+   * e.g. ['.ttf', 'WebTracks', '*beacon*']. Added to the project's rules.
+   */
+  networkExclude?: string[];
+  /**
+   * Keep the session log (default true): what happened since the app was
+   * launched, in IndexedDB on the device, for an attached agent to read. The
+   * project policy can turn it off for every page.
+   */
+  record?: boolean;
+  /**
+   * The host app's id for this launch (same for every webview until the app
+   * process ends). Without it the SDK infers the launch; a host can also
+   * define window.RWDLaunchId.
+   */
+  launchId?: string;
+}
+export type Status = 'idle' | LinkState;
+/** welcome.config: the project policy the page applies (docs/protocol.md §3.4, §11). */
+export interface RemoteConfig {
+  helpButton: boolean;
+  maskSelectors: string[];
+  maskPatterns: {
+    name: string;
+    regex: string;
+  }[];
+  confirmSelectors: string[];
+  networkExclude: string[];
+  /** Keep the session log (project policy). */
+  sessionLog: boolean;
+  eruda: ErudaRemote | null;
+}
+export interface RunResult {
+  deviceCode: string | null;
+  status: Status;
+}
+/**
+ * Bring this page online for remote debugging. Resolves with the device code
+ * once the gateway has answered (or after a few seconds with what is known).
+ * Calling it again is harmless.
+ */
+export declare function run(gatewayUrl: string, appKey: string, opts?: RunOptions): Promise<RunResult>;
+/** Current state: device code, link status, control state. */
+export declare function getStatus(): {
+  deviceCode: string | null;
+  status: Status;
+  control: ControlState;
+  help: boolean;
+  label: string | null;
+  deviceId: string | null;
+  pageId: string | null;
+  version: string;
+  lang: string | null;
+  deviceToken: string | null;
+  level: Level | null;
+  config: RemoteConfig | null;
+  pending: AttachPending | ConfirmPending | null;
+  /** Id of the session log this page writes to; null when not recording. */
+  logSession: string | null;
+};
+/** Disconnect and remove the UI. Console / network collection continues (bounded). */
+export declare function stop(): void;
+/**
+ * Change the UI language at runtime (an app's own language switch): a tag
+ * like run({ lang }), or nothing to follow the browser again.
+ */
+export declare function setLang(lang?: string | null): void;
+/** The languages that ship with the SDK (all but en and zh load on demand). */
+export declare const builtinLocales: string[];
+/** Set or change the signed-in user. The gateway learns it through a new hello. */
+export declare function setUser(userId: string | null): void;
+/** Request assistance (the pill shows it; the console and agents see the device as assisting), or cancel the request. */
+export declare function help(on?: boolean): void;
+/**
+ * Take over, hand back or end from the native host's own UI. Requires the
+ * nativeKey given to run(): page scripts, including an agent's
+ * evaluate_script, cannot read it, so they cannot hand control to the agent.
+ */
+export declare function nativeControl(key: string, action: 'takeover' | 'handback' | 'end'): boolean;
+/**
+ * Answer status().pending from the native host's own dialog: a level (or null
+ * to refuse) for `attach`, 'allow' (or null) for `confirm`. Requires the
+ * nativeKey, like nativeControl(). False when the key, request or value is wrong.
+ */
+export declare function nativeDecide(key: string, requestId: string, value: string | null): boolean;
+export { type ActionMessages, type AgentMessages, type DeepPartial, type Locale, type LocalePack, type MessageOverrides, type Messages, type StyleOptions, type UiMessages, getStatus as status };