@appport/protocol
The AppPort wire contract: envelope types, error codes, naming rules, manifest shapes, structural validation and compatibility analysis.
This package is pure. It has no runtime dependencies and knows nothing about transports, servers or clients — which is what makes it safe to depend on from a browser bundle, an Electron preload script or a CLI.
import { createRequest, parseClientEnvelope, PROTOCOL_ID } from "@appport/protocol";
const request = createRequest({
requestId: "req_01J...",
capability: { name: "documents.save", version: 1 },
input: { documentId: "doc_1", content: "hello" }
});
parseClientEnvelope(request); // throws AppPortError on a malformed envelope
What is here
| Module | Contents |
|---|---|
version | appport/1, conformance levels |
envelopes | request, response, event, subscribe, stream envelopes and guards |
validate | protocol-level structural validation, decode and encode |
errors | the standard error codes and AppPortError |
names | capability, event, permission and application-id grammar |
ids | ULID-based identifier helpers |
manifest | manifest, discovery and transport descriptor types |
jsonschema | the JSON Schema subset published in manifests |
session | Principal and Session |
operations | long-running operation records |
blob | binary references |
compatibility | breaking vs non-breaking manifest diffing; compareSchemas for one schema pair |
fulfillment | canonical contracts (isCanonicalContract), fulfillment claims (claimFor, claimsFor, lintFulfillment) and their evaluation (evaluateFulfillment) (spec/fulfillment-1.md), since 1.2.0 |
integration | integration metadata and lintIntegration; dependencies, including canonical targets (CanonicalDependencyTarget, isCanonicalDependencyTarget, since 1.2.0) |
Names are checked, not merely typed: electron.documents.save and
ipc.saveDocument are rejected, because a capability name that encodes a
transport breaks the protocol's central invariant.
Public discovery (1.1.0)
buildPublicDescription, validatePublicDescription, capabilityDigest, contractDigest, PUBLIC_DESCRIPTION_PATH and the
appport.public-description/1 schema (spec/schemas/public-description.schema.json in the repository). Publication is the application
owner's explicit, fail-closed decision; a description is a pointer to, and a digest of, the authoritative manifest and is untrusted data.
Discovery is not authorization, approval or publisher trust.