@iflow-mcp/attio-mcp 1.3.6

package/dist/utils/token-footprint-analyzer.js

@@ -0,0 +1,221 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getToolsListPayload, getPromptsListPayload, } from '../utils/mcp-discovery.js';
+import { countJsonTokens, getCountModel } from '../utils/token-count.js';
+import { TOOL_DEFINITIONS } from '../handlers/tools/registry.js';
+const DEFAULT_THRESHOLD = 250;
+const DEFAULT_TOP_N = 10;
+const CONTEXT_WINDOWS = {
+    '32k': 32_000,
+    '128k': 128_000,
+    '200k': 200_000,
+};
+function resolveCategoryKey(rawKey) {
+    if (!rawKey) {
+        return 'unclassified';
+    }
+    return rawKey.toLowerCase();
+}
+function buildToolCategoryIndex() {
+    const index = {};
+    for (const [categoryKey, toolDefs] of Object.entries(TOOL_DEFINITIONS)) {
+        if (!toolDefs)
+            continue;
+        const category = resolveCategoryKey(categoryKey);
+        if (Array.isArray(toolDefs)) {
+            for (const tool of toolDefs) {
+                index[tool.name] = category;
+            }
+        }
+        else if (typeof toolDefs === 'object') {
+            for (const tool of Object.values(toolDefs)) {
+                index[tool.name] = category;
+            }
+        }
+    }
+    return index;
+}
+function mapToolsToCategories(tools, index) {
+    return tools.map((tool) => ({
+        tool,
+        category: index[tool.name] ?? 'unclassified',
+    }));
+}
+async function analyzeTools(toolsPayload, heavyThreshold, model) {
+    const categoryIndex = buildToolCategoryIndex();
+    const categorised = mapToolsToCategories(toolsPayload.tools, categoryIndex);
+    const categoryMap = {};
+    const items = [];
+    const payloadTokens = await countJsonTokens({ tools: toolsPayload.tools }, model);
+    for (const entry of categorised) {
+        const tokens = await countJsonTokens(entry.tool, model);
+        const category = entry.category;
+        if (!categoryMap[category]) {
+            categoryMap[category] = { tokens: 0, items: [] };
+        }
+        categoryMap[category].tokens += tokens;
+        categoryMap[category].items.push(entry.tool.name);
+        items.push({
+            type: 'tool',
+            name: entry.tool.name,
+            tokens,
+            category,
+            isHeavy: tokens >= heavyThreshold,
+        });
+    }
+    items.sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+    return {
+        totalTokens: payloadTokens,
+        count: items.length,
+        byCategory: categoryMap,
+        items,
+    };
+}
+async function analyzePrompts(promptsPayload, heavyThreshold, model) {
+    const categoryMap = {};
+    const items = [];
+    const payloadTokens = await countJsonTokens({ prompts: promptsPayload.prompts }, model);
+    for (const prompt of promptsPayload.prompts) {
+        const tokens = await countJsonTokens(prompt, model);
+        const category = resolveCategoryKey(prompt.category);
+        if (!categoryMap[category]) {
+            categoryMap[category] = { tokens: 0, items: [] };
+        }
+        categoryMap[category].tokens += tokens;
+        categoryMap[category].items.push(prompt.id);
+        items.push({
+            type: 'prompt',
+            name: prompt.id,
+            tokens,
+            category,
+            isHeavy: tokens >= heavyThreshold,
+        });
+    }
+    items.sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+    return {
+        totalTokens: payloadTokens,
+        count: items.length,
+        byCategory: categoryMap,
+        items,
+    };
+}
+function calculatePercentages(totalTokens) {
+    const result = {
+        '32k': 0,
+        '128k': 0,
+        '200k': 0,
+    };
+    for (const [label, size] of Object.entries(CONTEXT_WINDOWS)) {
+        result[label] = Number(((totalTokens / size) * 100).toFixed(2));
+    }
+    return result;
+}
+function selectTopItems(items, topN) {
+    return items.slice(0, topN);
+}
+export async function analyzeBaselineTokenFootprint(options = {}) {
+    const model = options.model || getCountModel();
+    const heavyThreshold = options.heavyThreshold ?? DEFAULT_THRESHOLD;
+    const topN = options.topN ?? DEFAULT_TOP_N;
+    const toolsPayload = options.toolsPayload ?? getToolsListPayload();
+    const promptsPayload = options.promptsPayload ?? getPromptsListPayload();
+    const tools = await analyzeTools(toolsPayload, heavyThreshold, model);
+    const prompts = await analyzePrompts(promptsPayload, heavyThreshold, model);
+    const totalTokens = tools.totalTokens + prompts.totalTokens;
+    const heaviestItems = selectTopItems([...tools.items, ...prompts.items].sort((a, b) => b.tokens - a.tokens), topN);
+    return {
+        timestamp: new Date().toISOString(),
+        model,
+        baselineContextLoad: {
+            totalTokens,
+            tools,
+            prompts,
+        },
+        contextWindowPercentages: calculatePercentages(totalTokens),
+        heaviestItems,
+        threshold: heavyThreshold,
+    };
+}
+export function renderMarkdownReport(report) {
+    const lines = [];
+    lines.push('# Attio MCP Token Footprint Report');
+    lines.push('');
+    lines.push(`Generated: ${report.timestamp}`);
+    lines.push(`Model: ${report.model}`);
+    lines.push('');
+    lines.push('## Baseline Context Load');
+    lines.push('');
+    const total = report.baselineContextLoad.totalTokens;
+    const toolTotal = report.baselineContextLoad.tools.totalTokens;
+    const promptTotal = report.baselineContextLoad.prompts.totalTokens;
+    lines.push(`- Total tokens: ${total}`);
+    lines.push(`- Tools: ${toolTotal}`);
+    lines.push(`- Prompts: ${promptTotal}`);
+    lines.push('');
+    lines.push('### Context Window Impact');
+    lines.push('');
+    for (const [label, percentage] of Object.entries(report.contextWindowPercentages)) {
+        lines.push(`- ${label}: ${percentage}%`);
+    }
+    lines.push('');
+    lines.push('### Tools by Category');
+    lines.push('');
+    lines.push('| Category | Tokens | Tool Count |');
+    lines.push('|----------|--------|------------|');
+    for (const [category, data] of Object.entries(report.baselineContextLoad.tools.byCategory)) {
+        lines.push(`| ${category} | ${data.tokens} | ${data.items.length} |`);
+    }
+    lines.push('');
+    lines.push('### Prompts by Category');
+    lines.push('');
+    lines.push('| Category | Tokens | Prompt Count |');
+    lines.push('|----------|--------|--------------|');
+    for (const [category, data] of Object.entries(report.baselineContextLoad.prompts.byCategory)) {
+        lines.push(`| ${category} | ${data.tokens} | ${data.items.length} |`);
+    }
+    lines.push('');
+    lines.push('### Top Heavy Items');
+    lines.push('');
+    lines.push('| Type | Name | Tokens | Category | Flagged |');
+    lines.push('|------|------|--------|----------|---------|');
+    for (const item of report.heaviestItems) {
+        lines.push(`| ${item.type} | ${item.name} | ${item.tokens} | ${item.category} | ${item.isHeavy ? '⚠️' : ''} |`);
+    }
+    return lines.join('\n');
+}
+export function writeReportFiles(report, directory = '/tmp') {
+    const timestamp = report.timestamp.replace(/[:.]/g, '-');
+    const baseName = `attio-mcp-token-footprint-${timestamp}`;
+    const jsonPath = path.join(directory, `${baseName}.json`);
+    const markdownPath = path.join(directory, `${baseName}.md`);
+    fs.writeFileSync(jsonPath, JSON.stringify(report, null, 2), 'utf8');
+    fs.writeFileSync(markdownPath, renderMarkdownReport(report), 'utf8');
+    return { jsonPath, markdownPath };
+}
+export function formatConsoleSummary(report, maxItems = 5) {
+    const lines = [];
+    const { totalTokens, tools, prompts } = report.baselineContextLoad;
+    lines.push('');
+    lines.push('Attio MCP Baseline Token Footprint');
+    lines.push('----------------------------------');
+    lines.push(`Total tokens: ${totalTokens}`);
+    lines.push(`Tools: ${tools.totalTokens} tokens across ${tools.count} definitions`);
+    lines.push(`Prompts: ${prompts.totalTokens} tokens across ${prompts.count} definitions`);
+    lines.push('');
+    lines.push('Context window impact:');
+    for (const [label, percentage] of Object.entries(report.contextWindowPercentages)) {
+        lines.push(`  - ${label}: ${percentage}%`);
+    }
+    lines.push('');
+    lines.push('Top items:');
+    for (const item of report.heaviestItems.slice(0, maxItems)) {
+        const flag = item.isHeavy ? ' ⚠️' : '';
+        lines.push(`  - ${item.type} :: ${item.name} :: ${item.tokens} tokens (category: ${item.category})${flag}`);
+    }
+    return lines.join('\n');
+}
+// Helper exposed for unit testing with fixtures
+export async function buildPromptSummary(prompts, heavyThreshold, model) {
+    return analyzePrompts({ prompts }, heavyThreshold, model);
+}
+//# sourceMappingURL=token-footprint-analyzer.js.map

