@abloatai/ablo 0.25.0 → 0.27.0

package/dist/source/conformance.js

@@ -1,26 +1,32 @@
 /**
- * Data Source adapter conformance suite — the shared "is this adapter correct?"
- * test set, in the Auth.js `@auth/adapter-test` mould. Every ORM adapter
- * (Prisma/Drizzle/Kysely) and any hand-written handler runs THIS to prove,
- * before production, the guarantees the adapter interface promises. A new adapter is "done"
- * when it passes — not when it compiles.
+ * The conformance suite for data-source adapters: a shared set of tests that checks
+ * whether an adapter is correct. Every adapter in this package (Prisma, Drizzle,
+ * Kysely) and any adapter you write yourself runs this suite to confirm it upholds
+ * the guarantees {@link DataSourceAdapter} promises. An adapter is complete when it
+ * passes, not merely when it compiles.
  *
- * Runner-agnostic: checks are plain async functions that throw (node:assert) on
- * failure. `runDataSourceTests` registers them with whatever `it`/`test` you
- * pass, so it works under vitest, jest, or node:test:
+ * The suite is runner-agnostic: each check is a plain async function that throws,
+ * via `node:assert`, on failure. {@link runDataSourceTests} registers the checks
+ * with whichever `it` or `test` function you pass, so it runs under vitest, jest,
+ * or `node:test`:
  *
  *   import { it } from 'vitest';
  *   runDataSourceTests(memoryDataSource, it);
  *
- * Scope: this covers the ADAPTER contract (commit idempotency, read-after-write,
- * the transactional outbox + cursor). Signature/scope rejection is a HANDLER
- * concern (the adapter never sees a signature) and is tested separately.
+ * The checks cover the adapter contract: commit idempotency, read-after-write, and
+ * the transactional outbox with its cursor. They do not cover request-signature or
+ * scope rejection, which the HTTP handler enforces before the adapter is ever
+ * called and which is tested separately.
  */
 import assert from 'node:assert/strict';
 const change = (clientTxId, ops) => ({
     clientTxId,
     operations: ops,
 });
