open-index/open-npm huggingface dataset:
npm package: @sideband/protocol
Description: Canonical Sideband wire contract: branded IDs, protocol constants/error codes, frame + handshake shapes, and binary codec. No I/O, runtime logic, or transport definitions.
Author: Sideband
Latest version: 0.5.0

# @sideband/protocol

Canonical Sideband wire contract: branded IDs, protocol constants/error codes, frame + handshake shapes, and binary codec. No I/O, runtime logic, or transport definitions.

## Install

```bash
bun add @sideband/protocol
```

## Quick use

```ts
import {
  FrameKind,
  PROTOCOL_NAME,
  PROTOCOL_VERSION,
  createHandshakeFrame,
  createMessageFrame,
  encodeFrame,
  decodeFrame,
  encodeHandshake,
  asPeerId,
  asSubject,
} from "@sideband/protocol";

// Build a handshake frame
const handshake = createHandshakeFrame(
  encodeHandshake({
    protocol: PROTOCOL_NAME,
    version: PROTOCOL_VERSION,
    peerId: asPeerId("peer-123"),
    caps: ["rpc"],
  }),
);

// Encode for the wire
const bytes = encodeFrame(handshake);

// Decode on the other side
const frame = decodeFrame(bytes);
if (frame.kind === FrameKind.Control) {
  console.log("control frame received");
}

// Send an application message (method identity lives in the payload, not the subject)
const msg = createMessageFrame(
  asSubject("rpc"),
  new TextEncoder().encode(JSON.stringify({ m: "echo", p: "hello" })),
);
const msgBytes = encodeFrame(msg);
```

## What it provides

- **Branded types**: `PeerId`, `FrameId`, `Subject`, `ConnectionId`, `CorrelationId`, `StreamId` with smart constructors (`asPeerId`, `asFrameId`, `asSubject`, `asConnectionId`, `asCorrelationId`, `asStreamId`) and `MAX_SUBJECT_BYTES` for wire-safe validation
- **Frame codec**: `encodeFrame` / `decodeFrame` with invariant enforcement (validates subject compliance with reserved namespaces per ADR-008)
- **Frame builders**: `createHandshakeFrame`, `createMessageFrame`, `createPingFrame`, `createPongFrame`, `createCloseFrame`, `createErrorFrame`
- **FrameId helpers**: `generateFrameId`, `frameIdToHex`, `frameIdFromHex` for correlation and logging
- **Handshake encode/decode**: `encodeHandshake` / `decodeHandshake` with validation
- **Protocol constants**: `PROTOCOL_NAME`, `PROTOCOL_ID`, `PROTOCOL_VERSION`, `FrameKind` enum, `ControlOp` enum, `ErrorCode` enum
- **Type guards**: `isControlFrame`, `isHandshakeFrame`, `isPingFrame`, `isPongFrame`, `isCloseFrame`, `isMessageFrame`, `isAckFrame`, `isErrorFrame`, `isValidFrameId`
- **Protocol error**: `ProtocolError` — typed error with `code` (numeric) and optional `details`

