STRUCTURE.md

SDK File Structure

Overview

The @affix-io/verification-sdk is a production-grade TypeScript SDK for AffixIO's verification API, focused on agentic payment authorization.

Directory Tree

Agentic/
├── src/
│   ├── index.ts              # Main export file (all public APIs)
│   ├── client.ts             # AffixioClient class (5 public methods)
│   ├── types.ts              # TypeScript definitions (15 types)
│   ├── errors.ts             # Error classes (3 custom errors + base)
│   ├── http.ts               # HTTP abstraction (fetch wrapper)
│   └── helpers.ts            # Helper functions (6 builders + utilities)
├── tests/
│   └── client.test.ts        # Comprehensive test suite
├── examples/
│   └── full-usage.ts         # 6 real-world usage examples
├── package.json              # npm metadata + scripts
├── tsconfig.json             # TypeScript config
├── .npmignore                # npm publish exclusions
├── .gitignore                # git exclusions
├── README.md                 # Quick start & API reference
├── ARCHITECTURE.md           # Design decisions & extension guide
└── STRUCTURE.md              # This file

File Descriptions

Core SDK (src/)

index.ts (35 lines)

Public API surface. Exports:

• AffixioClient - main class
• Error classes: AffixioError, AffixioTransportError, AffixioApiError, AffixioValidationError
• Types: AffixioClientConfig, CircuitId, VerifyRequest, VerifyResponse, etc.
• Helpers: buildIssuerAuthRequest, generateRequestId, etc.

client.ts (260 lines)

Main SDK class. Contains:

• Constructor with config validation
• Static fromEnv() factory
• verify<TContext>() - generic verification
• verifyIssuerAgentAuthorization() - issuer auth flow
• verifyMerchantAgentCheckout() - merchant checkout flow
• verifyAgentConsent() - consent verification
• verifyAgentPaymentComposite() - multi-circuit verification
• Logging integration for all methods

types.ts (150 lines)

Type definitions (no runtime code).

• AffixioClientConfig - client setup
• Logger interface - custom logging
• CircuitId - union of known circuits
• VerifyRequest<TContext> - generic request template
• VerifyResponse - standard response
• Request/response types for each helper:
  • IssuerAgentAuthorizationRequest
  • MerchantAgentCheckoutRequest
  • AgentConsentRequest
  • AgentPaymentCompositeRequest / Response
• HTTP error details type

errors.ts (60 lines)

Custom error classes:

• AffixioError - base class with code + metadata
• AffixioTransportError - network/timeout (retryable)
• AffixioApiError - 4xx/5xx responses (may be retryable)
• AffixioValidationError - client-side validation (not retryable)

Each includes metadata for logging and debugging.

http.ts (130 lines)

Low-level HTTP abstraction:

• HttpClient class with post<T>() and get<T>() methods
• Timeout enforcement using AbortController
• Error mapping (TypeError → AffixioTransportError, HTTP errors → AffixioApiError)
• Authorization header (Bearer token)
• Request ID propagation (X-Request-ID)
• Uses native Node.js fetch (v18+)

helpers.ts (120 lines)

Utility functions:

• buildIssuerAuthRequest() - convert high-level request to VerifyRequest
• buildMerchantCheckoutRequest() - same for checkout
• buildAgentConsentRequest() - same for consent
• getDefaultCompositeCircuits() - returns default 3-circuit chain
• buildCompositeContext() - assemble context for composite verification
• buildVerifyRequestForCircuit() - generic request builder
• validateRequired() - field validation
• aggregateProofs() - combine proofs from multiple circuits
• generateRequestId() - create unique request IDs

Testing (tests/)

client.test.ts (270 lines)

Comprehensive unit test suite using Node's built-in test module:

• Global fetch mock to avoid real API calls
• Tests for each public method:
  • Constructor validation
  • verify() happy path
  • verifyIssuerAgentAuthorization()
  • verifyMerchantAgentCheckout()
  • verifyAgentConsent()
  • verifyAgentPaymentComposite()
• Error handling tests:
  • API errors (4xx/5xx)
  • Network errors
  • Timeout errors
  • Validation errors
• Composite verification logic

Run with: npm test

