@framers/agentos 0.1.75 → 0.1.76

package/dist/voice/providers/plivo.js

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview Plivo telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Plivo Voice REST API v1.
+ * Webhook verification uses HMAC-SHA256 with the v3 signature scheme.
+ *
+ * @module @framers/agentos/voice/providers/plivo
+ */
+import { createHmac, randomUUID } from 'node:crypto';
+// ============================================================================
+// PlivoVoiceProvider
+// ============================================================================
+/**
+ * Plivo voice call provider.
+ *
+ * Uses the Plivo REST API v1 for outbound call control and HMAC-SHA256
+ * for inbound webhook signature verification (v3 signature scheme).
+ *
+ * @example
+ * ```typescript
+ * const provider = new PlivoVoiceProvider({
+ *   authId:    process.env.PLIVO_AUTH_ID!,
+ *   authToken: process.env.PLIVO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export class PlivoVoiceProvider {
+    constructor(config) {
+        this.name = 'plivo';
+        this.config = config;
+        this.baseUrl = 'https://api.plivo.com/v1';
+        this.authHeader =
+            'Basic ' + Buffer.from(`${config.authId}:${config.authToken}`).toString('base64');
+        this.fetch = config.fetchImpl ?? globalThis.fetch;
+    }
+    // ── Webhook ───────────────────────────────────────────────────────────────
+    /**
+     * Verify an incoming Plivo webhook request using HMAC-SHA256 (v3 scheme).
+     *
+     * Plivo signs the concatenation of the full request URL and the nonce
+     * header value. The resulting base64-encoded digest is compared against
+     * the `x-plivo-signature-v3` header.
+     */
+    verifyWebhook(ctx) {
+        const nonce = ctx.headers['x-plivo-signature-v3-nonce'];
+        const signature = ctx.headers['x-plivo-signature-v3'];
+        if (Array.isArray(nonce) || Array.isArray(signature)) {
+            return { valid: false, error: 'Duplicate Plivo signature headers' };
+        }
+        const nonceStr = nonce ?? '';
+        const data = ctx.url + nonceStr;
+        const expected = createHmac('sha256', this.config.authToken)
+            .update(data)
+            .digest('base64');
+        const valid = expected === signature;
+        return { valid };
+    }
+    /**
+     * Parse a Plivo webhook body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Supports both URL-encoded and JSON request bodies. Maps `CallStatus`
+     * parameter values to call lifecycle events.
+     */
+    parseWebhookEvent(ctx) {
+        const body = ctx.body.toString();
+        let params;
+        // Plivo sends URL-encoded bodies for most events; try JSON as fallback.
+        try {
+            if (body.trimStart().startsWith('{')) {
+                const obj = JSON.parse(body);
+                params = new URLSearchParams(obj);
+            }
+            else {
+                params = new URLSearchParams(body);
+            }
+        }
+        catch {
+            params = new URLSearchParams(body);
+        }
+        const callUuid = params.get('CallUUID') ?? params.get('call_uuid') ?? '';
+        const callStatus = params.get('CallStatus') ?? params.get('call_status') ?? '';
+        const digits = params.get('Digits');
+        const timestamp = Date.now();
+        const events = [];
+        const base = () => ({
+            eventId: randomUUID(),
+            providerCallId: callUuid,
+            timestamp,
+        });
+        switch (callStatus) {
+            case 'ringing':
+                events.push({ ...base(), kind: 'call-ringing' });
+                break;
+            case 'in-progress':
+                events.push({ ...base(), kind: 'call-answered' });
+                break;
+            case 'completed':
+                events.push({ ...base(), kind: 'call-completed' });
+                break;
+            case 'busy':
+                events.push({ ...base(), kind: 'call-busy' });
+                break;
+            case 'no-answer':
+                events.push({ ...base(), kind: 'call-no-answer' });
+                break;
+            case 'failed':
+                events.push({ ...base(), kind: 'call-failed' });
+                break;
+            default:
+                // initiated / queued / etc. — no normalized event emitted
+                break;
+        }
+        if (digits != null && digits !== '') {
+            events.push({ ...base(), kind: 'call-dtmf', digit: digits });
+        }
+        return { events };
+    }
+    // ── Call Control ──────────────────────────────────────────────────────────
+    /**
+     * Initiate an outbound call via the Plivo Call API.
+     *
+     * POSTs a JSON body to `/Account/{authId}/Call/` with the caller, callee,
+     * and answer URL. Returns the `request_uuid` as the provider call ID.
+     */
+    async initiateCall(input) {
+        const url = `${this.baseUrl}/Account/${this.config.authId}/Call/`;
+        const response = await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                from: input.fromNumber,
+                to: input.toNumber,
+                answer_url: input.webhookUrl,
+                answer_method: 'POST',
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => String(response.status));
+            return { providerCallId: '', success: false, error: `Plivo error ${response.status}: ${text}` };
+        }
+        const data = (await response.json());
+        return { providerCallId: data.request_uuid, success: true };
+    }
+    /**
+     * Hang up an active call using the Plivo Call DELETE endpoint.
+     */
+    async hangupCall(input) {
+        const url = `${this.baseUrl}/Account/${this.config.authId}/Call/${input.providerCallId}/`;
+        await this.fetch(url, {
+            method: 'DELETE',
+            headers: {
+                Authorization: this.authHeader,
+            },
+        });
+    }
+    /**
+     * Speak text into a live call using the Plivo Speak API.
+     *
+     * Defaults to `WOMAN` voice and `en-US` language when not specified.
+     */
+    async playTts(input) {
+        const url = `${this.baseUrl}/Account/${this.config.authId}/Call/${input.providerCallId}/Speak/`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                text: input.text,
+                voice: input.voice ?? 'WOMAN',
+                language: 'en-US',
+            }),
+        });
+    }
+}
+//# sourceMappingURL=plivo.js.map