+/**
+ * Builds the list of conformance checks for an adapter. Call this to run the checks
+ * yourself, or use {@link runDataSourceTests} to register them with a test runner.
+ */
 export function dataSourceConformanceChecks(make) {
     return [
         {
@@ -29,8 +35,10 @@ export function dataSourceConformanceChecks(make) {
                 const adapter = await make();
                 const result = await adapter.commit(change('tx_create', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
                 assert.equal(result.rows.length, 1, 'one row returned');
-                assert.equal(result.rows[0].id, 't1');
-                assert.equal(result.rows[0].title, 'A');
+                const created = result.rows[0];
+                assert.ok(created, 'one row returned');
+                assert.equal(created.id, 't1');
+                assert.equal(created.title, 'A');
             },
         },
         {
@@ -40,7 +48,7 @@ export function dataSourceConformanceChecks(make) {
                 await adapter.commit(change('tx1', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
                 const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
                 assert.equal(found.length, 1);
-                assert.equal(found[0].title, 'A');
+                assert.equal(found[0]?.title, 'A');
                 const missing = await adapter.read({ kind: 'load', model: 'task', id: 'nope' });
                 assert.equal(missing.length, 0, 'unknown id reads empty');
             },
@@ -54,7 +62,7 @@ export function dataSourceConformanceChecks(make) {
                     { type: 'CREATE', model: 'task', id: 't2', input: { title: 'B' } },
                 ]));
                 const rows = await adapter.read({ kind: 'list', model: 'task' });
-                const ids = rows.map((r) => r.id).sort();
+                const ids = rows.map((r) => (r).id).sort();
                 assert.deepEqual(ids, ['t1', 't2']);
             },
         },
@@ -83,9 +91,9 @@ export function dataSourceConformanceChecks(make) {
                 assert.ok(page.events.length >= 1, 'at least one event');
                 const evt = page.events.find((e) => e.entityId === 't1');
                 assert.ok(evt, 'event for the committed row');
-                assert.equal(evt?.model, 'task');
-                assert.equal(evt?.type, 'CREATE');
-                assert.equal(evt?.clientTxId, 'tx_evt');
+                assert.equal(evt.model, 'task');
+                assert.equal(evt.type, 'CREATE');
+                assert.equal(evt.clientTxId, 'tx_evt');
             },
         },
         {
@@ -115,7 +123,7 @@ export function dataSourceConformanceChecks(make) {
                 await adapter.commit(change('tx_c1', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
                 await adapter.commit(change('tx_u1', [{ type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } }]));
                 const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
-                assert.equal(found[0].title, 'B', 'update applied');
+                assert.equal(found[0]?.title, 'B', 'update applied');
             },
         },
     ];

package/dist/source/connector.d.ts

@@ -1,15 +1,13 @@
 /**
- * Customer-side Data Source reverse-channel connector.
+ * 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 dial-out half of the reverse channel (see `connector-protocol.ts`). The
- * customer runs this next to their database; it opens an OUTBOUND WebSocket to
- * Ablo Cloud and serves the `commit`/`load`/`list` leg over that socket instead
- * of receiving inbound webhooks. This is the symmetric primitive to
- * `createPushQueue` (which already gives the `events` leg an outbound transport)
- * and mirrors the Stripe CLI's `stripe listen`.
- *
- * The connector does NOT reimplement any handler logic. It wraps the SAME
- * `(request: Request) => Promise<Response>` the customer's deployed route uses:
+ * 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
@@ -20,23 +18,24 @@
  *   });
  *   await connector.run(controller.signal);
  *
- * Each drained `request` frame is replayed into a synthesized `Request` carrying
- * the original Standard Webhooks signature headers, so the handler verifies it
- * through the unchanged `verifyAbloSourceRequest` — identical to the webhook
- * path. The transport changes; the trust model does not.
+ * 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.
  */
 /**
- * Reconnect backoff, in ms, indexed by consecutive failed connect attempts.
- * Unlike the (multi-day) Standard Webhooks delivery schedule, a long-lived
- * control socket should re-establish quickly and cap at a steady interval, so
- * this is a short capped curve. The last entry repeats for further attempts. A
- * clean `ready` resets the counter to 0.
+ * 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[];
 /**
- * Minimal structural WebSocket surface — the browser/`globalThis.WebSocket` API,
- * which Node 24+ implements natively. The `ws` package's default export also
- * satisfies this (it exposes `addEventListener`). Injectable for tests.
+ * 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;
@@ -57,18 +56,18 @@ export type ConnectorWebSocketFactory = (url: string, protocols: readonly string
 export type ConnectorStatus = 'connecting' | 'ready' | 'disconnected';
 export interface SourceConnectorOptions {
     /**
-     * Ablo project API key. Defaults gate to `sk_test_*` (local-dev / sandbox);
-     * an `sk_live_*` key is only accepted when the source has opted into
-     * reverse-channel for production server-side.
+     * 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 unchanged Data Source handler — `dataSource(options)` /
-     * `abloSource(options)`. The connector feeds it synthesized `Request`s and
-     * relays the `Response`s back; it never inspects or alters them.
+     * The Data Source handler to serve, as returned by `dataSource(options)` or
+     * `abloSource(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>;
-    /** Ablo Cloud base URL. Default `https://api.abloatai.com`. */
+    /** 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;
@@ -87,9 +86,9 @@ export interface SourceConnectorOptions {
 }
 export interface SourceConnector {
     /**
-     * Run the connect → serve → reconnect loop until `signal` aborts. Resolves
-     * when aborted. Rejects only on a fatal, non-retryable condition (e.g. no
-     * WebSocket implementation available).
+     * 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>;
 }

package/dist/source/connector.js

@@ -1,15 +1,13 @@
 /**
- * Customer-side Data Source reverse-channel connector.
+ * 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 dial-out half of the reverse channel (see `connector-protocol.ts`). The
- * customer runs this next to their database; it opens an OUTBOUND WebSocket to
- * Ablo Cloud and serves the `commit`/`load`/`list` leg over that socket instead
- * of receiving inbound webhooks. This is the symmetric primitive to
- * `createPushQueue` (which already gives the `events` leg an outbound transport)
- * and mirrors the Stripe CLI's `stripe listen`.
- *
- * The connector does NOT reimplement any handler logic. It wraps the SAME
- * `(request: Request) => Promise<Response>` the customer's deployed route uses:
+ * 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
@@ -20,20 +18,24 @@
  *   });
  *   await connector.run(controller.signal);
  *
- * Each drained `request` frame is replayed into a synthesized `Request` carrying
- * the original Standard Webhooks signature headers, so the handler verifies it
- * through the unchanged `verifyAbloSourceRequest` — identical to the webhook
- * path. The transport changes; the trust model does not.
+ * 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 '../client/hostedEndpoints.js';
+/**
+ * The default Ablo base URL the connector dials, to which it appends
+ * `SOURCE_CONNECTOR_WS_PATH`.
  */
-import { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, } from './connector-protocol.js';
-/** Default Ablo Cloud base. The connector appends `SOURCE_CONNECTOR_WS_PATH`. */
-const DEFAULT_BASE_URL = 'https://api.abloatai.com';
+const DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;
 /**
- * Reconnect backoff, in ms, indexed by consecutive failed connect attempts.
- * Unlike the (multi-day) Standard Webhooks delivery schedule, a long-lived
- * control socket should re-establish quickly and cap at a steady interval, so
- * this is a short capped curve. The last entry repeats for further attempts. A
- * clean `ready` resets the counter to 0.
+ * 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
@@ -77,10 +79,10 @@ export function createSourceConnector(options) {
     };
 }
 /**
- * One connection lifecycle: open → register → serve drained requests until the
- * socket closes or `signal` aborts. Resolves to whether the connection reached
- * the `ready` state (used to reset reconnect backoff). Never rejects — transport
- * failures are normal and drive a reconnect.
+ * 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) => {
@@ -197,8 +199,8 @@ function connectOnce(params) {
             }
             catch (err) {
                 params.onError?.(err);
-                // Surface as a 500 so the server-side SourceClient treats it as a
-                // retryable failure, exactly like a webhook endpoint throwing.
+                // 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,

package/dist/source/connectorProtocol.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>;
+}, 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.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>;
+}, 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;

package/dist/source/connectorProtocol.js

@@ -0,0 +1,162 @@
+/**
+ * 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';
+import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
+/**
+ * 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 const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
+/** The WebSocket path the connector dials, appended to its configured base URL. */
+export 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 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 function sourceConnectorSubprotocols(apiKey) {
+    return [WS_SOURCE_SUBPROTOCOL, `${WS_BEARER_SUBPROTOCOL_PREFIX}${apiKey}`];
+}
+const headerRecord = z.record(z.string(), z.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 const registerFrameSchema = z.object({
+    type: z.literal('register'),
+    protocolVersion: z.number().int(),
+    /**
+     * An optional client identifier, such as `@abloatai/ablo@0.12.0`, recorded in
+     * the server's logs. It is advisory only and never affects a decision.
+     */
+    client: z.string().optional(),
+});
+/**
+ * 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 const readyFrameSchema = z.object({
+    type: z.literal('ready'),
+    protocolVersion: z.number().int(),
+    sourceId: z.string().optional(),
+    organizationId: z.string().optional(),
+    environment: z.enum(['production', 'sandbox']).optional(),
+});
+/**
+ * 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 const requestFrameSchema = z.object({
+    type: z.literal('request'),
+    /** Correlation id; the matching `response` frame carries the same value. */
+    id: z.string().min(1),
+    method: z.literal('POST'),
+    /** Synthetic absolute URL used only to construct the `Request` object. */
+    url: z.string().min(1),
+    /** The signed webhook signature headers, plus `Content-Type`. */
+    headers: headerRecord,
+    /** Raw JSON request body — exactly the bytes that were signed. */
+    body: z.string(),
+});
+/**
+ * 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 const responseFrameSchema = z.object({
+    type: z.literal('response'),
+    id: z.string().min(1),
+    status: z.number().int(),
+    headers: headerRecord.optional(),
+    /** Raw JSON response body. */
+    body: z.string(),
+});
+/**
+ * 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 const errorFrameSchema = z.object({
+    type: z.literal('error'),
+    id: z.string().min(1).optional(),
+    code: z.string().min(1),
+    message: z.string(),
+});
+export const connectorFrameSchema = z.discriminatedUnion('type', [
+    registerFrameSchema,
+    readyFrameSchema,
+    requestFrameSchema,
+    responseFrameSchema,
+    errorFrameSchema,
+]);
+/** Thrown when an incoming frame fails to parse or validate. */
+export class ConnectorProtocolError extends Error {
+    code = 'source_connector_protocol_error';
+    constructor(message) {
+        super(message);
+        this.name = 'ConnectorProtocolError';
+    }
+}
+/** Serialize a frame for transmission. */
+export function encodeFrame(frame) {
+    return JSON.stringify(frame);
+}
+/**
+ * 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 function decodeFrame(raw) {
+    const text = typeof raw === 'string' ? raw : decodeBinary(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ConnectorProtocolError('Frame is not valid JSON');
+    }
+    const result = connectorFrameSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ConnectorProtocolError(`Invalid connector frame: ${result.error.message}`);
+    }
+    return result.data;
+}
+function decodeBinary(raw) {
+    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+    return new TextDecoder().decode(bytes);
+}