@rashidazarang/airtable-mcp 3.1.0 → 3.2.8

package/dist/typescript/app/tools/handleError.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleToolError = handleToolError;
+const errors_1 = require("../../errors");
+function formatTokenWarnings(warnings) {
+    if (warnings.length === 0)
+        return '';
+    return '\n\nToken format issues detected:\n' + warnings.map((w) => `• ${w}`).join('\n');
+}
+function buildAuthErrorMessage(error, tokenWarnings) {
+    const errorType = error.context?.upstreamErrorType;
+    const baseId = error.context?.baseId;
+    const endpoint = error.context?.endpoint ?? '';
+    const isMetaApi = endpoint.includes('/meta/');
+    const isBaseSpecific = baseId && endpoint.includes(`/bases/${baseId}`);
+    const warningsText = formatTokenWarnings(tokenWarnings);
+    // Handle specific Airtable error types
+    if (errorType === 'AUTHENTICATION_REQUIRED') {
+        return `Authentication failed: Token is invalid or expired.
+
+Troubleshooting:
+1. Verify your token at https://airtable.com/create/tokens
+2. Check that the token hasn't been revoked
+3. Ensure you copied the entire token (typically ~82 characters)${warningsText}`;
+    }
+    if (errorType === 'INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND') {
+        if (baseId) {
+            return `Authentication failed for base "${baseId}".
+
+Your token is valid but cannot access this specific base.
+
+Troubleshooting:
+1. Run list_bases to see which bases your token can access
+2. If this base is not listed, regenerate your token with access to it
+3. Verify your token has the required scopes:
+   • schema.bases:read (for describe/list operations)
+   • data.records:read (for query operations)
+   • data.records:write (for create/update operations)${warningsText}`;
+        }
+        return `Authentication failed: Token lacks required permissions.
+
+Troubleshooting:
+1. Verify your token has the "schema.bases:read" scope
+2. Check token permissions at https://airtable.com/create/tokens
+3. Regenerate token if scopes are missing${warningsText}`;
+    }
+    // Fallback for unrecognized error types
+    if (isMetaApi && isBaseSpecific) {
+        return `Authentication failed for base "${baseId}".
+
+This could mean:
+1. Your token lacks the "schema.bases:read" scope
+2. Your token does not have access to this specific base
+
+Run list_bases to see which bases your token can access.${warningsText}`;
+    }
+    if (isMetaApi) {
+        return `Authentication failed for Meta API.
+
+Troubleshooting:
+1. Ensure your token has the "schema.bases:read" scope
+2. Verify token at https://airtable.com/create/tokens${warningsText}`;
+    }
+    return `Authentication failed.
+
+Troubleshooting:
+1. Verify token scopes match the operation you're attempting
+2. Check base/table access permissions
+3. Review token at https://airtable.com/create/tokens${warningsText}`;
+}
+function buildValidationErrorMessage(error) {
+    const errorType = error.context?.upstreamErrorType;
+    const errorMessage = error.context?.upstreamErrorMessage;
+    if (errorType === 'UNKNOWN_FIELD_NAME') {
+        return `Airtable rejected the request: Unknown field name.
+
+${errorMessage ? `Details: ${errorMessage}\n\n` : ''}Troubleshooting:
+1. Use describe tool to see valid field names for this table
+2. Field names are case-sensitive
+3. Check for typos in field names`;
+    }
+    if (errorType === 'INVALID_FIELD_TYPE') {
+        return `Airtable rejected the request: Invalid field value type.
+
+${errorMessage ? `Details: ${errorMessage}\n\n` : ''}Troubleshooting:
+1. Use describe tool to see field types
+2. Ensure values match expected types (text, number, date, etc.)
+3. Check Airtable field configuration`;
+    }
+    if (errorMessage) {
+        return `Airtable validation error: ${errorMessage}
+
+Troubleshooting:
+1. Check field names and values match table schema
+2. Use describe tool to verify field types
+3. Ensure required fields are provided`;
+    }
+    return `Airtable rejected the request.
+
+Troubleshooting:
+1. Check field names exist in the table
+2. Verify values match expected field types
+3. Use describe tool to inspect table schema`;
+}
+function buildNotFoundErrorMessage(error) {
+    const baseId = error.context?.baseId;
+    const errorMessage = error.context?.upstreamErrorMessage;
+    if (baseId) {
+        return `Resource not found in base "${baseId}".
+
+${errorMessage ? `Details: ${errorMessage}\n\n` : ''}Troubleshooting:
+1. Verify the base ID is correct
+2. Check table/record IDs exist
+3. Use list_bases and describe tools to confirm identifiers`;
+    }
+    return `Requested Airtable resource was not found.
+
+Troubleshooting:
+1. Confirm base, table, and record identifiers are correct
+2. Use list_bases to see available bases
+3. Use describe to see tables in a base`;
+}
+function buildRateLimitMessage(error) {
+    const retryAfter = error.retryAfterMs;
+    const retrySeconds = retryAfter ? Math.ceil(retryAfter / 1000) : undefined;
+    if (retrySeconds) {
+        return `Airtable rate limit exceeded. Retry after ${retrySeconds} seconds.
+
+The API allows 5 requests per second per base. Consider:
+1. Reducing request frequency
+2. Batching multiple record operations
+3. Using pagination for large result sets`;
+    }
+    return `Airtable rate limit exceeded.
+
+The API allows 5 requests per second per base. Retry after a brief delay.`;
+}
+function toUserMessage(error, ctx) {
+    const tokenWarnings = ctx.config.auth.tokenFormatWarnings || [];
+    switch (error.code) {
+        case 'RateLimited':
+            return buildRateLimitMessage(error);
+        case 'ValidationError':
+            return buildValidationErrorMessage(error);
+        case 'AuthError':
+            return buildAuthErrorMessage(error, tokenWarnings);
+        case 'ConflictError':
+            return `Record conflict detected.
+
+The record was modified since it was fetched.
+
+Troubleshooting:
+1. Fetch the latest version of the record
+2. Review the changes (diff)
+3. Retry the update with fresh data`;
+        case 'NotFound':
+            return buildNotFoundErrorMessage(error);
+        case 'GovernanceError':
+            return `Operation blocked by governance policy.
+
+This operation is not allowed by the configured governance rules.
+Check AIRTABLE_ALLOWED_BASES and AIRTABLE_ALLOWED_TABLES settings.`;
+        default:
+            return `Unexpected Airtable error.
+
+Please retry the operation. If the problem persists, check:
+1. Airtable service status
+2. Server logs for details
+3. Request ID: ${error.context?.upstreamRequestId || 'N/A'}`;
+    }
+}
+function handleToolError(toolName, error, ctx) {
+    if (error instanceof errors_1.AirtableBrainError) {
+        ctx.logger.error(`${toolName} failed`, {
+            code: error.code,
+            status: error.status,
+            retryAfterMs: error.retryAfterMs,
+            upstreamErrorType: error.context?.upstreamErrorType,
+            upstreamRequestId: error.context?.upstreamRequestId
+        });
+        ctx.exceptions.record(error, `${toolName} failed`, error.message);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: toUserMessage(error, ctx)
+                }
+            ]
+        };
+    }
+    ctx.logger.error(`${toolName} failed with unknown error`, {
+        error: error instanceof Error ? error.message : String(error)
+    });
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: 'Unexpected server error. Check logs for details.'
+            }
+        ]
+    };
+}
+//# sourceMappingURL=handleError.js.map

