@private.me/xbind 1.2.0

package/dist-standalone/gateway-transport.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Gateway transport adapter for delivering envelopes to Xail inbox users.
+ *
+ * Sends envelopes via POST /gateway/deliver on the hosted gateway API.
+ * For agent-to-agent (M2M), use HttpsTransportAdapter with direct URLs.
+ * Optionally polls for incoming messages.
+ */
+import type { Result } from '@private.me/shared';
+import type { TransportEnvelope } from './envelope.js';
+import type { XailTransportAdapter, TransportError, EnvelopeHandler } from './transport.js';
+/** Options for GatewayTransport. */
+export interface GatewayTransportOptions {
+    /** API key for gateway authentication. */
+    readonly apiKey: string;
+    /** Gateway base URL. Required — no default to prevent accidental sends. */
+    readonly gateway: string;
+    /** Request timeout in ms. Default: 15000. */
+    readonly timeoutMs?: number;
+    /** Custom fetch implementation (for testing). */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Polling interval for incoming messages in ms. Default: 0 (disabled). */
+    readonly pollIntervalMs?: number;
+}
+/**
+ * Transport adapter for the Xail Gateway.
+ *
+ * Sends envelopes via POST /gateway/deliver with API key auth.
+ * Optionally polls GET /gateway/messages/:did for incoming messages.
+ */
+export declare class GatewayTransport implements XailTransportAdapter {
+    private readonly apiKey;
+    private readonly gateway;
+    private readonly timeoutMs;
+    private readonly fetchFn;
+    private readonly pollIntervalMs;
+    private handlers;
+    private pollTimer;
+    private senderDid;
+    constructor(opts: GatewayTransportOptions);
+    /**
+     * Send a signed envelope to a recipient via the gateway.
+     * @param envelope - The signed transport envelope.
+     * @param _recipientDid - Recipient DID (already in envelope.recipient).
+     * @returns Success or transport error.
+     */
+    send(envelope: TransportEnvelope, _recipientDid: string): Promise<Result<void, TransportError>>;
+    /** Register a handler for incoming envelopes. */
+    onReceive(handler: EnvelopeHandler): void;
+    /**
+     * Start polling for incoming messages.
+     * Must be called after Agent.create() sets the sender DID.
+     * @param did - The agent's own DID for polling.
+     */
+    startPolling(did: string): void;
+    /** Shut down the transport (stop polling, clear handlers). */
+    dispose(): void;
+    /** Poll for incoming messages and dispatch to handlers. */
+    private poll;
+}

package/dist-standalone/gateway-transport.js

