@signatrust/mcp-server 0.1.1

package/dist/handlers.js

@@ -0,0 +1,389 @@
+/**
+ * MCP tool definitions and handlers.
+ *
+ * The SignaTrust client is injected rather than instantiated at module level
+ * so handlers are straightforward to unit test.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+// =============================================================================
+// Tool Definitions
+// =============================================================================
+export const TOOLS = [
+    {
+        name: "list_envelopes",
+        description: "List signature envelopes with optional status filter and pagination. " +
+            "Returns envelope summaries including signers, documents, and blockchain " +
+            "anchoring status.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                status: {
+                    type: "string",
+                    enum: ["DRAFT", "SENT", "NEEDS_SIGNATURE", "COMPLETED", "VOIDED", "DECLINED"],
+                    description: "Filter by envelope status",
+                },
+                page: {
+                    type: "number",
+                    description: "Page number (1-indexed)",
+                    minimum: 1,
+                },
+                limit: {
+                    type: "number",
+                    enum: [10, 25, 50],
+                    description: "Results per page (default: 10)",
+                },
+            },
+        },
+        annotations: {
+            title: "List Envelopes",
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    },
+    {
+        name: "get_envelope",
+        description: "Get full details of a specific envelope including all signers, " +
+            "documents, status, security level, and blockchain anchoring info.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Envelope ID",
+                },
+            },
+            required: ["id"],
+        },
+        annotations: {
+            title: "Get Envelope Details",
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    },
+    {
+        name: "create_envelope",
+        description: "Create and send a new envelope for signing. Requires a name, at least " +
+            "one signer, and at least one document (pass document IDs from " +
+            "upload_document, or pass a templateId to create from a template). " +
+            "Signers are notified via their chosen delivery method. Use " +
+            "securityLevel to match the legal weight required: STANDARD for routine/" +
+            "internal approvals; VERIFIED (adds SMS/email OTP) for employment, " +
+            "vendor, or healthcare consent; CERTIFIED (adds WebAuthn biometric + " +
+            "device binding) for real estate, high-value, or regulatory signings.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Envelope name/title shown to signers (max 256 chars)",
+                    maxLength: 256,
+                },
+                securityLevel: {
+                    type: "string",
+                    enum: ["STANDARD", "VERIFIED", "CERTIFIED"],
+                    description: "Signing ceremony tier. STANDARD = bearer-token only (default, " +
+                        "legally weakest — vulnerable to link-forwarding disputes). " +
+                        "VERIFIED = STANDARD + SMS/email OTP (defeats link forwarding; " +
+                        "suitable for employment contracts, vendor agreements, healthcare " +
+                        "consent). CERTIFIED = VERIFIED + WebAuthn biometric on a " +
+                        "device-bound credential (near-unrepudiable; suitable for real " +
+                        "estate, high-value transactions, regulated industries). All " +
+                        "tiers are included on every plan.",
+                },
+                signers: {
+                    type: "array",
+                    description: "List of signers for this envelope",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: {
+                                type: "string",
+                                description: "Signer's full name",
+                            },
+                            email: {
+                                type: "string",
+                                description: "Signer's email address (required unless phone is provided)",
+                            },
+                            phone: {
+                                type: "string",
+                                description: "Signer's phone number for SMS delivery (required unless " +
+                                    "email is provided)",
+                            },
+                            role: {
+                                type: "string",
+                                enum: ["SIGNER", "OBSERVER"],
+                                description: "SIGNER must sign, OBSERVER can only view (default: SIGNER)",
+                            },
+                            routingOrder: {
+                                type: "number",
+                                description: "Signing order (1 = first, 2 = second, ...)",
+                                minimum: 1,
+                            },
+                            deliveryMethod: {
+                                type: "string",
+                                enum: ["EMAIL", "SMS", "BOTH"],
+                                description: "How to notify signer (default: EMAIL)",
+                            },
+                        },
+                        required: ["name"],
+                    },
+                    minItems: 1,
+                },
+                documentIds: {
+                    type: "array",
+                    description: "IDs of documents to include. Use upload_document to create a " +
+                        "document first. Either documentIds or templateId is required.",
+                    items: { type: "string" },
+                },
+                templateId: {
+                    type: "string",
+                    description: "Template ID to create the envelope from. When set, the backend " +
+                        "copies the template's document server-side — you do not need to " +
+                        "supply documentIds. Either documentIds or templateId is required.",
+                },
+                message: {
+                    type: "string",
+                    description: "Optional message included in the signing notification",
+                },
+            },
+            required: ["signers"],
+        },
+        annotations: {
+            title: "Create Envelope",
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    },
+    {
+        name: "list_templates",
+        description: "List available document templates. Templates provide pre-configured " +
+            "documents with defined signer roles and form-field placement.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                includeSystem: {
+                    type: "boolean",
+                    description: "Include system-provided templates alongside user templates " +
+                        "(default: true)",
+                },
+            },
+        },
+        annotations: {
+            title: "List Templates",
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    },
+    {
+        name: "upload_document",
+        description: "Upload a local file to SignaTrust and return a document ID suitable " +
+            "for passing to create_envelope. Reads the file from disk, requests a " +
+            "pre-signed S3 upload URL, streams the bytes, and returns metadata. " +
+            "Supported: PDF (recommended), DOCX, images. Max size is enforced by " +
+            "your plan's limits.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filePath: {
+                    type: "string",
+                    description: "Absolute path to the file on the local filesystem",
+                },
+                name: {
+                    type: "string",
+                    description: "Display name for the document (default: the file's basename)",
+                },
+                contentType: {
+                    type: "string",
+                    description: "MIME type (default: inferred from the file extension — .pdf, " +
+                        ".docx, .png, .jpg, .jpeg are recognised)",
+                },
+            },
+            required: ["filePath"],
+        },
+        annotations: {
+            title: "Upload Document",
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    },
+    {
+        name: "analyze_document",
+        description: "Run AI contract analysis (Google Gemini) on a completed envelope's " +
+            "document. Returns a structured report covering risk assessment, " +
+            "flagged clauses, and overall sentiment (SAFE / CAUTION / RISKY). " +
+            "Plan-gated: free accounts receive a 403; upgrade to Pro Lite or above " +
+            "to use this. Surface the 403 message to the user rather than retrying.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                envelopeId: {
+                    type: "string",
+                    description: "Envelope ID to analyze",
+                },
+            },
+            required: ["envelopeId"],
+        },
+        annotations: {
+            title: "Analyze Document (AI)",
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    },
+    {
+        name: "void_envelope",
+        description: "Void (cancel) an in-progress envelope. The envelope's status becomes " +
+            "VOIDED, all signers receive a cancellation notice, and the void is " +
+            "recorded in the audit trail. Use this when the sender needs to cancel " +
+            "a contract that has already been sent to signers. Fails if the envelope " +
+            "is already COMPLETED or already VOIDED — use get_envelope first to " +
+            "check status. After voiding, the envelope can be deleted via the " +
+            "dashboard or DELETE /api/v1/envelopes/{id}.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Envelope ID to void",
+                },
+                reason: {
+                    type: "string",
+                    description: "Optional reason for voiding — included in the cancellation " +
+                        "notice sent to signers, the audit event, and the webhook payload. " +
+                        "Recommend providing one so signers understand why.",
+                    maxLength: 500,
+                },
+            },
+            required: ["id"],
+        },
+        annotations: {
+            title: "Void Envelope",
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
+    },
+    {
+        name: "verify_blockchain",
+        description: "Verify a completed envelope's Solana anchor. Returns the composite " +
+            "hash (SHA-256 binding the final PDF, signer metadata, and the " +
+            "hash-chained audit trail), the file hash, the Solana transaction ID, " +
+            "and an explorer URL. Because the composite hash is anchored to " +
+            "Solana, any modification to the document, signer records, or audit " +
+            "trail breaks the hash chain and fails verification. This is the " +
+            "proof that makes the envelope independently verifiable without " +
+            "SignaTrust.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                envelopeId: {
+                    type: "string",
+                    description: "Envelope ID to verify",
+                },
+            },
+            required: ["envelopeId"],
+        },
+        annotations: {
+            title: "Verify Blockchain Anchor",
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    },
+];
+function success(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+const EXTENSION_MIME = {
+    ".pdf": "application/pdf",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".doc": "application/msword",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".txt": "text/plain",
+};
+function inferContentType(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return EXTENSION_MIME[ext] ?? "application/octet-stream";
+}
+// =============================================================================
+// Handler
+// =============================================================================
+export async function handleTool(client, name, args) {
+    switch (name) {
+        case "list_envelopes": {
+            const result = await client.listEnvelopes({
+                status: args.status,
+                page: args.page,
+                limit: args.limit,
+            });
+            return success(result);
+        }
+        case "get_envelope": {
+            const result = await client.getEnvelope(args.id);
+            return success(result);
+        }
+        case "create_envelope": {
+            const result = await client.createEnvelope({
+                name: args.name,
+                signers: args.signers,
+                documentIds: args.documentIds,
+                templateId: args.templateId,
+                message: args.message,
+                securityLevel: args.securityLevel,
+            });
+            return success(result);
+        }
+        case "list_templates": {
+            const result = await client.listTemplates({
+                includeSystem: args.includeSystem,
+            });
+            return success(result);
+        }
+        case "upload_document": {
+            const filePath = args.filePath;
+            const stats = await stat(filePath);
+            const bytes = await readFile(filePath);
+            const displayName = args.name ?? basename(filePath);
+            const contentType = args.contentType ?? inferContentType(filePath);
+            const uploaded = await client.requestDocumentUpload({
+                name: displayName,
+                contentType,
+                size: stats.size,
+            });
+            await client.putBytesToUploadUrl(uploaded.uploadUrl, bytes, contentType);
+            return success({
+                id: uploaded.id,
+                name: uploaded.name,
+                contentType: uploaded.contentType,
+                size: uploaded.size,
+                hash: uploaded.hash,
+                createdAt: uploaded.createdAt,
+            });
+        }
+        case "analyze_document": {
+            const result = await client.analyzeEnvelope(args.envelopeId);
+            return success(result);
+        }
+        case "void_envelope": {
+            const result = await client.voidEnvelope(args.id, args.reason);
+            return success(result);
+        }
+        case "verify_blockchain": {
+            const result = await client.verifyBlockchain(args.envelopeId);
+            return success(result);
+        }
+        default:
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown tool: ${name}. Use list_tools to see available tools.`,
+                    },
+                ],
+                isError: true,
+            };
+    }
+}
+//# sourceMappingURL=handlers.js.map

package/dist/handlers.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * SignaTrust MCP Server
+ *
+ * Model Context Protocol server enabling AI assistants to interact with the
+ * SignaTrust document signing API. Supports envelope management, templates,
+ * blockchain verification, and more.
+ *
+ * Setup:
+ *   SIGNATRUST_API_KEY=sk_live_xxx npx @signatrust/mcp-server
+ *
+ * Or add to claude_desktop_config.json:
+ *   { "mcpServers": { "signatrust": { "command": "npx", "args": ["-y", "@signatrust/mcp-server"], "env": { "SIGNATRUST_API_KEY": "sk_live_xxx" } } } }
+ */
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG"}