package/dist/utils/token-footprint-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-footprint-analyzer.js","sourceRoot":"","sources":["../../src/utils/token-footprint-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAOxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AA4ChE,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAC9B,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,eAAe,GAA4C;IAC/D,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,OAAO;IACf,MAAM,EAAE,OAAO;CAChB,CAAC;AAEF,SAAS,kBAAkB,CAAC,MAAc;IACxC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,sBAAsB;IAC7B,MAAM,KAAK,GAA2B,EAAE,CAAC;IAEzC,KAAK,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAClD,gBAA2C,CAC5C,EAAE,CAAC;QACF,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;QAEjD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,KAAK,MAAM,IAAI,IAAI,QAAkB,EAAE,CAAC;gBACtC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;YAC9B,CAAC;QACH,CAAC;aAAM,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACxC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,QAAgC,CAAC,EAAE,CAAC;gBACnE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAOD,SAAS,oBAAoB,CAC3B,KAAa,EACb,KAA6B;IAE7B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI;QACJ,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,cAAc;KAC7C,CAAC,CAAC,CAAC;AACN,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,YAA8B,EAC9B,cAAsB,EACtB,KAAa;IAEb,MAAM,aAAa,GAAG,sBAAsB,EAAE,CAAC;IAC/C,MAAM,WAAW,GAAG,oBAAoB,CAAC,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAE5E,MAAM,WAAW,GAAwD,EAAE,CAAC;IAC5E,MAAM,KAAK,GAAyB,EAAE,CAAC;IACvC,MAAM,aAAa,GAAG,MAAM,eAAe,CACzC,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,EAC7B,KAAK,CACN,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACxD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAEhC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3B,WAAW,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QACnD,CAAC;QAED,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC;QACvC,WAAW,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAElD,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI;YACrB,MAAM;YACN,QAAQ;YACR,OAAO,EAAE,MAAM,IAAI,cAAc;SAClC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE1E,OAAO;QACL,WAAW,EAAE,aAAa;QAC1B,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,UAAU,EAAE,WAAW;QACvB,KAAK;KACN,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,cAAkC,EAClC,cAAsB,EACtB,KAAa;IAEb,MAAM,WAAW,GAAwD,EAAE,CAAC;IAC5E,MAAM,KAAK,GAAyB,EAAE,CAAC;IACvC,MAAM,aAAa,GAAG,MAAM,eAAe,CACzC,EAAE,OAAO,EAAE,cAAc,CAAC,OAAO,EAAE,EACnC,KAAK,CACN,CAAC;IAEF,KAAK,MAAM,MAAM,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAErD,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3B,WAAW,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QACnD,CAAC;QAED,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC;QACvC,WAAW,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAE5C,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,MAAM,CAAC,EAAE;YACf,MAAM;YACN,QAAQ;YACR,OAAO,EAAE,MAAM,IAAI,cAAc;SAClC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE1E,OAAO;QACL,WAAW,EAAE,aAAa;QAC1B,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,UAAU,EAAE,WAAW;QACvB,KAAK;KACN,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,WAAmB;IAEnB,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,CAAC;QACT,MAAM,EAAE,CAAC;KACiC,CAAC;IAE7C,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC5D,MAAM,CAAC,KAA4B,CAAC,GAAG,MAAM,CAC3C,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CACxC,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CACrB,KAA2B,EAC3B,IAAY;IAEZ,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,UAA0B,EAAE;IAE5B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,EAAE,CAAC;IAC/C,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,iBAAiB,CAAC;IACnE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,aAAa,CAAC;IAE3C,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,mBAAmB,EAAE,CAAC;IACnE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,qBAAqB,EAAE,CAAC;IAEzE,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,YAAY,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,cAAc,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;IAE5E,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAE5D,MAAM,aAAa,GAAG,cAAc,CAClC,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EACtE,IAAI,CACL,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK;QACL,mBAAmB,EAAE;YACnB,WAAW;YACX,KAAK;YACL,OAAO;SACR;QACD,wBAAwB,EAAE,oBAAoB,CAAC,WAAW,CAAC;QAC3D,aAAa;QACb,SAAS,EAAE,cAAc;KAC1B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAC/D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACrC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,MAAM,KAAK,GAAG,MAAM,CAAC,mBAAmB,CAAC,WAAW,CAAC;IACrD,MAAM,SAAS,GAAG,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,WAAW,CAAC;IAC/D,MAAM,WAAW,GAAG,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,WAAW,CAAC;IAEnE,KAAK,CAAC,IAAI,CAAC,mBAAmB,KAAK,EAAE,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,YAAY,SAAS,EAAE,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,cAAc,WAAW,EAAE,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAC9C,MAAM,CAAC,wBAAwB,CAChC,EAAE,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,UAAU,GAAG,CAAC,CAAC;IAC3C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAC3C,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAC5C,EAAE,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,MAAM,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IACxE,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACnD,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAC3C,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,UAAU,CAC9C,EAAE,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,MAAM,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IACxE,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC5D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CACR,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CACpG,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAOD,MAAM,UAAU,gBAAgB,CAC9B,MAA4B,EAC5B,YAAoB,MAAM;IAE1B,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,6BAA6B,SAAS,EAAE,CAAC;IAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,QAAQ,OAAO,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,QAAQ,KAAK,CAAC,CAAC;IAE5D,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpE,EAAE,CAAC,aAAa,CAAC,YAAY,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAErE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,MAA4B,EAC5B,WAAmB,CAAC;IAEpB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC;IAEnE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,iBAAiB,WAAW,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CACR,UAAU,KAAK,CAAC,WAAW,kBAAkB,KAAK,CAAC,KAAK,cAAc,CACvE,CAAC;IACF,KAAK,CAAC,IAAI,CACR,YAAY,OAAO,CAAC,WAAW,kBAAkB,OAAO,CAAC,KAAK,cAAc,CAC7E,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;IACrC,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAC9C,MAAM,CAAC,wBAAwB,CAChC,EAAE,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,UAAU,GAAG,CAAC,CAAC;IAC7C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CACR,OAAO,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,sBAAsB,IAAI,CAAC,QAAQ,IAAI,IAAI,EAAE,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAwB,EACxB,cAAsB,EACtB,KAAa;IAEb,OAAO,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;AAC5D,CAAC"}