package/dist/typescript/app/tools/handleError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleError.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/handleError.ts"],"names":[],"mappings":";;AAoNA,0CAkCC;AAtPD,yCAAkD;AAiBlD,SAAS,mBAAmB,CAAC,QAAkB;IAC7C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,OAAO,qCAAqC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1F,CAAC;AAED,SAAS,qBAAqB,CAC5B,KAAyB,EACzB,aAAuB;IAEvB,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,EAAE,iBAAkD,CAAC;IACpF,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC;IACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;IAC/C,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,cAAc,GAAG,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,MAAM,EAAE,CAAC,CAAC;IACvE,MAAM,YAAY,GAAG,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAExD,uCAAuC;IACvC,IAAI,SAAS,KAAK,yBAAyB,EAAE,CAAC;QAC5C,OAAO;;;;;kEAKuD,YAAY,EAAE,CAAC;IAC/E,CAAC;IAED,IAAI,SAAS,KAAK,wCAAwC,EAAE,CAAC;QAC3D,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,mCAAmC,MAAM;;;;;;;;;;wDAUE,YAAY,EAAE,CAAC;QACnE,CAAC;QACD,OAAO;;;;;2CAKgC,YAAY,EAAE,CAAC;IACxD,CAAC;IAED,wCAAwC;IACxC,IAAI,SAAS,IAAI,cAAc,EAAE,CAAC;QAChC,OAAO,mCAAmC,MAAM;;;;;;0DAMM,YAAY,EAAE,CAAC;IACvE,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,OAAO;;;;uDAI4C,YAAY,EAAE,CAAC;IACpE,CAAC;IAED,OAAO;;;;;uDAK8C,YAAY,EAAE,CAAC;AACtE,CAAC;AAED,SAAS,2BAA2B,CAAC,KAAyB;IAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACnD,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,EAAE,oBAAoB,CAAC;IAEzD,IAAI,SAAS,KAAK,oBAAoB,EAAE,CAAC;QACvC,OAAO;;EAET,YAAY,CAAC,CAAC,CAAC,YAAY,YAAY,MAAM,CAAC,CAAC,CAAC,EAAE;;;kCAGlB,CAAC;IACjC,CAAC;IAED,IAAI,SAAS,KAAK,oBAAoB,EAAE,CAAC;QACvC,OAAO;;EAET,YAAY,CAAC,CAAC,CAAC,YAAY,YAAY,MAAM,CAAC,CAAC,CAAC,EAAE;;;sCAGd,CAAC;IACrC,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,8BAA8B,YAAY;;;;;uCAKd,CAAC;IACtC,CAAC;IAED,OAAO;;;;;6CAKoC,CAAC;AAC9C,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAyB;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC;IACrC,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,EAAE,oBAAoB,CAAC;IAEzD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,+BAA+B,MAAM;;EAE9C,YAAY,CAAC,CAAC,CAAC,YAAY,YAAY,MAAM,CAAC,CAAC,CAAC,EAAE;;;4DAGQ,CAAC;IAC3D,CAAC;IAED,OAAO;;;;;wCAK+B,CAAC;AACzC,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAyB;IACtD,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC;IACtC,MAAM,YAAY,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE3E,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,6CAA6C,YAAY;;;;;0CAK1B,CAAC;IACzC,CAAC;IAED,OAAO;;0EAEiE,CAAC;AAC3E,CAAC;AAED,SAAS,aAAa,CAAC,KAAyB,EAAE,GAAe;IAC/D,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,IAAI,EAAE,CAAC;IAEhE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,aAAa;YAChB,OAAO,qBAAqB,CAAC,KAAK,CAAC,CAAC;QAEtC,KAAK,iBAAiB;YACpB,OAAO,2BAA2B,CAAC,KAAK,CAAC,CAAC;QAE5C,KAAK,WAAW;YACd,OAAO,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QAErD,KAAK,eAAe;YAClB,OAAO;;;;;;;oCAOuB,CAAC;QAEjC,KAAK,UAAU;YACb,OAAO,yBAAyB,CAAC,KAAK,CAAC,CAAC;QAE1C,KAAK,iBAAiB;YACpB,OAAO;;;mEAGsD,CAAC;QAEhE;YACE,OAAO;;;;;iBAKI,KAAK,CAAC,OAAO,EAAE,iBAAiB,IAAI,KAAK,EAAE,CAAC;IAC3D,CAAC;AACH,CAAC;AAED,SAAgB,eAAe,CAAC,QAAgB,EAAE,KAAc,EAAE,GAAe;IAC/E,IAAI,KAAK,YAAY,2BAAkB,EAAE,CAAC;QACxC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,SAAS,EAAE;YACrC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,iBAAiB,EAAE,KAAK,CAAC,OAAO,EAAE,iBAAiB;YACnD,iBAAiB,EAAE,KAAK,CAAC,OAAO,EAAE,iBAAiB;SACpD,CAAC,CAAC;QACH,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,QAAQ,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAClE,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC;iBAChC;aACF;SACF,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,4BAA4B,EAAE;QACxD,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;KAC9D,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,kDAAkD;aACzD;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/typescript/app/tools/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAllTools = registerAllTools;
+const listBases_1 = require("./listBases");
+const describe_1 = require("./describe");
+const query_1 = require("./query");
+const listGovernance_1 = require("./listGovernance");
+const listExceptions_1 = require("./listExceptions");
+const create_1 = require("./create");
+const update_1 = require("./update");
+const upsert_1 = require("./upsert");
+const webhooks_1 = require("./webhooks");
+function registerAllTools(server, ctx) {
+    (0, listBases_1.registerListBasesTool)(server, ctx);
+    (0, describe_1.registerDescribeTool)(server, ctx);
+    (0, query_1.registerQueryTool)(server, ctx);
+    (0, listGovernance_1.registerGovernanceTool)(server, ctx);
+    (0, listExceptions_1.registerExceptionsTool)(server, ctx);
+    (0, create_1.registerCreateTool)(server, ctx);
+    (0, update_1.registerUpdateTool)(server, ctx);
+    (0, upsert_1.registerUpsertTool)(server, ctx);
+    (0, webhooks_1.registerWebhookTools)(server, ctx);
+}
+//# sourceMappingURL=index.js.map