package/dist/voice/providers/plivo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plivo.js","sourceRoot":"","sources":["../../../src/voice/providers/plivo.ts"],"names":[],"mappings":"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"}

package/dist/voice/providers/telnyx.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Telnyx telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Telnyx Call Control v2 API.
+ * Webhook verification uses Ed25519 public key verification as specified in
+ * the Telnyx security documentation.
+ *
+ * @module @framers/agentos/voice/providers/telnyx
+ */
+import type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput } from '../IVoiceCallProvider.js';
+import type { WebhookContext, WebhookVerificationResult, WebhookParseResult } from '../types.js';
+/** Configuration for {@link TelnyxVoiceProvider}. */
+export interface TelnyxVoiceProviderConfig {
+    /** Telnyx API key (starts with "KEY"). */
+    apiKey: string;
+    /** Telnyx connection/application ID for call routing. */
+    connectionId: string;
+    /**
+     * Base64-encoded DER-encoded SPKI Ed25519 public key for webhook verification.
+     * When omitted, webhook verification is skipped.
+     */
+    publicKey?: string;
+    /**
+     * Optional fetch override — inject a mock in tests.
+     * Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Telnyx voice call provider.
+ *
+ * Uses the Telnyx Call Control v2 API for outbound call initiation and
+ * in-call actions (hangup, speak). Webhook verification uses Ed25519 public
+ * key signing.
+ *
+ * @example
+ * ```typescript
+ * const provider = new TelnyxVoiceProvider({
+ *   apiKey:       process.env.TELNYX_API_KEY!,
+ *   connectionId: process.env.TELNYX_CONNECTION_ID!,
+ *   publicKey:    process.env.TELNYX_PUBLIC_KEY,   // optional
+ * });
+ * ```
+ */
+export declare class TelnyxVoiceProvider implements IVoiceCallProvider {
+    readonly name: "telnyx";
+    private readonly config;
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly fetch;
+    constructor(config: TelnyxVoiceProviderConfig);
+    /**
+     * Verify an incoming Telnyx webhook using Ed25519 signature verification.
+     *
+     * Telnyx signs `{timestamp}|{rawBody}` with the configured Ed25519 private key.
+     * The matching public key is provided as a base64-encoded DER SPKI blob.
+     *
+     * If no public key is configured, the check is skipped and `valid: true`
+     * is returned so the provider can operate without cryptographic validation
+     * during initial development.
+     */
+    verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
+    /**
+     * Parse a Telnyx webhook JSON body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Handles Telnyx Call Control event types:
+     * - `call.initiated` → `call-ringing`
+     * - `call.answered` → `call-answered`
+     * - `call.hangup` → `call-completed` or `call-hangup-user` based on hangup_cause
+     * - `call.dtmf.received` → `call-dtmf`
+     * - `call.machine.detection.ended` with `result === 'machine'` → `call-voicemail`
+     */
+    parseWebhookEvent(ctx: WebhookContext): WebhookParseResult;
+    /**
+     * Initiate an outbound call via the Telnyx Call Control v2 API.
+     *
+     * POSTs to `/calls` with a JSON body. The `mediaStreamUrl` (if provided)
+     * is stored internally for use after the call is answered — it is NOT sent
+     * in the initial call creation request.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up an active call via the Telnyx Call Control hangup action.
+     */
+    hangupCall(input: HangupCallInput): Promise<void>;
+    /**
+     * Speak text into a live call using Telnyx's text-to-speech speak action.
+     *
+     * Defaults to `female` voice and `en-US` language when not specified.
+     */
+    playTts(input: PlayTtsInput): Promise<void>;
+}
+//# sourceMappingURL=telnyx.d.ts.map

package/dist/voice/providers/telnyx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telnyx.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/telnyx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB,qDAAqD;AACrD,MAAM,WAAW,yBAAyB;IACxC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAyBD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC5D,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,MAAM,EAAE,yBAAyB;IAS7C;;;;;;;;;OASG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAgC7D;;;;;;;;;OASG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IAyD1D;;;;;;OAMG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}