package/dist/utils/ttl-cache.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Simple TTL (Time-To-Live) Cache Implementation
+ *
+ * Provides automatic expiration of cached entries after a specified duration.
+ * Used for workspace-level caching of attribute metadata to reduce API calls
+ * while preventing stale data issues.
+ */
+export interface TTLCacheEntry<T> {
+    value: T;
+    expiresAt: number;
+}
+export declare class TTLCache<K, V> {
+    private cache;
+    private readonly ttlMs;
+    private cleanupInterval?;
+    /**
+     * Creates a new TTL cache
+     *
+     * @param ttlMs - Time-to-live in milliseconds (default: 15 minutes)
+     * @param cleanupIntervalMs - How often to check for expired entries (default: 5 minutes)
+     */
+    constructor(ttlMs?: number, cleanupIntervalMs?: number);
+    /**
+     * Gets a value from the cache
+     *
+     * @param key - The cache key
+     * @returns The cached value, or undefined if not found or expired
+     */
+    get(key: K): V | undefined;
+    /**
+     * Sets a value in the cache with TTL
+     *
+     * @param key - The cache key
+     * @param value - The value to cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * Checks if a key exists and is not expired
+     *
+     * @param key - The cache key
+     * @returns True if the key exists and is not expired
+     */
+    has(key: K): boolean;
+    /**
+     * Removes a specific key from the cache
+     *
+     * @param key - The cache key to remove
+     */
+    delete(key: K): boolean;
+    /**
+     * Clears all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Returns the number of entries in the cache (including expired ones)
+     */
+    get size(): number;
+    /**
+     * Removes expired entries from the cache
+     * Called automatically by cleanup interval
+     */
+    private cleanup;
+    /**
+     * Stops the cleanup interval
+     * Should be called when the cache is no longer needed
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=ttl-cache.d.ts.map

package/dist/utils/ttl-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/utils/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;IACxB,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAiB;IAEzC;;;;;OAKG;gBAED,KAAK,GAAE,MAAuB,EAC9B,iBAAiB,GAAE,MAAsB;IAgB3C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAgB1B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAO3B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,OAAO,CAAC,OAAO;IASf;;;OAGG;IACH,OAAO,IAAI,IAAI;CAOhB"}

package/dist/utils/ttl-cache.js

@@ -0,0 +1,113 @@
+/**
+ * Simple TTL (Time-To-Live) Cache Implementation
+ *
+ * Provides automatic expiration of cached entries after a specified duration.
+ * Used for workspace-level caching of attribute metadata to reduce API calls
+ * while preventing stale data issues.
+ */
+export class TTLCache {
+    cache;
+    ttlMs;
+    cleanupInterval;
+    /**
+     * Creates a new TTL cache
+     *
+     * @param ttlMs - Time-to-live in milliseconds (default: 15 minutes)
+     * @param cleanupIntervalMs - How often to check for expired entries (default: 5 minutes)
+     */
+    constructor(ttlMs = 15 * 60 * 1000, cleanupIntervalMs = 5 * 60 * 1000) {
+        this.cache = new Map();
+        this.ttlMs = ttlMs;
+        // Start periodic cleanup
+        this.cleanupInterval = setInterval(() => {
+            this.cleanup();
+        }, cleanupIntervalMs);
+        // Ensure cleanup interval doesn't keep process alive
+        if (this.cleanupInterval.unref) {
+            this.cleanupInterval.unref();
+        }
+    }
+    /**
+     * Gets a value from the cache
+     *
+     * @param key - The cache key
+     * @returns The cached value, or undefined if not found or expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Sets a value in the cache with TTL
+     *
+     * @param key - The cache key
+     * @param value - The value to cache
+     */
+    set(key, value) {
+        this.cache.set(key, {
+            value,
+            expiresAt: Date.now() + this.ttlMs,
+        });
+    }
+    /**
+     * Checks if a key exists and is not expired
+     *
+     * @param key - The cache key
+     * @returns True if the key exists and is not expired
+     */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    /**
+     * Removes a specific key from the cache
+     *
+     * @param key - The cache key to remove
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clears all entries from the cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Returns the number of entries in the cache (including expired ones)
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Removes expired entries from the cache
+     * Called automatically by cleanup interval
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Stops the cleanup interval
+     * Should be called when the cache is no longer needed
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+        this.clear();
+    }
+}
+//# sourceMappingURL=ttl-cache.js.map

package/dist/utils/ttl-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/utils/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,MAAM,OAAO,QAAQ;IACX,KAAK,CAA2B;IACvB,KAAK,CAAS;IACvB,eAAe,CAAkB;IAEzC;;;;;OAKG;IACH,YACE,QAAgB,EAAE,GAAG,EAAE,GAAG,IAAI,EAC9B,oBAA4B,CAAC,GAAG,EAAE,GAAG,IAAI;QAEzC,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,yBAAyB;QACzB,IAAI,CAAC,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE;YACtC,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC,EAAE,iBAAiB,CAAC,CAAC;QAEtB,qDAAqD;QACrD,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC/B,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAM;QACR,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAM,EAAE,KAAQ;QAClB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;SACnC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAM;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,GAAM;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;OAGG;IACK,OAAO;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;gBAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YACpC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;CACF"}

package/dist/utils/type-extraction.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Type-safe utility functions for extracting nested values from complex object structures
+ *
+ * **Issue #679 Implementation:**
+ * Addresses complex nested type assertions that appear throughout the services directory
+ * and hurt code readability. Provides clean, type-safe alternatives to patterns like:
+ * `((rec as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id`
+ *
+ * **Performance Notes:**
+ * - Functions are optimized for readability over raw performance
+ * - For hot paths with frequent access, consider caching results
+ * - Debug logging only active in development mode for performance
+ */
+/**
+ * Safely extracts record_id from nested object structures
+ * Handles the common pattern: obj?.id?.record_id with proper type safety
+ *
+ * @param obj - Object that may contain nested id.record_id structure
+ * @returns The record_id string or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const recordId = ((rec as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id as string;
+ *
+ * // After (clean):
+ * const recordId = safeExtractRecordId(rec);
+ * if (recordId) {
+ *   // Use recordId safely
+ * }
+ */
+export declare function safeExtractRecordId(obj: unknown): string | undefined;
+/**
+ * Safely extracts the id object from a record
+ * Handles the pattern: obj?.id with proper type safety
+ *
+ * @param obj - Object that may contain an id field
+ * @returns The id object or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const idObj = (rec as Record<string, unknown>)?.id as Record<string, unknown>;
+ *
+ * // After (clean):
+ * const idObj = safeExtractIdObject(rec);
+ * if (idObj?.record_id) {
+ *   // Use idObj safely
+ * }
+ */
+export declare function safeExtractIdObject(obj: unknown): Record<string, unknown> | undefined;
+/**
+ * Safely extracts nested property values with type safety
+ * Handles patterns like: obj?.values?.propertyName with multiple levels
+ *
+ * @param obj - Object to extract from
+ * @param path - Array of property names to traverse
+ * @returns The extracted value or undefined if path is invalid
+ *
+ * @example
+ * // Before (complex):
+ * // const name = ((rec as Record<string, unknown>)?.values as Record<string, unknown>)?.name;
+ *
+ * // After (clean with type inference):
+ * const name = safeExtractNestedValue<string>(rec, 'values', 'name');
+ * const domains = safeExtractNestedValue<string[]>(rec, 'values', 'domains');
+ * const count = safeExtractNestedValue<number>(rec, 'data', 'count');
+ *
+ * // Generic type parameter provides better IntelliSense and type safety
+ */
+export declare function safeExtractNestedValue<T = unknown>(obj: unknown, ...path: string[]): T | undefined;
+/**
+ * Safely extracts values object from a record
+ * Handles the pattern: obj?.values with proper type safety
+ *
+ * @param obj - Object that may contain a values field
+ * @returns The values object or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const values = (rec as Record<string, unknown>)?.values as Record<string, unknown>;
+ *
+ * // After (clean):
+ * const values = safeExtractValuesObject(rec);
+ * if (values?.name) {
+ *   // Use values safely
+ * }
+ */
+export declare function safeExtractValuesObject(obj: unknown): Record<string, unknown> | undefined;
+/**
+ * Safely checks if a record has a valid record_id
+ * Combines existence check with type safety for common validation pattern
+ *
+ * @param obj - Object to check
+ * @returns True if object has a valid string record_id
+ *
+ * @example
+ * // Before (complex):
+ * // const isValid = !!(((record as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id);
+ *
+ * // After (clean):
+ * const isValid = hasValidRecordId(record);
+ * if (!isValid) {
+ *   // Handle missing record_id
+ * }
+ */
+export declare function hasValidRecordId(obj: unknown): boolean;
+/**
+ * Type guard to check if an object looks like an Attio record
+ * Provides runtime type checking for record-like structures
+ *
+ * @param obj - Object to check
+ * @returns True if object has the expected record structure
+ *
+ * @example
+ * if (isAttioRecordLike(response)) {
+ *   const recordId = safeExtractRecordId(response);
+ *   // TypeScript knows this is safe
+ * }
+ */
+export declare function isAttioRecordLike(obj: unknown): obj is Record<string, unknown>;
+/**
+ * Safely extracts an array from a nested object path with type safety
+ * Handles the common pattern: Array.isArray(obj?.values?.field) && obj.values.field
+ *
+ * @param obj - Object to extract from
+ * @param path - Array of property names to traverse to the array field
+ * @returns The array or undefined if path is invalid or not an array
+ *
+ * @example
+ * // Before (complex):
+ * // const domains = Array.isArray(record.values?.domains) ? record.values.domains : undefined;
+ *
+ * // After (clean):
+ * const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * const tags = safeExtractArray<string>(record, 'data', 'tags');
+ */
+export declare function safeExtractArray<T = unknown>(obj: unknown, ...path: string[]): T[] | undefined;
+/**
+ * Type guard to check if a nested field is an array with optional type checking
+ * Provides runtime validation for array fields in nested objects
+ *
+ * @param obj - Object to check
+ * @param path - Array of property names to traverse to the field
+ * @returns True if the nested field is an array
+ *
+ * @example
+ * // Before (complex):
+ * // if (Array.isArray(((record as Record<string, unknown>)?.values as Record<string, unknown>)?.domains)) {
+ *
+ * // After (clean):
+ * if (safeIsArrayField(record, 'values', 'domains')) {
+ *   // TypeScript knows domains is an array
+ *   const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * }
+ */
+export declare function safeIsArrayField(obj: unknown, ...path: string[]): boolean;
+/**
+ * Safely extracts a string value from nested object with fallback
+ * Common pattern for extracting string fields with default values
+ *
+ * @param obj - Object to extract from
+ * @param fallback - Default value if extraction fails
+ * @param path - Array of property names to traverse
+ * @returns The string value or fallback
+ *
+ * @example
+ * const name = safeExtractString(record, 'Unknown', 'values', 'name');
+ * const title = safeExtractString(task, 'Untitled', 'data', 'title');
+ */
+export declare function safeExtractString(obj: unknown, fallback: string, ...path: string[]): string;
+/**
+ * Safely extracts a number value from nested object with fallback
+ * Common pattern for extracting numeric fields with default values
+ *
+ * @param obj - Object to extract from
+ * @param fallback - Default value if extraction fails
+ * @param path - Array of property names to traverse
+ * @returns The number value or fallback
+ *
+ * @example
+ * const count = safeExtractNumber(record, 0, 'data', 'count');
+ * const priority = safeExtractNumber(task, 1, 'values', 'priority');
+ */
+export declare function safeExtractNumber(obj: unknown, fallback: number, ...path: string[]): number;
+/**
+ * Enhanced type guard for validating object structure with specific properties
+ * Provides runtime validation for complex object structures
+ *
+ * @param obj - Object to validate
+ * @param requiredProps - Array of required property names
+ * @returns True if object has all required properties
+ *
+ * @example
+ * if (hasRequiredProperties(record, ['id', 'values'])) {
+ *   // TypeScript knows record has id and values properties
+ *   const recordId = safeExtractRecordId(record);
+ * }
+ */
+export declare function hasRequiredProperties(obj: unknown, requiredProps: string[]): obj is Record<string, unknown>;
+/**
+ * Type guard to check if a value is a non-empty string
+ * Useful for validating string fields that shouldn't be empty
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-empty string
+ *
+ * @example
+ * const name = safeExtractString(record, '', 'values', 'name');
+ * if (isNonEmptyString(name)) {
+ *   // TypeScript knows name is a non-empty string
+ *   console.log(name.toUpperCase());
+ * }
+ */
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a valid array with minimum length
+ * Provides runtime validation for arrays with length constraints
+ *
+ * @param value - Value to check
+ * @param minLength - Minimum required length (default: 1)
+ * @returns True if value is an array with at least minLength items
+ *
+ * @example
+ * const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * if (isValidArray(domains, 1)) {
+ *   // TypeScript knows domains is a non-empty array
+ *   domains.forEach(domain => console.log(domain));
+ * }
+ */
+export declare function isValidArray<T>(value: unknown, minLength?: number): value is T[];
+/**
+ * Advanced type guard for Attio record validation with strict checking
+ * Validates that an object has the complete Attio record structure
+ *
+ * @param obj - Object to validate
+ * @returns True if object is a complete Attio record
+ *
+ * @example
+ * if (isCompleteAttioRecord(response)) {
+ *   // TypeScript knows this has id.record_id and values
+ *   const recordId = safeExtractRecordId(response); // guaranteed to be string
+ *   const values = safeExtractValuesObject(response); // guaranteed to be object
+ * }
+ */
+export declare function isCompleteAttioRecord(obj: unknown): obj is {
+    id: {
+        record_id: string;
+        [key: string]: unknown;
+    };
+    values: Record<string, unknown>;
+    [key: string]: unknown;
+};
+//# sourceMappingURL=type-extraction.d.ts.map