package/dist/typescript/app/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/index.ts"],"names":[],"mappings":";;AAYA,4CAUC;AApBD,2CAAoD;AACpD,yCAAkD;AAClD,mCAA4C;AAC5C,qDAA0D;AAC1D,qDAA0D;AAC1D,qCAA8C;AAC9C,qCAA8C;AAC9C,qCAA8C;AAC9C,yCAAkD;AAElD,SAAgB,gBAAgB,CAAC,MAAiB,EAAE,GAAe;IACjE,IAAA,iCAAqB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,IAAA,+BAAoB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClC,IAAA,yBAAiB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,IAAA,uCAAsB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,IAAA,uCAAsB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,IAAA,2BAAkB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,IAAA,2BAAkB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,IAAA,2BAAkB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,IAAA,+BAAoB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC"}

package/dist/typescript/app/tools/listBases.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerListBasesTool = registerListBasesTool;
+const zod_1 = require("zod");
+const handleError_1 = require("./handleError");
+const response_1 = require("./response");
+// Schema for list_bases output
+const listBasesOutputSchema = zod_1.z.object({
+    bases: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        name: zod_1.z.string(),
+        permissionLevel: zod_1.z.string().optional()
+    }))
+});
+function registerListBasesTool(server, ctx) {
+    server.registerTool('list_bases', {
+        description: 'List all accessible Airtable bases with their names, IDs, and permission levels',
+        inputSchema: {},
+        outputSchema: listBasesOutputSchema.shape
+    }, async (_args, _extra) => {
+        try {
+            ctx.logger.info('Listing accessible Airtable bases');
+            const response = await ctx.airtable.listBases();
+            const bases = response.bases;
+            if (!bases || bases.length === 0) {
+                const structuredContent = {
+                    bases: []
+                };
+                return (0, response_1.createToolResponse)(structuredContent);
+            }
+            const normalizedBases = bases.map((base) => ({
+                id: String(base.id ?? ''),
+                name: String(base.name ?? ''),
+                permissionLevel: base.permissionLevel ? String(base.permissionLevel) : undefined
+            }));
+            const structuredContent = {
+                bases: normalizedBases
+            };
+            ctx.logger.info('Successfully listed bases', { count: bases.length });
+            return (0, response_1.createToolResponse)(structuredContent);
+        }
+        catch (error) {
+            return (0, handleError_1.handleToolError)('list_bases', error, ctx);
+        }
+    });
+}
+//# sourceMappingURL=listBases.js.map

