mizcausevic-dev/aeo-sdk-typescript

Purpose and principal workflow

This TypeScript SDK implements AEO Protocol v0.1 document parsing, validation, serialization, claim queries, and well-known URL fetching. An application or developer using the SDK initiates the workflow by calling its public API: either provide a document to parse, or provide an origin to fetch from. In the fetch path, the SDK requests /.well-known/aeo.json and parses the response into a validated document.

Components

Public SDK and document operations

• SDK public API — src/index.ts: Exports the document schemas, types, parsing and query functions, fetch helpers, and SDK version for consumers.

• Document model and operations — src/document.ts: Defines strict Zod schemas and inferred types; parses and safely validates inputs, serializes documents, and lists or finds claims.

Discovery and validation dependencies

• Well-known HTTP client — src/client.ts: Builds the discovery URL, fetches it with an Accept header and timeout/abort handling, checks the response, and passes its text to document parsing.

• Zod — null repository path (external dependency): Supplies the runtime schema validation and inferred types used by the document model.

• Native Fetch and timer APIs — null repository path (external runtime interfaces): Provide the HTTP request and timeout mechanism used by the client.

Actors

• SDK consumer — null repository path (external caller): Application or developer code that invokes the published SDK API and receives parsed documents or operation results.

• AEO declaration origin — null repository path (external system): Host serving the document at the protocol’s well-known path.

Relationships

• SDK consumer -> SDK public API: Calls exported SDK functions; the package entry point re-exports the document and client APIs.

• SDK public API -> Document model and operations: Re-exports schemas, types, parsing, serialization, and claim-query functions.

• SDK public API -> Well-known HTTP client: Re-exports fetchWellKnown and wellKnownUrl.

• SDK consumer -> Document model and operations: Calls parsing, validation, serialization, or claim-query functions through the public API.

• SDK consumer -> Well-known HTTP client: Calls fetchWellKnown through the public API with an origin and optional fetch settings.

• Well-known HTTP client -> AEO declaration origin: Sends an HTTP GET to the constructed well-known URL; this is a direct fetch, not an asynchronous job dispatch.

• Well-known HTTP client -> Native Fetch and timer APIs: Uses fetch for the request and setTimeout/clearTimeout for the timeout.

• Well-known HTTP client -> Document model and operations: Passes successful response text to parseDocument; non-success responses throw instead.

• Document model and operations -> Zod: Uses schemas to validate document fields and construct typed parse results.

• Document model and operations -> SDK consumer: Returns parsed or safely validated results, serialized JSON, claim IDs, or a matching claim.

Coverage limits

The source excerpts establish the client-to-parser call and the schema/query behavior. They do not establish deployment details for declaration origins or consumer applications. The README documents Level 1 (Declare) conformance and defers signature verification and audit-endpoint posting; those capabilities are not part of the demonstrated workflow.