@abloatai/transaction 0.37.0

package/dist/source/connector.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Opens the connector's side of the Data Source reverse channel. You run this
+ * process next to your database; it dials an outbound WebSocket to Ablo and serves
+ * the load, list, and commit requests over that socket, so a handler with no
+ * public URL never needs to receive inbound webhooks. It is the counterpart to
+ * `createPushQueue`, which gives the outbound events feed the same treatment, and
+ * it speaks the frames defined in `connectorProtocol.ts`.
+ *
+ * The connector reimplements none of the handler logic. It wraps the same
+ * `(request: Request) => Promise<Response>` your deployed route already uses:
+ *
+ *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
+ *   import { sourceOptions } from './ablo.source'; // shared with route.ts
+ *
+ *   const connector = createSourceConnector({
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     handler: dataSource(sourceOptions),
+ *   });
+ *   await connector.run(controller.signal);
+ *
+ * Each incoming `request` frame is replayed into a `Request` that carries the
+ * original signature headers, so the handler verifies it through the same
+ * `verifyAbloSourceRequest` it uses on the webhook path. The transport changes;
+ * the trust model does not.
+ */
+/**
+ * The reconnect backoff, in milliseconds, indexed by the number of consecutive
+ * failed connect attempts. A long-lived control socket should recover quickly and
+ * then settle at a steady interval, so this is a short curve that caps rather than
+ * growing without bound. The final entry repeats for any further attempts, and a
+ * connection that reaches `ready` resets the count to zero.
+ */
+export declare const DEFAULT_RECONNECT_SCHEDULE: readonly number[];
+/**
+ * The minimal WebSocket surface the connector needs, matching the standard
+ * `globalThis.WebSocket` API that browsers and current Node versions provide. The
+ * `ws` package's default export also satisfies it. Supply your own implementation
+ * to substitute a fake in tests.
+ */
+export interface ConnectorWebSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    addEventListener(type: 'open', listener: () => void): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', listener: (event: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: 'error', listener: (event: unknown) => void): void;
+}
+export type ConnectorWebSocketFactory = (url: string, protocols: readonly string[]) => ConnectorWebSocket;
+/** Lifecycle of the connector's socket, surfaced via `onStatus`. */
+export type ConnectorStatus = 'connecting' | 'ready' | 'disconnected';
+export interface SourceConnectorOptions {
+    /**
+     * Your Ablo project API key. A test key (`sk_test_*`) works by default for local
+     * development and sandboxes; a live key (`sk_live_*`) is accepted only once the
+     * source has opted the reverse channel in for production use.
+     */
+    readonly apiKey: string;
+    /**
+     * The Data Source handler to serve, as returned by `dataSource(options)`.
+     * The connector feeds it each request and relays the response back untouched;
+     * it never inspects or alters either one.
+     */
+    readonly handler: (request: Request) => Promise<Response>;
+    /** The Ablo base URL to dial. Defaults to `https://api.abloatai.com`. */
+    readonly baseURL?: string;
+    /** Inject a WebSocket implementation. Default `globalThis.WebSocket`. */
+    readonly webSocket?: ConnectorWebSocketFactory;
+    /** Override reconnect backoff. Default `DEFAULT_RECONNECT_SCHEDULE`. */
+    readonly reconnectSchedule?: readonly number[];
+    /** Random jitter on reconnect delays. Default ±10%. Set 0 to disable. */
+    readonly jitter?: number;
+    /** Advisory client id sent in the `register` frame for server-side logs. */
+    readonly client?: string;
+    /** Pluggable clock (tests). */
+    readonly now?: () => number;
+    /** Observe connection lifecycle transitions. */
+    readonly onStatus?: (status: ConnectorStatus) => void;
+    /** Observe non-fatal errors (decode failures, handler throws, socket errors). */
+    readonly onError?: (error: unknown) => void;
+}
+export interface SourceConnector {
+    /**
+     * Runs the connect, serve, and reconnect loop until `signal` aborts, then
+     * resolves. It rejects only on a fatal condition that cannot be retried, such as
+     * no WebSocket implementation being available.
+     */
+    run(signal: AbortSignal): Promise<void>;
+}
+export declare function createSourceConnector(options: SourceConnectorOptions): SourceConnector;
+//# sourceMappingURL=connector.d.ts.map

package/dist/source/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../src/source/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAsBH;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAOvD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC3C,IAAI,CAAC;IACR,gBAAgB,CACd,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAC5D,IAAI,CAAC;IACR,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;CAC3E;AAED,MAAM,MAAM,yBAAyB,GAAG,CACtC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,SAAS,MAAM,EAAE,KACzB,kBAAkB,CAAC;AAExB,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,OAAO,GAAG,cAAc,CAAC;AAEtE,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1D,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,yBAAyB,CAAC;IAC/C,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IACtD,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CAgCjB"}

