# @aerograph/contracts

> Shared Zod contracts for AeroGraph trace events and APIs.

Latest version **0.3.0** (published 2026-06-30) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @aerograph/contracts
pnpm add @aerograph/contracts
yarn add @aerograph/contracts
bun add @aerograph/contracts
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-06-30 |
| First published | 2026-05-24 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 267 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Maintainers | sgcpu |
| Keywords | ai, agent, contracts, trace, zod |

## Links

- npm: https://www.npmjs.com/package/@aerograph/contracts
- Repository: https://github.com/SGcpu/AeroGraph
- Homepage: https://github.com/SGcpu/AeroGraph#readme
- Issues: https://github.com/SGcpu/AeroGraph/issues
- npm.io page: https://npm.io/package/@aerograph/contracts

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^3.25.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.3.0 (latest) — 2026-06-30
- 0.2.1 — 2026-06-10
- 0.2.0 — 2026-06-03
- 0.1.0 — 2026-05-24

## README

# @aerograph/contracts

The single source of truth for all AeroGraph Event schemas using Zod.

## Overview

AeroGraph employs a strict contract-first architecture. This package defines the canonical `TraceEvent` schemas, lineage graph types, and topological structures using Zod. It ensures deterministic validation on both ingress and egress at the collector.

## Installation

```bash
npm install @aerograph/contracts
```

*(Requires Node.js >= 18.18.0)*

## Usage

Use this package if you are building custom ingestion tools, backend extensions, or parsing scripts that need to validate AeroGraph schemas natively in TypeScript.

```typescript
import { validateTraceEvent, TraceEvent } from "@aerograph/contracts";

const rawEvent = {
  schemaVersion: "1.0.0",
  traceId: "some-trace-id",
  spanId: "some-span-id",
  parentSpanId: null,
  occurredAt: "2026-06-10T12:00:00.000Z",
  actor: { kind: "system", id: "app" },
  kind: "note",
  status: "ok",
  links: [],
  payload: { key: "value" }
};

// Validates the shape and returns a typed TraceEvent, or throws a ZodError
const event: TraceEvent = validateTraceEvent(rawEvent);
```

## Available Schemas

- `traceEventSchema` (Supports v1.1.0 with canonical `model`, `usage`, `projectId`, and `environment`)
- `traceLineageGraphSchema`
- `traceForkRequestSchema`
- `traceAnalysisSchema`
- `traceDiffResultSchema`
- `traceStatsSchema`

## License
Apache-2.0

---
_Source: https://npm.io/package/@aerograph/contracts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._