ave-common

TypeScript type definitions for the Averiun Ledger API.

Auto-generated from Rust source code using ts-rs, keeping backend types and frontend interfaces aligned from the same source model.

Installation

npm install ave-common

Current package version: 0.9.0.

Usage

import type {
  BridgeSignedEventRequest,
  BridgeEventRequest,
  BridgeCreateRequest,
  SubjectDB,
  RequestState,
  LedgerDB
} from "ave-common";

// Example: Create event request
const createRequest: BridgeEventRequest = {
  event: "create",
  data: {
    name: "My Subject",
    description: "Subject description",
    governance_id: "EqDbWS...",
    schema_id: "governance",
    namespace: ["example", "namespace"]
  }
};

// Example: Signed request
const signedRequest: BridgeSignedEventRequest = {
  request: createRequest,
  signature: {
    signer: "EqCxN...",
    timestamp: 1234567890,
    value: "EqD8z...",
    content_hash: "EqBqK..."
  }
};

Available Types

Request Types

• BridgeSignedEventRequest - Wrapper for signed event requests
• BridgeEventRequest - Event request (tagged union)
• BridgeCreateRequest - Create a new subject
• BridgeFactRequest - Add facts to a subject
• BridgeTransferRequest - Transfer subject ownership
• BridgeConfirmRequest - Confirm a transfer
• BridgeRejectRequest - Reject a transfer
• BridgeEOLRequest - Mark subject as end-of-life
• EventRequestType - Enum of event types: "create" | "fact" | "transfer" | "confirm" | "reject" | "eol"

Response Types

• SubjectDB - Subject database record
• LedgerDB - Ledger event record with timestamps
• RequestState - Request processing state enum
• RequestEventDB - Database event representation (tagged union)
• RequestInfo - Request state and version
• RequestInfoExtend - Request state and version with request ID
• RequestData - Request ID and subject ID pair
• SubjsData - Subject metadata
• GovsData - Governance metadata
• Paginator - Pagination metadata
• PaginatorEvents - Paginated ledger events
• PaginatorAborts - Paginated abort events
• AbortDB - Abort event record
• EvalResDB - Evaluation result
• RequestsInManager - Request manager state
• RequestsInManagerSubject - Subject request queue state

Query Types

• SubjectQuery - Filter subjects by active and/or schema_id
• GovQuery - Filter governances by active
• EventsQuery - Filter ledger events by time ranges, page, quantity, and event type
• FirstEndEvents - Query for first/last events by type and quantity
• AbortsQuery - Filter abort events by request ID, sn, page, and quantity
• ApprovalQuery - Filter approvals by state
• TimeRange - ISO 8601 time range filter

Approval Types

• ApprovalEntry - Approval request combined with its current state
• ApprovalReq - Approval request data
• ApprovalState - Approval status: "Pending" | "RespondedAccepted" | "RespondedRejected" | "Obsolete"
• ApprovalStateRes - Approval response state (excludes "Pending")

Other Types

• BridgeSignature - Cryptographic signature with timestamp
• TransferSubject - Transfer subject data
• MonitorNetworkState - Network connectivity state
• DataToSink - Event sink data (tagged union)
• DataToSinkEvent - Sink event types (create, fact, transfer, etc.)
• Namespace - Subject namespace (Array<string>)
• SchemaType - Schema type: "Governance" | { Type: string } | "TrackerSchemas"
• JsonValue - Recursive JSON value type

Type Notes

Tagged Unions

Event types use TypeScript discriminated unions matching Rust's serde tag/content serialization:

type BridgeEventRequest =
  | { event: "create"; data: BridgeCreateRequest }
  | { event: "fact"; data: BridgeFactRequest }
  | { event: "transfer"; data: BridgeTransferRequest }
  // ...

Namespace

Namespace is an array of strings representing the hierarchical path of a subject:

const ns: Namespace = ["example", "namespace"]; // Array<string>

Number for u64/i64

Rust u64 and i64 fields (timestamps, sequence numbers) map to TypeScript number for JavaScript compatibility:

const timestamp = 1234567890; // number
const sn = 42; // number

Note: The types are generated with TS_RS_LARGE_INT=number to ensure compatibility with JavaScript's number type instead of bigint.

Optional Fields

Rust Option<T> becomes T | null in TypeScript:

signature: BridgeSignature | null

Development

Generating Types

To regenerate the TypeScript bindings from Rust source:

# From common/ts directory
npm run generate

# Or directly
bash generate.sh

This will:

1. Run cargo tests with the typescript feature enabled
2. Export types to src/ directory using ts-rs
3. Generate a barrel index.ts that re-exports all types
4. Use TS_RS_LARGE_INT=number to map Rust u64/i64 to TypeScript number

Checking for Drift Without Committing Generated Files

If you do not want to version src/**/*.ts, compare a fresh local generation against the currently published npm package:

npm run check:published

# Optional: print normalized diffs for real API changes
bash check-published.sh --full

That command:

1. Generates bindings in a temporary directory
2. Downloads ave-common@<package.json version> from npm
3. Groups drift into API changes vs docs/comment changes only
4. Fails if the published package differs from the current Rust type surface

This keeps the repository clean while still telling you when the TypeScript package is stale.

Publishing Updates

When Rust types are modified:

# 1. Regenerate types
npm run generate

# 2. Bump version and publish
npm run release:patch   # 0.3.3 -> 0.3.4
npm run release:minor   # 0.3.3 -> 0.4.0
npm run release:major   # 0.3.3 -> 1.0.0

This will automatically:

• Regenerate the types
• Bump the package version
• Publish to npm with public access

License

AGPL-3.0-only

Links

• Averiun Ledger
• GitHub Repository
• API Documentation (coming soon)

Generated from Rust • Built with ts-rs