Examples (examples/)

full-usage.ts (400+ lines)

6 real-world usage scenarios:

1. Issuer Authorization - Agent on behalf of bank account holder
2. Merchant Checkout - Agent bot processing marketplace checkout
3. Consent Verification - AI travel assistant booking flight
4. Composite Verification - $5M capital equipment purchase (3-circuit chain)
5. Custom Circuits - Low-value subscription with 2 circuits only
6. Error Handling - Proper catch patterns for validation/API/transport errors

Each example is standalone and well-commented.

Configuration

package.json

• Name: @affix-io/verification-sdk
• Version: 0.1.0
• Type: module (ESM)
• Exports: Main entry + type definitions
• Scripts: build (tsc), test (node --test), prepublish
• Dev dependencies: TypeScript 5.3+, @types/node 20+
• Engines: Node.js 18+
• No runtime dependencies

tsconfig.json

• Target: ES2020
• Module: ES2020 (ESM output)
• Strict mode enabled
• Declaration + declaration maps
• OutDir: ./dist

.npmignore

Excludes from npm publish:

• src/, tests/, .git/, tsconfig.json, *.log

Includes in package:

• dist/ (compiled JS), package.json, README.md, LICENSE

.gitignore

Excludes from git:

• node_modules/, dist/, *.log, .env, coverage/

Documentation

README.md (450 lines)

User-facing documentation:

• Installation
• Quick start (basic setup, env vars)
• 4 usage examples (issuer auth, merchant checkout, consent, composite)
• Error handling (3 error types with catch examples)
• Logging & proofs (audit trail patterns)
• Configuration (env vars, custom logger)
• Type reference (VerifyResponse, CompositeResponse)
• Development (build, test)
• Design principles (stateless, typed, minimal, portable, observable)

ARCHITECTURE.md (400+ lines)

Technical reference:

• Design philosophy (5 core principles)
• Module organization (purpose of each file)
• Error handling strategy (retryable vs. not)
• Extension points (add new helpers, circuits, logger)
• Testing strategy (unit, integration, manual)
• Performance notes (timeouts, batch, proof aggregation)
• Future roadmap (webhooks, batch API, introspection)
• Security considerations (API key, transport, proofs)
• Glossary

STRUCTURE.md

This file. Overview of all files and their purpose.

Code Statistics

Component	Lines	Purpose
client.ts	260	Main SDK class, 5 public methods
types.ts	150	15+ TypeScript definitions
errors.ts	60	4 error classes
http.ts	130	fetch wrapper, timeout, error mapping
helpers.ts	120	8 utility functions
index.ts	35	Public API exports
src/ total	755	Core SDK
client.test.ts	270	Unit tests + mocks
full-usage.ts	400+	6 real-world examples
tests/ + examples/	670+	Testing & examples
Docs	1000+	README, ARCHITECTURE, STRUCTURE
Total	2400+	Production-grade SDK

Key Design Decisions

1. Stateless: No sessions, no caching. Each call independent.
2. Strongly typed: Full TypeScript, zero implicit any.
3. Minimal deps: Only Node.js 18+ and TypeScript (dev).
4. Purpose-built helpers: High-level methods for common flows.
5. Portable pattern: Structure designed for Go/Java/Python ports.
6. Observable: Every call returns proof + latency for audit trails.
7. Error-first: Distinct error types for different failure modes.
8. Logger-friendly: Custom logger interface for observability.

Quick Start for Users

npm install @affix-io/verification-sdk

import { AffixioClient } from '@affix-io/verification-sdk';

const client = new AffixioClient({
  apiKey: process.env.AFFIXIO_API_KEY!,
});

const result = await client.verifyIssuerAgentAuthorization({
  agentId: 'agent:procurement-001',
  accountId: 'acct_123',
  consentReference: 'consent_abc',
  amount: 14900,
  currency: 'USD',
  merchantCategory: 'software_subscription',
});

if (result.eligible) {
  // Proceed with payment
}

Build & Publish

# Install deps
npm install

# Build TypeScript to dist/
npm run build

# Run tests
npm test

# Publish to npm
npm publish

The prepublish hook ensures dist/ is fresh before publishing.