For transport implementations, see [`@sideband/transport`](https://www.npmjs.com/package/@sideband/transport) (defines the Transport interface). For request correlation and RPC semantics, see [`@sideband/rpc`](https://www.npmjs.com/package/@sideband/rpc). Keep state machines, retries, and routing in [`@sideband/runtime`](https://www.npmjs.com/package/@sideband/runtime)—this package only defines the wire contract.

## Specification

See the [SBP protocol specification](https://sideband.tech/protocols/sbp/) for wire format details.

## License

Apache-2.0
npm package: @sideband/rpc
Description: Typed RPC envelope layer over Sideband message frames: request/response/notification shapes, reserved subject helpers, JSON codec, and guards.
Author: Sideband
Latest version: 0.5.0

# @sideband/rpc

Canonical RPC envelope layer over Sideband message frames: typed request/response/notification shapes, reserved subject helpers, JSON codec, and guards for safe handling.

## Install

```bash
bun add @sideband/rpc
```

## Quick use

```ts
import {
  createRpcRequest,
  createRpcSuccessResponse,
  createRpcErrorResponse,
  createRpcNotification,
  encodeRpcEnvelope,
  decodeRpcEnvelope,
  isRpcResponse,
  SUBJECT_CHANNELS,
  asRpcSubject,
} from "@sideband/rpc";
import {
  generateFrameId,
  createMessageFrame,
  encodeFrame,
  decodeFrame,
  asSubject,
  FrameKind,
} from "@sideband/protocol";

// Build an RPC request envelope
const cid = generateFrameId(); // Correlation ID = frame's frameId
const methodName = "echo";
const request = createRpcRequest(methodName, cid, { text: "hi" });
const envelopeBytes = encodeRpcEnvelope(request);

// Wrap in a MessageFrame with `rpc` channel subject
// Method name lives in the envelope, not the subject
const subject = asSubject(SUBJECT_CHANNELS.RPC); // "rpc"
const messageFrame = createMessageFrame(subject, envelopeBytes);
const frameBytes = encodeFrame(messageFrame);

// ...send frameBytes over transport...

// On receive: decode frame, extract envelope, dispatch by envelope.m
const decodedFrame = decodeFrame(frameBytes);
if (decodedFrame.kind === FrameKind.Message) {
  const envelope = decodeRpcEnvelope(decodedFrame.data);
  if (isRpcResponse(envelope)) {
    console.log("result:", envelope.result);
  }
}

// Craft responses/notifications
const responseEnvelope = createRpcSuccessResponse(cid, { text: "hi back" });
// Notifications use `event` channel; event name lives in envelope.e
const notifyEnvelope = createRpcNotification("user.joined", { userId: "123" });

// Validate reserved subjects for routing
const validRpcSubject = asRpcSubject(SUBJECT_CHANNELS.RPC); // "rpc"
const validAppSubject = asRpcSubject("app/custom"); // custom sub-path
```

## What it provides

- Typed RPC envelopes with helpers and discriminated unions for requests, responses, and notifications
- Channel subjects (`rpc`, `event`, `stream`) and `app/` prefix constants, plus validator re-export (`asRpcSubject`)
- JSON encoder/decoder that handles FrameId ↔ hex, emits protocol errors on malformed input
- Integrates with runtime correlation ([`@sideband/runtime`](https://www.npmjs.com/package/@sideband/runtime)) and any transport carrying MessageFrames

## Specification

See the [RPC protocol specification](https://sideband.tech/protocols/rpc/) for envelope format details.

## License

Apache-2.0
npm package: @sideband/transport
Description: Transport ABI for Sideband: Transport interface, error taxonomy, and reference loopback transport.
Author: Sideband
Latest version: 0.5.0

# @sideband/transport

Transport ABI + shared helpers for Sideband. Defines the contract concrete transports must implement (WebSocket, loopback, custom TCP, etc.). No runtime/RPC coupling.

## Install

```bash
bun add @sideband/transport
```

## Quick use

```ts
import {
  LoopbackTransport,
  unsafeAsTransportEndpoint,
} from "@sideband/transport";

// unsafeAsTransportEndpoint brands a raw string as TransportEndpoint with no
// URL validation — suitable for custom schemes and tests. For WebSocket URLs,
// use wsEndpoint() from @sideband/transport-ws instead.
const transport = new LoopbackTransport();
const endpoint = unsafeAsTransportEndpoint("loopback://test");

// Server side
await transport.listen(endpoint, async (conn) => {
  for await (const bytes of conn.inbound) {
    await conn.send(bytes); // echo back
  }
});

// Client side
const conn = await transport.connect(endpoint);
await conn.send(new TextEncoder().encode("hello"));
for await (const bytes of conn.inbound) {
  console.log(new TextDecoder().decode(bytes)); // "hello"
  break;
}
```

## What it provides

**Interfaces**

- `Transport` — connect (required) + listen (optional) contract all transports implement
- `TransportConnection` — single byte-level link: `inbound`, `send()`, `close()`, `closed`, `state`
- `TransportListener` — returned by `listen()`; holds `address` and `close()`
- `ConnectionHandler` — `(conn: TransportConnection) => void | Promise<void>`

**Types**

- `TransportEndpoint` — branded string; use `unsafeAsTransportEndpoint` or a transport-specific helper
- `ConnectionState` — `"connecting" | "open" | "closing" | "closed"`
- `ConnectOptions` — `timeoutMs`, `signal`, `headers` (Node.js only), extensible
- `CloseOptions` / `CloseInfo` — close codes, reason, graceful flag, optional error
- `ListenOptions` — extensible per-transport listen configuration
- `ConnectionId` — re-exported from `@sideband/protocol`

**Errors**

- `TransportError` — typed transport failure with `kind: TransportErrorKind`
- `TransportErrorKind` — `connection_refused | dns_failure | tls_failure | timeout | network_offline | abnormal_close | message_too_large | buffer_overflow | policy_violation | authentication_failed | aborted | subprotocol_mismatch | transport_failure`
- `isRetryable(kind)` — returns true for transient failures

**Helpers**

- `unsafeAsTransportEndpoint(value)` — brands a raw string as `TransportEndpoint` with no validation
- `asConnectionId(value)` — brands a value as `ConnectionId` (re-exported from `@sideband/protocol`)
- `LoopbackTransport` — in-process transport for tests and local loops

Depends only on [`@sideband/protocol`](https://www.npmjs.com/package/@sideband/protocol); safe in browser, Node, and Bun environments.

## License

Apache-2.0
npm package: @sideband/transport-browser
Description: Browser transport implementation of the Sideband Transport interface using WebSocket primitives with reconnect/error handling for real-time apps.
Author: Sideband
Latest version: 0.0.3

# @sideband/transport-browser

Browser transport for Sideband.

> **Not yet implemented.** This package is a placeholder for the planned browser WebSocket transport.

## Planned Features

- WebSocket-based `Transport` implementation for browsers
- Automatic reconnection with exponential backoff
- Error recovery and connection state management
- Works in modern browsers and ServiceWorkers

## Install

```bash
bun add @sideband/transport-browser
```

Will implement the `Transport` interface from [`@sideband/transport`](https://www.npmjs.com/package/@sideband/transport). For Node.js/Bun environments, see [`@sideband/transport-node`](https://www.npmjs.com/package/@sideband/transport-node).

## License

Apache-2.0
npm package: @sideband/transport-node
Description: Node/Bun transport implementation of the Sideband Transport interface using ws/TCP primitives with server/client wiring for services and workers.
Author: Sideband
Latest version: 0.0.3

# @sideband/transport-node

Node.js and Bun transport for Sideband.

> **Not yet implemented.** This package is a placeholder for the planned Node/Bun WebSocket transport.

## Planned Features

- WebSocket server and client via `ws` or Bun.serve()
- `Transport` implementation for services and workers
- Connection management and error recovery
- TLS support for secure connections

## Install

```bash
bun add @sideband/transport-node
```

Will implement the `Transport` interface from [`@sideband/transport`](https://www.npmjs.com/package/@sideband/transport). For browser environments, see [`@sideband/transport-browser`](https://www.npmjs.com/package/@sideband/transport-browser).

## License

Apache-2.0