@operor/testing 0.1.0

package/API_VALIDATION.md

@@ -0,0 +1,572 @@
+# API Validation Report
+
+**Generated:** 2026-02-15
+**Purpose:** Validate integration API usage against current documentation (2025-2026)
+
+---
+
+## Executive Summary
+
+This report validates the API usage patterns across all integrations in Operor against current vendor documentation. Key findings:
+
+- **Shopify**: CRITICAL - Using deprecated REST API (2024-01) that reached EOL on 2025-01-01. Price Rules API deprecated. Migration to GraphQL required.
+- **Stripe**: LEGACY - Using deprecated Charges API. Should migrate to Payment Intents API.
+- **Salesforce**: CURRENT - jsforce patterns are valid, but API versions 21.0-30.0 retired in 2025.
+- **Zendesk**: CURRENT - API v2 endpoints are current and stable.
+
+---
+
+## 1. Shopify Integration
+
+**File:** `packages/integrations/shopify/src/ShopifyIntegration.ts`
+
+### Current Implementation
+
+```typescript
+apiVersion: '2024-01'
+baseUrl: `https://${shopDomain}/admin/api/${apiVersion}`
+
+Endpoints used:
+- GET /admin/api/2024-01/shop.json (authentication)
+- GET /admin/api/2024-01/orders.json?name=X&status=any
+- GET /admin/api/2024-01/orders/{id}.json
+- POST /admin/api/2024-01/price_rules.json
+- POST /admin/api/2024-01/price_rules/{id}/discount_codes.json
+- GET /admin/api/2024-01/products.json?limit=X&title=Y
+```
+
+### Validation Results
+
+#### ❌ CRITICAL: API Version Deprecated
+- **Status:** REST Admin API version 2024-01 reached **end-of-life on January 1, 2025**
+- **Impact:** API version no longer supported
+- **Timeline:**
+  - October 1, 2024: Entire REST Admin API became "legacy" (no updates/features)
+  - February 1, 2025: Critical REST endpoints (products/variants) ceased functioning
+  - April 1, 2025: All new apps must use GraphQL exclusively
+  - 2026+: GraphQL will be the only supported API
+
+#### ❌ CRITICAL: Price Rules API Deprecated
+- **Status:** Price Rules REST API deprecated in favor of GraphQL discounts
+- **Timeline:**
+  - February/March 2023: `priceRule` GraphQL queries/mutations deprecated
+  - April 2024: Access to priceRule resources removed
+  - Current: REST Price Rules API is legacy, no longer receives updates
+
+### Recommendations
+
+**Priority 1: Migrate to GraphQL Admin API**
+```graphql
+# Replace REST orders endpoint
+query {
+  orders(first: 10, query: "name:#1001") {
+    edges {
+      node {
+        id
+        name
+        displayFinancialStatus
+        displayFulfillmentStatus
+        createdAt
+        totalPriceSet { shopMoney { amount currencyCode } }
+        lineItems(first: 10) {
+          edges {
+            node {
+              title
+              quantity
+              originalUnitPriceSet { shopMoney { amount } }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+# Replace Price Rules with Discount API
+mutation discountCodeBasicCreate($basicCodeDiscount: DiscountCodeBasicInput!) {
+  discountCodeBasicCreate(basicCodeDiscount: $basicCodeDiscount) {
+    codeDiscountNode {
+      id
+      codeDiscount {
+        ... on DiscountCodeBasic {
+          title
+          codes(first: 1) {
+            edges {
+              node {
+                code
+              }
+            }
+          }
+        }
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+**Priority 2: Update API Version**
+- If continuing with REST temporarily, upgrade to latest stable version (2025-01 or later)
+- Note: REST API will eventually be fully deprecated
+
+**Breaking Changes:**
+- GraphQL uses different data structures (edges/nodes pattern)
+- Discount creation requires different parameters
+- Authentication headers remain the same (`X-Shopify-Access-Token`)
+
+**Sources:**
+- [Shopify API Versioning](https://shopify.dev)
+- [REST to GraphQL Migration Guide](https://shopify.dev)
+- [Discount API Documentation](https://digitalsuits.co)
+
+---
+
+## 2. Stripe Integration
+
+**File:** `packages/integrations/stripe/src/StripeIntegration.ts`
+
+### Current Implementation
+
+```typescript
+Endpoints used:
+- stripe.balance.retrieve() (authentication)
+- stripe.customers.retrieve(id)
+- stripe.customers.list({ email })
+- stripe.charges.list({ customer, limit })
+- stripe.paymentIntents.retrieve(id)
+- stripe.refunds.create({ charge, payment_intent, amount, reason })
+- stripe.products.create()
+- stripe.prices.create()
+- stripe.paymentLinks.create()
+```
+
+### Validation Results
+
+#### ⚠️ WARNING: Charges API is Legacy
+- **Status:** Charges API is a **legacy feature** as of 2025
+- **Recommendation:** Stripe strongly recommends using **Payment Intents API** for new integrations
+- **Impact:** Limited access to newer Stripe features when using Charges API
+- **Current Support:** Still functional but not recommended for new code
+
+#### ✅ CURRENT: Other APIs Valid
+- **Customers API:** Current and stable
+- **Payment Intents API:** Current (already used for `stripe_get_payment_intent`)
+- **Refunds API:** Current and stable
+- **Payment Links API:** Current and stable
+
+### Recommendations
+
+**Priority 1: Migrate from Charges to Payment Intents**
+
+Current implementation:
+```typescript
+stripe_get_charges: {
+  execute: async (params) => {
+    const charges = await this.stripe.charges.list({
+      customer: params.customerId,
+      limit: params.limit || 10,
+    });
+  }
+}
+```
+
+Recommended implementation:
+```typescript
+stripe_get_payment_intents: {
+  execute: async (params) => {
+    const paymentIntents = await this.stripe.paymentIntents.list({
+      customer: params.customerId,
+      limit: params.limit || 10,
+    });
+    // Payment Intents provide more context and support modern features
+  }
+}
+```
+
+**Priority 2: Update Refund Tool**
+- Current implementation correctly supports both `charge` and `payment_intent` parameters
+- Consider deprecating `chargeId` parameter in favor of `paymentIntentId` only
+
+**API Versioning:**
+- Current API version: `2026-01-28.clover` (as of late 2024)
+- Stripe uses date-based versioning (e.g., `2024-10-01`)
+- SDK automatically handles version compatibility
+- **Important:** Certificate trust chain changes effective February 1, 2026
+
+**Sources:**
+- [Stripe API Documentation](https://stripe.com)
+- [Payment Intents vs Charges](https://stripe.com)
+- [Stripe Node.js SDK](https://github.com)
+
+---
+
+## 3. Salesforce Integration
+
+**File:** `packages/integrations/salesforce/src/SalesforceIntegration.ts`
+
+### Current Implementation
+
+```typescript
+Library: jsforce
+Authentication: OAuth2 + username/password login
+API calls:
+- conn.sobject('Contact').retrieve(id)
+- conn.query(SOQL) for Contact, Case queries
+- conn.sobject('Contact').update({ Id, ...fields })
+- conn.sobject('Case').create({ ContactId, Subject, Description, Priority, Status })
+- conn.sobject('Note').create({ ParentId, Title, Body })
+```
+
+### Validation Results
+
+#### ✅ CURRENT: jsforce Patterns Valid
+- **Status:** jsforce library and SOQL patterns are current for 2025
+- **API Version:** Summer '25 release (API version 64.0) is current
+- **Authentication:** OAuth 2.0 and username-password flows supported
+
+#### ⚠️ WARNING: API Version Retirements
+- **Retired:** API versions 21.0 through 30.0 (REST, SOAP, Bulk APIs)
+- **Impact:** Applications using old versions will experience "endpoint not found" errors
+- **Action:** Ensure using API version 31.0 or higher
+
+#### ⚠️ WARNING: SOAP login() Retirement
+- **Timeline:** SOAP `login()` API retiring in Summer '27 (API version 65.0)
+- **Current Impact:** None (still functional)
+- **Future Action:** Migrate to OAuth 2.0 Username-Password Flow
+
+### Recommendations
+
+**Priority 1: Verify API Version**
+- jsforce defaults to latest API version, but verify configuration
+- Ensure not pinned to versions 21.0-30.0
+
+**Priority 2: Update Authentication (Future)**
+- Current username/password login via jsforce is acceptable for 2025-2026
+- Plan migration to OAuth 2.0 Username-Password Flow before Summer 2027
+
+**Priority 3: Security Best Practices**
+- ✅ Already using SOQL escaping (`escapeSoql` function)
+- ✅ Using parameterized queries
+- Consider: My Domain URL requirement (all API calls must use org-specific My Domain URL)
+
+**New Features Available:**
+- OpenAPI Specification for sObjects REST API (Beta) - can generate client SDKs
+- Reduced Outbound Message timeout (60s → 20s)
+
+**Note Object:**
+- Current implementation uses `Note` object
+- Consider: `ContentNote` may be more appropriate for newer implementations
+- Current usage is valid but verify against org's object model
+
+**Sources:**
+- [Salesforce Summer '25 Release Notes](https://salesforce.com)
+- [jsforce Documentation](https://github.io)
+- [Salesforce REST API Best Practices](https://integrate.io)
+
+---
+
+## 4. Zendesk Integration
+
+**File:** `packages/integrations/zendesk/src/ZendeskIntegration.ts`
+
+### Current Implementation
+
+```typescript
+Library: axios
+Base URL: https://{subdomain}.zendesk.com/api/v2
+Authentication: Basic auth with {email}/token and API token
+
+Endpoints used:
+- GET /api/v2/users/me.json (authentication)
+- POST /api/v2/tickets.json
+- GET /api/v2/tickets/{id}.json
+- PUT /api/v2/tickets/{id}.json
+- GET /api/v2/search.json?query=type:ticket {query}&per_page={limit}
+```
+
+### Validation Results
+
+#### ✅ CURRENT: All Endpoints Valid
+- **Status:** Zendesk API v2 is current and stable for 2025-2026
+- **Authentication:** Basic auth with email/token is current standard
+- **Endpoints:** All ticket, search, and comment endpoints are current
+
+#### ✅ CURRENT: Search API Implementation
+- **Query Syntax:** Correctly using `type:ticket` prefix
+- **Pagination:** Using `per_page` parameter (correct)
+- **Limits:** API returns up to 1,000 results (100 per page max)
+
+### Recommendations
+
+**Priority 1: Consider Pagination Limits**
+- Current implementation doesn't handle the 1,000 result limit
+- For large datasets, consider:
+  - Breaking searches into date ranges
+  - Using Export Search Results endpoint
+  - Using Incremental Export endpoints for changes
+
+**Priority 2: Add Side-loading Support (Optional)**
+- Zendesk supports side-loading related records
+- Example: `GET /api/v2/tickets/{id}.json?include=users,groups`
+- Could reduce API calls for ticket details
+
+**Priority 3: Error Handling Enhancement**
+- Current error handling is basic
+- Consider handling specific Zendesk error codes:
+  - 422: Insufficient Resource Error (pagination beyond limit)
+  - 429: Rate limiting
+  - 401: Authentication failures
+
+**Best Practices:**
+- ✅ Using correct authentication method
+- ✅ Proper Content-Type headers
+- ✅ URL encoding for search queries (handled by axios)
+
+**Sources:**
+- [Zendesk API v2 Documentation](https://zendesk.com)
+- [Search API Reference](https://zendesk.com)
+- [Zendesk Developer Docs](https://zendesk.com)
+
+---
+
+## Library Usage Validation
+
+### 1. vitest
+
+**Files:** `packages/core/test/integration.test.ts`, `packages/memory/src/memory.test.ts`
+
+#### ✅ CURRENT: Test Patterns Valid
+
+**Patterns Used:**
+```typescript
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+
+describe('Test Suite', () => {
+  beforeAll(async () => { /* setup */ });
+  afterAll(async () => { /* cleanup */ });
+
+  it('should test something', () => {
+    expect(value).toBe(expected);
+  });
+});
+```
+
+**Validation:**
+- ✅ Correct import pattern
+- ✅ Proper use of `describe`, `it`, `expect`
+- ✅ Async test support with `async/await`
+- ✅ Setup/teardown with `beforeAll`/`afterAll`
+- ✅ Timeout configuration (15000ms) for long-running tests
+- ✅ Using `--run` flag to avoid watch mode (per CLAUDE.md)
+
+**Best Practices Followed:**
+- Proper cleanup in `afterAll`
+- Async setup with proper awaits
+- Clear test descriptions
+- Appropriate timeout for integration tests
+
+---
+
+### 2. commander
+
+**File:** `packages/cli/src/index.ts`
+
+#### ✅ CURRENT: Command Registration Patterns Valid
+
+**Patterns Used:**
+```typescript
+import { Command } from 'commander';
+
+const program = new Command();
+
+program
+  .name('operor')
+  .description('Operor - AI Agent Operating System')
+  .version('0.1.0');
+
+program
+  .command('setup')
+  .description('Run the interactive setup wizard')
+  .action(async () => { /* ... */ });
+
+const configCmd = program.command('config').description('View and modify configuration');
+configCmd
+  .command('set <key> <value>')
+  .action(async (k, v) => { /* ... */ });
+
+program.parse();
+```
+
+**Validation:**
+- ✅ Correct import pattern (ESM)
+- ✅ Proper command registration with `.command()`
+- ✅ Descriptions for help generation
+- ✅ Action handlers with async support
+- ✅ Subcommands (config subcommands)
+- ✅ Required arguments (`<key> <value>`)
+- ✅ Final `program.parse()` call
+
+**Alignment with 2025 Best Practices:**
+- ✅ Using ESM syntax
+- ✅ Async action handlers
+- ✅ Proper metadata (name, description, version)
+- ✅ Modular command structure
+
+**Note:** Commander v14 (May 2025) requires Node.js v20+. Verify package.json engines field.
+
+---
+
+### 3. tsup
+
+**Files:** Multiple `tsup.config.ts` files across packages
+
+#### ✅ CURRENT: Build Configuration Valid
+
+**Pattern Used:**
+```typescript
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  banner: {
+    js: '#!/usr/bin/env node',  // CLI package only
+  },
+});
+```
+
+**Validation:**
+- ✅ Using `defineConfig` for type safety
+- ✅ ESM format specified
+- ✅ TypeScript declarations enabled (`dts: true`)
+- ✅ Clean builds (`clean: true`)
+- ✅ Sourcemaps enabled (`sourcemap: true`)
+- ✅ Banner for CLI executables (CLI package only)
+
+**Best Practices:**
+- ✅ Consistent configuration across packages
+- ✅ Proper entry point specification
+- ✅ Type-safe configuration
+- ✅ Development-friendly sourcemaps
+
+**Recommendations:**
+- Consider adding `splitting: true` for code splitting (defaults to true for ESM)
+- Consider `minify: true` for production builds (optional)
+- Consider `target: 'node18'` or higher to match Node.js requirements
+
+---
+
+### 4. @clack/prompts
+
+**Files:** `packages/cli/src/setup.ts`, `packages/cli/src/commands/doctor.ts`
+
+#### ✅ CURRENT: Prompt Usage Patterns Valid
+
+**Patterns Used:**
+```typescript
+import * as clack from '@clack/prompts';
+
+// Intro/Outro
+clack.intro('Operor - Setup');
+clack.outro('Config saved to .env');
+
+// Select
+const provider = await clack.select({
+  message: 'Choose your LLM provider',
+  options: [
+    { value: 'openai', label: 'OpenAI' },
+    { value: 'anthropic', label: 'Anthropic (Claude)' },
+  ],
+});
+
+// Confirm
+const useDetected = await clack.confirm({
+  message: `Found API key. Use it?`,
+  initialValue: true,
+});
+
+// Cancel handling
+if (clack.isCancel(provider)) {
+  clack.cancel('Setup cancelled');
+  process.exit(0);
+}
+
+// Spinner
+const spinner = clack.spinner();
+spinner.start('Validating credentials');
+spinner.stop('Validation complete');
+```
+
+**Validation:**
+- ✅ Correct import pattern
+- ✅ Proper use of `select`, `confirm`, `multiselect`
+- ✅ Cancel detection with `isCancel()`
+- ✅ Graceful exit on cancel
+- ✅ Spinner for async operations
+- ✅ Intro/outro for session management
+- ✅ Validation functions in prompts
+
+**Best Practices Followed:**
+- ✅ Consistent cancel handling across all prompts
+- ✅ User-friendly messages
+- ✅ Visual feedback with spinners
+- ✅ Input validation
+- ✅ Proper error handling
+
+---
+
+## Summary of Findings
+
+### Critical Issues (Immediate Action Required)
+
+1. **Shopify Integration**
+   - API version 2024-01 reached EOL on 2025-01-01
+   - Price Rules API deprecated
+   - **Action:** Migrate to GraphQL Admin API
+
+### Warnings (Plan for Migration)
+
+2. **Stripe Integration**
+   - Charges API is legacy
+   - **Action:** Migrate to Payment Intents API
+
+3. **Salesforce Integration**
+   - SOAP login() retiring in Summer 2027
+   - **Action:** Plan OAuth 2.0 migration
+
+### Current and Valid
+
+4. **Zendesk Integration** - All endpoints current ✅
+5. **vitest** - Test patterns valid ✅
+6. **commander** - CLI patterns valid ✅
+7. **tsup** - Build configuration valid ✅
+8. **@clack/prompts** - Prompt usage valid ✅
+
+---
+
+## Recommended Action Plan
+
+### Phase 1: Critical (Q1 2026)
+1. Migrate Shopify to GraphQL Admin API
+2. Update Shopify API version to 2025-01 or later (if staying on REST temporarily)
+
+### Phase 2: Important (Q2 2026)
+3. Migrate Stripe from Charges API to Payment Intents API
+4. Verify Salesforce API version configuration
+
+### Phase 3: Future (2026-2027)
+5. Plan Salesforce OAuth 2.0 migration (before Summer 2027)
+6. Consider Zendesk pagination enhancements
+7. Review tsup configuration for production optimizations
+
+---
+
+**Report Generated:** 2026-02-15
+**Validation Method:** Web search against current vendor documentation (2025-2026)
+**Next Review:** Q3 2026