# @jdg-keyforge/protocol

> TypeScript types for the KeyForge WebSocket protocol, generated from the canonical JSON Schema contracts.

Latest version **0.11.0** (published 2026-09-24) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @jdg-keyforge/protocol
pnpm add @jdg-keyforge/protocol
yarn add @jdg-keyforge/protocol
bun add @jdg-keyforge/protocol
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.11.0 |
| Published | 2026-09-24 |
| First published | 2026-06-08 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 128.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jonathan Daniel Gomez |
| Maintainers | jdg-dev |
| Keywords | keyforge, protocol, types, json-schema, websocket |

## Links

- npm: https://www.npmjs.com/package/@jdg-keyforge/protocol
- Repository: https://github.com/JoniDG/keyforge-protocol
- Issues: https://github.com/JoniDG/keyforge-protocol/issues
- npm.io page: https://npm.io/package/@jdg-keyforge/protocol

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.11.0 (latest) — 2026-09-24
- 0.10.0 — 2026-09-24
- 0.9.0 — 2026-09-24
- 0.8.0 — 2026-06-10
- 0.7.0 — 2026-06-09
- 0.6.0 — 2026-06-08

## README

# @jdg-keyforge/protocol

> TypeScript types for the [KeyForge](https://github.com/JoniDG/keyforge) WebSocket protocol, generated from the canonical JSON Schema contracts in this repository.

This package contains only type declarations — there is no runtime code. It mirrors the Go submodule published at `github.com/JoniDG/keyforge-protocol/go/protocol`.

## Install

```bash
npm install @jdg-keyforge/protocol
```

While the package is unpublished, consumers in the KeyForge workspace can install it directly from the source tree:

```bash
npm install file:../keyforge-protocol/ts
```

## Usage

```ts
import type {
  Envelope,
  Request,
  Response,
  Event,
  Device,
  InputEvent,
  MethodHello,
  MethodListDevices,
  EventInput,
} from '@jdg-keyforge/protocol';
```

The root `index` re-exports shared types from [`common`](./src/common.ts) and [`envelope`](./src/envelope.ts) plus the top-level `Method*` / `Event*` types for each method and event. Inner payload shapes (e.g. `MethodListDevices['result']`) are reachable through the parent type.

For schema definitions and the wire-protocol overview, see the [repository root README](../README.md).

## Versioning

This package is versioned independently from the schema's `/v1/` path and from the Go submodule:

| Artifact | Source of truth | Tag |
|---|---|---|
| Schema major | `$id` path (`.../v1/...`) | — |
| Go submodule | [`go/protocol/`](../go/protocol) | `go/vX.Y.Z` |
| TS package | [`ts/`](.) | `ts/vX.Y.Z` |

A breaking schema change bumps `/v1/` to `/v2/` *and* the major version of both packages. Non-breaking schema additions bump only the minor/patch of each package.

## Local regeneration

The contents of `src/` are auto-generated from the JSON Schemas. To regenerate after editing a schema, run from the repository root:

```bash
make generate-ts
```

Then build the package:

```bash
cd ts && npm install && npm run build
```

CI fails the build if `git diff --exit-code ts/src/` is dirty — i.e. someone changed a schema without committing the regenerated types.

## License

[Apache 2.0](./LICENSE) — Copyright (c) 2026 Jonathan Daniel Gomez.

---
_Source: https://npm.io/package/@jdg-keyforge/protocol · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._