package/dist/voice/providers/telnyx.js

@@ -0,0 +1,193 @@
+/**
+ * @fileoverview Telnyx telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Telnyx Call Control v2 API.
+ * Webhook verification uses Ed25519 public key verification as specified in
+ * the Telnyx security documentation.
+ *
+ * @module @framers/agentos/voice/providers/telnyx
+ */
+import { verify } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+// ============================================================================
+// TelnyxVoiceProvider
+// ============================================================================
+/**
+ * Telnyx voice call provider.
+ *
+ * Uses the Telnyx Call Control v2 API for outbound call initiation and
+ * in-call actions (hangup, speak). Webhook verification uses Ed25519 public
+ * key signing.
+ *
+ * @example
+ * ```typescript
+ * const provider = new TelnyxVoiceProvider({
+ *   apiKey:       process.env.TELNYX_API_KEY!,
+ *   connectionId: process.env.TELNYX_CONNECTION_ID!,
+ *   publicKey:    process.env.TELNYX_PUBLIC_KEY,   // optional
+ * });
+ * ```
+ */
+export class TelnyxVoiceProvider {
+    constructor(config) {
+        this.name = 'telnyx';
+        this.config = config;
+        this.baseUrl = 'https://api.telnyx.com/v2';
+        this.authHeader = `Bearer ${config.apiKey}`;
+        this.fetch = config.fetchImpl ?? globalThis.fetch;
+    }
+    // ── Webhook ───────────────────────────────────────────────────────────────
+    /**
+     * Verify an incoming Telnyx webhook using Ed25519 signature verification.
+     *
+     * Telnyx signs `{timestamp}|{rawBody}` with the configured Ed25519 private key.
+     * The matching public key is provided as a base64-encoded DER SPKI blob.
+     *
+     * If no public key is configured, the check is skipped and `valid: true`
+     * is returned so the provider can operate without cryptographic validation
+     * during initial development.
+     */
+    verifyWebhook(ctx) {
+        if (!this.config.publicKey) {
+            return { valid: true };
+        }
+        const timestamp = ctx.headers['x-telnyx-timestamp'];
+        const sigHeader = ctx.headers['x-telnyx-signature-ed25519'];
+        if (!timestamp || Array.isArray(timestamp) || !sigHeader || Array.isArray(sigHeader)) {
+            return { valid: false, error: 'Missing Telnyx signature headers' };
+        }
+        const signature = Buffer.from(sigHeader, 'base64');
+        const payload = Buffer.from(`${timestamp}|${ctx.body.toString()}`);
+        try {
+            const valid = verify(null, payload, {
+                key: Buffer.from(this.config.publicKey, 'base64'),
+                format: 'der',
+                type: 'spki',
+            }, signature);
+            return { valid };
+        }
+        catch {
+            return { valid: false, error: 'Verification failed' };
+        }
+    }
+    /**
+     * Parse a Telnyx webhook JSON body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Handles Telnyx Call Control event types:
+     * - `call.initiated` → `call-ringing`
+     * - `call.answered` → `call-answered`
+     * - `call.hangup` → `call-completed` or `call-hangup-user` based on hangup_cause
+     * - `call.dtmf.received` → `call-dtmf`
+     * - `call.machine.detection.ended` with `result === 'machine'` → `call-voicemail`
+     */
+    parseWebhookEvent(ctx) {
+        let parsed;
+        try {
+            parsed = JSON.parse(ctx.body.toString());
+        }
+        catch {
+            return { events: [] };
+        }
+        const { event_type, payload } = parsed.data;
+        const providerCallId = payload.call_control_id ?? '';
+        const timestamp = Date.now();
+        const events = [];
+        const base = () => ({ eventId: randomUUID(), providerCallId, timestamp });
+        switch (event_type) {
+            case 'call.initiated':
+                events.push({ ...base(), kind: 'call-ringing' });
+                break;
+            case 'call.answered':
+                events.push({ ...base(), kind: 'call-answered' });
+                break;
+            case 'call.hangup': {
+                // Distinguish user-initiated hangup from normal completion
+                const cause = payload.hangup_cause ?? '';
+                const kind = cause === 'user_busy' || cause === 'normal_clearing' || cause === 'originator_cancel'
+                    ? 'call-hangup-user'
+                    : 'call-completed';
+                events.push({ ...base(), kind });
+                break;
+            }
+            case 'call.dtmf.received': {
+                const digit = payload.digit ?? '';
+                events.push({ ...base(), kind: 'call-dtmf', digit });
+                break;
+            }
+            case 'call.machine.detection.ended':
+                if (payload.result === 'machine') {
+                    events.push({ ...base(), kind: 'call-voicemail' });
+                }
+                break;
+            default:
+                // Unrecognized event type — emit nothing
+                break;
+        }
+        return { events };
+    }
+    // ── Call Control ──────────────────────────────────────────────────────────
+    /**
+     * Initiate an outbound call via the Telnyx Call Control v2 API.
+     *
+     * POSTs to `/calls` with a JSON body. The `mediaStreamUrl` (if provided)
+     * is stored internally for use after the call is answered — it is NOT sent
+     * in the initial call creation request.
+     */
+    async initiateCall(input) {
+        const url = `${this.baseUrl}/calls`;
+        const response = await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                connection_id: this.config.connectionId,
+                to: input.toNumber,
+                from: input.fromNumber,
+                webhook_url: input.webhookUrl,
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => String(response.status));
+            return { providerCallId: '', success: false, error: `Telnyx error ${response.status}: ${text}` };
+        }
+        const data = (await response.json());
+        return { providerCallId: data.data.call_control_id, success: true };
+    }
+    /**
+     * Hang up an active call via the Telnyx Call Control hangup action.
+     */
+    async hangupCall(input) {
+        const url = `${this.baseUrl}/calls/${input.providerCallId}/actions/hangup`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({}),
+        });
+    }
+    /**
+     * Speak text into a live call using Telnyx's text-to-speech speak action.
+     *
+     * Defaults to `female` voice and `en-US` language when not specified.
+     */
+    async playTts(input) {
+        const url = `${this.baseUrl}/calls/${input.providerCallId}/actions/speak`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                payload: input.text,
+                voice: input.voice ?? 'female',
+                language: 'en-US',
+            }),
+        });
+    }
+}
+//# sourceMappingURL=telnyx.js.map

