aura-protocol/dist/index.d.ts

Core TypeScript definitions and JSON Schema for the AURA protocol - making websites machine-readable for AI agents

/**
 * AURA Protocol v1.0 - Initial Release
 * A protocol for agent-website interactions
 */
/**
 * AuraManifest - Central site-wide manifest served from /.well-known/aura.json
 * Replaces the old AuraAssertion concept
 */
export interface AuraManifest {
    $schema: string;
    id?: string;
    protocol: 'AURA';
    version: '1.0';
    site: {
        name: string;
        description?: string;
        url: string;
    };
    resources: Record<string, Resource>;
    capabilities: Record<string, Capability>;
    policy?: Policy;
}
/**
 * Resource - Defines where actions can be performed
 * Separated from capabilities for improved clarity
 */
export interface Resource {
    uriPattern: string;
    description: string;
    operations: {
        GET?: {
            capabilityId: string;
        };
        POST?: {
            capabilityId: string;
        };
        PUT?: {
            capabilityId: string;
        };
        DELETE?: {
            capabilityId: string;
        };
    };
}
/**
 * Capability - Self-executing contract with concrete action
 * Now includes versioning and HttpAction definition
 */
export interface Capability {
    id: string;
    v: number;
    description: string;
    parameters?: JSONSchema;
    action: HttpAction;
}
/**
 * JSONSchema - A simplified JSON Schema definition
 * Represents the structure for capability parameters
 */
export interface JSONSchema {
    type?: string;
    properties?: Record<string, JSONSchema>;
    required?: string[];
    items?: JSONSchema;
    format?: string;
    minimum?: number;
    maximum?: number;
    minLength?: number;
    maxLength?: number;
    pattern?: string;
    enum?: any[];
    default?: any;
    description?: string;
    title?: string;
    additionalProperties?: boolean | JSONSchema;
}
/**
 * HttpAction - Defines how to execute a capability via HTTP
 * Includes security, encoding, and parameter mapping
 */
export interface HttpAction {
    type: 'HTTP';
    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
    urlTemplate: string;
    cors?: boolean;
    encoding?: 'json' | 'query';
    parameterMapping: Record<string, string>;
}
/**
 * Policy - Site-wide policies for rate limiting and authentication
 * Provides hints to agents about how to interact with the site
 */
export interface Policy {
    rateLimit?: {
        limit: number;
        window: 'second' | 'minute' | 'hour' | 'day';
    };
    authHint?: 'none' | 'cookie' | 'bearer';
}
/**
 * AuraState - Structure for the AURA-State header
 * Sent as Base64-encoded JSON in HTTP responses
 */
export interface AuraState {
    isAuthenticated?: boolean;
    context?: Record<string, any>;
    capabilities?: string[];
}