package/dist/typescript/app/tools/listBases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listBases.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/listBases.ts"],"names":[],"mappings":";;AAmBA,sDAwCC;AAzDD,6BAAwB;AACxB,+CAAgD;AAChD,yCAAgD;AAEhD,+BAA+B;AAC/B,MAAM,qBAAqB,GAAG,OAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,OAAC,CAAC,KAAK,CACZ,OAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE;QACd,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;QAChB,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACvC,CAAC,CACH;CACF,CAAC,CAAC;AAIH,SAAgB,qBAAqB,CAAC,MAAiB,EAAE,GAAe;IACtE,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,WAAW,EAAE,iFAAiF;QAC9F,WAAW,EAAE,EAAS;QACtB,YAAY,EAAE,qBAAqB,CAAC,KAAY;KACjD,EACD,KAAK,EAAE,KAAc,EAAE,MAAe,EAAE,EAAE;QACxC,IAAI,CAAC;YACH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;YAErD,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;YAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;YAE7B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACjC,MAAM,iBAAiB,GAAoB;oBACzC,KAAK,EAAE,EAAE;iBACV,CAAC;gBACF,OAAO,IAAA,6BAAkB,EAAC,iBAAiB,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,eAAe,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAS,EAAE,EAAE,CAAC,CAAC;gBAChD,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;gBACzB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;gBAC7B,eAAe,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS;aACjF,CAAC,CAAC,CAAC;YAEJ,MAAM,iBAAiB,GAAoB;gBACzC,KAAK,EAAE,eAAe;aACvB,CAAC;YAEF,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;YAEtE,OAAO,IAAA,6BAAkB,EAAC,iBAAiB,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAA,6BAAe,EAAC,YAAY,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/typescript/app/tools/listExceptions.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExceptionsTool = registerExceptionsTool;
+const types_1 = require("../types");
+const response_1 = require("./response");
+function registerExceptionsTool(server, ctx) {
+    server.registerTool('list_exceptions', {
+        description: 'List recent exceptions and remediation proposals.',
+        inputSchema: types_1.listExceptionsInputSchema.shape,
+        outputSchema: types_1.listExceptionsOutputSchema.shape
+    }, async (args) => {
+        const snapshot = ctx.exceptions.list(args);
+        return (0, response_1.createToolResponse)(snapshot);
+    });
+}
+//# sourceMappingURL=listExceptions.js.map

