@appfunnel-dev/sdk 2.0.0-canary.1 → 2.0.0-canary.10

package/dist/chunk-ZZJG4EYL.js

@@ -0,0 +1,6 @@
+// src/protocol/index.ts
+var AF_PROTOCOL = 1;
+
+export { AF_PROTOCOL };
+//# sourceMappingURL=chunk-ZZJG4EYL.js.map
+//# sourceMappingURL=chunk-ZZJG4EYL.js.map

package/dist/chunk-ZZJG4EYL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol/index.ts"],"names":[],"mappings":";AAsBO,IAAM,WAAA,GAAc","file":"chunk-ZZJG4EYL.js","sourcesContent":["/**\n * The **Funnel Embed API** wire protocol — the versioned contract for the cross-origin channel\n * between a host (the editor today; 3rd-party embedders later) and a funnel running in a frame.\n *\n * Side-effect-free and (almost) type-only: import it from `@appfunnel-dev/sdk/protocol` on BOTH\n * ends — the funnel side (SDK `EmbedBridge`) and the host side (`@appfunnel/embed` / the dashboard)\n * — so the two can never drift. The runtime that carries these types (the RPC dispatcher, the\n * bridge, the host client) lives elsewhere; this file is just the shared shapes.\n *\n * Two message families ride one envelope:\n *  - **methods** — request/response, `id`-correlated (needed the moment anything returns data, e.g.\n *    `screenshot`). Host → funnel.\n *  - **events** — fire-and-forget notifications. Funnel → host (e.g. `navigation`).\n * A `hello` handshake advertises the protocol major + capability set so an older funnel (pinned to\n * an older SDK via esm.sh) degrades gracefully instead of hanging on an unknown method.\n */\n\n/**\n * Wire-format major. **Frozen** — bump ONLY on a breaking envelope change, which the design tries to\n * make never happen (new capabilities are new `method`/`event` names, not new envelope shapes). A\n * receiver drops any message whose `af` major it doesn't speak.\n */\nexport const AF_PROTOCOL = 1 as const\n\n/**\n * Trust-direction tag — the ONLY vocabulary the preview-host relay gates on (besides origin). **Frozen**:\n * these strings are compiled into every sealed funnel build, so they are renamed NEVER; the protocol\n * evolves via `af`/`kind`/`method`, not by re-tagging. `af-host` = from the host/parent (dashboard/\n * embedder); `af-preview` = from the funnel/embed (the child frame).\n */\nexport type EnvelopeSource = 'af-host' | 'af-preview'\n\ninterface BaseEnvelope {\n  /** Wire-format major — see {@link AF_PROTOCOL}. */\n  af: typeof AF_PROTOCOL\n  /** Who sent it (trust direction). */\n  source: EnvelopeSource\n}\n\n/** Host → funnel: invoke a method. Correlate the reply by `id`. */\nexport interface RequestMessage<M extends MethodName = MethodName> extends BaseEnvelope {\n  kind: 'request'\n  id: string\n  method: M\n  params: MethodParams<M>\n}\n\n/** Funnel → host: the reply to a {@link RequestMessage}, echoing its `id`. */\nexport interface ResponseMessage extends BaseEnvelope {\n  kind: 'response'\n  id: string\n  ok: boolean\n  result?: unknown\n  error?: EmbedError\n}\n\n/** Funnel → host: a fire-and-forget notification (no `id`, lossy-tolerant). */\nexport interface EventMessage<E extends EventName = EventName> extends BaseEnvelope {\n  kind: 'event'\n  event: E\n  data: EventData<E>\n}\n\n/** Either side on connect: announce protocol major + capabilities (see the handshake note above). */\nexport interface HelloMessage extends BaseEnvelope {\n  kind: 'hello'\n  role: 'funnel' | 'host'\n  /** Wire major this end speaks (== `af`). Negotiated dialect = min of both ends. */\n  protocol: number\n  /** Diagnostics only (e.g. '2.0.0-canary.5'). Never gate behavior on this — use `capabilities`. */\n  sdkVersion?: string\n  capabilities: Capabilities\n}\n\nexport type EmbedMessage = RequestMessage | ResponseMessage | EventMessage | HelloMessage\n\nexport interface EmbedError {\n  code: 'unknown_method' | 'bad_params' | 'not_allowed' | 'failed' | 'timeout'\n  message: string\n}\n\n// ── Capability registries ────────────────────────────────\n// Adding a capability = one entry here (+ its handler). No envelope change, no relay change.\n\n/** Host → funnel request/response methods, namespaced by domain. */\nexport interface Methods {\n  /** Current flow position (replaces the old fire-and-forget `nav-request`). */\n  'nav.snapshot': { params: void; result: NavSnapshot }\n  /** Jump to a page key. Resolves when accepted (unknown key → `bad_params` error); the resulting\n   *  position arrives as a `navigation` event, since the funnel navigates asynchronously. */\n  'nav.goTo': { params: { key: string }; result: void }\n  'nav.goNext': { params: void; result: void }\n  'nav.goPrevious': { params: void; result: void }\n  /** Capture the running funnel to an image (see {@link ScreenshotParams}). */\n  screenshot: { params: ScreenshotParams; result: ScreenshotResult }\n}\n\n/** Funnel → host fire-and-forget events. */\nexport interface Events {\n  /** The flow moved — pushed on every page change (incl. the initial page). Always on. */\n  navigation: NavSnapshot\n}\n\nexport type MethodName = keyof Methods\nexport type MethodParams<M extends MethodName> = Methods[M]['params']\nexport type MethodResult<M extends MethodName> = Methods[M]['result']\nexport type EventName = keyof Events\nexport type EventData<E extends EventName> = Events[E]\n\n/** What an end implements — a SET of tokens (a funnel can be on any historical SDK), not a version int. */\nexport interface Capabilities {\n  methods: MethodName[]\n  events: EventName[]\n}\n\n// ── Shared data shapes ───────────────────────────────────\n\n/** A live snapshot of the funnel's flow position — the single source of truth for both surfaces. */\nexport interface NavSnapshot {\n  /** Current page key. */\n  key: string\n  /** Zero-based position in the visitor's traversed path. */\n  index: number\n  /** Expected total steps on the branch the current answers imply. */\n  total: number\n  /** 0..100 progress along that expected path (matches PageContext.progressPercentage). */\n  progressPercentage: number\n  /** Whether `nav.goPrevious` would move. */\n  canGoBack: boolean\n  /** Page keys the visitor could advance to next. */\n  nextCandidates: string[]\n}\n\n/** What region of the funnel to capture. Default `{ kind: 'page' }` (the funnel root, full height). */\nexport type ScreenshotTarget =\n  | { kind: 'page' }\n  | { kind: 'viewport' }\n  | { kind: 'selector'; selector: string }\n\nexport interface ScreenshotParams {\n  target?: ScreenshotTarget\n  /** Encoded image format. Default 'png'. */\n  format?: 'png' | 'jpeg' | 'webp'\n  /** Lossy quality 0..1 for jpeg/webp (ignored for png). Default 0.92. */\n  quality?: number\n  /** How the bytes cross postMessage. Default 'blob' (no base64 inflation across the two-hop relay). */\n  encoding?: 'blob' | 'dataURL'\n  /** Device-pixel scale. Default 2 (deterministic, NOT the live devicePixelRatio). Clamped to `maxScale`. */\n  scale?: number\n  /** Upper bound on `scale` (bounds payload size). Default 3. */\n  maxScale?: number\n  /** Explicit output box in CSS px (pre-scale). Default = the target's rendered box. */\n  width?: number\n  height?: number\n  /** Painted under transparent regions. Default '#ffffff'. `null` → transparent (png/webp only). */\n  backgroundColor?: string | null\n  /** await document.fonts.ready before capture. Default true. */\n  waitForFonts?: boolean\n  /** await in-tree images decoding + inline them. Default true. */\n  waitForImages?: boolean\n  /** Scroll the target through its height first to trigger lazy/IO images (restores scroll). Default false. */\n  triggerLazyLoad?: boolean\n  /** Selectors hidden during capture (dev overlays, the \"compiling…\" chip, cursors). Default []. */\n  hideSelectors?: string[]\n  /** Hard cap (ms) on the whole capture incl. asset waits. Default 10000. */\n  timeout?: number\n}\n\nexport interface ScreenshotResult {\n  mime: string\n  /** Produced pixel dimensions (post-scale). */\n  width: number\n  height: number\n  /** The scale actually used (after the maxScale clamp). */\n  scale: number\n  /** Payload size, for the caller to guard / for telemetry. */\n  bytesApprox: number\n  /** Exactly one of these is set, per `params.encoding`. */\n  blob?: Blob\n  dataURL?: string\n}\n"]}