@@ -0,0 +1,116 @@
+/**
+ * Gateway transport adapter for delivering envelopes to Xail inbox users.
+ *
+ * Sends envelopes via POST /gateway/deliver on the hosted gateway API.
+ * For agent-to-agent (M2M), use HttpsTransportAdapter with direct URLs.
+ * Optionally polls for incoming messages.
+ */
+import { ok, err } from"./_deps/shared/index.js";
+/**
+ * Transport adapter for the Xail Gateway.
+ *
+ * Sends envelopes via POST /gateway/deliver with API key auth.
+ * Optionally polls GET /gateway/messages/:did for incoming messages.
+ */
+export class GatewayTransport {
+    apiKey;
+    gateway;
+    timeoutMs;
+    fetchFn;
+    pollIntervalMs;
+    handlers = [];
+    pollTimer = null;
+    senderDid = null;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.gateway = opts.gateway.replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 15_000;
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.pollIntervalMs = opts.pollIntervalMs ?? 0;
+    }
+    /**
+     * Send a signed envelope to a recipient via the gateway.
+     * @param envelope - The signed transport envelope.
+     * @param _recipientDid - Recipient DID (already in envelope.recipient).
+     * @returns Success or transport error.
+     */
+    async send(envelope, _recipientDid) {
+        const url = `${this.gateway}/gateway/deliver`;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            const response = await this.fetchFn(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(envelope),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!response.ok) {
+                return err(response.status === 404
+                    ? 'RECIPIENT_UNREACHABLE'
+                    : 'SEND_FAILED');
+            }
+            return ok(undefined);
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === 'AbortError') {
+                return err('TIMEOUT');
+            }
+            return err('NETWORK_ERROR');
+        }
+    }
+    /** Register a handler for incoming envelopes. */
+    onReceive(handler) {
+        this.handlers.push(handler);
+    }
+    /**
+     * Start polling for incoming messages.
+     * Must be called after Agent.create() sets the sender DID.
+     * @param did - The agent's own DID for polling.
+     */
+    startPolling(did) {
+        this.senderDid = did;
+        if (this.pollIntervalMs > 0 && !this.pollTimer) {
+            this.pollTimer = setInterval(() => void this.poll(), this.pollIntervalMs);
+        }
+    }
+    /** Shut down the transport (stop polling, clear handlers). */
+    dispose() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.handlers = [];
+    }
+    /** Poll for incoming messages and dispatch to handlers. */
+    async poll() {
+        if (!this.senderDid)
+            return;
+        try {
+            const url = `${this.gateway}/gateway/messages/${encodeURIComponent(this.senderDid)}`;
+            const res = await this.fetchFn(url, {
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+            });
+            if (!res.ok)
+                return;
+            const data = (await res.json());
+            for (const msg of data.messages) {
+                for (const handler of this.handlers) {
+                    handler(msg.envelope);
+                }
+                // Ack delivery
+                await this.fetchFn(`${this.gateway}/gateway/ack/${msg.id}`, {
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${this.apiKey}` },
+                });
+            }
+        }
+        catch {
+            // Silent failure — polling errors are non-fatal
+        }
+    }
+}

package/dist-standalone/guardrails.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @module guardrails
+ * Enhanced error messages with actionable suggestions for policy violations
+ *
+ * When policies deny requests, guardrails provide specific, actionable
+ * guidance on how to fix the issue or what to request from admins.
+ */
+import type { PolicyViolationDetails } from './policy.js';
+/**
+ * Policy violation error with actionable suggestions
+ */
+export declare class PolicyDenied extends Error {
+    /** Which policy rule was violated */
+    readonly rule: string;
+    /** What the policy allows */
+    readonly allowed: unknown;
+    /** What was requested */
+    readonly requested: unknown;
+    /** Actionable suggestion for how to fix */
+    readonly suggestion: string;
+    /** Full policy violation details */
+    readonly details?: PolicyViolationDetails | undefined;
+    constructor(
+    /** Which policy rule was violated */
+    rule: string, 
+    /** What the policy allows */
+    allowed: unknown, 
+    /** What was requested */
+    requested: unknown, 
+    /** Actionable suggestion for how to fix */
+    suggestion: string, 
+    /** Full policy violation details */
+    details?: PolicyViolationDetails | undefined);
+    /**
+     * Format error for AI agent consumption
+     *
+     * Structured format optimized for LLM parsing
+     */
+    toAgentFormat(): string;
+    /**
+     * Format error for human consumption
+     *
+     * User-friendly format with clear next steps
+     */
+    toUserFormat(): string;
+    /**
+     * Format error for logs (structured JSON)
+     */
+    toLogFormat(): Record<string, unknown>;
+    private formatValue;
+}
+/**
+ * Guardrail builder - fluent API for creating policy errors with suggestions
+ *
+ * @example
+ * ```typescript
+ * const error = Guardrails.amountExceeded({
+ *   requested: 5000,
+ *   limit: 1000,
+ *   type: 'per-transaction'
+ * });
+ *
+ * throw error;
+ * // ❌ Policy Violation: maxAmount
+ * // You requested: $5,000
+ * // Policy allows: $1,000
+ * // 💡 Suggestion: Reduce amount to $1,000 or request policy update from admin
+ * ```
+ */
+export declare class Guardrails {
+    /**
+     * Amount exceeded (per-transaction limit)
+     */
+    static amountExceeded(options: {
+        requested: number;
+        limit: number;
+        type: 'per-transaction' | 'daily' | 'monthly';
+    }): PolicyDenied;
+    /**
+     * Rate limit exceeded
+     */
+    static rateLimitExceeded(options: {
+        current: number;
+        limit: number;
+        windowMs: number;
+    }): PolicyDenied;
+    /**
+     * Tool not allowed
+     */
+    static toolDenied(options: {
+        tool: string;
+        allowed: string[];
+    }): PolicyDenied;
+    /**
+     * Scope not allowed
+     */
+    static scopeDenied(options: {
+        scope: string;
+        allowed: string[];
+    }): PolicyDenied;
+    /**
+     * Field filter denied (data access restriction)
+     */
+    static fieldDenied(options: {
+        field: string;
+        allowed: string[];
+        tool: string;
+    }): PolicyDenied;
+    /**
+     * Time window restriction
+     */
+    static timeWindowDenied(options: {
+        current: Date;
+        allowedStart: string;
+        allowedEnd: string;
+    }): PolicyDenied;
+    /**
+     * Generic policy violation
+     */
+    static custom(options: {
+        rule: string;
+        allowed: unknown;
+        requested: unknown;
+        suggestion: string;
+    }): PolicyDenied;
+}
+/**
+ * Helper: Extract actionable suggestion from AgentError details
+ *
+ * Used by agent.call() to convert PolicyViolationDetails into PolicyDenied
+ */
+export declare function extractSuggestion(details: PolicyViolationDetails): string;
+/**
+ * Helper: Convert PolicyViolationDetails to PolicyDenied
+ */
+export declare function toPolicyDenied(details: PolicyViolationDetails): PolicyDenied;

package/dist-standalone/guardrails.js

@@ -0,0 +1,216 @@
+/**
+ * @module guardrails
+ * Enhanced error messages with actionable suggestions for policy violations
+ *
+ * When policies deny requests, guardrails provide specific, actionable
+ * guidance on how to fix the issue or what to request from admins.
+ */
+/**
+ * Policy violation error with actionable suggestions
+ */
+export class PolicyDenied extends Error {
+    rule;
+    allowed;
+    requested;
+    suggestion;
+    details;
+    constructor(
+    /** Which policy rule was violated */
+    rule, 
+    /** What the policy allows */
+    allowed, 
+    /** What was requested */
+    requested, 
+    /** Actionable suggestion for how to fix */
+    suggestion, 
+    /** Full policy violation details */
+    details) {
+        super(`Policy violation: ${rule}`);
+        this.rule = rule;
+        this.allowed = allowed;
+        this.requested = requested;
+        this.suggestion = suggestion;
+        this.details = details;
+        this.name = 'PolicyDenied';
+    }
+    /**
+     * Format error for AI agent consumption
+     *
+     * Structured format optimized for LLM parsing
+     */
+    toAgentFormat() {
+        return [
+            `POLICY_VIOLATION: ${this.rule}`,
+            `REQUESTED: ${JSON.stringify(this.requested)}`,
+            `ALLOWED: ${JSON.stringify(this.allowed)}`,
+            `SUGGESTION: ${this.suggestion}`,
+        ].join('\n');
+    }
+    /**
+     * Format error for human consumption
+     *
+     * User-friendly format with clear next steps
+     */
+    toUserFormat() {
+        return [
+            `❌ Policy Violation: ${this.rule}`,
+            '',
+            `You requested: ${this.formatValue(this.requested)}`,
+            `Policy allows: ${this.formatValue(this.allowed)}`,
+            '',
+            `💡 Suggestion: ${this.suggestion}`,
+        ].join('\n');
+    }
+    /**
+     * Format error for logs (structured JSON)
+     */
+    toLogFormat() {
+        return {
+            error: 'PolicyDenied',
+            rule: this.rule,
+            allowed: this.allowed,
+            requested: this.requested,
+            suggestion: this.suggestion,
+            details: this.details,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    formatValue(value) {
+        if (typeof value === 'number') {
+            // Format currency if it looks like money
+            if (this.rule.includes('amount') || this.rule.includes('Amount')) {
+                return `$${value.toLocaleString()}`;
+            }
+            return value.toLocaleString();
+        }
+        if (Array.isArray(value)) {
+            return value.map((v) => `"${String(v)}"`).join(', ');
+        }
+        return JSON.stringify(value);
+    }
+}
+/**
+ * Guardrail builder - fluent API for creating policy errors with suggestions
+ *
+ * @example
+ * ```typescript
+ * const error = Guardrails.amountExceeded({
+ *   requested: 5000,
+ *   limit: 1000,
+ *   type: 'per-transaction'
+ * });
+ *
+ * throw error;
+ * // ❌ Policy Violation: maxAmount
+ * // You requested: $5,000
+ * // Policy allows: $1,000
+ * // 💡 Suggestion: Reduce amount to $1,000 or request policy update from admin
+ * ```
+ */
+export class Guardrails {
+    /**
+     * Amount exceeded (per-transaction limit)
+     */
+    static amountExceeded(options) {
+        let rule;
+        let suggestion;
+        switch (options.type) {
+            case 'per-transaction':
+                rule = 'maxAmount';
+                suggestion = `Reduce amount to $${options.limit.toLocaleString()} or request policy update from admin`;
+                break;
+            case 'daily':
+                rule = 'dailyAmount';
+                suggestion = `Reduce amount to stay within daily limit of $${options.limit.toLocaleString()}, or wait until tomorrow`;
+                break;
+            case 'monthly':
+                rule = 'monthlyAmount';
+                suggestion = `Reduce amount to stay within monthly limit of $${options.limit.toLocaleString()}, or wait until next month`;
+                break;
+        }
+        return new PolicyDenied(rule, options.limit, options.requested, suggestion);
+    }
+    /**
+     * Rate limit exceeded
+     */
+    static rateLimitExceeded(options) {
+        const windowSec = options.windowMs / 1000;
+        const suggestion = windowSec >= 60
+            ? `Wait ${Math.ceil(windowSec / 60)} minutes before making additional calls`
+            : `Wait ${windowSec} seconds before making additional calls`;
+        return new PolicyDenied('callsPerMinute', options.limit, options.current + 1, suggestion);
+    }
+    /**
+     * Tool not allowed
+     */
+    static toolDenied(options) {
+        const [service] = options.tool.split(':');
+        const suggestion = options.allowed.length === 0
+            ? `No tools are currently allowed. Request approval from admin to enable "${options.tool}"`
+            : `Request approval from admin to add "${options.tool}" or "${service}:*" to allowed tools`;
+        return new PolicyDenied('allowedTools', options.allowed, options.tool, suggestion);
+    }
+    /**
+     * Scope not allowed
+     */
+    static scopeDenied(options) {
+        const suggestion = options.allowed.length === 0
+            ? `No scopes are currently allowed. Request approval from admin to enable "${options.scope}"`
+            : `Request approval from admin to add "${options.scope}" to allowed scopes`;
+        return new PolicyDenied('allowedScopes', options.allowed, options.scope, suggestion);
+    }
+    /**
+     * Field filter denied (data access restriction)
+     */
+    static fieldDenied(options) {
+        const suggestion = `Field "${options.field}" is restricted. Contact admin to update policy.fieldFilters for "${options.tool}"`;
+        return new PolicyDenied('fieldFilters', options.allowed, options.field, suggestion);
+    }
+    /**
+     * Time window restriction
+     */
+    static timeWindowDenied(options) {
+        const suggestion = `Actions are only allowed between ${options.allowedStart} and ${options.allowedEnd}. Current time is ${options.current.toTimeString()}`;
+        return new PolicyDenied('timeWindow', `${options.allowedStart} - ${options.allowedEnd}`, options.current.toTimeString(), suggestion);
+    }
+    /**
+     * Generic policy violation
+     */
+    static custom(options) {
+        return new PolicyDenied(options.rule, options.allowed, options.requested, options.suggestion);
+    }
+}
+/**
+ * Helper: Extract actionable suggestion from AgentError details
+ *
+ * Used by agent.call() to convert PolicyViolationDetails into PolicyDenied
+ */
+export function extractSuggestion(details) {
+    return details.fix ?? 'Contact administrator to update policy';
+}
+/**
+ * Helper: Convert PolicyViolationDetails to PolicyDenied
+ */
+export function toPolicyDenied(details) {
+    let rule;
+    switch (details.constraint) {
+        case 'amountPerTxn':
+            rule = 'maxAmount';
+            break;
+        case 'dailyAmount':
+            rule = 'dailyAmount';
+            break;
+        case 'callsPerMinute':
+            rule = 'callsPerMinute';
+            break;
+        case 'scope':
+            rule = 'allowedScopes';
+            break;
+        case 'tool':
+            rule = 'allowedTools';
+            break;
+        default:
+            rule = String(details.constraint);
+    }
+    return new PolicyDenied(rule, details.allowed, details.requested, details.fix, details);
+}

package/dist-standalone/http-compat.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @module http-compat
+ * HTTP client compatibility adapters for xBind auto-upgrade
+ *
+ * Provides drop-in replacements for popular HTTP clients (fetch, axios, got)
+ * that transparently upgrade to xBind when both parties support it.
+ */
+import { xfetch } from './xfetch.js';
+/**
+ * Axios-compatible request config
+ */
+export interface AxiosRequestConfig {
+    url?: string;
+    method?: string;
+    baseURL?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, unknown>;
+    data?: unknown;
+    timeout?: number;
+    responseType?: 'json' | 'text' | 'blob' | 'arraybuffer';
+    validateStatus?: (status: number) => boolean;
+    forceXBind?: boolean;
+    disableXBind?: boolean;
+}
+/**
+ * Axios-compatible response
+ */
+export interface AxiosResponse<T = unknown> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    config: AxiosRequestConfig;
+    request?: unknown;
+    xbind?: {
+        used: boolean;
+        protocol: 'xbind' | 'http' | 'https';
+        latency?: number;
+        peerDID?: string;
+    };
+}
+/**
+ * Got-compatible options
+ */
+export interface GotOptions {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    searchParams?: Record<string, string | number | boolean>;
+    json?: unknown;
+    body?: string | Buffer;
+    timeout?: number | {
+        request?: number;
+    };
+    responseType?: 'json' | 'text' | 'buffer';
+    forceXBind?: boolean;
+    disableXBind?: boolean;
+}
+/**
+ * Got-compatible response
+ */
+export interface GotResponse<T = unknown> {
+    body: T;
+    statusCode: number;
+    headers: Record<string, string>;
+    url: string;
+    requestUrl: string;
+    xbind?: {
+        used: boolean;
+        protocol: 'xbind' | 'http' | 'https';
+        latency?: number;
+        peerDID?: string;
+    };
+}
+/**
+ * Create axios-compatible HTTP client with xBind auto-upgrade
+ *
+ * Drop-in replacement for axios that transparently upgrades to xBind.
+ *
+ * @returns Axios-compatible client
+ *
+ * @example
+ * ```typescript
+ * import { createAxiosCompat } from '@private.me/xbind/http-compat';
+ *
+ * const axios = createAxiosCompat();
+ *
+ * // Auto-upgrades to xBind if supported
+ * const response = await axios.get('https://api.example.com/data');
+ * console.log('Used xBind?', response.xbind?.used);
+ * console.log('Data:', response.data);
+ * ```
+ */
+export declare function createAxiosCompat(): {
+    request: <T = unknown>(config: AxiosRequestConfig | string) => Promise<AxiosResponse<T>>;
+    get: <T = unknown>(url: string, config?: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
+    post: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
+    put: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
+    patch: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
+    delete: <T = unknown>(url: string, config?: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
+};
+/**
+ * Create got-compatible HTTP client with xBind auto-upgrade
+ *
+ * Drop-in replacement for got that transparently upgrades to xBind.
+ *
+ * @returns Got-compatible client
+ *
+ * @example
+ * ```typescript
+ * import { createGotCompat } from '@private.me/xbind/http-compat';
+ *
+ * const got = createGotCompat();
+ *
+ * // Auto-upgrades to xBind if supported
+ * const response = await got('https://api.example.com/data', {
+ *   responseType: 'json',
+ * });
+ * console.log('Used xBind?', response.xbind?.used);
+ * console.log('Body:', response.body);
+ * ```
+ */
+export declare function createGotCompat(): {
+    <T = unknown>(url: string | GotOptions, options?: GotOptions): Promise<GotResponse<T>>;
+    get<T = unknown>(url: string, options?: GotOptions): Promise<GotResponse<T>>;
+    post<T = unknown>(url: string, options?: GotOptions): Promise<GotResponse<T>>;
+    put<T = unknown>(url: string, options?: GotOptions): Promise<GotResponse<T>>;
+    patch<T = unknown>(url: string, options?: GotOptions): Promise<GotResponse<T>>;
+    delete<T = unknown>(url: string, options?: GotOptions): Promise<GotResponse<T>>;
+};
+/**
+ * Wrap existing fetch implementation with xBind auto-upgrade
+ *
+ * Use this to upgrade an existing fetch instance (like node-fetch, cross-fetch, etc.)
+ *
+ * @param fetchImpl - Fetch implementation to wrap
+ * @returns Wrapped fetch with xBind support
+ *
+ * @example
+ * ```typescript
+ * import { wrapFetch } from '@private.me/xbind/http-compat';
+ * import nodeFetch from 'node-fetch';
+ *
+ * const fetch = wrapFetch(nodeFetch);
+ *
+ * // Uses xBind if supported, falls back to node-fetch
+ * const response = await fetch('https://api.example.com/data');
+ * ```
+ */
+export declare function wrapFetch(fetchImpl: typeof fetch): typeof xfetch;