@phranck/pewee-protocol

Schema-first API contract for pewee. Ships:

• Zod schemas for every DTO crossing the wire (apps, projects, flow yields, log lines, system status).
• An auto-generated OpenAPI v3 document (openapi.json + openapi.yaml) covering all 26 endpoints exposed by the admin server.

The package is the source of truth between the pewee CLI, the pewee admin server + UI, and any third-party consumer (e.g. a Swift client) that needs to talk to a running pewee admin instance without depending on the CLI or server source.

Install

npm install @phranck/pewee-protocol zod

zod is a peer dependency.

Usage

Validate a payload

import { ProjectDTOSchema } from "@phranck/pewee-protocol";

const result = ProjectDTOSchema.safeParse(jsonFromServer);
if (!result.success) {
  console.error(result.error);
} else {
  console.log(result.data.apps[0].name);
}

Consume the OpenAPI document

The package ships the rendered document in two formats:

import openapi from "@phranck/pewee-protocol/openapi.json" with { type: "json" };

Or directly from the file:

node -e "console.log(require('@phranck/pewee-protocol/openapi.json').info.version)"

The same document in YAML lives at @phranck/pewee-protocol/openapi.yaml — useful for tools that prefer YAML input (e.g. some code generators).

Build the OpenAPI document yourself

import { buildOpenApiDocument } from "@phranck/pewee-protocol";

const doc = buildOpenApiDocument();

This is what the package's build step does to produce the committed openapi.{json,yaml} files; consumers normally don't need to call it themselves.

Versioning

The protocol package uses semantic versioning independently of the CLI and admin packages. A breaking change to any DTO or route is a major bump.

| Version | Compatible with | | --- | --- | | 1.x | [email protected]+ (CLI), [email protected]+ (admin server) |

Repository

This package is part of the pewee monorepo. The source for this package lives at packages/protocol. Issues and pull requests are tracked at github.com/phranck/pewee/issues.

License

This repository has been published under the MIT license.