package/dist/server.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * SignaTrust MCP Server
+ *
+ * Model Context Protocol server enabling AI assistants to interact with the
+ * SignaTrust document signing API. Supports envelope management, templates,
+ * blockchain verification, and more.
+ *
+ * Setup:
+ *   SIGNATRUST_API_KEY=sk_live_xxx npx @signatrust/mcp-server
+ *
+ * Or add to claude_desktop_config.json:
+ *   { "mcpServers": { "signatrust": { "command": "npx", "args": ["-y", "@signatrust/mcp-server"], "env": { "SIGNATRUST_API_KEY": "sk_live_xxx" } } } }
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { SignaTrustClient, ApiError } from "./vendor/signatrust-sdk/index.js";
+import { formatApiError } from "./errors.js";
+import { TOOLS, handleTool } from "./handlers.js";
+// =============================================================================
+// Configuration
+// =============================================================================
+const API_KEY = process.env.SIGNATRUST_API_KEY;
+const API_URL = process.env.SIGNATRUST_API_URL || "https://app.signatrust.io";
+const VERCEL_PROTECTION_BYPASS = process.env.VERCEL_PROTECTION_BYPASS;
+if (!API_KEY) {
+    console.error("Error: SIGNATRUST_API_KEY environment variable is required.\n" +
+        "Get your API key at https://app.signatrust.io/settings/api-keys");
+    process.exit(1);
+}
+// Staging is fronted by Vercel's deployment protection. Forwarding the bypass
+// header lets harness runs and staging smoke tests reach the application.
+// In production the env var is unset, so nothing is forwarded.
+// Note: do NOT also send x-vercel-set-bypass-cookie — that triggers a
+// redirect loop under node's fetch because cookies aren't persisted across
+// the follow-up request.
+const extraHeaders = {};
+if (VERCEL_PROTECTION_BYPASS) {
+    extraHeaders["x-vercel-protection-bypass"] = VERCEL_PROTECTION_BYPASS;
+}
+const client = new SignaTrustClient({
+    apiKey: API_KEY,
+    baseUrl: API_URL,
+    extraHeaders,
+});
+// =============================================================================
+// Server Setup
+// =============================================================================
+const server = new Server({
+    name: "signatrust",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name } = request.params;
+    const args = (request.params.arguments ?? {});
+    try {
+        return await handleTool(client, name, args);
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            return formatApiError(error.status, error.body, error.retryAfter);
+        }
+        const message = error instanceof Error ? error.message : "An unexpected error occurred";
+        return {
+            content: [{ type: "text", text: message }],
+            isError: true,
+        };
+    }
+});
+// =============================================================================
+// Start
+// =============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("SignaTrust MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/vendor/signatrust-sdk/api-client.d.ts

