@flop-labs/contracts
Structural types, JSON Schema exports, and assertion validators for the FLOP
public HTTP API. Version 0.1.0 covers listModels, getModel, and JSON
createChatCompletion payloads and streaming frames from services/rest-gateway/openapi.yaml.
The unreleased surface also includes exact-ID credential receipt lookup.
npm install @flop-labs/contracts
import { assertModelList, type ModelList } from "@flop-labs/contracts";
const response = await fetch("https://api.flop.network/v1/models");
const value: unknown = await response.json();
assertModelList(value);
const models: ModelList = value;
Exports: Model, ModelList (also ModelListResponse), ModelResponse,
ChatCompletionRequest, ChatCompletionResponse, ChatCompletionChunk, and
ChatCompletionStreamError; their assert* functions
and *Schema objects. Invalid data throws ContractValidationError; its message
contains the contract name, never the submitted values.
CredentialReceipt, CredentialReceiptError and CredentialReceiptRequestId also
export assert* functions and *Schema objects, generated from
GET /keys/me/receipts/{request_id}. A receipt is a current scoped ledger observation;
it does not rewrite the original completion checkpoint. Exact terminal allocations
use settled_spend_raw decimal strings in raw FLOP units (10^18 raw = 1 FLOP).
Unavailable values remain null. A pooled channel event is not a separate payment
or burn transaction for each request. See the client's recovery example for authority,
state, retention and manual replay rules.
Validation checks structure without coercion, default insertion, or removal of
fields. Responses allow extensions, including receipt evidence, exactly as the
source schemas allow. Validating an envelope does not authenticate its evidence,
verify a receipt, or establish settlement/finality. Request validation follows
the API schema. ChatCompletionStreamUsage and ChatCompletionToolCallFragment
also have types, assert* functions and *Schema objects. assertChatCompletionStreamError covers in-band
broker errors (including estimated usage and retry hints), session expiry, and
receipt reconciliation failures; it does not validate arbitrary HTTP error bodies.
OpenAPI 3.1 models the SSE wire body as a string and references decoded data schemas
through x-sse-data-schema. The literal [DONE] is a framing sentinel rather than
a JSON chunk. Structural assertions validate individual frames; @flop-labs/client
additionally enforces ordering, identity consistency, complete tool-call assembly,
and terminal behavior.
Estimated error usage does not become receipt evidence by passing validation.
The published ESM package has no runtime dependencies. Types are generated with
json-schema-to-typescript; AJV generates standalone JSON Schema 2020-12
validators. Generation fails if validators start requiring runtime helpers,
so a schema change cannot silently introduce a dependency.
From the repository root:
pnpm --filter @flop-labs/contracts generate
pnpm --filter @flop-labs/contracts check:generated
pnpm --filter @flop-labs/contracts build
pnpm --filter @flop-labs/contracts test
Generated files are checked in. Edit the canonical OpenAPI schemas, regenerate, and review their consumer impact together. Schema identities and package versions describe this contract artifact; they do not assert server or runtime compatibility.