package/dist/typescript/app/tools/listExceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listExceptions.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/listExceptions.ts"],"names":[],"mappings":";;AASA,wDAaC;AArBD,oCAIkB;AAElB,yCAAgD;AAEhD,SAAgB,sBAAsB,CAAC,MAAiB,EAAE,GAAe;IACvE,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EAAE,mDAAmD;QAChE,WAAW,EAAE,iCAAyB,CAAC,KAAY;QACnD,YAAY,EAAE,kCAA0B,CAAC,KAAY;KACtD,EACD,KAAK,EAAE,IAAyB,EAAE,EAAE;QAClC,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,IAAA,6BAAkB,EAAC,QAAQ,CAAC,CAAC;IACtC,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/typescript/app/tools/listGovernance.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerGovernanceTool = registerGovernanceTool;
+const types_1 = require("../types");
+const response_1 = require("./response");
+function registerGovernanceTool(server, ctx) {
+    server.registerTool('list_governance', {
+        description: 'Return governance allow-lists and PII masking policies.',
+        outputSchema: types_1.governanceOutputSchema.shape
+    }, async () => {
+        const snapshot = ctx.governance.getSnapshot();
+        return (0, response_1.createToolResponse)(snapshot);
+    });
+}
+//# sourceMappingURL=listGovernance.js.map