@@ -0,0 +1,77 @@
+/**
+ * HTTP client for the SignaTrust REST API (v1).
+ *
+ * Vendored from @signatrustdev/signatrust-sdk. Uses native fetch() (Node 18+)
+ * with API key authentication via x-api-key header. All methods return typed
+ * responses or throw ApiError on non-2xx status.
+ */
+import type { EnvelopeDetail, CreateEnvelopeInput, TemplateResponse, VerificationResponse, AnalysisResponse, DocumentUploadResponse, PaginatedResponse, ProblemDetails } from "./types.js";
+export interface ClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    /**
+     * Optional extra headers added to every API request. Useful for
+     * preview/staging deployments gated by a platform auth layer (e.g.
+     * Vercel's protection bypass). Never used in production.
+     */
+    extraHeaders?: Record<string, string>;
+}
+export interface ApiResponse<T> {
+    ok: boolean;
+    status: number;
+    data: T;
+    retryAfter?: string | null;
+}
+export declare class ApiError extends Error {
+    status: number;
+    body: ProblemDetails | string | null;
+    retryAfter?: string | null | undefined;
+    constructor(status: number, body: ProblemDetails | string | null, retryAfter?: string | null | undefined);
+}
+export declare class SignaTrustClient {
+    private apiKey;
+    private baseUrl;
+    private extraHeaders;
+    constructor(config: ClientConfig);
+    private request;
+    listEnvelopes(params?: {
+        status?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<EnvelopeDetail>>;
+    getEnvelope(id: string): Promise<EnvelopeDetail>;
+    createEnvelope(input: CreateEnvelopeInput): Promise<EnvelopeDetail>;
+    listTemplates(params?: {
+        includeSystem?: boolean;
+    }): Promise<TemplateResponse[]>;
+    /**
+     * Request a pre-signed upload URL for a new document.
+     * After this returns, PUT the file bytes to `uploadUrl` with the given
+     * Content-Type header, then use the returned `id` when creating an envelope.
+     */
+    requestDocumentUpload(input: {
+        name: string;
+        contentType: string;
+        size: number;
+    }): Promise<DocumentUploadResponse>;
+    /**
+     * Upload file bytes to a pre-signed S3 URL obtained from requestDocumentUpload.
+     * Does not use the API key — the pre-signed URL carries its own auth.
+     */
+    putBytesToUploadUrl(uploadUrl: string, bytes: Uint8Array, contentType: string): Promise<void>;
+    /**
+     * Void an in-progress envelope. Sets status to VOIDED, notifies signers
+     * with a cancellation notice, writes an ENVELOPE_VOIDED audit event, and
+     * dispatches an `envelope.voided` webhook.
+     *
+     * Fails with 400 if the envelope is already COMPLETED or already VOIDED.
+     */
+    voidEnvelope(envelopeId: string, reason?: string): Promise<EnvelopeDetail>;
+    verifyBlockchain(envelopeId: string): Promise<VerificationResponse>;
+    /**
+     * Trigger AI contract analysis on an envelope's document.
+     * Plan-gated: Free plan returns 403.
+     */
+    analyzeEnvelope(envelopeId: string): Promise<AnalysisResponse>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/vendor/signatrust-sdk/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/vendor/signatrust-sdk/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;IACR,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,QAAS,SAAQ,KAAK;IAExB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;gBAF1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,EACpC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA;CAKpC;AAMD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAyB;gBAEjC,MAAM,EAAE,YAAY;YAMlB,OAAO;IAgDf,aAAa,CAAC,MAAM,CAAC,EAAE;QAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IASxC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAQhD,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IASnE,aAAa,CAAC,MAAM,CAAC,EAAE;QAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAS/B;;;;OAIG;IACG,qBAAqB,CAAC,KAAK,EAAE;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,sBAAsB,CAAC;IASnC;;;OAGG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAehB;;;;;;OAMG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC;IASpB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAQzE;;;OAGG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAOrE"}