@browserbridge/bbx 1.8.0 → 1.10.0

package/packages/protocol/src/types.ts

@@ -29,7 +29,8 @@ export type Capability =
   | 'tabs.manage'
   | 'performance.read'
   | 'network.read'
-  | 'network.intercept';
+  | 'network.intercept'
+  | 'sensitive.read';
 
 export type ErrorCode =
   | 'ACCESS_DENIED'
@@ -45,7 +46,15 @@ export type ErrorCode =
   | 'DIALOG_NOT_OPEN'
   | 'DIALOG_ACTION_CONFLICT'
   | 'RESULT_TRUNCATED'
-  | 'RATE_LIMITED'
+  | 'RESULT_TOO_LARGE'
+  | 'SENSITIVE_TARGET_NOT_FOUND'
+  | 'CONTENT_SCRIPT_UNAVAILABLE'
+  | 'ARTIFACT_NOT_FOUND'
+  | 'ARTIFACT_QUOTA_EXCEEDED'
+  | 'ARTIFACT_TRANSFER_INVALID'
+  | 'DOM_BASELINE_NOT_FOUND'
+  | 'DOM_BASELINE_INVALIDATED'
+  | 'DOM_BASELINE_QUOTA_EXCEEDED'
   | 'INTERNAL_ERROR'
   | 'INVALID_REQUEST'
   | 'NATIVE_HOST_UNAVAILABLE'
@@ -54,6 +63,7 @@ export type ErrorCode =
 
 export type BridgeMethod =
   | 'access.request'
+  | 'protocol.describe'
   | 'tabs.list'
   | 'tabs.create'
   | 'tabs.close'
@@ -67,9 +77,11 @@ export type BridgeMethod =
   | 'page.handle_dialog'
   | 'page.wait_for_load_state'
   | 'page.get_storage'
+  | 'sensitive.read'
   | 'page.get_text'
   | 'page.extract_content'
   | 'page.get_network'
+  | 'network.export_har'
   | 'network.intercept.add'
   | 'network.intercept.remove'
   | 'network.intercept.list'
@@ -79,6 +91,10 @@ export type BridgeMethod =
   | 'navigation.go_back'
   | 'navigation.go_forward'
   | 'dom.query'
+  | 'dom.baseline.create'
+  | 'dom.baseline.compare'
+  | 'dom.baseline.describe'
+  | 'dom.baseline.release'
   | 'dom.describe'
   | 'dom.get_text'
   | 'dom.get_attributes'
@@ -106,6 +122,8 @@ export type BridgeMethod =
   | 'screenshot.capture_region'
   | 'screenshot.capture_element'
   | 'screenshot.capture_full_page'
+  | 'artifact.read'
+  | 'artifact.delete'
   | 'patch.apply_styles'
   | 'patch.apply_dom'
   | 'patch.list'
@@ -142,9 +160,44 @@ export interface BridgeMeta {
   budget_applied?: boolean;
   budget_truncated?: boolean;
   continuation_hint?: string | null;
+  automatic_retry?: { attempt: 2; reason: 'retryable_error' };
+  stale_recovery?: 'success' | 'failure';
   [key: string]: unknown;
 }
 
+export type RecoveryScope = 'routedExtension' | 'daemon';
+
+export type RecoveryEventKind =
+  | 'automatic_mcp_retry'
+  | 'stale_ref_recovery'
+  | 'debugger_reattach'
+  | 'content_script_reinjection'
+  | 'native_host_reconnect'
+  | 'request_outcome';
+
+export interface RecoveryEventSummary {
+  attempts: number;
+  successes: number;
+  failures: number;
+  pending: number;
+  saturated: boolean;
+  successRate: number | null;
+  failureRate: number | null;
+  activeLoop: boolean;
+  lastEventAt: number | null;
+}
+
+export interface RecoveryTelemetrySummary {
+  scope: RecoveryScope;
+  windowMs: number;
+  bucketMs: number;
+  loopWindowMs: number;
+  loopThreshold: number;
+  asOf: number;
+  activeLoop: boolean;
+  events: Record<RecoveryEventKind, RecoveryEventSummary>;
+}
+
 export interface BridgeParams {
   [key: string]: unknown;
 }
@@ -223,6 +276,147 @@ export interface NormalizedDomQuery extends BridgeParams {
   budget: Budget;
 }
 
