@forsyteco/app-provider-transport

WebSocket wire contract and codec for @forsyteco/app-provider.

This package owns the transport contract between the cloud (the data gateway broker) and an on-prem provider runtime (the agent). It is intentionally small: envelope types, a PROTOCOL_VERSION, and a codec that serialises, validates, and protocol-checks messages. It does not own the socket runtime — the broker and agent keep their own socket layers and call this codec.

Requests are keyed by { capability, operation }, where both come from the @forsyteco/app-provider contract. A missing capability is backfilled from the operation via capabilityForOperation, so cross-cutting operations (healthz, run_script) carry no capability.

Install

pnpm add @forsyteco/app-provider-transport @forsyteco/app-provider

This package depends on the published @forsyteco/app-provider contract (^1.0.0).

Subpath exports

| Import | Contents | | --- | --- | | @forsyteco/app-provider-transport | Everything (re-exports ws + codec). | | @forsyteco/app-provider-transport/ws | Envelope types, PROTOCOL_VERSION, isCompatibleProtocolVersion. | | @forsyteco/app-provider-transport/codec | encode*/decode* functions and ProtocolError. |

Usage

import { encodeRequest, decodeRequest, decodeResponse } from "@forsyteco/app-provider-transport/codec";

// Broker (cloud) -> wire
const wire = encodeRequest({ id: "req-1", operation: "get_matter", payload: { matterId: "m-1" } });

// Agent (on-prem) <- wire
const request = decodeRequest(wire); // { capability: "matters", operation: "get_matter", ... }

Protocol versioning

PROTOCOL_VERSION starts at 1 for this package and is not compatible with the legacy @forsyteco/data-gateway-provider WsCommand wire. Bump it only on an incompatible change; both broker and agent must ship the new version together.

Scripts

pnpm typecheck
pnpm lint
pnpm test
pnpm build