attio-mcp 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -17,6 +17,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Deprecated
 
+## [1.1.0] - 2025-10-06
+
+This release enhances developer experience with intelligent prompts, comprehensive tool standardization, and strengthens enterprise readiness with security hardening and validation improvements.
+
+### Added
+
+- **10 Pre-Built MCP Prompts for Common CRM Tasks** (#774) - Intelligent shortcuts that help Claude work faster and more efficiently with your Attio data
+  - **Search & Find** (5 prompts): `people_search.v1`, `company_search.v1`, `deal_search.v1`, `meeting_prep.v1`, `pipeline_health.v1`
+    - Natural language search with automatic formatting (table, JSON, or IDs)
+    - Meeting preparation summaries with recent activity context
+    - Pipeline analysis with bottleneck detection and conversion metrics
+  - **Take Actions** (4 prompts): `log_activity.v1`, `create_task.v1`, `advance_deal.v1`, `add_to_list.v1`
+    - Dry-run mode for safe preview before executing changes
+    - Consistent formatting across all write operations
+  - **Research & Qualify** (1 prompt): `qualify_lead.v1`
+    - Automated web research with BANT/CHAMP qualification frameworks
+    - Lead scoring and actionable recommendations
+  - **Key Features**:
+    - Token-efficient design (300-700 tokens per prompt)
+    - Server-side validation with helpful error messages
+    - Discoverable by Claude for smart suggestions
+    - Universal arguments for consistent behavior (format, fields_preset, verbosity)
+    - Optional telemetry and dev metadata modes for monitoring
+- **Comprehensive Tool Standardization** (#776) - Complete audit and optimization of all 33 MCP tools
+  - **Phase 0+1** (PR #785): Infrastructure and core universal tools
+    - Fixed critical MCP naming compliance (`records.search` → `records_search`) across 89 files
+    - Created `formatToolDescription` template for consistent tool documentation
+    - Built schema linter with 300-character description limit and quality checks
+    - Token baseline established: 188 tokens/tool (60% better than industry average)
+    - Standardized 19 universal tools (search, create, update, delete, get-details, etc.)
+  - **Phase 2** (PR #792): List and note tools
+    - Standardized 11 list management tools with consistent patterns
+    - Standardized 2 note operation tools (create-note, list-notes)
+    - Added `additionalProperties: false` to all schemas for strict validation
+    - Enhanced with property-level examples throughout
+  - **Phase 3** (PR #796): Workspace member tools
+    - Standardized final 3 tools (list/search/get workspace members)
+    - Completed tool discovery snapshot baseline for regression prevention
+  - **Quality Improvements**:
+    - All tools follow verb-first naming with clear boundaries
+    - Enhanced JSON schemas with proper validation and examples
+    - Token-efficient descriptions optimized for LLM routing
+    - Automated quality gates prevent future regressions
+- **Markdown Note Support** (#854, #862) - `create-note` tool now supports markdown formatting via optional `format` parameter ('plaintext' | 'markdown')
+  - Rich formatted notes with headers, lists, and emphasis
+  - Backward compatible with default plaintext format
+  - Full E2E test coverage for markdown creation
+- **Enhanced Phone Validation** (#837, #863) - Structured validation with libphonenumber-js integration
+  - Central validation helpers (`validatePhoneNumber`, `isValidPhoneNumber`, `isPossiblePhoneNumber`)
+  - Actionable `PhoneValidationError` metadata with length/country/format guidance
+  - CLI auto-configures `libphonenumber-js` to use `min` metadata bundle
+  - Server runtime exposes `PHONE_METADATA_SOURCE` for diagnostics
+  - Phone normalization failures include aggregated issue counts and newline-delimited details
+- **Intelligent Search Query Parsing** (#781) - Enhanced search capabilities for people and company resources
+  - International phone format support with multi-level domain extraction
+  - Consistent empty-filter handling across search strategies
+  - Stopword filtering and large query input protection
+- **Phone Number UX Improvements** (#798) - Comprehensive enhancements for phone number handling
+  - Inline tool help with phone format examples and E.164 normalization guidance
+  - Common update patterns documentation (`docs/examples/common-update-patterns.md`)
+  - Field verification configuration guide (`docs/configuration/field-verification.md`)
+  - Enhanced error messages for phone number validation with format examples
+  - Pre-update field validation with automatic normalization
+- Debug documentation for anonymized production placeholders used in diagnostic suites
+
+### Changed
+
+- **Phone Number Normalization** (#798, #837) - Automatic transformation from user-friendly `phone_number` to Attio's `original_phone_number` format
+  - Additional fields (label, type, extension, is_primary) preserved during normalization
+  - `AttributeAwareNormalizer` now rejects invalid phone inputs with `UniversalValidationError`
+  - Precise length/country/format guidance instead of silent pass-through
+- **Warning Suppression** (#798) - Update verification now filters out cosmetic formatting differences (e.g., `"Demo"` vs `Demo`)
+- **Search Query Parsing** (#781) - Updated `parseQuery` to support international phone formats and robust multi-level domain extraction
+  - Enhanced people/company search strategies leverage parsed tokens and phone variants
+  - Swapped unit test fixtures/docs to anonymized examples (Alex Rivera / Example Medical Group / +1 555 010 4477)
+
+### Fixed
+
+- **Query Builder Issues** (#781) - Eliminated redundant `$or` filters and US-only phone assumptions in query filter builders
+- **Token Processing** (#781) - Hardened token processing to ignore stopwords and guard against large query inputs
+- **Phone Number Field Confusion** (#798) - Users can now use `phone_number` (user-friendly) which auto-converts to `original_phone_number` (Attio API format)
+
+### Security
+
+- **XSS Prevention** (#840, #841, #845) - Comprehensive protection against reflected XSS attacks
+  - Replaced regex-based HTML sanitization with `sanitize-html` library (CodeQL alert #121)
+  - URL scheme filtering (javascript:, data:, vbscript:, file:)
+  - Hardened prompt handlers against XSS injection
+  - Security test suite with 11 test cases covering XSS, protocol injection, double-encoding, and edge cases
+- **Stack Trace Protection** (#841, #844) - Enhanced error handling to prevent sensitive information exposure
+  - Stack traces no longer exposed in client-facing errors
+  - File paths and system information sanitized
+  - Correlation IDs for debugging without exposing internals
+- **Enhanced Error Context** (#844) - Safe metadata enrichment without information leakage
+  - Field type metadata preserved in error responses
+  - Network information (localhost, ports, connection strings) sanitized
+  - Error type consistency across all response formats
+
 ## [1.0.0] - 2025-09-27
 
 🎉 **MAJOR RELEASE** - Complete Attio CRM Coverage + ChatGPT Integration
@@ -276,9 +374,10 @@ Users upgrading from v0.1.x should note:
 - Troubleshooting guides
 - Development and contribution guidelines
 
-[Unreleased]: https://github.com/kesslerio/attio-mcp-server/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.3...v1.0.0
-[0.1.3]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.2...v0.1.3
+[Unreleased]: https://github.com/kesslerio/attio-mcp-server/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/kesslerio/attio-mcp-server/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/kesslerio/attio-mcp-server/compare/v0.2.0...v1.0.0
+[0.2.0]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/kesslerio/attio-mcp-server/releases/tag/v0.1.0

package/README.md

@@ -91,6 +91,76 @@ Transform your CRM workflows with AI-powered automation. Instead of clicking thr
 - **Data Export**: JSON serialization for integrations
 - **Real-time Updates**: Live data synchronization with Attio
 
+### 💬 **Pre-Built Prompts** (10 Prompts)
+
+Intelligent shortcuts that help Claude work faster with your CRM data:
+
+- **Search & Find** (5): people_search, company_search, deal_search, meeting_prep, pipeline_health
+- **Take Actions** (4): log_activity, create_task, advance_deal, add_to_list with dry-run safety
+- **Research & Qualify** (1): qualify_lead with automated web research and BANT/CHAMP frameworks
+- **Token-efficient**: 300-700 tokens per prompt with consistent formatting
+- **Discoverable**: Claude automatically suggests relevant prompts for your tasks
+
+See [Using Out-of-the-Box Prompts](#-using-out-of-the-box-prompts) for detailed documentation and examples.
+
+## 🎯 **Using Out-of-the-Box Prompts**
+
+**NEW**: 10 pre-built MCP prompts for common Sales workflows. No setup required—just use them!
+
+### Available Prompts
+
+| Prompt               | Description                                     | Key Arguments                                    | Example                            |
+| -------------------- | ----------------------------------------------- | ------------------------------------------------ | ---------------------------------- |
+| `people_search.v1`   | Find people by title, company, territory        | `query`, `limit`, `format`                       | Find AE in fintech, SF             |
+| `company_search.v1`  | Query companies by domain, segment, plan        | `query`, `limit`, `format`                       | Find SaaS companies >100 employees |
+| `deal_search.v1`     | Filter deals by owner, stage, value, close date | `query`, `limit`, `format`                       | Find deals >$50k closing Q1        |
+| `log_activity.v1`    | Log calls/meetings/emails to records            | `target`, `type`, `summary`, `dry_run`           | Log call with Nina at Acme         |
+| `create_task.v1`     | Create tasks with natural language due dates    | `title`, `content`, `due_date`, `dry_run`        | Create task: Follow up tomorrow    |
+| `advance_deal.v1`    | Move deal to target stage with next action      | `deal`, `target_stage`, `create_task`, `dry_run` | Advance deal to "Proposal Sent"    |
+| `add_to_list.v1`     | Add records to a List by name or ID             | `records`, `list`, `dry_run`                     | Add 5 companies to Q1 Outreach     |
+| `qualify_lead.v1`    | Research lead with web + BANT/CHAMP scoring     | `target`, `framework`, `limit_web`, `dry_run`    | Qualify Acme Corp with BANT        |
+| `meeting_prep.v1`    | 360° prep: notes, tasks, deals, agenda          | `target`, `format`, `verbosity`                  | Prep for meeting with Acme CEO     |
+| `pipeline_health.v1` | Weekly snapshot: created/won/slipped + risks    | `owner`, `timeframe`, `segment`                  | Pipeline health for @me last 30d   |
+
+### Quick Examples
+
+```bash
+# Search for prospects
+"Use people_search.v1: Find Account Executives in San Francisco at fintech companies, limit 25"
+
+# Log activity
+"Use log_activity.v1: Log a call with Nina at Acme Corp, discussed Q1 pricing, create follow-up task"
+
+# Qualify a lead (with web research)
+"Use qualify_lead.v1: Qualify Acme Corp using BANT framework, dry run mode"
+
+# Meeting prep
+"Use meeting_prep.v1: Prepare for meeting with contact at Acme Corp"
+```
+
+### Universal Arguments
+
+**All read prompts** support:
+
+- `format`: `table` | `json` | `ids` (default: `table`)
+- `fields_preset`: `sales_short` | `full` (default: `sales_short`)
+- `verbosity`: `brief` | `normal` (default: `brief`)
+
+**All write prompts** support:
+
+- `dry_run`: `true` | `false` (default: `false`) - Preview changes without executing
+
+### Token Awareness Features
+
+Prompts include built-in token optimization:
+
+- **Budget Guards**: Prompts stay within token limits (people_search <500, qualify_lead <400)
+- **Dev Metadata**: Set `MCP_DEV_META=true` for token counts in responses
+- **Telemetry**: Set `PROMPT_TELEMETRY_ENABLED=true` for usage logging
+- **Configurable Limits**: Override with `MAX_PROMPT_TOKENS` environment variable
+
+For complete prompt documentation, see [docs/prompts/v1-catalog.md](./docs/prompts/v1-catalog.md).
+
 ## ⚠️ **Known Limitations & Important Notes**
 
 ### **Current Limitations**
@@ -107,7 +177,7 @@ Transform your CRM workflows with AI-powered automation. Instead of clicking thr
 ### 🤝 **OpenAI MCP Compatibility**
 
 - **Developer Mode Ready**: Every tool now publishes MCP safety annotations (`readOnlyHint`, `destructiveHint`) so OpenAI Developer Mode can auto-approve reads and request confirmation for writes.
-- **Search Compatibility Surface**: The `search` and `fetch` tools remain available for OpenAI’s baseline MCP support. Set `ATTIO_MCP_TOOL_MODE=search` to expose only these read-only endpoints (plus health checks) when Developer Mode is unavailable.
+- **Search Compatibility Surface**: The `search` and `fetch` tools remain available for OpenAI's baseline MCP support. Set `ATTIO_MCP_TOOL_MODE=search` to expose only these read-only endpoints (plus `aaa-health-check`) when Developer Mode is unavailable.
 - **Default Behaviour**: With `ATTIO_MCP_TOOL_MODE` unset, the full universal tool set is exposed—matching Claude’s experience—while OpenAI users still see the compatibility wrappers.
 - **Detailed Guide**: See [docs/chatgpt-developer-mode.md](./docs/chatgpt-developer-mode.md) for environment variables, approval flows, and validation tips.
 - **User Documentation**: See the [ChatGPT Developer Mode docs](./docs/chatgpt-developer-mode.md) for a complete walkthrough of approval flows and setup instructions.
@@ -534,6 +604,11 @@ Comprehensive documentation is available in the [docs directory](./docs):
 - [Claude Desktop Configuration](./docs/claude-desktop-config.md)
 - [Troubleshooting Guide](./TROUBLESHOOTING.md)
 
+### **Configuration**
+
+- [Warning Filter Configuration](./docs/configuration/warning-filters.md) - Understanding cosmetic vs semantic mismatches, ESLint budgets, and suppression strategies
+- [Field Verification Configuration](./docs/configuration/field-verification.md) - Field persistence verification and validation settings
+
 ### **API Reference**
 
 📋 **Implementation Status**: These docs describe the Attio API endpoints. For MCP tool usage, refer to universal tools documentation above.
@@ -669,6 +744,7 @@ See the [Testing Guide](./docs/testing.md) and [E2E Troubleshooting Guide](./doc
 npm run build          # Build TypeScript
 npm run test           # Run all tests
 npm run test:offline   # Run tests without API calls
+npm run analyze:token-footprint # Generate baseline MCP token footprint report
 npm run lint           # Check code style
 npm run check          # Full quality check
 npm run setup:test-data # Create test data for integration tests

package/dist/api/attio-client.d.ts

@@ -1,12 +1,30 @@
 /**
  * Attio API client and related utilities
+ * Unified client factory with strategy pattern for different environments
  */
 import { AxiosInstance } from 'axios';
 import { AttioAttributeSchema, AttioSelectOption, AttioStatusOption } from './types.js';
+import { ClientConfig } from './client-config.js';
 export declare const __MODULE_PATH__ = "attio-client";
 export type AttioClient = AxiosInstance;
 /**
- * Centralized authenticated Attio client builder
+ * UNIFIED CLIENT FACTORY: Support new createAttioClient(config) signature
+ *
+ * @param config - Client configuration options
+ * @returns Configured Axios instance
+ */
+export declare function createAttioClient(config?: ClientConfig): AxiosInstance;
+/**
+ * BACKWARD COMPATIBILITY: Support old createAttioClient(apiKey) signature
+ *
+ * @param apiKey - The Attio API key (legacy signature)
+ * @returns Configured Axios instance
+ */
+export declare function createAttioClient(apiKey: string): AxiosInstance;
+/**
+ * LEGACY: Centralized authenticated Attio client builder
+ *
+ * @deprecated Use createAttioClient() instead for unified interface
  * Guarantees proper Authorization header and fails fast if API key is missing
  */
 export declare function buildAttioClient(opts?: {
@@ -15,12 +33,13 @@ export declare function buildAttioClient(opts?: {
     timeoutMs?: number;
 }): AttioClient;
 /**
- * Creates and configures an Axios instance for the Attio API
+ * LEGACY: Creates and configures an Axios instance for the Attio API
  *
+ * @deprecated Use createAttioClient(config) instead for unified interface
  * @param apiKey - The Attio API key
  * @returns Configured Axios instance
  */
-export declare function createAttioClient(apiKey: string): AxiosInstance;
+export declare function createLegacyAttioClient(apiKey: string): AxiosInstance;
 /**
  * Gets the schema for a specific attribute.
  * @param objectSlug - The slug of the object (e.g., 'companies').
@@ -45,13 +64,14 @@ export declare function getStatusOptions(objectSlug: string, attributeSlug: stri
 /**
  * Initializes the global API client with the provided API key
  *
+ * @deprecated Use createAttioClient() with ClientCache instead
  * @param apiKey - The Attio API key
  */
 export declare function initializeAttioClient(apiKey: string): AxiosInstance;
 /**
- * Gets the global API client instance
+ * Gets the global API client instance - SIMPLIFIED using unified architecture
  *
- * @deprecated Use getLazyAttioClient from lazy-client.js instead for lazy initialization
+ * @deprecated Use createAttioClient() or getLazyAttioClient() instead
  * @returns The Axios instance for the Attio API
  * @throws If the API client hasn't been initialized and no API key is available
  */

package/dist/api/attio-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attio-client.d.ts","sourceRoot":"","sources":["../../src/api/attio-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAc,EAAE,aAAa,EAA6B,MAAM,OAAO,CAAC;AAIxE,OAAO,EAEL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAWpB,eAAO,MAAM,eAAe,iBAAc,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC;AAmCxC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CA2Cd;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0D/D;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAGnE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,aAAa,CAuHzE"}
+{"version":3,"file":"attio-client.d.ts","sourceRoot":"","sources":["../../src/api/attio-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAc,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAG7C,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EAGb,MAAM,oBAAoB,CAAC;AAa5B,eAAO,MAAM,eAAe,iBAAc,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC;AAmCxC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC;AACxE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC;AA8DjE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CAqBd;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0DrE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,aAAa,CAoEzE"}

package/dist/api/attio-client.js

@@ -1,11 +1,14 @@
 /**
  * Attio API client and related utilities
+ * Unified client factory with strategy pattern for different environments
  */
 import axios from 'axios';
 import { debug, error, OperationType } from '../utils/logger.js';
 import { getContextApiKey, validateApiKey } from './client-context.js';
 import { configureStandardInterceptors } from './client-interceptors.js';
-import { isAttioErrorData, } from './types.js';
+import { ClientMode, EnvironmentModeHandler, } from './client-config.js';
+import { ClientStrategyFactory } from './client-strategies.js';
+import { ClientCache } from './client-cache.js';
 // Module identification for debugging (compatible with both ESM and CJS)
 const MODULE_FILE = 'attio-client';
 // Debug loading info - use logger instead of console.log to avoid JSON parsing issues
@@ -33,54 +36,85 @@ function validateAndThrowForApiKey(apiKey, source = 'provided') {
         throw new Error(`Invalid API key: API key appears to be too short (source: ${source})`);
     }
 }
-// Global API client instance
+// LEGACY: Global API client instance - replaced by ClientCache
 let apiInstance = null;
 /**
- * Centralized authenticated Attio client builder
- * Guarantees proper Authorization header and fails fast if API key is missing
+ * Implementation of overloaded createAttioClient function
  */
-export function buildAttioClient(opts) {
-    const apiKey = opts?.apiKey ?? process.env.ATTIO_API_KEY ?? getContextApiKey() ?? '';
-    const baseURL = opts?.baseURL ?? process.env.ATTIO_BASE_URL ?? 'https://api.attio.com/v2';
-    const timeout = opts?.timeoutMs ?? 30000;
-    // Use standardized validation
-    const apiKeySource = opts?.apiKey
-        ? 'opts parameter'
+export function createAttioClient(configOrApiKey = {}) {
+    // Handle legacy string API key parameter
+    if (typeof configOrApiKey === 'string') {
+        debug('attio-client', 'createAttioClient (LEGACY string signature) - redirecting to unified version');
+        return createLegacyAttioClient(configOrApiKey);
+    }
+    // Handle new config object parameter - this is the main implementation we defined above
+    const config = configOrApiKey;
+    // Get API key from config, environment, or context
+    const apiKey = config.apiKey ?? process.env.ATTIO_API_KEY ?? getContextApiKey() ?? '';
+    // Determine the source for better error messages
+    const apiKeySource = config.apiKey
+        ? 'config parameter'
         : process.env.ATTIO_API_KEY
             ? 'environment variable'
             : 'context configuration';
+    // Validate API key using standardized validation
     validateAndThrowForApiKey(apiKey, apiKeySource);
-    const client = axios.create({ baseURL, timeout });
-    // IMPORTANT: Axios stores auth under headers.common
-    client.defaults.headers.common['Authorization'] = `Bearer ${apiKey}`;
-    client.defaults.headers.common['Accept'] = 'application/json';
-    client.defaults.headers.post['Content-Type'] = 'application/json';
-    // Response interceptor to attach serverData for error handling
-    client.interceptors.response.use((response) => response, (error) => {
-        const data = error?.response?.data;
-        if (isAttioErrorData(data)) {
-            // Mirror serverData onto the error so wrappers can preserve it
-            const attioError = error;
-            attioError.serverData = {
-                status_code: data.status_code ?? error.response?.status,
-                type: data.type,
-                code: data.code,
-                message: data.message,
-            };
-            return Promise.reject(attioError);
-        }
-        return Promise.reject(error);
+    // Get environment-aware configuration
+    const environmentConfig = EnvironmentModeHandler.getClientConfig({
+        rawE2E: config.mode === ClientMode.E2E_RAW,
     });
-    return client;
+    // Merge configurations: environment defaults < config parameter
+    const finalConfig = {
+        ...environmentConfig,
+        ...config,
+        apiKey, // Always use the validated API key
+        interceptors: {
+            ...environmentConfig.interceptors,
+            ...config.interceptors,
+        },
+    };
+    debug('attio-client', 'Creating unified client', {
+        mode: finalConfig.mode,
+        hasApiKey: Boolean(apiKey),
+        apiKeySource,
+        bypassCache: finalConfig.bypassCache,
+        baseURL: finalConfig.baseURL,
+        timeout: finalConfig.timeout,
+    });
+    // Use strategy factory to create the appropriate client
+    return ClientStrategyFactory.createClient(finalConfig);
+}
+/**
+ * LEGACY: Centralized authenticated Attio client builder
+ *
+ * @deprecated Use createAttioClient() instead for unified interface
+ * Guarantees proper Authorization header and fails fast if API key is missing
+ */
+export function buildAttioClient(opts) {
+    // Convert legacy options to new config format
+    const config = {
+        apiKey: opts?.apiKey,
+        baseURL: opts?.baseURL,
+        timeout: opts?.timeoutMs,
+        mode: ClientMode.PRODUCTION, // buildAttioClient was used for production
+    };
+    debug('attio-client', 'buildAttioClient (LEGACY) - redirecting to unified createAttioClient', {
+        hasApiKey: Boolean(opts?.apiKey),
+        baseURL: opts?.baseURL,
+        timeout: opts?.timeoutMs,
+    });
+    // Use the new unified client factory
+    return createAttioClient(config);
 }
 // Legacy getAttioClient exists below - it's already implemented
 /**
- * Creates and configures an Axios instance for the Attio API
+ * LEGACY: Creates and configures an Axios instance for the Attio API
  *
+ * @deprecated Use createAttioClient(config) instead for unified interface
  * @param apiKey - The Attio API key
  * @returns Configured Axios instance
  */
-export function createAttioClient(apiKey) {
+export function createLegacyAttioClient(apiKey) {
     // Use standardized validation
     validateAndThrowForApiKey(apiKey, 'parameter');
     // Log client initialization for debugging (without exposing sensitive data)
@@ -181,114 +215,74 @@ export async function getStatusOptions(objectSlug, attributeSlug) {
 /**
  * Initializes the global API client with the provided API key
  *
+ * @deprecated Use createAttioClient() with ClientCache instead
  * @param apiKey - The Attio API key
  */
 export function initializeAttioClient(apiKey) {
-    apiInstance = createAttioClient(apiKey);
+    apiInstance = createAttioClient(apiKey); // This will use the legacy signature
+    ClientCache.setInstance(apiInstance);
     return apiInstance;
 }
 /**
- * Gets the global API client instance
+ * Gets the global API client instance - SIMPLIFIED using unified architecture
  *
- * @deprecated Use getLazyAttioClient from lazy-client.js instead for lazy initialization
+ * @deprecated Use createAttioClient() or getLazyAttioClient() instead
  * @returns The Axios instance for the Attio API
  * @throws If the API client hasn't been initialized and no API key is available
  */
 export function getAttioClient(opts) {
-    const isE2E = process.env.E2E_MODE === 'true';
-    const useMocks = process.env.USE_MOCK_DATA === 'true' || process.env.OFFLINE_MODE === 'true';
-    const forceReal = isE2E && !useMocks;
-    // Debug log the client mode selection
-    debug('attio-client', 'Client mode selection', {
-        isE2E,
-        useMocks,
-        forceReal,
+    debug('attio-client', 'getAttioClient (LEGACY) called', {
         rawE2E: opts?.rawE2E,
-        NODE_ENV: process.env.NODE_ENV,
+        hasCache: ClientCache.hasInstance(),
         E2E_MODE: process.env.E2E_MODE,
         USE_MOCK_DATA: process.env.USE_MOCK_DATA,
-        OFFLINE_MODE: process.env.OFFLINE_MODE,
-    });
-    debug('AttioClient', 'mode', {
-        isE2E,
-        useMocks,
-        forceReal,
-        rawE2E: opts?.rawE2E,
-        NODE_ENV: process.env.NODE_ENV,
     });
-    // If we need the raw E2E client, do NOT reuse any cached instance
-    if (forceReal || opts?.rawE2E) {
-        debug('AttioClient', 'E2E MODE: bypassing cache, creating fresh client');
-        apiInstance = null; // guarantee we don't return a stale client
-        debug('AttioClient', 'Creating raw E2E client', {
-            forceReal,
-            rawE2E: opts?.rawE2E,
-            isE2E,
-            useMocks,
-        });
-        debug('AttioClient', 'Creating raw E2E client with http adapter');
-        // Create a fresh client instance with no interceptors for E2E
-        const apiKey = process.env.ATTIO_API_KEY || getContextApiKey();
-        const apiKeySource = process.env.ATTIO_API_KEY
-            ? 'environment variable'
-            : 'context configuration';
-        validateAndThrowForApiKey(apiKey, `${apiKeySource} (E2E mode)`);
-        const baseURL = (process.env.ATTIO_BASE_URL || 'https://api.attio.com/v2').replace(/\/+$/, '');
-        const rawClient = axios.create({
-            baseURL,
-            timeout: 20000,
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                'Content-Type': 'application/json',
-                Accept: 'application/json',
-            },
-            // do NOT transform the response; we want raw server JSON
-            transformResponse: [
-                (data) => {
-                    try {
-                        return JSON.parse(data);
-                    }
-                    catch {
-                        return data;
-                    }
-                },
-            ],
-            validateStatus: (s) => s >= 200 && s < 300, // don't swallow 4xx/5xx
-        });
-        // Configure E2E interceptors using centralized module
-        debug('attio-client', 'Configuring E2E raw client interceptors', {
-            baseURL,
-        });
-        configureStandardInterceptors(rawClient, {
-            prefix: 'E2E-RAW',
-            enableDiagnostics: true,
-            enableErrorHandling: true,
-        });
-        debug('AttioClient', 'Returning E2E raw client');
-        return rawClient;
+    // Check if we should bypass cache and create fresh client
+    const shouldBypassCache = EnvironmentModeHandler.shouldUseRealClient() || opts?.rawE2E;
+    if (shouldBypassCache) {
+        debug('attio-client', 'Bypassing cache - creating fresh client');
+        // Clear cache to ensure fresh client
+        ClientCache.clearInstance();
+        apiInstance = null;
+        // Determine mode based on rawE2E option
+        const mode = opts?.rawE2E
+            ? ClientMode.E2E_RAW
+            : EnvironmentModeHandler.determineMode();
+        const config = {
+            mode,
+            bypassCache: true,
+        };
+        const client = createAttioClient(config);
+        debug('attio-client', 'Returning fresh E2E client');
+        return client;
     }
-    if (!apiInstance) {
-        // Fallback: try to initialize from environment variable
-        const apiKey = process.env.ATTIO_API_KEY || getContextApiKey();
-        const apiKeySource = process.env.ATTIO_API_KEY
-            ? 'environment variable'
-            : 'context configuration';
-        try {
-            validateAndThrowForApiKey(apiKey, apiKeySource);
-            debug('attio-client', `Creating default client (auto-init from ${apiKeySource})`);
-            debug('attio-client', `API client not initialized, auto-initializing from ${apiKeySource}`, undefined, 'initialization', OperationType.SYSTEM);
-            apiInstance = createAttioClient(apiKey);
-        }
-        catch (validationError) {
-            const errorMessage = validationError instanceof Error
-                ? validationError.message
-                : String(validationError);
-            throw new Error(`API client not initialized and no valid API key available. ${errorMessage} Call initializeAttioClient first or set ATTIO_API_KEY environment variable.`);
-        }
+    // Check cache first
+    const cachedClient = ClientCache.getInstance();
+    if (cachedClient) {
+        debug('attio-client', 'Returning cached client from ClientCache');
+        return cachedClient;
     }
-    else {
-        debug('attio-client', 'Returning cached default client');
+    // Check legacy cache
+    if (apiInstance) {
+        debug('attio-client', 'Returning cached client from legacy apiInstance');
+        return apiInstance;
+    }
+    // No cached client - create new one
+    debug('attio-client', 'No cached client found - creating new client');
+    try {
+        const config = {}; // Use environment defaults
+        const client = createAttioClient(config);
+        // Cache the client in both new and legacy systems
+        ClientCache.setInstance(client);
+        apiInstance = client;
+        debug('attio-client', 'Created and cached new client');
+        return client;
+    }
+    catch (validationError) {
+        const errorMessage = validationError instanceof Error
+            ? validationError.message
+            : String(validationError);
+        throw new Error(`API client not initialized and no valid API key available. ${errorMessage} Call initializeAttioClient first or set ATTIO_API_KEY environment variable.`);
     }
-    return apiInstance;
 }
 //# sourceMappingURL=attio-client.js.map