package/dist/typescript/app/tools/listGovernance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listGovernance.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/listGovernance.ts"],"names":[],"mappings":";;AAKA,wDAYC;AAhBD,oCAAkD;AAElD,yCAAgD;AAEhD,SAAgB,sBAAsB,CAAC,MAAiB,EAAE,GAAe;IACvE,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EAAE,yDAAyD;QACtE,YAAY,EAAE,8BAAsB,CAAC,KAAY;KAClD,EACD,KAAK,IAAI,EAAE;QACT,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;QAC9C,OAAO,IAAA,6BAAkB,EAAC,QAAQ,CAAC,CAAC;IACtC,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/typescript/app/tools/query.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerQueryTool = registerQueryTool;
+const node_crypto_1 = require("node:crypto");
+const types_1 = require("../types");
+const handleError_1 = require("./handleError");
+const response_1 = require("./response");
+const sanitize_1 = require("../sanitize");
+function maskValue(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(() => '••••');
+    }
+    if (typeof value === 'object') {
+        return '[redacted]';
+    }
+    return '••••';
+}
+function hashValue(value) {
+    const serialized = typeof value === 'string' ? value : JSON.stringify(value ?? '');
+    return (0, node_crypto_1.createHash)('sha256').update(serialized).digest('hex');
+}
+function applyPiiPolicies(fields, policies) {
+    if (!policies.length) {
+        return fields;
+    }
+    const result = { ...fields };
+    for (const policy of policies) {
+        if (!(policy.field in result))
+            continue;
+        switch (policy.policy) {
+            case 'drop':
+                delete result[policy.field];
+                break;
+            case 'mask':
+                result[policy.field] = maskValue(result[policy.field]);
+                break;
+            case 'hash':
+                result[policy.field] = hashValue(result[policy.field]);
+                break;
+            default:
+                break;
+        }
+    }
+    return result;
+}
+function registerQueryTool(server, ctx) {
+    server.registerTool('query', {
+        description: 'Query Airtable records with filtering, sorting, and pagination.',
+        inputSchema: types_1.queryInputShape,
+        outputSchema: types_1.queryOutputSchema.shape
+    }, async (args, _extra) => {
+        try {
+            const input = types_1.queryInputSchema.parse(args);
+            ctx.governance.ensureOperationAllowed('query');
+            ctx.governance.ensureBaseAllowed(input.baseId);
+            ctx.governance.ensureTableAllowed(input.baseId, input.table);
+            const logger = ctx.logger.child({
+                tool: 'query',
+                baseId: input.baseId,
+                table: input.table
+            });
+            const queryParams = {};
+            if (input.fields) {
+                queryParams.fields = input.fields;
+            }
+            if (input.filterByFormula) {
+                // Validate formula for suspicious patterns (log warning but don't block)
+                const formulaValidation = (0, sanitize_1.validateFormula)(input.filterByFormula);
+                if (!formulaValidation.isValid) {
+                    logger.warn('Potentially unsafe formula pattern detected', {
+                        warning: formulaValidation.warning,
+                        formula: input.filterByFormula.substring(0, 100) // Truncate for logging
+                    });
+                }
+                queryParams.filterByFormula = input.filterByFormula;
+            }
+            if (input.view) {
+                queryParams.view = input.view;
+            }
+            if (input.pageSize) {
+                queryParams.pageSize = input.pageSize;
+            }
+            if (input.maxRecords) {
+                queryParams.maxRecords = input.maxRecords;
+            }
+            if (input.offset) {
+                queryParams.offset = input.offset;
+            }
+            if (typeof input.returnFieldsByFieldId === 'boolean') {
+                queryParams.returnFieldsByFieldId = input.returnFieldsByFieldId;
+            }
+            if (input.sorts) {
+                input.sorts.forEach((sort, index) => {
+                    queryParams[`sort[${index}][field]`] = sort.field;
+                    queryParams[`sort[${index}][direction]`] = sort.direction ?? 'asc';
+                });
+            }
+            const response = await ctx.airtable.queryRecords(input.baseId, input.table, queryParams);
+            const rawRecords = Array.isArray(response?.records)
+                ? response.records
+                : [];
+            const piiPolicies = ctx.governance.listPiiPolicies(input.baseId, input.table);
+            const sanitizedRecords = rawRecords.map((record) => {
+                const fields = typeof record.fields === 'object' && record.fields !== null ? record.fields : {};
+                return {
+                    id: String(record.id ?? ''),
+                    createdTime: record.createdTime ? String(record.createdTime) : undefined,
+                    fields: applyPiiPolicies(fields, piiPolicies)
+                };
+            });
+            const structuredContent = {
+                records: sanitizedRecords,
+                offset: typeof response?.offset === 'string' ? response.offset : undefined,
+                summary: {
+                    returned: sanitizedRecords.length,
+                    hasMore: Boolean(response?.offset)
+                }
+            };
+            logger.debug('Query completed', {
+                returned: sanitizedRecords.length,
+                hasMore: structuredContent.summary?.hasMore
+            });
+            return (0, response_1.createToolResponse)(structuredContent);
+        }
+        catch (error) {
+            return (0, handleError_1.handleToolError)('query', error, ctx);
+        }
+    });
+}
+//# sourceMappingURL=query.js.map

package/dist/typescript/app/tools/query.js.map

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

package/dist/typescript/app/tools/response.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Utility for creating consistent MCP tool responses.
+ *
+ * The MCP protocol requires the `content` array to contain displayable data.
+ * While `structuredContent` is the newer typed output format, most clients
+ * read from `content` for backwards compatibility.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolResponse = createToolResponse;
+/**
+ * Creates a tool response with both structuredContent (for typed clients)
+ * and content array (for backwards compatibility with MCP clients).
+ */
+function createToolResponse(data) {
+    return {
+        structuredContent: data,
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
+    };
+}
+//# sourceMappingURL=response.js.map

package/dist/typescript/app/tools/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/response.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAYH,gDAKC;AATD;;;GAGG;AACH,SAAgB,kBAAkB,CAAI,IAAO;IAC3C,OAAO;QACL,iBAAiB,EAAE,IAAI;QACvB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC"}

