@awi-protocol/sdk 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# @awi-protocol/sdk
+
+**AWI (Agent Web Interface) JavaScript SDK**
+
+Deterministic web automation for AI agents. Transform any website into a structured, machine-readable API.
+
+## Installation
+
+```bash
+npm install @awi-protocol/sdk
+# or
+yarn add @awi-protocol/sdk
+# or
+pnpm add @awi-protocol/sdk
+```
+
+## Quick Start
+
+### Proxy Mode (Server Executes Browser)
+
+```typescript
+import { AWIClient } from '@awi-protocol/sdk';
+
+const client = new AWIClient({
+  endpoint: 'https://awi.example.com',
+  certificate: 'your-awi-jwt-token',
+});
+
+// Execute a recipe - server runs the browser
+const result = await client.execute({
+  target: 'awi://linkedin.com/jobs/search/v1',
+  params: {
+    query: 'senior rust engineer',
+    location: 'remote',
+  },
+});
+
+if (result.success) {
+  console.log(result.data);
+  // [{ title: "Senior Rust Engineer", company: "TechCorp", location: "Remote" }, ...]
+}
+```
+
+### Advisory Mode (Agent Executes Locally)
+
+```typescript
+// Get the recipe blueprint
+const advisory = await client.getAdvisory('awi://linkedin.com/jobs/search/v1');
+
+// Execute locally with your own browser automation
+const result = await client.executeAdvisory(
+  {
+    target: 'awi://linkedin.com/jobs/search/v1',
+    params: { query: 'rust' },
+  },
+  async (blueprint, params) => {
+    // Your local execution logic
+    // e.g., Puppeteer, Playwright, or DOM manipulation
+    return localBrowser.execute(blueprint, params);
+  }
+);
+```
+
+### Explore Unknown Sites
+
+```typescript
+// Automatically explore and generate a recipe
+const recipe = await client.explore('new-site.com', 'search', 'products');
+
+if (recipe.success) {
+  console.log('Generated recipe:', recipe.data);
+}
+```
+
+## Features
+
+- **Deterministic Execution**: Recipes guarantee consistent extraction
+- **Self-Healing**: AXIR semantic intent regenerates selectors when sites redesign
+- **Multi-Strategy Fallback**: CSS → semantic → text → attribute resolution
+- **Stealth Browser**: Undetectable automation with fingerprint rotation
+- **Agent Identity**: W3C did:key DIDs with tiered rate limiting
+- **OpenTelemetry**: Full distributed tracing
+- **Type-Safe**: Full TypeScript support with generic response types
+
+## API Reference
+
+### `AWIClient`
+
+#### Constructor
+
+```typescript
+new AWIClient(options: {
+  endpoint: string;      // AWI server URL
+  certificate: string;   // JWT authentication token
+  timeout?: number;      // Request timeout (ms) - default 30000
+  retries?: number;      // Retry attempts - default 3
+})
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `execute(request)` | Execute recipe in proxy mode |
+| `getAdvisory(target)` | Get recipe blueprint |
+| `executeAdvisory(request, executor)` | Get blueprint + execute locally |
+| `explore(domain, action, resource?)` | Explore unknown domain |
+| `feedback(request)` | Submit execution feedback |
+| `listRegistry(options?)` | List supported sites |
+| `searchRegistry(query, limit?)` | Search registry |
+| `delegate(request)` | Delegate to another agent |
+| `joinSession(sessionId)` | Join multi-agent session |
+| `health()` | Check server health |
+
+### Error Handling
+
+```typescript
+import { AWIClient, AWIError } from '@awi-protocol/sdk';
+
+try {
+  const result = await client.execute({...});
+} catch (error) {
+  if (error instanceof AWIError) {
+    console.log(error.code);      // 'RECIPE_NOT_FOUND'
+    console.log(error.statusCode); // 404
+    console.log(error.details);    // { recipe_id: '...' }
+  }
+}
+```
+
+## React Integration
+
+```bash
+npm install @awi-protocol/react
+```
+
+```tsx
+import { useAWI } from '@awi-protocol/react';
+
+function JobSearch() {
+  const { execute, loading, data, error, metrics } = useAWI({
+    endpoint: 'https://awi.example.com',
+    certificate: 'your-jwt',
+  });
+
+  const search = async (query: string) => {
+    await execute({
+      target: 'awi://linkedin.com/jobs/search/v1',
+      params: { query },
+    });
+  };
+
+  return (
+    <div>
+      {loading && <Spinner />}
+      {error && <Error message={error.message} />}
+      {data && <JobList jobs={data} />}
+      {metrics && <div>Latency: {metrics.latency_ms}ms</div>}
+    </div>
+  );
+}
+```
+
+## Site SDK (For Website Operators)
+
+```bash
+npm install @awi-protocol/site-sdk
+```
+
+```typescript
+import { AWISite } from '@awi-protocol/site-sdk';
+import express from 'express';
+
+const app = new AWISite();
+
+// Define agent-native endpoints
+app.route('/jobs/search', (req, res) => {
+  const { query, location } = req.body.params;
+  const jobs = database.search(query, location);
+
+  res.json({
+    success: true,
+    data: jobs,
+  });
+});
+
+// Mount on your Express app
+const server = express();
+server.use('/awi', app.middleware());
+server.listen(3000);
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,382 @@
+/**
+ * AWI Protocol Types
+ *
+ * TypeScript definitions for the Agent Web Interface protocol.
+ */
+type ExecutionMode = 'proxy' | 'advisory';
+type RecipeStatus = 'candidate' | 'active' | 'suspended' | 'deprecated';
+type AgentTier = 'free' | 'pro' | 'enterprise';
+interface AgentRequest {
+    target: string;
+    params: Record<string, unknown>;
+    agent_id?: string;
+    mode?: ExecutionMode;
+    session_id?: string;
+    workflow_id?: string;
+    delegate_to?: string;
+    options?: Record<string, unknown>;
+}
+interface AgentResponse<T = unknown> {
+    success: boolean;
+    data: T | null;
+    errors: Array<{
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    }>;
+    metadata: {
+        execution_id?: string;
+        latency_ms?: number;
+        recipe_id?: string;
+        recipe_version?: string;
+        recipe_confidence?: number;
+        cache_status?: 'hit' | 'miss' | 'bypass';
+        [key: string]: unknown;
+    };
+    execution_path: string[];
+    axir_intent?: {
+        intent: string;
+        action: string;
+        parameters: string[];
+    };
+}
+interface Recipe {
+    id: string;
+    version: string;
+    domain: string;
+    resource: string;
+    action: string;
+    status: RecipeStatus;
+    confidence: number;
+    steps: RecipeStep[];
+    selectors: Record<string, SelectorSet>;
+    extraction: ExtractionSpec;
+    validation: ValidationRules;
+    axir?: AXIRIntent;
+}
+interface RecipeStep {
+    type: 'navigate' | 'wait' | 'click' | 'type' | 'scroll' | 'extract_list' | 'extract_one';
+    name?: string;
+    url?: string;
+    selector?: string;
+    value?: string;
+    amount?: number;
+    timeout_ms?: number;
+    retry?: number;
+}
+interface SelectorSet {
+    name: string;
+    selectors: Selector[];
+}
+interface Selector {
+    type: 'css' | 'semantic' | 'text' | 'attribute';
+    value: string;
+    priority: number;
+    confidence: number;
+}
+interface ExtractionSpec {
+    mode: 'list' | 'one';
+    container: string;
+    fields: ExtractionField[];
+    min_items: number;
+}
+interface ExtractionField {
+    name: string;
+    selector: string;
+    transform?: 'strip' | 'strip_currency' | 'number' | 'lower' | 'upper';
+    required?: boolean;
+}
+interface ValidationRules {
+    required_fields: string[];
+    min_items: number;
+    custom_checks: ValidationRule[];
+}
+interface ValidationRule {
+    field: string;
+    rule_type: 'required' | 'type' | 'regex' | 'range';
+    value?: string | number;
+}
+interface AXIRIntent {
+    intent: string;
+    action: string;
+    parameters: string[];
+    semantic_context?: Record<string, unknown>;
+}
+interface RegistryEntry {
+    domain: string;
+    display_name: string;
+    category: string;
+    country: string;
+    actions: Array<{
+        resource: string;
+        action: string;
+        version: string;
+        confidence: number;
+        status: RecipeStatus;
+    }>;
+    confidence: number;
+    certified: boolean;
+    recipe_count: number;
+}
+interface FeedbackRequest {
+    execution_id: string;
+    rating: 'good' | 'bad' | 'neutral';
+    notes?: string;
+    field_issues?: Array<{
+        field: string;
+        issue: string;
+    }>;
+}
+interface DelegationRequest {
+    target: string;
+    delegate_to: string;
+    session_id?: string;
+    workflow_id?: string;
+    params?: Record<string, unknown>;
+    permissions?: string[];
+}
+interface AWIClientOptions {
+    endpoint: string;
+    certificate: string;
+    timeout?: number;
+    retries?: number;
+}
+interface ExecutionMetrics {
+    latency_ms: number;
+    fallback_count: number;
+    selectors_used: string[];
+    cache_status: 'hit' | 'miss' | 'bypass';
+}
+
+/**
+ * AWI Client
+ *
+ * Main SDK class for interacting with AWI servers.
+ * Supports proxy mode (server executes browser) and advisory mode (returns blueprint).
+ */
+
+declare class AWIError extends Error {
+    code: string;
+    statusCode: number;
+    details?: Record<string, unknown>;
+    constructor(code: string, message: string, statusCode: number, details?: Record<string, unknown>);
+}
+declare class AWIClient {
+    private endpoint;
+    private certificate;
+    private timeout;
+    private retries;
+    constructor(options: AWIClientOptions);
+    /**
+     * Execute a recipe in proxy mode.
+     * The server runs the browser and returns structured data.
+     */
+    execute<T = unknown>(request: Omit<AgentRequest, 'mode'>): Promise<AgentResponse<T>>;
+    /**
+     * Get advisory blueprint for agent-side execution.
+     * Returns the recipe structure without running the browser.
+     */
+    getAdvisory(target: string): Promise<AgentResponse<Recipe>>;
+    /**
+     * Execute in advisory mode - get blueprint then run locally.
+     * This is useful when you want to control the browser yourself.
+     */
+    executeAdvisory<T = unknown>(request: Omit<AgentRequest, 'mode'>, localExecutor: (blueprint: Recipe, params: Record<string, unknown>) => Promise<T>): Promise<AgentResponse<T>>;
+    /**
+     * Submit feedback on execution quality.
+     */
+    feedback(request: FeedbackRequest): Promise<AgentResponse<{
+        feedback_received: boolean;
+    }>>;
+    /**
+     * Explore an unknown domain and generate a recipe.
+     */
+    explore(domain: string, action: string, resource?: string): Promise<AgentResponse<Recipe>>;
+    /**
+     * List supported sites in the registry.
+     */
+    listRegistry(options?: {
+        category?: string;
+        certifiedOnly?: boolean;
+        minConfidence?: number;
+        search?: string;
+        limit?: number;
+    }): Promise<AgentResponse<{
+        sites: RegistryEntry[];
+        stats: Record<string, unknown>;
+    }>>;
+    /**
+     * Search registry.
+     */
+    searchRegistry(query: string, limit?: number): Promise<AgentResponse<{
+        results: RegistryEntry[];
+    }>>;
+    /**
+     * Delegate execution to another agent.
+     */
+    delegate(request: DelegationRequest): Promise<AgentResponse<{
+        delegation_id: string;
+    }>>;
+    /**
+     * Join a multi-agent session.
+     */
+    joinSession(sessionId: string): Promise<AgentResponse<{
+        session_id: string;
+        participants: string[];
+    }>>;
+    /**
+     * Check server health.
+     */
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+    /**
+     * Get execution metrics from a response.
+     */
+    getMetrics(response: AgentResponse<unknown>): ExecutionMetrics;
+    private _request;
+}
+
+/**
+ * Advisory Mode Executor
+ *
+ * Executes recipe blueprints locally in a browser or Node.js environment.
+ * Useful when you want to control the browser yourself but use AWI selectors.
+ */
+
+interface LocalExecutionContext {
+    document: Document;
+    window: Window;
+    console: Console;
+}
+declare class AdvisoryExecutor {
+    private context;
+    private metrics;
+    constructor(context: LocalExecutionContext);
+    /**
+     * Execute a recipe blueprint locally.
+     */
+    execute<T = unknown>(recipe: Recipe, params: Record<string, unknown>): Promise<{
+        success: boolean;
+        data: T | null;
+        errors: Array<{
+            code: string;
+            message: string;
+        }>;
+        metrics: ExecutionMetrics;
+    }>;
+    private _executeStep;
+    private _extractData;
+    private _resolveSelector;
+    private _resolveSelectorWithin;
+    private _trySelector;
+    private _waitForSelector;
+    private _interpolate;
+    private _applyTransform;
+    private _sleep;
+}
+
+interface SelectorCandidate {
+    type: 'css' | 'semantic' | 'text' | 'attribute';
+    value: string;
+    priority: number;
+    confidence?: number;
+}
+interface AXIRNode {
+    node_id: string;
+    element_type: 'button' | 'link' | 'input' | 'form' | 'navigation' | 'search' | 'filter' | 'sort' | 'pagination' | 'container' | 'list' | 'item' | 'heading' | 'text' | 'image' | 'unknown';
+    semantic_role?: string;
+    intent?: string;
+    tag?: string;
+    selector_candidates: SelectorCandidate[];
+    parent_id?: string;
+    children_ids?: string[];
+    aria_label?: string;
+    aria_role?: string;
+    text_content?: string;
+    confidence: number;
+    reasoning?: string;
+}
+interface AXIREdge {
+    from_node: string;
+    to_node: string;
+    action: string;
+    condition?: string;
+    probability: number;
+}
+type PageType = 'landing' | 'search' | 'listing' | 'detail' | 'form' | 'checkout' | 'dashboard' | 'unknown';
+interface AXIRWorkflow {
+    nodes: Record<string, AXIRNode>;
+    edges: AXIREdge[];
+    entry_points: string[];
+    exit_points: string[];
+    domain: string;
+    page_type: PageType;
+    structure_hash?: string;
+}
+interface AXIRIntentMapping {
+    intent: string;
+    action: string;
+    parameters: string[];
+    context: string;
+}
+interface AXIRField {
+    name: string;
+    selector: string;
+    transform?: string;
+    required: boolean;
+}
+interface AXIRCompilationResult {
+    workflow: AXIRWorkflow;
+    intents: AXIRIntentMapping[];
+    selectors: Record<string, SelectorCandidate[]>;
+    fields: AXIRField[];
+    container?: string;
+    model_used: string;
+    tokens_used: number;
+    compilation_time_ms: number;
+}
+interface AXIRHealingResult {
+    selector: string;
+    confidence: number;
+    reasoning?: string;
+}
+
+interface LocalAXIRCompilerOptions {
+    modelPath?: string;
+    modelUrl?: string;
+    contextSize?: number;
+    gpuLayers?: number;
+    onDownloadProgress?: (downloaded: number, total: number) => void;
+    onStatus?: (message: string) => void;
+}
+declare class LocalAXIRCompiler {
+    private modelPath;
+    private modelUrl;
+    private contextSize;
+    private gpuLayers;
+    private onDownloadProgress?;
+    private onStatus?;
+    private model;
+    private context;
+    private grammar;
+    private ready;
+    constructor(options?: LocalAXIRCompilerOptions);
+    compile(domHTML: string, a11yTree: string, intent: string, params?: Record<string, unknown>): Promise<AXIRCompilationResult>;
+    heal(domHTML: string, brokenSelector: string, semanticIntent: string): Promise<AXIRHealingResult>;
+    isModelCached(): boolean;
+    clearCache(): void;
+    private _ensureModel;
+    private _ensureGrammar;
+    private _autoDetectGPULayers;
+    private _downloadModel;
+    private _complete;
+    private _buildCompilePrompt;
+    private _buildHealPrompt;
+    private _truncate;
+    private _estimateTokens;
+    private _status;
+}
+
+export { AWIClient, type AWIClientOptions, AWIError, type AXIRCompilationResult, type AXIREdge, type AXIRField, type AXIRHealingResult, type AXIRIntent, type AXIRIntentMapping, type AXIRNode, type AXIRWorkflow, AdvisoryExecutor, type AgentRequest, type AgentResponse, type AgentTier, type DelegationRequest, type ExecutionMetrics, type ExecutionMode, type ExtractionField, type ExtractionSpec, type FeedbackRequest, LocalAXIRCompiler, type LocalAXIRCompilerOptions, type PageType, type Recipe, type RecipeStatus, type RecipeStep, type RegistryEntry, type Selector, type SelectorCandidate, type SelectorSet, type ValidationRules, AWIClient as default };