package/dist/voice/providers/telnyx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telnyx.js","sourceRoot":"","sources":["../../../src/voice/providers/telnyx.ts"],"names":[],"mappings":"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"}

package/dist/voice/providers/twilio.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Twilio telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Twilio REST API v2010-04-01.
+ * Webhook verification uses HMAC-SHA1 per Twilio's security documentation.
+ *
+ * @module @framers/agentos/voice/providers/twilio
+ */
+import type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput } from '../IVoiceCallProvider.js';
+import type { WebhookContext, WebhookVerificationResult, WebhookParseResult } from '../types.js';
+/** Configuration for {@link TwilioVoiceProvider}. */
+export interface TwilioVoiceProviderConfig {
+    /** Twilio Account SID (starts with "AC"). */
+    accountSid: string;
+    /** Twilio Auth Token. */
+    authToken: string;
+    /**
+     * Optional fetch override — inject a mock in tests.
+     * Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Twilio voice call provider.
+ *
+ * Uses the Twilio REST API 2010-04-01 for outbound call control and
+ * HMAC-SHA1 for inbound webhook signature verification.
+ *
+ * @example
+ * ```typescript
+ * const provider = new TwilioVoiceProvider({
+ *   accountSid: process.env.TWILIO_ACCOUNT_SID!,
+ *   authToken:  process.env.TWILIO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export declare class TwilioVoiceProvider implements IVoiceCallProvider {
+    readonly name: "twilio";
+    private readonly config;
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly fetch;
+    constructor(config: TwilioVoiceProviderConfig);
+    /**
+     * Verify an incoming Twilio webhook request using HMAC-SHA1.
+     *
+     * Twilio constructs the signed data by appending all POST params (sorted
+     * alphabetically) as key+value pairs directly to the full request URL.
+     */
+    verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
+    /**
+     * Parse a Twilio webhook body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Handles call status transitions (ringing, in-progress, completed, failed,
+     * busy, no-answer, canceled) and DTMF input.
+     */
+    parseWebhookEvent(ctx: WebhookContext): WebhookParseResult;
+    /**
+     * Initiate an outbound call via the Twilio Calls API.
+     *
+     * Posts to `/Accounts/{accountSid}/Calls.json` with form-encoded body.
+     * All four status callback events (initiated, ringing, answered, completed)
+     * are requested.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up an active call by posting `Status=completed`.
+     */
+    hangupCall(input: HangupCallInput): Promise<void>;
+    /**
+     * Inject TTS into a live call using a TwiML `<Say>` verb.
+     *
+     * Sends a `Twiml` parameter containing a minimal `<Response><Say>` document.
+     * The optional `voice` attribute maps to Twilio's built-in voice names
+     * (e.g., `alice`, `Polly.Joanna`).
+     */
+    playTts(input: PlayTtsInput): Promise<void>;
+}
+//# sourceMappingURL=twilio.d.ts.map

package/dist/voice/providers/twilio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/twilio.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB,qDAAqD;AACrD,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC5D,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,MAAM,EAAE,yBAAyB;IAW7C;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAyB7D;;;;;OAKG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IAyD1D;;;;;;OAMG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgCzE;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAelD"}