package/dist/typescript/app/tools/update.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUpdateTool = registerUpdateTool;
+const types_1 = require("../types");
+const handleError_1 = require("./handleError");
+const response_1 = require("./response");
+function chunk(arr, size) {
+    const out = [];
+    for (let i = 0; i < arr.length; i += size)
+        out.push(arr.slice(i, i + size));
+    return out;
+}
+function registerUpdateTool(server, ctx) {
+    server.registerTool('update', {
+        description: 'Update Airtable records (requires diff-before-write via dryRun first).',
+        inputSchema: types_1.updateInputSchema.shape,
+        outputSchema: types_1.updateOutputSchema.shape
+    }, async (raw) => {
+        try {
+            const args = types_1.updateInputSchema.parse(raw);
+            ctx.governance.ensureOperationAllowed('update');
+            ctx.governance.ensureBaseAllowed(args.baseId);
+            ctx.governance.ensureTableAllowed(args.baseId, args.table);
+            const logger = ctx.logger.child({ tool: 'update', baseId: args.baseId, table: args.table });
+            if (args.dryRun) {
+                const structuredContent = {
+                    diff: { added: 0, updated: args.records.length, unchanged: 0, conflicts: 0 },
+                    dryRun: true,
+                    records: args.records.map((r) => ({ id: r.id, fields: r.fields })),
+                    conflicts: []
+                };
+                return (0, response_1.createToolResponse)(structuredContent);
+            }
+            const chunks = chunk(args.records, 10);
+            const aggregated = [];
+            for (let i = 0; i < chunks.length; i++) {
+                const body = { records: chunks[i], typecast: args.typecast ?? false };
+                const headerKey = args.idempotencyKey ? `${args.idempotencyKey}:${i}` : undefined;
+                const response = await ctx.airtable.updateRecords(args.baseId, args.table, body, headerKey);
+                if (Array.isArray(response?.records))
+                    aggregated.push(...response.records);
+            }
+            const structuredContent = {
+                diff: { added: 0, updated: aggregated.length, unchanged: 0, conflicts: 0 },
+                records: aggregated.map((r) => ({ id: String(r.id), fields: r.fields || {} })),
+                dryRun: false,
+                conflicts: []
+            };
+            logger.info('Update completed', { updated: aggregated.length });
+            return (0, response_1.createToolResponse)(structuredContent);
+        }
+        catch (error) {
+            return (0, handleError_1.handleToolError)('update', error, ctx);
+        }
+    });
+}
+//# sourceMappingURL=update.js.map

package/dist/typescript/app/tools/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/update.ts"],"names":[],"mappings":";;AAiBA,gDAmDC;AAlED,oCAKkB;AAClB,+CAAgD;AAChD,yCAAgD;AAEhD,SAAS,KAAK,CAAI,GAAQ,EAAE,IAAY;IACtC,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC5E,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAgB,kBAAkB,CAAC,MAAiB,EAAE,GAAe;IACnE,MAAM,CAAC,YAAY,CACjB,QAAQ,EACR;QACE,WAAW,EAAE,wEAAwE;QACrF,WAAW,EAAE,yBAAiB,CAAC,KAAY;QAC3C,YAAY,EAAE,0BAAkB,CAAC,KAAY;KAC9C,EACD,KAAK,EAAE,GAAgB,EAAE,EAAE;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,yBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC1C,GAAG,CAAC,UAAU,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;YAChD,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9C,GAAG,CAAC,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAE3D,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAE5F,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,MAAM,iBAAiB,GAAiB;oBACtC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;oBAC5E,MAAM,EAAE,IAAI;oBACZ,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;oBAClE,SAAS,EAAE,EAAE;iBACd,CAAC;gBACF,OAAO,IAAA,6BAAkB,EAAC,iBAAiB,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACvC,MAAM,UAAU,GAAU,EAAE,CAAC;YAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACvC,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK,EAAE,CAAC;gBACtE,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBAClF,MAAM,QAAQ,GAAQ,MAAM,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;gBACjG,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC;oBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC7E,CAAC;YAED,MAAM,iBAAiB,GAAiB;gBACtC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;gBAC1E,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC9E,MAAM,EAAE,KAAK;gBACb,SAAS,EAAE,EAAE;aACd,CAAC;YAEF,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;YAChE,OAAO,IAAA,6BAAkB,EAAC,iBAAiB,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAA,6BAAe,EAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/typescript/app/tools/upsert.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUpsertTool = registerUpsertTool;
+const types_1 = require("../types");
+const handleError_1 = require("./handleError");
+const response_1 = require("./response");
+function chunk(arr, size) {
+    const out = [];
+    for (let i = 0; i < arr.length; i += size)
+        out.push(arr.slice(i, i + size));
+    return out;
+}
+function registerUpsertTool(server, ctx) {
+    server.registerTool('upsert', {
+        description: 'Upsert Airtable records using performUpsert.fieldsToMergeOn.',
+        inputSchema: types_1.upsertInputSchema.shape,
+        outputSchema: types_1.upsertOutputSchema.shape
+    }, async (raw) => {
+        try {
+            const args = types_1.upsertInputSchema.parse(raw);
+            ctx.governance.ensureOperationAllowed('upsert');
+            ctx.governance.ensureBaseAllowed(args.baseId);
+            ctx.governance.ensureTableAllowed(args.baseId, args.table);
+            const logger = ctx.logger.child({ tool: 'upsert', baseId: args.baseId, table: args.table });
+            const matchedBy = args.performUpsert.fieldsToMergeOn;
+            if (args.dryRun) {
+                const structuredContent = {
+                    diff: { added: args.records.length, updated: 0, unchanged: 0, conflicts: 0 },
+                    dryRun: true,
+                    records: args.records.map((r) => ({ id: 'pending', fields: r.fields })),
+                    conflicts: []
+                };
+                // Note: Upsert output in PRD expects 'matchedBy' array and no conflicts property; keep consistent with docs
+                // When using strict PRD output, we can omit conflicts and include matchedBy
+                structuredContent.matchedBy = matchedBy;
+                delete structuredContent.conflicts;
+                return (0, response_1.createToolResponse)(structuredContent);
+            }
+            const chunks = chunk(args.records, 10);
+            const aggregated = [];
+            for (let i = 0; i < chunks.length; i++) {
+                const body = {
+                    records: chunks[i],
+                    typecast: args.typecast ?? false,
+                    performUpsert: { fieldsToMergeOn: matchedBy }
+                };
+                const headerKey = args.idempotencyKey ? `${args.idempotencyKey}:${i}` : undefined;
+                const response = await ctx.airtable.upsertRecords(args.baseId, args.table, body, headerKey);
+                if (Array.isArray(response?.records))
+                    aggregated.push(...response.records);
+            }
+            const structuredContent = {
+                diff: { added: 0, updated: aggregated.length, unchanged: 0 },
+                matchedBy,
+                records: aggregated.map((r) => ({ id: String(r.id), fields: r.fields || {} })),
+                dryRun: false
+            };
+            logger.info('Upsert completed', { processed: aggregated.length, matchedBy });
+            return (0, response_1.createToolResponse)(structuredContent);
+        }
+        catch (error) {
+            return (0, handleError_1.handleToolError)('upsert', error, ctx);
+        }
+    });
+}
+//# sourceMappingURL=upsert.js.map

