@nightmoose/contractgate-sdk 0.2.0

package/README.md

@@ -0,0 +1,93 @@
+# @nightmoose/contractgate-sdk
+
+Official TypeScript SDK for [ContractGate](https://contractgate.io) — HTTP client + local validator.
+
+**Node 20+, ESM only.**
+
+## Install
+
+```bash
+npm install @nightmoose/contractgate-sdk
+```
+
+## Quick start
+
+```ts
+import { Client, Contract } from "@nightmoose/contractgate-sdk";
+
+// HTTP client
+const c = new Client({ baseUrl: "https://gw.example.com", apiKey: process.env.CG_KEY });
+
+const result = await c.ingest({ contractId: "...", events: [{ user_id: "alice_01", event_type: "click", timestamp: 1700000000 }] });
+for (const r of result.results) {
+  if (!r.passed) for (const v of r.violations) console.log(v.field, v.kind, v.message);
+}
+
+// Local validator (no network)
+const contract = Contract.fromYaml(yamlString);
+const compiled = contract.compile();
+const vr = compiled.validate({ user_id: "alice_01", event_type: "click", timestamp: 1700000000 });
+console.assert(vr.passed, vr.violations);
+```
+
+## Client API
+
+| Method | Description |
+|--------|-------------|
+| `ingest({ contractId, events, version?, dryRun?, atomic? })` | Validate + persist a batch |
+| `egress({ contractId, events, version?, disposition?, dryRun? })` | Validate outbound payload |
+| `audit({ contractId?, limit?, offset? })` | Read audit entries |
+| `stats()` | Global ingestion stats |
+| `getContract(id)` | Fetch contract metadata |
+| `listContracts()` | List all contracts |
+| `listVersions(contractId)` | List versions |
+| `getVersion(contractId, version)` | Fetch a specific version |
+| `getLatestStable(contractId)` | Fetch the latest stable version |
+| `playgroundValidate({ yamlContent, event })` | Validate without persisting |
+
+## Local validator
+
+```ts
+import { Contract } from "@nightmoose/contractgate-sdk";
+
+const contract = Contract.fromYaml(`
+version: "1.0"
+name: "events"
+ontology:
+  entities:
+    - name: user_id
+      type: string
+      required: true
+      pattern: "^[a-zA-Z0-9_-]+$"
+    - name: timestamp
+      type: integer
+      required: true
+      min: 0
+`);
+
+const compiled = contract.compile();
+const { passed, violations } = compiled.validate({ user_id: "alice", timestamp: 1700000000 });
+```
+
+The local validator mirrors the Rust engine exactly. Conformance is enforced via a shared fixture corpus under `tests/conformance/`.
+
+## Error hierarchy
+
+```
+ContractGateError
+├── ContractCompileError     — bad contract YAML
+├── ConnectionError          — network / DNS failure
+└── HTTPError
+    ├── BadRequestError      — 400
+    ├── AuthError            — 401
+    ├── NotFoundError        — 404
+    ├── ConflictError        — 409
+    ├── ValidationFailedError — 422 (whole-batch rejection)
+    └── ServerError          — 5xx
+```
+
+Per-event validation failures in a 207 Multi-Status response do **not** raise. They surface in `result.results[n].violations`.
+
+## Version policy
+
+SDK version is kept in lockstep with the ContractGate gateway minor version. `0.1.x` of the SDK works with gateway `0.1.x`.

package/dist/client.d.ts

@@ -0,0 +1,65 @@
+import type { AuditEntry, BatchIngestResponse, ContractResponse, EgressResponse, IngestionStats, VersionResponse, VersionSummary } from './types.js';
+export interface ClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    orgId?: string;
+    timeoutMs?: number;
+    /** Override the global fetch (useful for tests). */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class Client {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly orgId?;
+    private readonly timeoutMs;
+    private readonly fetchFn;
+    constructor(opts: ClientOptions);
+    ingest(opts: {
+        contractId: string;
+        events: unknown;
+        version?: string;
+        dryRun?: boolean;
+        atomic?: boolean;
+        timeoutMs?: number;
+    }): Promise<BatchIngestResponse>;
+    egress(opts: {
+        contractId: string;
+        events: unknown;
+        version?: string;
+        disposition?: string;
+        dryRun?: boolean;
+        timeoutMs?: number;
+    }): Promise<EgressResponse>;
+    audit(opts?: {
+        contractId?: string;
+        limit?: number;
+        offset?: number;
+        timeoutMs?: number;
+    }): Promise<AuditEntry[]>;
+    stats(opts?: {
+        timeoutMs?: number;
+    }): Promise<IngestionStats>;
+    getContract(contractId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ContractResponse>;
+    listContracts(opts?: {
+        timeoutMs?: number;
+    }): Promise<ContractResponse[]>;
+    listVersions(contractId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<VersionSummary[]>;
+    getVersion(contractId: string, version: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<VersionResponse>;
+    getLatestStable(contractId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<VersionResponse>;
+    playgroundValidate(opts: {
+        yamlContent: string;
+        event: unknown;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    private buildUrl;
+    private buildHeaders;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,180 @@
+import { ConnectionError, raiseForStatus } from './errors.js';
+import { auditEntryFromJson, batchIngestResponseFromJson, contractResponseFromJson, egressResponseFromJson, expectList, ingestionStatsFromJson, versionResponseFromJson, versionSummaryFromJson, } from './types.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const SDK_VERSION = '0.2.0';
+const USER_AGENT = `contractgate-typescript/${SDK_VERSION}`;
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+export class Client {
+    baseUrl;
+    apiKey;
+    orgId;
+    timeoutMs;
+    fetchFn;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.apiKey = opts.apiKey;
+        this.orgId = opts.orgId;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchFn = opts.fetch ?? globalThis.fetch;
+    }
+    // ── Ingest ────────────────────────────────────────────────────────────────
+    async ingest(opts) {
+        const params = {};
+        if (opts.dryRun)
+            params['dry_run'] = 'true';
+        if (opts.atomic)
+            params['atomic'] = 'true';
+        const extra = {};
+        if (opts.version)
+            extra['X-Contract-Version'] = opts.version;
+        const body = await this.request({
+            method: 'POST',
+            path: `/ingest/${opts.contractId}`,
+            params,
+            body: opts.events,
+            extraHeaders: extra,
+            timeoutMs: opts.timeoutMs,
+        });
+        return batchIngestResponseFromJson(body);
+    }
+    // ── Egress ────────────────────────────────────────────────────────────────
+    async egress(opts) {
+        const params = {};
+        if (opts.dryRun)
+            params['dry_run'] = 'true';
+        if (opts.disposition)
+            params['disposition'] = opts.disposition;
+        const extra = {};
+        if (opts.version)
+            extra['X-Contract-Version'] = opts.version;
+        const body = await this.request({
+            method: 'POST',
+            path: `/egress/${opts.contractId}`,
+            params,
+            body: opts.events,
+            extraHeaders: extra,
+            timeoutMs: opts.timeoutMs,
+        });
+        return egressResponseFromJson(body);
+    }
+    // ── Audit ─────────────────────────────────────────────────────────────────
+    async audit(opts = {}) {
+        const params = {
+            limit: String(opts.limit ?? 50),
+            offset: String(opts.offset ?? 0),
+        };
+        if (opts.contractId)
+            params['contract_id'] = opts.contractId;
+        const body = await this.request({ method: 'GET', path: '/audit', params, timeoutMs: opts.timeoutMs });
+        return expectList(body).map(auditEntryFromJson);
+    }
+    async stats(opts = {}) {
+        const body = await this.request({ method: 'GET', path: '/stats', timeoutMs: opts.timeoutMs });
+        return ingestionStatsFromJson(body);
+    }
+    // ── Contract reads ────────────────────────────────────────────────────────
+    async getContract(contractId, opts = {}) {
+        const body = await this.request({
+            method: 'GET',
+            path: `/contracts/${contractId}`,
+            timeoutMs: opts.timeoutMs,
+        });
+        return contractResponseFromJson(body);
+    }
+    async listContracts(opts = {}) {
+        const body = await this.request({ method: 'GET', path: '/contracts', timeoutMs: opts.timeoutMs });
+        return expectList(body).map(contractResponseFromJson);
+    }
+    async listVersions(contractId, opts = {}) {
+        const body = await this.request({
+            method: 'GET',
+            path: `/contracts/${contractId}/versions`,
+            timeoutMs: opts.timeoutMs,
+        });
+        return expectList(body).map(versionSummaryFromJson);
+    }
+    async getVersion(contractId, version, opts = {}) {
+        const body = await this.request({
+            method: 'GET',
+            path: `/contracts/${contractId}/versions/${version}`,
+            timeoutMs: opts.timeoutMs,
+        });
+        return versionResponseFromJson(body);
+    }
+    async getLatestStable(contractId, opts = {}) {
+        const body = await this.request({
+            method: 'GET',
+            path: `/contracts/${contractId}/versions/latest-stable`,
+            timeoutMs: opts.timeoutMs,
+        });
+        return versionResponseFromJson(body);
+    }
+    // ── Playground ────────────────────────────────────────────────────────────
+    async playgroundValidate(opts) {
+        return this.request({
+            method: 'POST',
+            path: '/playground/validate',
+            body: { yaml_content: opts.yamlContent, event: opts.event },
+            timeoutMs: opts.timeoutMs,
+        });
+    }
+    // ── Internal ──────────────────────────────────────────────────────────────
+    buildUrl(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        return url.toString();
+    }
+    buildHeaders(extra) {
+        const h = {
+            'User-Agent': USER_AGENT,
+            'Accept': 'application/json',
+        };
+        if (this.apiKey)
+            h['x-api-key'] = this.apiKey;
+        if (this.orgId)
+            h['x-org-id'] = this.orgId;
+        if (extra)
+            Object.assign(h, extra);
+        return h;
+    }
+    async request(opts) {
+        const url = this.buildUrl(opts.path, opts.params);
+        const headers = this.buildHeaders(opts.extraHeaders);
+        let bodyStr;
+        if (opts.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            bodyStr = JSON.stringify(opts.body);
+        }
+        const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+        let response;
+        try {
+            response = await this.fetchFn(url, {
+                method: opts.method,
+                headers,
+                body: bodyStr,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (e) {
+            throw new ConnectionError(String(e));
+        }
+        const text = await response.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        raiseForStatus(response.status, parsed);
+        return parsed;
+    }
+}

package/dist/contract.d.ts

@@ -0,0 +1,59 @@
+import type { ValidationResult } from './types.js';
+export type FieldType = 'string' | 'integer' | 'float' | 'boolean' | 'object' | 'array' | 'any';
+export declare function fieldTypeDisplay(ft: FieldType): string;
+export type TransformKind = 'mask' | 'hash' | 'drop' | 'redact';
+export type MaskStyle = 'opaque' | 'format_preserving';
+export interface Transform {
+    kind: TransformKind;
+    style?: MaskStyle;
+}
+export interface FieldDefinition {
+    name: string;
+    fieldType: FieldType;
+    required: boolean;
+    pattern?: string;
+    allowedValues?: unknown[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    properties?: FieldDefinition[];
+    items?: FieldDefinition;
+    transform?: Transform;
+}
+export type MetricType = 'integer' | 'float';
+export interface MetricDefinition {
+    name: string;
+    field?: string;
+    metricType?: MetricType;
+    formula?: string;
+    min?: number;
+    max?: number;
+}
+export interface GlossaryEntry {
+    field: string;
+    description: string;
+    constraints?: string;
+    synonyms?: string[];
+}
+export interface ContractData {
+    version: string;
+    name: string;
+    description?: string;
+    complianceMode: boolean;
+    entities: FieldDefinition[];
+    glossary: GlossaryEntry[];
+    metrics: MetricDefinition[];
+}
+export interface CompiledContract {
+    contract: ContractData;
+    patterns: Map<string, RegExp>;
+    declaredTopLevelFields: Set<string>;
+    validate(event: unknown): ValidationResult;
+}
+export declare class Contract {
+    private readonly data;
+    private constructor();
+    static fromYaml(source: string): Contract;
+    compile(): CompiledContract;
+}

package/dist/contract.js

@@ -0,0 +1,244 @@
+import yaml from 'js-yaml';
+import { ContractCompileError } from './errors.js';
+// validate is imported at runtime; validator.ts uses only "import type" from this
+// module so there is no cycle in the compiled JavaScript.
+import { validate as runValidate } from './validator.js';
+const FIELD_TYPE_DISPLAY = {
+    string: 'String',
+    integer: 'Integer',
+    float: 'Float',
+    boolean: 'Boolean',
+    object: 'Object',
+    array: 'Array',
+    any: 'Any',
+};
+export function fieldTypeDisplay(ft) {
+    return FIELD_TYPE_DISPLAY[ft];
+}
+function parseFieldType(raw) {
+    if (typeof raw !== 'string') {
+        throw new ContractCompileError(`field type must be a string, got ${typeof raw}`);
+    }
+    const normalized = raw.toLowerCase() === 'number' ? 'float' : raw.toLowerCase();
+    const valid = ['string', 'integer', 'float', 'boolean', 'object', 'array', 'any'];
+    if (!valid.includes(normalized)) {
+        throw new ContractCompileError(`unknown field type: ${JSON.stringify(raw)}`);
+    }
+    return normalized;
+}
+function parseTransform(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ContractCompileError('transform must be a mapping');
+    }
+    const r = raw;
+    const kindRaw = r['kind'];
+    if (typeof kindRaw !== 'string') {
+        throw new ContractCompileError('transform.kind is required and must be a string');
+    }
+    const validKinds = ['mask', 'hash', 'drop', 'redact'];
+    const kind = kindRaw.toLowerCase();
+    if (!validKinds.includes(kind)) {
+        throw new ContractCompileError(`unknown transform kind: ${JSON.stringify(kindRaw)}`);
+    }
+    let style;
+    if (r['style'] != null) {
+        const validStyles = ['opaque', 'format_preserving'];
+        const s = String(r['style']).toLowerCase();
+        if (!validStyles.includes(s)) {
+            throw new ContractCompileError(`unknown mask style: ${JSON.stringify(r['style'])}`);
+        }
+        style = s;
+    }
+    return { kind, style };
+}
+function parseFieldDefinition(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ContractCompileError(`entity must be a mapping, got ${typeof raw}`);
+    }
+    const r = raw;
+    const name = r['name'];
+    if (typeof name !== 'string' || !name) {
+        throw new ContractCompileError('entity.name is required');
+    }
+    const fieldType = parseFieldType(r['type']);
+    let properties;
+    if (r['properties'] != null) {
+        if (!Array.isArray(r['properties'])) {
+            throw new ContractCompileError(`${name}.properties must be a list`);
+        }
+        properties = r['properties'].map(parseFieldDefinition);
+    }
+    let items;
+    if (r['items'] != null) {
+        items = parseFieldDefinition(r['items']);
+    }
+    let transform;
+    if (r['transform'] != null) {
+        transform = parseTransform(r['transform']);
+    }
+    return {
+        name,
+        fieldType,
+        required: r['required'] !== false,
+        pattern: typeof r['pattern'] === 'string' ? r['pattern'] : undefined,
+        allowedValues: Array.isArray(r['enum']) ? r['enum'] : undefined,
+        min: typeof r['min'] === 'number' ? r['min'] : undefined,
+        max: typeof r['max'] === 'number' ? r['max'] : undefined,
+        minLength: typeof r['min_length'] === 'number' ? Math.trunc(r['min_length']) : undefined,
+        maxLength: typeof r['max_length'] === 'number' ? Math.trunc(r['max_length']) : undefined,
+        properties,
+        items,
+        transform,
+    };
+}
+function parseMetricDefinition(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ContractCompileError('metric must be a mapping');
+    }
+    const r = raw;
+    const name = r['name'];
+    if (typeof name !== 'string' || !name) {
+        throw new ContractCompileError('metric.name is required');
+    }
+    let metricType;
+    if (r['type'] != null) {
+        const mt = String(r['type']).toLowerCase();
+        if (mt !== 'integer' && mt !== 'float') {
+            throw new ContractCompileError(`unknown metric type: ${JSON.stringify(r['type'])}`);
+        }
+        metricType = mt;
+    }
+    return {
+        name,
+        field: typeof r['field'] === 'string' ? r['field'] : undefined,
+        metricType,
+        formula: typeof r['formula'] === 'string' ? r['formula'] : undefined,
+        min: typeof r['min'] === 'number' ? r['min'] : undefined,
+        max: typeof r['max'] === 'number' ? r['max'] : undefined,
+    };
+}
+function parseGlossaryEntry(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ContractCompileError('glossary entry must be a mapping');
+    }
+    const r = raw;
+    const fieldName = r['field'] ?? r['term'];
+    const description = r['description'] ?? r['definition'];
+    if (typeof fieldName !== 'string' || !fieldName) {
+        throw new ContractCompileError('glossary.field (or .term) is required');
+    }
+    if (typeof description !== 'string' || !description) {
+        throw new ContractCompileError('glossary.description (or .definition) is required');
+    }
+    let synonyms;
+    if (r['synonyms'] != null) {
+        if (!Array.isArray(r['synonyms'])) {
+            throw new ContractCompileError('glossary.synonyms must be a list');
+        }
+        synonyms = r['synonyms'].map(String);
+    }
+    return {
+        field: fieldName,
+        description,
+        constraints: typeof r['constraints'] === 'string' ? r['constraints'] : undefined,
+        synonyms,
+    };
+}
+export class Contract {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    static fromYaml(source) {
+        let raw;
+        try {
+            raw = yaml.load(source);
+        }
+        catch (e) {
+            throw new ContractCompileError(`invalid YAML: ${e}`);
+        }
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new ContractCompileError('contract YAML must be a mapping at the top level');
+        }
+        const r = raw;
+        const version = r['version'];
+        const name = r['name'];
+        if (typeof version !== 'string' || !version) {
+            throw new ContractCompileError('contract.version is required');
+        }
+        if (typeof name !== 'string' || !name) {
+            throw new ContractCompileError('contract.name is required');
+        }
+        const ontologyRaw = r['ontology'];
+        if (ontologyRaw === null || typeof ontologyRaw !== 'object' || Array.isArray(ontologyRaw)) {
+            throw new ContractCompileError('contract.ontology is required and must be a mapping');
+        }
+        const entitiesRaw = ontologyRaw['entities'];
+        if (!Array.isArray(entitiesRaw)) {
+            throw new ContractCompileError('contract.ontology.entities must be a list');
+        }
+        const entities = entitiesRaw.map(parseFieldDefinition);
+        const glossary = Array.isArray(r['glossary'])
+            ? r['glossary'].map(parseGlossaryEntry)
+            : [];
+        const metrics = Array.isArray(r['metrics'])
+            ? r['metrics'].map(parseMetricDefinition)
+            : [];
+        return new Contract({
+            version,
+            name,
+            description: typeof r['description'] === 'string' ? r['description'] : undefined,
+            complianceMode: r['compliance_mode'] === true,
+            entities,
+            glossary,
+            metrics,
+        });
+    }
+    compile() {
+        const patterns = new Map();
+        compileFieldPatterns(this.data.entities, '', patterns);
+        validateTransformTypes(this.data.entities, '');
+        const declaredTopLevelFields = this.data.complianceMode
+            ? new Set(this.data.entities.map((e) => e.name))
+            : new Set();
+        const compiled = {
+            contract: this.data,
+            patterns,
+            declaredTopLevelFields,
+            validate(event) {
+                return runValidate(compiled, event);
+            },
+        };
+        return compiled;
+    }
+}
+// ---------------------------------------------------------------------------
+// Compile helpers
+// ---------------------------------------------------------------------------
+function compileFieldPatterns(fields, prefix, out) {
+    for (const f of fields) {
+        const path = prefix ? `${prefix}.${f.name}` : f.name;
+        if (f.pattern != null) {
+            try {
+                out.set(path, new RegExp(f.pattern));
+            }
+            catch (e) {
+                throw new ContractCompileError(`Invalid regex ${JSON.stringify(f.pattern)} for field ${JSON.stringify(path)}: ${e}`);
+            }
+        }
+        if (f.fieldType === 'object' && f.properties) {
+            compileFieldPatterns(f.properties, path, out);
+        }
+    }
+}
+function validateTransformTypes(fields, prefix) {
+    for (const f of fields) {
+        const path = prefix ? `${prefix}.${f.name}` : f.name;
+        if (f.transform != null && f.fieldType !== 'string') {
+            throw new ContractCompileError(`Field '${path}' declares a PII transform but has type '${fieldTypeDisplay(f.fieldType)}' — transforms are only supported on string fields. If this field holds PII, change its type to 'string'.`);
+        }
+        if (f.fieldType === 'object' && f.properties) {
+            validateTransformTypes(f.properties, path);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+export declare class ContractGateError extends Error {
+    constructor(message: string);
+}
+export declare class ContractCompileError extends ContractGateError {
+}
+export declare class ConnectionError extends ContractGateError {
+}
+export declare class HTTPError extends ContractGateError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class BadRequestError extends HTTPError {
+}
+export declare class AuthError extends HTTPError {
+}
+export declare class NotFoundError extends HTTPError {
+}
+export declare class ConflictError extends HTTPError {
+}
+export declare class ValidationFailedError extends HTTPError {
+}
+export declare class ServerError extends HTTPError {
+}
+type HTTPErrorCtor = new (message: string, status: number, body: unknown) => HTTPError;
+export declare function statusToException(status: number): HTTPErrorCtor;
+export declare function raiseForStatus(status: number, body: unknown): void;
+export {};

package/dist/errors.js

@@ -0,0 +1,63 @@
+export class ContractGateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+export class ContractCompileError extends ContractGateError {
+}
+export class ConnectionError extends ContractGateError {
+}
+export class HTTPError extends ContractGateError {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class BadRequestError extends HTTPError {
+}
+export class AuthError extends HTTPError {
+}
+export class NotFoundError extends HTTPError {
+}
+export class ConflictError extends HTTPError {
+}
+export class ValidationFailedError extends HTTPError {
+}
+export class ServerError extends HTTPError {
+}
+export function statusToException(status) {
+    if (status === 400)
+        return BadRequestError;
+    if (status === 401)
+        return AuthError;
+    if (status === 404)
+        return NotFoundError;
+    if (status === 409)
+        return ConflictError;
+    if (status === 422)
+        return ValidationFailedError;
+    if (status >= 500 && status < 600)
+        return ServerError;
+    return HTTPError;
+}
+export function raiseForStatus(status, body) {
+    if (status >= 200 && status < 300)
+        return;
+    const Cls = statusToException(status);
+    const message = extractErrorMessage(body) ?? `HTTP ${status}`;
+    throw new Cls(message, status, body);
+}
+function extractErrorMessage(body) {
+    if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+        const b = body;
+        for (const key of ['error', 'message', 'detail']) {
+            if (typeof b[key] === 'string')
+                return b[key];
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Client } from './client.js';
+export type { ClientOptions } from './client.js';
+export { Contract } from './contract.js';
+export type { CompiledContract, ContractData, FieldDefinition, FieldType, GlossaryEntry, MaskStyle, MetricDefinition, MetricType, Transform, TransformKind, } from './contract.js';
+export { AuthError, BadRequestError, ConflictError, ConnectionError, ContractCompileError, ContractGateError, HTTPError, NotFoundError, ServerError, ValidationFailedError, } from './errors.js';
+export type { AuditEntry, BatchIngestResponse, ContractResponse, EgressOutcome, EgressResponse, IngestionStats, IngestEventResult, ValidationResult, Violation, ViolationKind, VersionResponse, VersionSummary, } from './types.js';
+export { validate } from './validator.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Client } from './client.js';
+export { Contract } from './contract.js';
+export { AuthError, BadRequestError, ConflictError, ConnectionError, ContractCompileError, ContractGateError, HTTPError, NotFoundError, ServerError, ValidationFailedError, } from './errors.js';
+export { validate } from './validator.js';

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+export type ViolationKind = 'missing_required_field' | 'type_mismatch' | 'pattern_mismatch' | 'enum_violation' | 'range_violation' | 'length_violation' | 'metric_range_violation' | 'unknown_field' | 'undeclared_field';
+export interface Violation {
+    field: string;
+    message: string;
+    kind: ViolationKind;
+}
+export interface ValidationResult {
+    passed: boolean;
+    violations: Violation[];
+    validation_us: number;
+}
+export interface IngestEventResult {
+    passed: boolean;
+    violations: Violation[];
+    validation_us: number;
+    forwarded: boolean;
+    contract_version: string;
+    transformed_event: unknown;
+}
+export interface BatchIngestResponse {
+    total: number;
+    passed: number;
+    failed: number;
+    dry_run: boolean;
+    atomic: boolean;
+    resolved_version: string;
+    version_pin_source: string;
+    results: IngestEventResult[];
+}
+export interface EgressOutcome {
+    index: number;
+    passed: boolean;
+    violations: Violation[];
+    validation_us: number;
+    action: string;
+}
+export interface EgressResponse {
+    total: number;
+    passed: number;
+    failed: number;
+    dry_run: boolean;
+    disposition: string;
+    resolved_version: string;
+    payload: unknown[];
+    outcomes: EgressOutcome[];
+}
+export interface ContractResponse {
+    id: string;
+    name: string;
+    description: string | null;
+    multi_stable_resolution: string;
+    created_at: string;
+    updated_at: string;
+    version_count: number;
+    latest_stable_version: string | null;
+}
+export interface VersionResponse {
+    id: string;
+    contract_id: string;
+    version: string;
+    state: string;
+    yaml_content: string;
+    created_at: string;
+    promoted_at: string | null;
+    deprecated_at: string | null;
+    compliance_mode: boolean;
+}
+export interface VersionSummary {
+    version: string;
+    state: string;
+    created_at: string;
+    promoted_at: string | null;
+    deprecated_at: string | null;
+}
+export interface AuditEntry {
+    id: string;
+    contract_id: string;
+    contract_version: string | null;
+    passed: boolean;
+    violation_count: number;
+    violation_details: unknown;
+    raw_event: unknown;
+    validation_us: number;
+    source_ip: string | null;
+    created_at: string;
+}
+export interface IngestionStats {
+    total_events: number;
+    passed_events: number;
+    failed_events: number;
+    pass_rate: number;
+    avg_validation_us: number;
+    p50_validation_us: number;
+    p95_validation_us: number;
+    p99_validation_us: number;
+}
+export declare function violationFromJson(raw: unknown): Violation;
+export declare function validationResultFromJson(raw: unknown): ValidationResult;
+export declare function ingestEventResultFromJson(raw: unknown): IngestEventResult;
+export declare function batchIngestResponseFromJson(raw: unknown): BatchIngestResponse;
+export declare function egressOutcomeFromJson(raw: unknown): EgressOutcome;
+export declare function egressResponseFromJson(raw: unknown): EgressResponse;
+export declare function contractResponseFromJson(raw: unknown): ContractResponse;
+export declare function versionResponseFromJson(raw: unknown): VersionResponse;
+export declare function versionSummaryFromJson(raw: unknown): VersionSummary;
+export declare function auditEntryFromJson(raw: unknown): AuditEntry;
+export declare function ingestionStatsFromJson(raw: unknown): IngestionStats;
+export declare function expectList(body: unknown): unknown[];

package/dist/types.js

@@ -0,0 +1,155 @@
+function toRaw(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+        throw new Error(`Expected object, got ${JSON.stringify(v)}`);
+    }
+    return v;
+}
+function optStr(v) {
+    return typeof v === 'string' ? v : null;
+}
+function toBool(v, fallback = false) {
+    return typeof v === 'boolean' ? v : fallback;
+}
+function toInt(v, fallback = 0) {
+    return typeof v === 'number' ? Math.trunc(v) : fallback;
+}
+export function violationFromJson(raw) {
+    const r = toRaw(raw);
+    return {
+        field: String(r['field'] ?? ''),
+        message: String(r['message'] ?? ''),
+        kind: String(r['kind'] ?? ''),
+    };
+}
+export function validationResultFromJson(raw) {
+    const r = toRaw(raw);
+    const vList = Array.isArray(r['violations']) ? r['violations'] : [];
+    return {
+        passed: toBool(r['passed']),
+        violations: vList.map(violationFromJson),
+        validation_us: toInt(r['validation_us']),
+    };
+}
+export function ingestEventResultFromJson(raw) {
+    const r = toRaw(raw);
+    const vList = Array.isArray(r['violations']) ? r['violations'] : [];
+    return {
+        passed: toBool(r['passed']),
+        violations: vList.map(violationFromJson),
+        validation_us: toInt(r['validation_us']),
+        forwarded: toBool(r['forwarded']),
+        contract_version: String(r['contract_version'] ?? ''),
+        transformed_event: r['transformed_event'] ?? null,
+    };
+}
+export function batchIngestResponseFromJson(raw) {
+    const r = toRaw(raw);
+    const rList = Array.isArray(r['results']) ? r['results'] : [];
+    return {
+        total: toInt(r['total']),
+        passed: toInt(r['passed']),
+        failed: toInt(r['failed']),
+        dry_run: toBool(r['dry_run']),
+        atomic: toBool(r['atomic']),
+        resolved_version: String(r['resolved_version'] ?? ''),
+        version_pin_source: String(r['version_pin_source'] ?? ''),
+        results: rList.map(ingestEventResultFromJson),
+    };
+}
+export function egressOutcomeFromJson(raw) {
+    const r = toRaw(raw);
+    const vList = Array.isArray(r['violations']) ? r['violations'] : [];
+    return {
+        index: toInt(r['index']),
+        passed: toBool(r['passed']),
+        violations: vList.map(violationFromJson),
+        validation_us: toInt(r['validation_us']),
+        action: String(r['action'] ?? ''),
+    };
+}
+export function egressResponseFromJson(raw) {
+    const r = toRaw(raw);
+    const oList = Array.isArray(r['outcomes']) ? r['outcomes'] : [];
+    return {
+        total: toInt(r['total']),
+        passed: toInt(r['passed']),
+        failed: toInt(r['failed']),
+        dry_run: toBool(r['dry_run']),
+        disposition: String(r['disposition'] ?? 'block'),
+        resolved_version: String(r['resolved_version'] ?? ''),
+        payload: Array.isArray(r['payload']) ? r['payload'] : [],
+        outcomes: oList.map(egressOutcomeFromJson),
+    };
+}
+export function contractResponseFromJson(raw) {
+    const r = toRaw(raw);
+    return {
+        id: String(r['id'] ?? ''),
+        name: String(r['name'] ?? ''),
+        description: optStr(r['description']),
+        multi_stable_resolution: String(r['multi_stable_resolution'] ?? 'strict'),
+        created_at: String(r['created_at'] ?? ''),
+        updated_at: String(r['updated_at'] ?? ''),
+        version_count: toInt(r['version_count']),
+        latest_stable_version: optStr(r['latest_stable_version']),
+    };
+}
+export function versionResponseFromJson(raw) {
+    const r = toRaw(raw);
+    return {
+        id: String(r['id'] ?? ''),
+        contract_id: String(r['contract_id'] ?? ''),
+        version: String(r['version'] ?? ''),
+        state: String(r['state'] ?? ''),
+        yaml_content: String(r['yaml_content'] ?? ''),
+        created_at: String(r['created_at'] ?? ''),
+        promoted_at: optStr(r['promoted_at']),
+        deprecated_at: optStr(r['deprecated_at']),
+        compliance_mode: toBool(r['compliance_mode']),
+    };
+}
+export function versionSummaryFromJson(raw) {
+    const r = toRaw(raw);
+    return {
+        version: String(r['version'] ?? ''),
+        state: String(r['state'] ?? ''),
+        created_at: String(r['created_at'] ?? ''),
+        promoted_at: optStr(r['promoted_at']),
+        deprecated_at: optStr(r['deprecated_at']),
+    };
+}
+export function auditEntryFromJson(raw) {
+    const r = toRaw(raw);
+    return {
+        id: String(r['id'] ?? ''),
+        contract_id: String(r['contract_id'] ?? ''),
+        contract_version: optStr(r['contract_version']),
+        passed: toBool(r['passed']),
+        violation_count: toInt(r['violation_count']),
+        violation_details: r['violation_details'] ?? null,
+        raw_event: r['raw_event'] ?? null,
+        validation_us: toInt(r['validation_us']),
+        source_ip: optStr(r['source_ip']),
+        created_at: String(r['created_at'] ?? ''),
+    };
+}
+export function ingestionStatsFromJson(raw) {
+    const r = toRaw(raw);
+    return {
+        total_events: toInt(r['total_events']),
+        passed_events: toInt(r['passed_events']),
+        failed_events: toInt(r['failed_events']),
+        pass_rate: typeof r['pass_rate'] === 'number' ? r['pass_rate'] : 0,
+        avg_validation_us: typeof r['avg_validation_us'] === 'number' ? r['avg_validation_us'] : 0,
+        p50_validation_us: toInt(r['p50_validation_us']),
+        p95_validation_us: toInt(r['p95_validation_us']),
+        p99_validation_us: toInt(r['p99_validation_us']),
+    };
+}
+export function expectList(body) {
+    if (body === null || body === undefined)
+        return [];
+    if (Array.isArray(body))
+        return body;
+    throw new Error(`Expected list response, got ${typeof body}`);
+}

package/dist/validator.d.ts

@@ -0,0 +1,4 @@
+import type { CompiledContract } from './contract.js';
+import type { ValidationResult, ViolationKind } from './types.js';
+export declare function validate(compiled: CompiledContract, event: unknown): ValidationResult;
+export type { ViolationKind };

package/dist/validator.js

@@ -0,0 +1,229 @@
+import { fieldTypeDisplay } from './contract.js';
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+export function validate(compiled, event) {
+    const t0 = performance.now();
+    const violations = [];
+    if (event === null || typeof event !== 'object' || Array.isArray(event)) {
+        return {
+            passed: false,
+            violations: [
+                {
+                    field: '<root>',
+                    message: 'Event must be a JSON object',
+                    kind: 'type_mismatch',
+                },
+            ],
+            validation_us: 0,
+        };
+    }
+    const ev = event;
+    // 1. Ontology fields
+    validateFields(compiled.contract.entities, ev, '', compiled.patterns, violations);
+    // 2. Metric definitions
+    for (const metric of compiled.contract.metrics) {
+        validateMetric(metric, ev, violations);
+    }
+    // 3. Compliance-mode undeclared field check (last — keeps standard violations
+    //    first, matching Rust order so triage workflows need no special-casing).
+    if (compiled.contract.complianceMode) {
+        for (const key of Object.keys(ev)) {
+            if (!compiled.declaredTopLevelFields.has(key)) {
+                violations.push({
+                    field: key,
+                    message: `Field '${key}' is not declared in the contract ontology. ` +
+                        'Compliance mode rejects undeclared fields.',
+                    kind: 'undeclared_field',
+                });
+            }
+        }
+    }
+    const elapsed_us = Math.round((performance.now() - t0) * 1000);
+    return { passed: violations.length === 0, violations, validation_us: elapsed_us };
+}
+// ---------------------------------------------------------------------------
+// Field walker
+// ---------------------------------------------------------------------------
+function validateFields(fields, data, prefix, patterns, violations) {
+    for (const f of fields) {
+        const path = prefix ? `${prefix}.${f.name}` : f.name;
+        if (!(f.name in data)) {
+            if (f.required) {
+                violations.push({
+                    field: path,
+                    message: `Required field '${f.name}' is missing`,
+                    kind: 'missing_required_field',
+                });
+            }
+            continue;
+        }
+        validateValue(f, data[f.name], path, patterns, violations);
+    }
+}
+function validateValue(f, value, path, patterns, violations) {
+    // --- Type check ---
+    if (!typeMatches(f.fieldType, value)) {
+        violations.push({
+            field: path,
+            message: `Field '${path}' expected type ${fieldTypeDisplay(f.fieldType)}, ` +
+                `got ${jsonTypeName(value)}`,
+            kind: 'type_mismatch',
+        });
+        return; // Further checks on the wrong type are noise.
+    }
+    // --- String checks ---
+    if (typeof value === 'string') {
+        if (f.minLength != null && value.length < f.minLength) {
+            violations.push({
+                field: path,
+                message: `Field '${path}' length ${value.length} is below minimum ${f.minLength}`,
+                kind: 'length_violation',
+            });
+        }
+        if (f.maxLength != null && value.length > f.maxLength) {
+            violations.push({
+                field: path,
+                message: `Field '${path}' length ${value.length} exceeds maximum ${f.maxLength}`,
+                kind: 'length_violation',
+            });
+        }
+        const regex = patterns.get(path);
+        if (regex != null && !regex.test(value)) {
+            violations.push({
+                field: path,
+                message: `Field '${path}' value ${JSON.stringify(value)} does not match required pattern`,
+                kind: 'pattern_mismatch',
+            });
+        }
+    }
+    // --- Numeric range checks ---
+    const n = numericValue(value);
+    if (n !== null) {
+        if (f.min != null && n < f.min) {
+            violations.push({
+                field: path,
+                message: `Field '${path}' value ${formatNumber(n)} is below minimum ${formatNumber(f.min)}`,
+                kind: 'range_violation',
+            });
+        }
+        if (f.max != null && n > f.max) {
+            violations.push({
+                field: path,
+                message: `Field '${path}' value ${formatNumber(n)} exceeds maximum ${formatNumber(f.max)}`,
+                kind: 'range_violation',
+            });
+        }
+    }
+    // --- Enum check ---
+    if (f.allowedValues != null && !f.allowedValues.some((av) => deepEqual(av, value))) {
+        const rendered = f.allowedValues.map((v) => JSON.stringify(v)).join(', ');
+        violations.push({
+            field: path,
+            message: `Field '${path}' value ${JSON.stringify(value)} not in allowed set: [${rendered}]`,
+            kind: 'enum_violation',
+        });
+    }
+    // --- Recurse into nested objects ---
+    if (f.fieldType === 'object' && f.properties && typeof value === 'object' && value !== null) {
+        validateFields(f.properties, value, path, patterns, violations);
+    }
+    // --- Recurse into array items ---
+    if (f.fieldType === 'array' && f.items != null && Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            validateValue(f.items, value[i], `${path}[${i}]`, patterns, violations);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Metric walker
+// ---------------------------------------------------------------------------
+function validateMetric(metric, event, violations) {
+    if (metric.field == null)
+        return; // formula-only metric
+    if (metric.min == null && metric.max == null)
+        return;
+    const rawValue = resolvePath(event, metric.field);
+    const n = rawValue != null ? numericValue(rawValue) : null;
+    if (n === null) {
+        violations.push({
+            field: metric.field,
+            message: `Metric '${metric.name}' field '${metric.field}' is missing or not numeric`,
+            kind: 'missing_required_field',
+        });
+        return;
+    }
+    if (metric.min != null && n < metric.min) {
+        violations.push({
+            field: metric.field,
+            message: `Metric '${metric.name}' value ${formatNumber(n)} is below ` +
+                `minimum ${formatNumber(metric.min)} (field: '${metric.field}')`,
+            kind: 'metric_range_violation',
+        });
+    }
+    if (metric.max != null && n > metric.max) {
+        violations.push({
+            field: metric.field,
+            message: `Metric '${metric.name}' value ${formatNumber(n)} exceeds ` +
+                `maximum ${formatNumber(metric.max)} (field: '${metric.field}')`,
+            kind: 'metric_range_violation',
+        });
+    }
+}
+function typeMatches(ft, value) {
+    switch (ft) {
+        case 'string': return typeof value === 'string';
+        // JSON booleans are typeof 'boolean', not 'number', so Number.isInteger
+        // correctly rejects them without an extra boolean guard.
+        case 'integer': return typeof value === 'number' && Number.isInteger(value);
+        case 'float': return typeof value === 'number';
+        case 'boolean': return typeof value === 'boolean';
+        case 'object':
+            return value !== null && typeof value === 'object' && !Array.isArray(value);
+        case 'array': return Array.isArray(value);
+        case 'any': return true;
+    }
+}
+function numericValue(value) {
+    if (typeof value === 'number')
+        return value;
+    return null;
+}
+function resolvePath(value, path) {
+    let current = value;
+    for (const key of path.split('.')) {
+        if (current === null || typeof current !== 'object' || Array.isArray(current)) {
+            return null;
+        }
+        current = current[key];
+        if (current == null)
+            return null;
+    }
+    return current;
+}
+function jsonTypeName(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'integer' : 'float';
+    }
+    if (typeof value === 'string')
+        return 'string';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'object')
+        return 'object';
+    return typeof value;
+}
+function formatNumber(n) {
+    // Match Rust's Display: whole numbers render without a decimal point.
+    // In JS, String(5.0) === "5" already, but be explicit for large integers.
+    if (Number.isInteger(n))
+        return String(n);
+    return String(n);
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nightmoose/contractgate-sdk",
+  "version": "0.2.0",
+  "description": "Official TypeScript SDK for ContractGate — HTTP client + local validator",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nightmoose/contractgate.git",
+    "directory": "sdks/typescript"
+  },
+  "keywords": [
+    "contractgate",
+    "data-contracts",
+    "validation",
+    "sdk"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}