+export interface DomBaselineCreateParams {
+  selector?: string;
+  maxNodes?: number;
+  maxDepth?: number;
+  textBudget?: number;
+  attributeAllowlist?: string[];
+}
+
+export interface NormalizedDomBaselineCreateParams extends BridgeParams {
+  selector: string;
+  maxNodes: number;
+  maxDepth: number;
+  textBudget: number;
+  attributeAllowlist: string[];
+}
+
+export interface DomBaselineCompareParams {
+  baselineId?: string;
+  maxChanges?: number;
+}
+
+export interface NormalizedDomBaselineCompareParams extends BridgeParams {
+  baselineId: string;
+  maxChanges: number;
+}
+
+export interface DomBaselineHandleParams {
+  baselineId?: string;
+}
+
+export interface NormalizedDomBaselineHandleParams extends BridgeParams {
+  baselineId: string;
+}
+
+export interface DomBaselineOptions {
+  maxNodes: number;
+  maxDepth: number;
+  textBudget: number;
+  attributeAllowlist: string[];
+}
+
+export interface DomBaselineScope {
+  windowId: number;
+  tabId: number;
+  frameId: number;
+  documentToken: string;
+  selector: string;
+  representation: 'semantic-dom-v1';
+}
+
+export interface DomBaselineSnapshotStats {
+  nodeCount: number;
+  byteLength: number;
+  digest: string;
+}
+
+export interface DomBaselineDescriptor {
+  baselineId: string;
+  createdAt: string;
+  expiresAt: string;
+  scope: DomBaselineScope;
+  options: DomBaselineOptions;
+  snapshot: DomBaselineSnapshotStats;
+  evicted?: Array<{
+    baselineId: string;
+    reason: 'per_tab_quota' | 'global_quota';
+  }>;
+}
+
+export type DomBaselineCreateResult = DomBaselineDescriptor;
+export type DomBaselineDescribeResult = DomBaselineDescriptor;
+
+export interface DomBaselineSemanticNodeEvidence {
+  tag: string;
+  role: string | null;
+  name: string | null;
+  text: string;
+  attributes: Record<string, string>;
+  depth: number;
+}
+
+export type DomBaselineNodeEvidence = DomBaselineSemanticNodeEvidence;
+
+export interface DomBaselineChangedNode {
+  fields: string[];
+  before: DomBaselineSemanticNodeEvidence;
+  after: DomBaselineSemanticNodeEvidence;
+}
+
+export interface DomBaselineNodeLocation {
+  ancestry: string[];
+  order: number;
+}
+
+export interface DomBaselineMovedNode {
+  node: DomBaselineSemanticNodeEvidence;
+  from: DomBaselineNodeLocation;
+  to: DomBaselineNodeLocation;
+}
+
+export interface DomBaselineChangeCounts {
+  added: number;
+  removed: number;
+  changed: number;
+  moved: number;
+  unchanged: number;
+  total: number;
+}
+
+export interface DomBaselineReturnedCounts {
+  added: number;
+  removed: number;
+  changed: number;
+  moved: number;
+  total: number;
+}
+
+export interface DomBaselineCompareResult {
+  baselineId: string;
+  equal: boolean;
+  comparedAt: string;
+  counts: DomBaselineChangeCounts;
+  returnedCounts: DomBaselineReturnedCounts;
+  added: DomBaselineSemanticNodeEvidence[];
+  removed: DomBaselineSemanticNodeEvidence[];
+  changed: DomBaselineChangedNode[];
+  moved: DomBaselineMovedNode[];
+  truncated: boolean;
+  omittedChanges: number;
+  ambiguity: {
+    count: number;
+    examples: DomBaselineSemanticNodeEvidence[];
+  };
+  guidance: string;
+}
+
+export interface DomBaselineReleaseResult {
+  baselineId: string;
+  released: boolean;
+}
+
 export interface DomFindResult {
   found: boolean;
   nodes: Record<string, unknown>[];
@@ -312,6 +506,10 @@ export interface CdpNodeIdParams {
   nodeId?: number;
 }
 
+export interface CdpDomSnapshotParams {
+  computedStyles?: string[];
+}
+
 export interface NormalizedCdpDispatchKeyEventParams extends BridgeParams {
   key: string;
   code: string;
@@ -322,6 +520,10 @@ export interface NormalizedCdpNodeIdParams extends BridgeParams {
   nodeId: number;
 }
 
+export interface NormalizedCdpDomSnapshotParams extends BridgeParams {
+  computedStyles: string[];
+}
+
 export interface CheckedActionParams {
   target?: InputTarget;
   checked?: boolean;
@@ -594,10 +796,31 @@ export interface NormalizedStorageParams extends BridgeParams {
   keys: string[] | null;
 }
 
+export type SensitiveStorageSource = 'local_storage' | 'session_storage';
+
+export interface SensitiveReadParams {
+  source: SensitiveStorageSource;
+  key: string;
+}
+
+export interface NormalizedSensitiveReadParams extends BridgeParams {
+  source: SensitiveStorageSource;
+  key: string;
+  maxBytes: number;
+}
+
+export interface SensitiveReadResult {
+  source: SensitiveStorageSource;
+  value: string;
+  exact: true;
+}
+
 export type ExtractContentFormat = 'text' | 'markdown';
 export type ExtractContentConsistency = 'best_effort' | 'settled';
 export type ExtractContentSource = 'readability' | 'semantic-root' | 'body';
 export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
+export type ScreenshotDelivery = 'auto' | 'inline' | 'artifact';
+export type ArtifactKind = 'screenshot' | 'har';
 
 export interface ExtractContentParams {
   format?: ExtractContentFormat;
@@ -620,22 +843,62 @@ export interface NormalizedExtractContentParams extends BridgeParams {
 export interface ScreenshotParams extends BridgeParams {
   format?: ScreenshotFormat;
   quality?: number;
+  delivery?: ScreenshotDelivery;
+  scale?: number;
 }
 
 export interface NormalizedScreenshotParams extends BridgeParams {
   format: ScreenshotFormat;
   quality: number | null;
+  delivery: ScreenshotDelivery;
+  scale: number;
 }
 
-export interface ScreenshotResult {
-  image: string;
+export interface ArtifactDescriptor<K extends ArtifactKind = ArtifactKind> {
+  artifactId: string;
+  kind: K;
+  mimeType: string;
+  byteLength: number;
+  sha256: string;
+  chunkSize: number;
+  chunkCount: number;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface ScreenshotMetadata {
   mimeType: `image/${ScreenshotFormat}`;
   format: ScreenshotFormat;
+  byteLength: number;
+  dimensions: { width: number; height: number };
   rect: { x: number; y: number; width: number; height: number; scale: number };
   complete: boolean;
   clipped: boolean;
 }
 
+export type ScreenshotResult =
+  | (ScreenshotMetadata & { delivery: 'inline'; image: string })
+  | (ScreenshotMetadata & {
+      delivery: 'artifact';
+      artifact: ArtifactDescriptor<'screenshot'>;
+    });
+
+export interface ArtifactReadParams extends BridgeParams {
+  artifactId?: string;
+  offset?: number;
+  maxBytes?: number;
+}
+
+export interface NormalizedArtifactReadParams extends BridgeParams {
+  artifactId: string;
+  offset: number;
+  maxBytes: number;
+}
+
+export interface ArtifactDeleteParams extends BridgeParams {
+  artifactId?: string;
+}
+
 export interface ExtractContentResult {
   format: ExtractContentFormat;
   content: string;
@@ -799,6 +1062,229 @@ export interface NetworkResult {
   truncation: { reason: 'limit' | null; limit: number; omitted: number };
 }
 
+export interface CdpPerformanceMetric {
+  name: string;
+  value: number;
+}
+
+export interface PerformanceMeasurement {
+  source: 'cdp.Performance.getMetrics';
+  kind: 'raw_cdp_counters';
+  sampledAt: string;
+  timeDomain: 'timeTicks';
+  observation: 'browser_maintained_point_sample';
+  webVitals: 'not_measured';
+}
+
+export interface PerformanceMetricsResult {
+  metrics: Record<string, number>;
+  measurement: PerformanceMeasurement;
+}
+
+export type HarDelivery = 'auto' | 'inline' | 'artifact';
+export type HarCaptureState = NetworkResult['captureState'];
+
+export interface HarExportParams {
+  limit?: number;
+  urlPattern?: string;
+  delivery?: HarDelivery;
+}
+
+export interface NormalizedHarExportParams extends BridgeParams {
+  limit: number;
+  urlPattern: string | null;
+  delivery: HarDelivery;
+}
+
+export interface HarEvidenceEntry extends Record<string, unknown> {
+  url: string;
+  method: string;
+  resourceType: string;
+  status: number;
+  mimeType: string;
+  protocol: string;
+  fromCache: boolean;
+  fromDiskCache: boolean;
+  fromServiceWorker: boolean;
+  fromPrefetchCache: boolean;
+  failureReason: string;
+  redirectURL: string;
+  duration: number;
+  startedAt: number;
+}
+
+export interface HarNameValue extends Record<string, unknown> {
+  name: string;
+  value: string;
+  comment?: string;
+}
+
+export interface HarCookie extends HarNameValue {
+  path?: string;
+  domain?: string;
+  expires?: string;
+  httpOnly?: boolean;
+  secure?: boolean;
+}
+
+export interface HarPostDataParam extends HarNameValue {
+  fileName?: string;
+  contentType?: string;
+}
+
+export interface HarPostData extends Record<string, unknown> {
+  mimeType: string;
+  params?: HarPostDataParam[];
+  text?: string;
+  comment?: string;
+}
+
+export interface HarRequest extends Record<string, unknown> {
+  method: string;
+  url: string;
+  httpVersion: string;
+  cookies: HarCookie[];
+  headers: HarNameValue[];
+  queryString: HarNameValue[];
+  postData?: HarPostData;
+  headersSize: number;
+  bodySize: number;
+  comment?: string;
+}
+
+export interface HarContent extends Record<string, unknown> {
+  size: number;
+  compression?: number;
+  mimeType: string;
+  text?: string;
+  encoding?: string;
+  comment?: string;
+}
+
+export interface HarResponse extends Record<string, unknown> {
+  status: number;
+  statusText: string;
+  httpVersion: string;
+  cookies: HarCookie[];
+  headers: HarNameValue[];
+  content: HarContent;
+  redirectURL: string;
+  headersSize: number;
+  bodySize: number;
+  comment?: string;
+}
+
+export interface HarCacheInfo extends Record<string, unknown> {
+  expires?: string;
+  lastAccess: string;
+  eTag: string;
+  hitCount: number;
+  comment?: string;
+}
+
+export interface HarCache extends Record<string, unknown> {
+  beforeRequest?: HarCacheInfo;
+  afterRequest?: HarCacheInfo;
+  comment?: string;
+}
+
+export interface HarTimings extends Record<string, unknown> {
+  blocked?: number;
+  dns?: number;
+  connect?: number;
+  send: number;
+  wait: number;
+  receive: number;
+  ssl?: number;
+  comment?: string;
+}
+
+export interface HarPageTimings extends Record<string, unknown> {
+  onContentLoad?: number;
+  onLoad?: number;
+  comment?: string;
+}
+
+export interface HarPage extends Record<string, unknown> {
+  startedDateTime: string;
+  id: string;
+  title: string;
+  pageTimings: HarPageTimings;
+  comment?: string;
+}
+
+export interface HarCreator extends Record<string, unknown> {
+  name: string;
+  version: string;
+  comment?: string;
+}
+
+export interface HarEntry extends Record<string, unknown> {
+  pageref?: string;
+  startedDateTime: string;
+  time: number;
+  request: HarRequest;
+  response: HarResponse;
+  cache: HarCache;
+  timings: HarTimings;
+  serverIPAddress?: string;
+  connection?: string;
+  comment?: string;
+}
+
+export interface HarLog extends Record<string, unknown> {
+  version: '1.2';
+  creator: HarCreator;
+  browser?: HarCreator;
+  pages?: HarPage[];
+  entries: HarEntry[];
+  comment?: string;
+}
+
+export interface HarDocument extends Record<string, unknown> {
+  log: HarLog;
+}
+
+export interface HarExportTruncation {
+  reason: 'limit' | 'inline_bytes' | null;
+  limit: number;
+  omitted: number;
+  omittedByLimit: number;
+  omittedBySize: number;
+}
+
+export interface HarExportMetadata {
+  format: 'har';
+  harVersion: '1.2';
+  mimeType: 'application/json';
+  byteLength: number;
+  entryCount: number;
+  totalEntries: number;
+  dropped: number;
+  abandoned: number;
+  inflight: number;
+  startedAt: number | null;
+  captureState: HarCaptureState;
+  truncated: boolean;
+  truncation: HarExportTruncation;
+}
+
+export type HarExportResult =
+  | (HarExportMetadata & { delivery: 'inline'; har: HarDocument })
+  | (HarExportMetadata & {
+      delivery: 'artifact';
+      artifact: ArtifactDescriptor<'har'>;
+    });
+
+export interface HarExportEvidence {
+  delivery: HarExportResult['delivery'];
+  entryCount: number;
+  totalEntries: number;
+  dropped: number;
+  abandoned: number;
+  inflight: number;
+}
+
 export type NetworkInterceptAction = 'fulfill' | 'continue' | 'block';
 
 export interface NetworkInterceptAddParams {