package/dist/typescript/app/tools/upsert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.js","sourceRoot":"","sources":["../../../../src/typescript/app/tools/upsert.ts"],"names":[],"mappings":";;AAiBA,gDA4DC;AA3ED,oCAKkB;AAClB,+CAAgD;AAChD,yCAAgD;AAEhD,SAAS,KAAK,CAAI,GAAQ,EAAE,IAAY;IACtC,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC5E,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAgB,kBAAkB,CAAC,MAAiB,EAAE,GAAe;IACnE,MAAM,CAAC,YAAY,CACjB,QAAQ,EACR;QACE,WAAW,EAAE,8DAA8D;QAC3E,WAAW,EAAE,yBAAiB,CAAC,KAAY;QAC3C,YAAY,EAAE,0BAAkB,CAAC,KAAY;KAC9C,EACD,KAAK,EAAE,GAAgB,EAAE,EAAE;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,yBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC1C,GAAG,CAAC,UAAU,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;YAChD,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9C,GAAG,CAAC,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAE3D,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAC5F,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC;YAErD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,MAAM,iBAAiB,GAAiB;oBACtC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;oBAC5E,MAAM,EAAE,IAAI;oBACZ,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;oBACvE,SAAS,EAAE,EAAE;iBACP,CAAC;gBACT,4GAA4G;gBAC5G,4EAA4E;gBAC3E,iBAAyB,CAAC,SAAS,GAAG,SAAS,CAAC;gBACjD,OAAQ,iBAAyB,CAAC,SAAS,CAAC;gBAC5C,OAAO,IAAA,6BAAkB,EAAC,iBAAiB,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACvC,MAAM,UAAU,GAAU,EAAE,CAAC;YAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACvC,MAAM,IAAI,GAAG;oBACX,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;oBAClB,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK;oBAChC,aAAa,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE;iBAC9C,CAAC;gBACF,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBAClF,MAAM,QAAQ,GAAQ,MAAM,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;gBACjG,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC;oBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC7E,CAAC;YAED,MAAM,iBAAiB,GAAQ;gBAC7B,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE;gBAC5D,SAAS;gBACT,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC9E,MAAM,EAAE,KAAK;aACd,CAAC;YAEF,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;YAC7E,OAAO,IAAA,6BAAkB,EAAC,iBAAiB,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAA,6BAAe,EAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}