@monad-inc/embed 0.1.0

package/dist/connect/index.d.cts

@@ -0,0 +1,373 @@
+/**
+ * postMessage contract between the host page (@monad-inc/embed/connect) and
+ * the Monad-hosted iframe (@monad-inc/embed-frame).
+ *
+ * Why a protocol module: both sides must agree on message shapes, and a
+ * drifting contract is a silent failure (a message just gets ignored).
+ * @monad-inc/embed/connect owns it because it's the public-facing SDK; the
+ * iframe app imports these types from here.
+ *
+ * Security model:
+ *  - Origin is the real boundary. Every listener validates
+ *    `event.origin` against an expected value before trusting a
+ *    message. The iframe knows its parent's origin (passed as a URL
+ *    param); the host knows the frame's origin (it chose it).
+ *  - `event.source` is also checked host-side so a sibling iframe on
+ *    the same origin can't impersonate ours.
+ *  - The `source: 'monad-embed'` tag is NOT security — it's just a
+ *    cheap filter so unrelated postMessage traffic (analytics SDKs,
+ *    devtools, wallet extensions) is ignored without parsing.
+ *  - The session token travels in the `init` message body, never in
+ *    the iframe URL, so it stays out of browser history and Referer.
+ */
+declare const PROTOCOL_SOURCE: "monad-embed";
+declare const PROTOCOL_VERSION: 1;
+type ComponentKind = 'input' | 'output';
+/**
+ * Appearance tokens the host may pass to theme the iframe. The iframe
+ * applies each as a `--monad-{token}` CSS variable. The host cannot
+ * style across the iframe boundary directly (same-origin policy), so
+ * this is the only theming channel — same idea as Stripe's `appearance`.
+ */
+interface Appearance {
+    colorPrimary?: string;
+    colorText?: string;
+    colorBackground?: string;
+    colorBorder?: string;
+    fontFamily?: string;
+    borderRadius?: string;
+}
+interface ReadyMessage {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'ready';
+    version: number;
+}
+interface ResizeMessage {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'resize';
+    /** Content height in CSS pixels — the host sizes the <iframe> to this. */
+    height: number;
+}
+interface SavedMessage {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'saved';
+    /** Safe reference to the created/updated connector — no secret material. */
+    connector: {
+        id: string;
+        name?: string;
+    };
+}
+interface ErrorMessage {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'error';
+    message: string;
+}
+interface CancelMessage {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'cancel';
+}
+type FrameMessage = ReadyMessage | ResizeMessage | SavedMessage | ErrorMessage | CancelMessage;
+interface InitMessage {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'init';
+    version: number;
+    /** Short-lived embed session token minted by the host's backend. */
+    sessionToken: string;
+    /** Monad API base, e.g. "https://api.monad.com" or dev "http://localhost/api". */
+    apiBase: string;
+    /**
+     * Team org id the session token is scoped to. The iframe uses this to
+     * build `/v1/<org>/*` and `/v2/<org>/*` URLs. Must match the token's
+     * `org` claim — server-side `org_access.Middleware` will 403 if not.
+     */
+    organizationId: string;
+    /** Connector type id, e.g. "runzero-findings". */
+    typeId: string;
+    kind: ComponentKind;
+    /** Display name shown in the frame header. */
+    displayName?: string;
+    /** Existing connector id — present for edit mode, absent for create. */
+    existingId?: string;
+    /**
+     * Whether the synthetic-data toggle is exposed in the form. Defaults
+     * to `false` (toggle hidden). Production embed customers keep this
+     * off — synthetic mode is a Monad-internal testing affordance.
+     */
+    synthetic?: boolean;
+    /** Theming tokens applied as CSS variables inside the iframe. */
+    appearance?: Appearance;
+    /**
+     * Stylesheet URLs the host wants to apply to the iframe page. The
+     * iframe loads these as `<link rel="stylesheet">` tags before
+     * rendering the form.
+     *
+     * All-or-nothing: if this array is present and non-empty, the
+     * iframe loads ONLY these stylesheets and does NOT load its
+     * built-in Monad UI defaults. If it's absent or empty, the iframe
+     * loads the built-in defaults and nothing else. Mixing host CSS
+     * with the defaults is intentionally not supported — partial
+     * styling tends to produce confusing half-themed forms.
+     *
+     * URLs MUST be reachable from the iframe origin (typically by
+     * being served from the host page's own origin, which the browser
+     * permits for stylesheet `<link>` loads even cross-origin).
+     */
+    stylesheets?: string[];
+}
+type HostMessage = InitMessage;
+
+/**
+ * Connector-lifecycle helpers — the "wiring harness" a host (Okta, in
+ * the demo's fiction) drops into its own backend to power Disable /
+ * Enable / Delete buttons in its own UI.
+ *
+ * Unlike createConnectorFrame (browser-only), these are isomorphic:
+ * they just sequence Monad's standard `/v2/{org}/*` + `/v1/{org}/*`
+ * API calls. They run wherever the host holds its API key — almost
+ * always its backend.
+ *
+ * The host supplies a `MonadRequest` thunk that performs an
+ * authenticated request and returns parsed JSON. The harness owns the
+ * non-obvious parts: which endpoint + verb each action maps to, the
+ * delete ordering (pipeline before the input/output it references),
+ * and resolving an input id to its pipeline without the host having to
+ * store that mapping.
+ */
+/**
+ * Authenticated request against the Monad API, returning parsed JSON
+ * (or undefined for empty responses). The host implements this with
+ * its long-lived API key and base URL. Path is the full API path,
+ * e.g. `/v2/{org}/pipelines/{id}`.
+ */
+type MonadRequest = (path: string, init?: RequestInit) => Promise<any>;
+/**
+ * Where an integration's resources live and their current state.
+ * Returned by findIntegrationPipeline so the host can act on an
+ * integration knowing only the input id.
+ */
+interface ResolvedIntegration {
+    org: string;
+    pipelineId: string;
+    /** Whether the pipeline is currently enabled. */
+    enabled: boolean;
+    inputId: string;
+    /** Output id of the pipeline's destination node, if it has one. */
+    outputId?: string;
+}
+/**
+ * Find the pipeline an input feeds. Lets the host act on an integration
+ * (disable/enable/delete) knowing only the input id — no need to
+ * persist an input→pipeline map of its own.
+ *
+ * The pipelines list is slim (no node wiring), so this fetches each
+ * pipeline's detail and scans for the input node. Fine for the modest
+ * pipeline counts a single tenant team has; a host managing many
+ * pipelines per team should instead persist the `pipelineId`
+ * buildDevNullPipeline returns and skip the lookup.
+ *
+ * Returns null when the input has no pipeline.
+ */
+declare function findIntegrationPipeline(opts: {
+    request: MonadRequest;
+    org: string;
+    inputId: string;
+}): Promise<ResolvedIntegration | null>;
+interface SetEnabledOptions {
+    request: MonadRequest;
+    org: string;
+    pipelineId: string;
+    /** true → resume processing, false → stop (config is kept either way). */
+    enabled: boolean;
+}
+/**
+ * Enable or disable an integration's pipeline. Disabling stops data
+ * flowing but destroys nothing — the input, output, and pipeline
+ * config all survive, so a later enable resumes it as it was.
+ *
+ * The pipeline PATCH endpoint replaces the whole config rather than
+ * accepting a partial, so this reads the current pipeline and sends it
+ * back with only the `enabled` flag flipped.
+ *
+ * Race warning: this is GET-then-PATCH on the same resource, so a
+ * concurrent edit between the two requests gets clobbered. Fine for
+ * human-driven toggles. If you call this from automation, fan-out, or
+ * a retry loop, ask the API team for a server-side `{ enabled }`
+ * partial PATCH instead — the round-trip we do here is only a
+ * workaround for the current full-config replace semantics.
+ */
+declare function setIntegrationEnabled(opts: SetEnabledOptions): Promise<void>;
+/** Convenience: disable the pipeline (stop without deleting). */
+declare function disableIntegration(opts: Omit<SetEnabledOptions, 'enabled'>): Promise<void>;
+/** Convenience: re-enable a disabled pipeline. */
+declare function enableIntegration(opts: Omit<SetEnabledOptions, 'enabled'>): Promise<void>;
+/**
+ * Which resources a delete removes. An embed integration is a pipeline
+ * + an input + (in the dev/null flow) an output — but hosts provision
+ * and own tenant resources differently. Some keep a shared output,
+ * some keep the input so it can be re-wired later, some only ever tear
+ * down the pipeline. Choose the policy that matches how you provision;
+ * a flag left undefined defaults to `true` (delete it).
+ *
+ * Three ready-made policies are exported — CLEANUP_FULL,
+ * CLEANUP_KEEP_OUTPUT, CLEANUP_PIPELINE_ONLY — or pass your own.
+ */
+interface CleanupPolicy {
+    /** Delete the pipeline. Default: true. */
+    pipeline?: boolean;
+    /** Delete the input connector. Default: true. */
+    input?: boolean;
+    /** Delete the output connector. Default: true. */
+    output?: boolean;
+}
+/** Tear down everything — pipeline, input, and output. */
+declare const CLEANUP_FULL: CleanupPolicy;
+/** Remove the pipeline and input but keep the output (e.g. a shared sink). */
+declare const CLEANUP_KEEP_OUTPUT: CleanupPolicy;
+/** Remove only the pipeline; keep the input so it can be re-wired. */
+declare const CLEANUP_PIPELINE_ONLY: CleanupPolicy;
+interface DeleteIntegrationOptions {
+    request: MonadRequest;
+    org: string;
+    /** Pipeline to remove. Omit when the input has no pipeline. */
+    pipelineId?: string;
+    /** Input to remove. Omit to leave it. */
+    inputId?: string;
+    /** Output to remove (the auto-created dev/null sink). Omit to leave it. */
+    outputId?: string;
+    /**
+     * What to actually delete. Defaults to everything supplied
+     * (CLEANUP_FULL). Set a flag false to keep that resource even when
+     * its id is provided.
+     */
+    cleanup?: CleanupPolicy;
+}
+/**
+ * Delete an integration per a cleanup policy. Order matters: the
+ * pipeline references the input and output, so it goes first. Only
+ * resources whose id is supplied AND whose policy flag is true are
+ * removed — so nothing the host wants to keep is touched, and nothing
+ * it wants gone is left orphaned.
+ */
+declare function deleteIntegration(opts: DeleteIntegrationOptions): Promise<void>;
+interface BuildDevNullPipelineOptions {
+    request: MonadRequest;
+    org: string;
+    inputId: string;
+    /** Used to name the auto-created output and pipeline. */
+    inputName: string;
+    /** Status polls before giving up (default 15, ~2s apart). */
+    pollAttempts?: number;
+}
+interface BuiltPipeline {
+    pipelineId: string;
+    outputId: string;
+    status: string;
+    /** True once the pipeline reports Running. */
+    active: boolean;
+}
+/**
+ * Stand up a dev/null pipeline for a freshly-configured input: create a
+ * dev/null output, create an enabled pipeline wiring input → output,
+ * then poll until it reports Running. The POC's "what happens after an
+ * input is configured" path, packaged as a reusable harness call.
+ */
+declare function buildDevNullPipeline(opts: BuildDevNullPipelineOptions): Promise<BuiltPipeline>;
+
+/**
+ * @monad-inc/embed/connect — host-side SDK for embedding Monad's
+ * connector-config UI as a secure iframe.
+ *
+ * The customer's page calls `createConnectorFrame()`; this injects an
+ * <iframe> pointing at a Monad-hosted page (@monad-inc/embed-frame). The
+ * connector form — and every secret the user types into it — runs
+ * inside that iframe on Monad's origin. Same-origin policy means the
+ * customer's own JavaScript can never read those secrets. The customer
+ * gets back only a connector id (a safe reference), the same way a
+ * Stripe integration only ever sees a `pm_…` token.
+ *
+ * The host is still responsible for one thing: minting a short-lived
+ * embed session token from its backend (POST /v1/embed/sessions, with
+ * the long-lived API key) and handing it to `createConnectorFrame`.
+ * That token travels into the iframe over postMessage, never the URL.
+ */
+
+interface ConnectorFrameOptions {
+    /** DOM node (or selector) the iframe is appended to. */
+    container: HTMLElement | string;
+    /**
+     * URL of the Monad embed-frame page. Defaults to
+     * "https://app.monad.com/embed" (production). Override for staging
+     * ("https://app.monad.security/embed") or local testing
+     * ("http://localhost:5173/embed"). MUST be a different origin than
+     * the host page — that cross-origin boundary is what isolates the
+     * secrets. A path component is allowed (so the embed page can live
+     * at a sub-route of the main app); the postMessage security checks
+     * compare against the URL's origin, not its full href.
+     */
+    frameOrigin?: string;
+    /**
+     * Monad API base the iframe should call. Defaults to
+     * "https://app.monad.com/api" (production). Override for non-prod
+     * environments. Set this together with `frameOrigin` — mixing
+     * environments will not work.
+     */
+    apiBase?: string;
+    /** Connector type id, e.g. "runzero-findings". */
+    typeId: string;
+    kind: ComponentKind;
+    /** Short-lived embed session token (host backend mints it). */
+    sessionToken: string;
+    /**
+     * Team org id the session is scoped to. The host backend already knows
+     * this — it's the same value passed to `/v1/embed/sessions` when minting
+     * the token. Forwarded into the iframe so it can build `/v1/<org>/*` and
+     * `/v2/<org>/*` URLs.
+     */
+    organizationId: string;
+    /** Display name shown in the frame header. */
+    displayName?: string;
+    /** Existing connector id — pass for edit mode, omit to create. */
+    existingId?: string;
+    /**
+     * Whether the synthetic-data toggle is exposed in the form. Defaults
+     * to `false` — production embed flows keep it hidden.
+     */
+    synthetic?: boolean;
+    /** Theming tokens applied as CSS variables inside the iframe. */
+    appearance?: Appearance;
+    /**
+     * Stylesheet URLs to apply inside the iframe. All-or-nothing: if
+     * any URL is provided, the iframe loads ONLY these and skips its
+     * built-in Monad UI defaults; if omitted/empty, the iframe loads
+     * the defaults and nothing else. URLs must be reachable from the
+     * iframe — typically served by the host page's own origin.
+     */
+    stylesheets?: string[];
+    /** Fired when the user saves successfully. */
+    onSave?: (connector: {
+        id: string;
+        name?: string;
+    }) => void;
+    /** Fired when the user cancels. */
+    onCancel?: () => void;
+    /** Fired on a save/test/load failure inside the iframe. */
+    onError?: (message: string) => void;
+}
+interface ConnectorFrame {
+    /** Remove the iframe and stop listening for its messages. */
+    destroy(): void;
+}
+/**
+ * Inject the Monad connector iframe into `container` and wire the
+ * postMessage channel. Returns a handle whose `destroy()` tears it all
+ * down.
+ *
+ * Handshake:
+ *  1. iframe loads, posts `ready`;
+ *  2. host replies with `init` (session token, type, appearance);
+ *  3. iframe mounts the form and streams `resize` as content grows;
+ *  4. on save, iframe posts `saved {connector}`; on cancel, `cancel`.
+ */
+declare function createConnectorFrame(opts: ConnectorFrameOptions): ConnectorFrame;
+
+export { type Appearance, type BuildDevNullPipelineOptions, type BuiltPipeline, CLEANUP_FULL, CLEANUP_KEEP_OUTPUT, CLEANUP_PIPELINE_ONLY, type CleanupPolicy, type ComponentKind, type ConnectorFrame, type ConnectorFrameOptions, type DeleteIntegrationOptions, type FrameMessage, type HostMessage, type InitMessage, type MonadRequest, PROTOCOL_SOURCE, PROTOCOL_VERSION, type ResolvedIntegration, type SetEnabledOptions, buildDevNullPipeline, createConnectorFrame, deleteIntegration, disableIntegration, enableIntegration, findIntegrationPipeline, setIntegrationEnabled };