package/dist/source/connector.js

@@ -0,0 +1,267 @@
+/**
+ * Opens the connector's side of the Data Source reverse channel. You run this
+ * process next to your database; it dials an outbound WebSocket to Ablo and serves
+ * the load, list, and commit requests over that socket, so a handler with no
+ * public URL never needs to receive inbound webhooks. It is the counterpart to
+ * `createPushQueue`, which gives the outbound events feed the same treatment, and
+ * it speaks the frames defined in `connectorProtocol.ts`.
+ *
+ * The connector reimplements none of the handler logic. It wraps the same
+ * `(request: Request) => Promise<Response>` your deployed route already uses:
+ *
+ *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
+ *   import { sourceOptions } from './ablo.source'; // shared with route.ts
+ *
+ *   const connector = createSourceConnector({
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     handler: dataSource(sourceOptions),
+ *   });
+ *   await connector.run(controller.signal);
+ *
+ * Each incoming `request` frame is replayed into a `Request` that carries the
+ * original signature headers, so the handler verifies it through the same
+ * `verifyAbloSourceRequest` it uses on the webhook path. The transport changes;
+ * the trust model does not.
+ */
+import { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, } from './connectorProtocol.js';
+import { ABLO_HOSTED_HTTP_BASE_URL } from '../auth/hostedEndpoints.js';
+/**
+ * The default Ablo base URL the connector dials, to which it appends
+ * `SOURCE_CONNECTOR_WS_PATH`.
+ */
+const DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;
+/**
+ * The reconnect backoff, in milliseconds, indexed by the number of consecutive
+ * failed connect attempts. A long-lived control socket should recover quickly and
+ * then settle at a steady interval, so this is a short curve that caps rather than
+ * growing without bound. The final entry repeats for any further attempts, and a
+ * connection that reaches `ready` resets the count to zero.
+ */
+export const DEFAULT_RECONNECT_SCHEDULE = [
+    0, // immediate first reconnect
+    1_000, // 1s
+    2_000, // 2s
+    5_000, // 5s
+    10_000, // 10s
+    30_000, // 30s (steady state)
+];
+export function createSourceConnector(options) {
+    const baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const url = toWebSocketUrl(baseURL) + SOURCE_CONNECTOR_WS_PATH;
+    const schedule = options.reconnectSchedule ?? DEFAULT_RECONNECT_SCHEDULE;
+    const jitter = options.jitter ?? 0.1;
+    const factory = options.webSocket ?? defaultWebSocketFactory;
+    return {
+        async run(signal) {
+            let attempt = 0;
+            while (!signal.aborted) {
+                const delay = backoffFor(schedule, attempt, jitter);
+                if (delay > 0)
+                    await sleep(delay, signal);
+                if (signal.aborted)
+                    return;
+                options.onStatus?.('connecting');
+                const becameReady = await connectOnce({
+                    url,
+                    apiKey: options.apiKey,
+                    handler: options.handler,
+                    factory,
+                    client: options.client,
+                    onStatus: options.onStatus,
+                    onError: options.onError,
+                    signal,
+                });
+                // A connection that reached `ready` resets the backoff so the next
+                // drop reconnects immediately; one that never readied keeps escalating.
+                attempt = becameReady ? 0 : attempt + 1;
+            }
+        },
+    };
+}
+/**
+ * Runs one connection: open the socket, register, then serve requests until the
+ * socket closes or `signal` aborts. Resolves to whether the connection reached the
+ * `ready` state, which the caller uses to reset the reconnect backoff. It never
+ * rejects, because a dropped transport is expected and simply drives a reconnect.
+ */
+function connectOnce(params) {
+    return new Promise((resolve) => {
+        let ws;
+        try {
+            ws = params.factory(params.url, sourceConnectorSubprotocols(params.apiKey));
+        }
+        catch (err) {
+            params.onError?.(err);
+            resolve(false);
+            return;
+        }
+        let ready = false;
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            params.signal.removeEventListener('abort', onAbort);
+            params.onStatus?.('disconnected');
+            resolve(ready);
+        };
+        const onAbort = () => {
+            try {
+                ws.close(1000, 'connector_aborted');
+            }
+            catch {
+                // Already closing/closed.
+            }
+            finish();
+        };
+        params.signal.addEventListener('abort', onAbort, { once: true });
+        ws.addEventListener('open', () => {
+            send(ws, {
+                type: 'register',
+                protocolVersion: SOURCE_CONNECTOR_PROTOCOL_VERSION,
+                ...(params.client ? { client: params.client } : {}),
+            });
+        });
+        ws.addEventListener('message', (event) => {
+            let frame;
+            try {
+                frame = decodeFrame(event.data);
+            }
+            catch (err) {
+                params.onError?.(err instanceof ConnectorProtocolError
+                    ? err
+                    : new ConnectorProtocolError(String(err)));
+                return;
+            }
+            handleFrame(frame);
+        });
+        ws.addEventListener('error', (event) => {
+            params.onError?.(event);
+            // `close` always follows `error`; finish() runs there.
+        });
+        ws.addEventListener('close', () => {
+            finish();
+        });
+        function handleFrame(frame) {
+            switch (frame.type) {
+                case 'ready':
+                    handleReady(frame);
+                    return;
+                case 'request':
+                    // Do not await — serve each request concurrently so a slow handler
+                    // never blocks draining the next frame off the socket.
+                    void serveRequest(frame);
+                    return;
+                case 'error':
+                    params.onError?.(new ConnectorProtocolError(`${frame.code}: ${frame.message}`));
+                    return;
+                // `register`/`response` are connector→server only; ignore if echoed.
+                case 'register':
+                case 'response':
+                    return;
+            }
+        }
+        function handleReady(frame) {
+            if (frame.protocolVersion !== SOURCE_CONNECTOR_PROTOCOL_VERSION) {
+                params.onError?.(new ConnectorProtocolError(`Server protocol version ${frame.protocolVersion} != ${SOURCE_CONNECTOR_PROTOCOL_VERSION}`));
+                try {
+                    ws.close(1002, 'protocol_version_mismatch');
+                }
+                catch {
+                    // closing
+                }
+                return;
+            }
+            ready = true;
+            params.onStatus?.('ready');
+        }
+        async function serveRequest(frame) {
+            const response = await runHandler(frame);
+            // Best-effort: if the socket dropped while the handler ran, the server
+            // times the request out and the SDK retries — same as a webhook timeout.
+            send(ws, response);
+        }
+        async function runHandler(frame) {
+            try {
+                const request = new Request(frame.url, {
+                    method: frame.method,
+                    headers: frame.headers,
+                    body: frame.body,
+                });
+                const result = await params.handler(request);
+                const body = await result.text();
+                return {
+                    type: 'response',
+                    id: frame.id,
+                    status: result.status,
+                    body,
+                };
+            }
+            catch (err) {
+                params.onError?.(err);
+                // Surface this as a 500 so Ablo treats it as a retryable failure, exactly
+                // as it would a webhook endpoint that threw.
+                return {
+                    type: 'response',
+                    id: frame.id,
+                    status: 500,
+                    body: JSON.stringify({
+                        error: 'source_connector_handler_error',
+                        message: err instanceof Error ? err.message : String(err),
+                    }),
+                };
+            }
+        }
+        function send(socket, frame) {
+            try {
+                socket.send(encodeFrame(frame));
+            }
+            catch (err) {
+                params.onError?.(err);
+            }
+        }
+    });
+}
+function defaultWebSocketFactory(url, protocols) {
+    const Ctor = globalThis.WebSocket;
+    if (!Ctor) {
+        throw new Error('No global WebSocket available. Pass `webSocket` (e.g. the `ws` package) to createSourceConnector.');
+    }
+    return new Ctor(url, protocols);
+}
+/** `http(s)://` → `ws(s)://`. Leaves an explicit `ws(s)` scheme untouched. */
+function toWebSocketUrl(baseURL) {
+    if (baseURL.startsWith('https://'))
+        return `wss://${baseURL.slice('https://'.length)}`;
+    if (baseURL.startsWith('http://'))
+        return `ws://${baseURL.slice('http://'.length)}`;
+    return baseURL;
+}
+function backoffFor(schedule, attempt, jitter) {
+    if (attempt <= 0)
+        return 0;
+    const base = schedule[Math.min(attempt, schedule.length - 1)] ?? 0;
+    if (jitter <= 0 || base === 0)
+        return base;
+    const swing = base * jitter;
+    return Math.max(0, base + (Math.random() * 2 - 1) * swing);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=connector.js.map

package/dist/source/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/source/connector.ts"],"names":[],"mappings":"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"}

package/dist/source/connectorProtocol.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The wire protocol for the Data Source reverse channel — the frames that travel
+ * over the WebSocket a connector opens to Ablo.
+ *
+ * The load, list, and commit leg of a Data Source normally arrives as an inbound
+ * webhook that Ablo posts to your HTTPS endpoint. That needs a public URL, so it
+ * cannot reach a handler running on localhost or inside a private network with no
+ * inbound path. The reverse channel flips the direction: the connector dials out
+ * to Ablo over a WebSocket and serves those same requests back over the open
+ * socket. This module defines the frames exchanged on that socket.
+ *
+ * The trust model does not change. A `request` frame carries the same signature
+ * headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and the same
+ * raw body Ablo would have posted, so the connector verifies it through
+ * `verifyAbloSourceRequest` exactly as it would a webhook. Only the transport
+ * differs.
+ *
+ * Frames are validated with Zod as they arrive, the same discipline `contract.ts`
+ * applies to change sets: a malformed frame is rejected at the boundary, and both
+ * sides infer every wire type from one schema so they cannot silently drift.
+ */
+import { z } from 'zod';
+/**
+ * The wire-protocol version. It increases on any breaking change to a frame's
+ * shape, so a connector and server on mismatched versions fail fast during
+ * `register` rather than misparsing a frame later in the stream.
+ */
+export declare const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
+/** The WebSocket path the connector dials, appended to its configured base URL. */
+export declare const SOURCE_CONNECTOR_WS_PATH = "/v1/source/listen";
+/**
+ * The WebSocket subprotocol that identifies a reverse-channel source connector,
+ * as opposed to the SDK's sync client, which uses `ablo.sync.v1`. During the
+ * handshake the server echoes back only this value and never the subprotocol that
+ * carries the credential, keeping the API key out of proxy and load-balancer logs.
+ */
+export declare const WS_SOURCE_SUBPROTOCOL = "ablo.source.v1";
+/**
+ * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
+ * handshake: the source subprotocol followed by the bearer credential, encoded as
+ * `ablo.bearer.<apiKey>`. A WebSocket handshake cannot carry an `Authorization`
+ * header, so the API key rides as a subprotocol instead — the same mechanism the
+ * SDK's sync client uses, which the server reads back with `extractBearer`.
+ */
+export declare function sourceConnectorSubprotocols(apiKey: string): string[];
+/**
+ * The first frame the connector sends, right after the socket opens. The server
+ * has already authenticated the connection and resolved which source it serves
+ * from the API key in the handshake, so this frame only negotiates the protocol
+ * version and carries advisory metadata.
+ */
+export declare const registerFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    protocolVersion: z.ZodNumber;
+    client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RegisterFrame = z.infer<typeof registerFrameSchema>;
+/**
+ * The server's acknowledgement of a successful `register`. It echoes the resolved
+ * source identity so the connector can confirm and log which source it is serving.
+ */
+export declare const readyFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+    protocolVersion: z.ZodNumber;
+    sourceId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReadyFrame = z.infer<typeof readyFrameSchema>;
+/**
+ * A single load, list, or commit request the server forwards to the connector.
+ * Its `headers` and `body` are byte-for-byte what the inbound webhook path would
+ * have sent, so the connector can replay them into a `Request` and let the same
+ * handler verify the signature exactly as it would for a webhook.
+ */
+export declare const requestFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"request">;
+    id: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    url: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type RequestFrame = z.infer<typeof requestFrameSchema>;
+/**
+ * The handler's response to one `request` frame, sent back by the connector. The
+ * server matches it to the pending request by `id` and treats its `status` and
+ * `body` as though an HTTP response had returned.
+ */
+export declare const responseFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    status: z.ZodNumber;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type ResponseFrame = z.infer<typeof responseFrameSchema>;
+/**
+ * An error either side can send for a failure that is not a normal request
+ * result, such as a rejected credential, an unsupported protocol version, or a
+ * malformed frame. When `id` is set the error belongs to that pending request and
+ * fails it; without an `id` it is a connection-level error.
+ */
+export declare const errorFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    id: z.ZodOptional<z.ZodString>;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type ErrorFrame = z.infer<typeof errorFrameSchema>;
+export declare const connectorFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    protocolVersion: z.ZodNumber;
+    client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+    protocolVersion: z.ZodNumber;
+    sourceId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"request">;
+    id: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    url: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    status: z.ZodNumber;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    id: z.ZodOptional<z.ZodString>;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>], "type">;
+export type ConnectorFrame = z.infer<typeof connectorFrameSchema>;
+/** Thrown when an incoming frame fails to parse or validate. */
+export declare class ConnectorProtocolError extends Error {
+    readonly code = "source_connector_protocol_error";
+    constructor(message: string);
+}
+/** Serialize a frame for transmission. */
+export declare function encodeFrame(frame: ConnectorFrame): string;
+/**
+ * Parses and validates one incoming frame. It accepts either the string or the
+ * binary payloads a WebSocket `message` event can deliver, and throws
+ * {@link ConnectorProtocolError} on any malformed or unrecognized frame so the
+ * caller can reject the connection instead of acting on bad data.
+ */
+export declare function decodeFrame(raw: string | ArrayBuffer | Uint8Array): ConnectorFrame;
+//# sourceMappingURL=connectorProtocol.d.ts.map

package/dist/source/connectorProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectorProtocol.d.ts","sourceRoot":"","sources":["../../src/source/connectorProtocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpE;AAID;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;iBAQ9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;iBAM3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;iBAW7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,gEAAgE;AAChE,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,qCAAqC;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GACrC,cAAc,CAehB"}