@ekka-ai/contracts

Canonical, versioned wire contracts (JSON Schema + TypeScript) for EKKA APIs.

What This Package Is

This package provides the authoritative request/response schemas and generated TypeScript types for EKKA APIs. It is intended for SDKs, host runtimes, servers, and tooling that need strict validation and compatibility guarantees. Most application developers should use @ekka-ai/sdk instead.

Installation

npm install @ekka-ai/contracts

What's Included

• JSON Schemas (runtime validation)
• Generated TypeScript types
• Versioned protocol, governance, vault, and common error contracts

Usage (Types)

import type {
  IntentRequest,
  IntentResult,
  PolicyProfile,
  ErrorPayload,
} from '@ekka-ai/contracts';

const request: IntentRequest = {
  op: 'file.write',
  payload: { path: '/tmp/test.txt', content: 'hello' },
};

Usage (JSON Schema Validation)

import Ajv from 'ajv';
import intentResultSchema from '@ekka-ai/contracts/protocol/intent.result.schema.json';

const ajv = new Ajv();
const validate = ajv.compile(intentResultSchema);

Published Schemas

All schemas are published and versioned at:

| Schema | URL | |--------|-----| | Error | https://schemas.ekka.ai/common/error.schema.json | | Envelope | https://schemas.ekka.ai/protocol/envelope.schema.json | | Intent Request | https://schemas.ekka.ai/protocol/intent.request.schema.json | | Intent Result | https://schemas.ekka.ai/protocol/intent.result.schema.json | | Event Stream | https://schemas.ekka.ai/protocol/event.stream.schema.json | | Policy Profile | https://schemas.ekka.ai/governance/policy.profile.schema.json | | Bundle Manifest | https://schemas.ekka.ai/vault/bundle.manifest.schema.json | | Resolved Policy | https://schemas.ekka.ai/vault/resolved.policy.schema.json |

Versioning Guarantees

This package follows SemVer:

• MAJOR: Breaking schema changes
• MINOR: Additive, backward-compatible changes
• PATCH: Documentation and non-breaking fixes

Relationship to Other EKKA Packages

• @ekka-ai/sdk — Application-facing client for EKKA APIs
• @ekka-ai/contracts — Low-level schemas and types (this package)

License

MIT