newo 3.4.0 → 3.4.2

package/src/application/sync/SyncEngine.ts

@@ -0,0 +1,467 @@
+/**
+ * SyncEngine - Core synchronization orchestrator
+ *
+ * This is the central engine that coordinates sync operations across all resource types.
+ * It uses the Strategy pattern to handle different resources uniformly.
+ *
+ * Key benefits:
+ * - One engine handles projects, integrations, AKB, attributes, conversations
+ * - Adding new resource = implement one strategy class
+ * - No duplicate pull/push logic
+ * - Easy to test (mock strategies)
+ */
+
+import type {
+  ISyncStrategy,
+  PullOptions,
+  PullResult,
+  PushResult,
+  StatusSummary,
+  ValidationResult
+} from '../../domain/strategies/sync/ISyncStrategy.js';
+import type { CustomerConfig, ILogger } from '../../domain/resources/common/types.js';
+
+/**
+ * Combined pull result from all strategies
+ */
+export interface SyncPullResult {
+  customer: string;
+  resources: Array<{
+    resourceType: string;
+    displayName: string;
+    result: PullResult;
+  }>;
+  totalItems: number;
+  errors: string[];
+}
+
+/**
+ * Combined push result from all strategies
+ */
+export interface SyncPushResult {
+  customer: string;
+  resources: Array<{
+    resourceType: string;
+    displayName: string;
+    result: PushResult;
+  }>;
+  totalCreated: number;
+  totalUpdated: number;
+  totalDeleted: number;
+  errors: string[];
+}
+
+/**
+ * Status report for all resources
+ */
+export interface StatusReport {
+  customer: string;
+  resources: StatusSummary[];
+  totalChanges: number;
+}
+
+/**
+ * Sync error with context
+ */
+export class SyncError extends Error {
+  constructor(
+    message: string,
+    public resourceType: string,
+    public override cause?: Error
+  ) {
+    super(message);
+    this.name = 'SyncError';
+  }
+}
+
+/**
+ * Validation error with details
+ */
+export class ValidationError extends Error {
+  constructor(
+    message: string,
+    public results: ValidationResult[]
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * SyncEngine Options
+ */
+export interface SyncEngineOptions {
+  /**
+   * Stop on first error instead of continuing
+   */
+  stopOnError?: boolean;
+
+  /**
+   * Run strategies in parallel where possible
+   */
+  parallel?: boolean;
+}
+
+/**
+ * SyncEngine - Generic synchronization orchestrator
+ *
+ * Orchestrates pull/push/status operations across all registered strategies.
+ */
+export class SyncEngine {
+  private strategies: Map<string, ISyncStrategy> = new Map();
+
+  constructor(
+    strategies: ISyncStrategy[],
+    private logger: ILogger,
+    private options: SyncEngineOptions = {}
+  ) {
+    for (const strategy of strategies) {
+      this.strategies.set(strategy.resourceType, strategy);
+    }
+  }
+
+  /**
+   * Register a new strategy
+   */
+  registerStrategy(strategy: ISyncStrategy): void {
+    this.strategies.set(strategy.resourceType, strategy);
+  }
+
+  /**
+   * Get a specific strategy by resource type
+   */
+  getStrategy(resourceType: string): ISyncStrategy | undefined {
+    return this.strategies.get(resourceType);
+  }
+
+  /**
+   * Get all registered strategies
+   */
+  getStrategies(): ISyncStrategy[] {
+    return Array.from(this.strategies.values());
+  }
+
+  /**
+   * Pull ALL resources using registered strategies
+   */
+  async pullAll(customer: CustomerConfig, options: PullOptions = {}): Promise<SyncPullResult> {
+    this.logger.info(`📥 Pulling all resources for customer: ${customer.idn}`);
+
+    const result: SyncPullResult = {
+      customer: customer.idn,
+      resources: [],
+      totalItems: 0,
+      errors: []
+    };
+
+    const strategies = Array.from(this.strategies.values());
+
+    if (this.options.parallel) {
+      // Parallel execution
+      const pullPromises = strategies.map(async (strategy) => {
+        try {
+          return await this.pullWithStrategy(strategy, customer, options);
+        } catch (error) {
+          const message = `Failed to pull ${strategy.displayName}: ${error instanceof Error ? error.message : String(error)}`;
+          if (this.options.stopOnError) {
+            throw new SyncError(message, strategy.resourceType, error instanceof Error ? error : undefined);
+          }
+          result.errors.push(message);
+          return null;
+        }
+      });
+
+      const pullResults = await Promise.all(pullPromises);
+
+      for (const pullResult of pullResults) {
+        if (pullResult) {
+          result.resources.push(pullResult);
+          result.totalItems += pullResult.result.count;
+        }
+      }
+    } else {
+      // Sequential execution
+      for (const strategy of strategies) {
+        this.logger.info(`  📦 Pulling ${strategy.displayName}...`);
+
+        try {
+          const pullResult = await this.pullWithStrategy(strategy, customer, options);
+          result.resources.push(pullResult);
+          result.totalItems += pullResult.result.count;
+          this.logger.info(`    ✅ Pulled ${pullResult.result.count} ${strategy.displayName}`);
+        } catch (error) {
+          const message = `Failed to pull ${strategy.displayName}: ${error instanceof Error ? error.message : String(error)}`;
+          this.logger.error(message, error);
+
+          if (this.options.stopOnError) {
+            throw new SyncError(message, strategy.resourceType, error instanceof Error ? error : undefined);
+          }
+          result.errors.push(message);
+        }
+      }
+    }
+
+    this.logger.info(`✅ Pull completed: ${result.totalItems} items from ${result.resources.length} resource types`);
+
+    return result;
+  }
+
+  /**
+   * Pull specific resource types
+   */
+  async pullSelected(
+    customer: CustomerConfig,
+    resourceTypes: string[],
+    options: PullOptions = {}
+  ): Promise<SyncPullResult> {
+    this.logger.info(`📥 Pulling selected resources for customer: ${customer.idn}`);
+
+    const result: SyncPullResult = {
+      customer: customer.idn,
+      resources: [],
+      totalItems: 0,
+      errors: []
+    };
+
+    for (const resourceType of resourceTypes) {
+      const strategy = this.strategies.get(resourceType);
+
+      if (!strategy) {
+        result.errors.push(`Unknown resource type: ${resourceType}`);
+        continue;
+      }
+
+      this.logger.info(`  📦 Pulling ${strategy.displayName}...`);
+
+      try {
+        const pullResult = await this.pullWithStrategy(strategy, customer, options);
+        result.resources.push(pullResult);
+        result.totalItems += pullResult.result.count;
+        this.logger.info(`    ✅ Pulled ${pullResult.result.count} ${strategy.displayName}`);
+      } catch (error) {
+        const message = `Failed to pull ${strategy.displayName}: ${error instanceof Error ? error.message : String(error)}`;
+        this.logger.error(message, error);
+
+        if (this.options.stopOnError) {
+          throw new SyncError(message, strategy.resourceType, error instanceof Error ? error : undefined);
+        }
+        result.errors.push(message);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Push ALL changed resources using registered strategies
+   */
+  async pushAll(customer: CustomerConfig): Promise<SyncPushResult> {
+    this.logger.info(`📤 Pushing changes for customer: ${customer.idn}`);
+
+    const result: SyncPushResult = {
+      customer: customer.idn,
+      resources: [],
+      totalCreated: 0,
+      totalUpdated: 0,
+      totalDeleted: 0,
+      errors: []
+    };
+
+    for (const strategy of this.strategies.values()) {
+      this.logger.info(`  🔍 Checking changes for ${strategy.displayName}...`);
+
+      try {
+        const changes = await strategy.getChanges(customer);
+
+        if (changes.length === 0) {
+          this.logger.verbose(`    No changes for ${strategy.displayName}`);
+          continue;
+        }
+
+        this.logger.info(`    Found ${changes.length} changes in ${strategy.displayName}`);
+
+        // Validate before push
+        const items = changes.map(c => c.item);
+        const validation = await strategy.validate(customer, items);
+
+        if (!validation.valid) {
+          const errorMessages = validation.errors.map(e => `${e.field}: ${e.message}`).join(', ');
+          throw new ValidationError(`Validation failed: ${errorMessages}`, [validation]);
+        }
+
+        // Push changes
+        const pushResult = await strategy.push(customer, changes);
+
+        result.resources.push({
+          resourceType: strategy.resourceType,
+          displayName: strategy.displayName,
+          result: pushResult
+        });
+
+        result.totalCreated += pushResult.created;
+        result.totalUpdated += pushResult.updated;
+        result.totalDeleted += pushResult.deleted;
+        result.errors.push(...pushResult.errors);
+
+        this.logger.info(`    ✅ Pushed: ${pushResult.created} created, ${pushResult.updated} updated, ${pushResult.deleted} deleted`);
+      } catch (error) {
+        const message = `Failed to push ${strategy.displayName}: ${error instanceof Error ? error.message : String(error)}`;
+        this.logger.error(message, error);
+
+        if (this.options.stopOnError) {
+          throw new SyncError(message, strategy.resourceType, error instanceof Error ? error : undefined);
+        }
+        result.errors.push(message);
+      }
+    }
+
+    this.logger.info(`✅ Push completed: ${result.totalCreated} created, ${result.totalUpdated} updated, ${result.totalDeleted} deleted`);
+
+    return result;
+  }
+
+  /**
+   * Push specific resource types
+   */
+  async pushSelected(customer: CustomerConfig, resourceTypes: string[]): Promise<SyncPushResult> {
+    this.logger.info(`📤 Pushing selected resources for customer: ${customer.idn}`);
+
+    const result: SyncPushResult = {
+      customer: customer.idn,
+      resources: [],
+      totalCreated: 0,
+      totalUpdated: 0,
+      totalDeleted: 0,
+      errors: []
+    };
+
+    for (const resourceType of resourceTypes) {
+      const strategy = this.strategies.get(resourceType);
+
+      if (!strategy) {
+        result.errors.push(`Unknown resource type: ${resourceType}`);
+        continue;
+      }
+
+      try {
+        const changes = await strategy.getChanges(customer);
+
+        if (changes.length === 0) {
+          continue;
+        }
+
+        // Validate before push
+        const items = changes.map(c => c.item);
+        const validation = await strategy.validate(customer, items);
+
+        if (!validation.valid) {
+          const errorMessages = validation.errors.map(e => `${e.field}: ${e.message}`).join(', ');
+          throw new ValidationError(`Validation failed: ${errorMessages}`, [validation]);
+        }
+
+        const pushResult = await strategy.push(customer, changes);
+
+        result.resources.push({
+          resourceType: strategy.resourceType,
+          displayName: strategy.displayName,
+          result: pushResult
+        });
+
+        result.totalCreated += pushResult.created;
+        result.totalUpdated += pushResult.updated;
+        result.totalDeleted += pushResult.deleted;
+        result.errors.push(...pushResult.errors);
+      } catch (error) {
+        const message = `Failed to push ${strategy.displayName}: ${error instanceof Error ? error.message : String(error)}`;
+        this.logger.error(message, error);
+
+        if (this.options.stopOnError) {
+          throw new SyncError(message, strategy.resourceType, error instanceof Error ? error : undefined);
+        }
+        result.errors.push(message);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get status for ALL resources
+   */
+  async getStatus(customer: CustomerConfig): Promise<StatusReport> {
+    const report: StatusReport = {
+      customer: customer.idn,
+      resources: [],
+      totalChanges: 0
+    };
+
+    for (const strategy of this.strategies.values()) {
+      try {
+        const status = await strategy.getStatus(customer);
+        report.resources.push(status);
+        report.totalChanges += status.changedCount;
+      } catch (error) {
+        this.logger.error(`Failed to get status for ${strategy.displayName}`, error);
+      }
+    }
+
+    return report;
+  }
+
+  /**
+   * Get status for specific resource types
+   */
+  async getStatusSelected(customer: CustomerConfig, resourceTypes: string[]): Promise<StatusReport> {
+    const report: StatusReport = {
+      customer: customer.idn,
+      resources: [],
+      totalChanges: 0
+    };
+
+    for (const resourceType of resourceTypes) {
+      const strategy = this.strategies.get(resourceType);
+
+      if (!strategy) {
+        continue;
+      }
+
+      try {
+        const status = await strategy.getStatus(customer);
+        report.resources.push(status);
+        report.totalChanges += status.changedCount;
+      } catch (error) {
+        this.logger.error(`Failed to get status for ${strategy.displayName}`, error);
+      }
+    }
+
+    return report;
+  }
+
+  /**
+   * Helper to execute pull with a single strategy
+   */
+  private async pullWithStrategy(
+    strategy: ISyncStrategy,
+    customer: CustomerConfig,
+    options: PullOptions
+  ): Promise<{ resourceType: string; displayName: string; result: PullResult }> {
+    const result = await strategy.pull(customer, options);
+
+    return {
+      resourceType: strategy.resourceType,
+      displayName: strategy.displayName,
+      result
+    };
+  }
+}
+
+/**
+ * Factory function for creating SyncEngine with default strategies
+ */
+export function createSyncEngine(
+  strategies: ISyncStrategy[],
+  logger: ILogger,
+  options?: SyncEngineOptions
+): SyncEngine {
+  return new SyncEngine(strategies, logger, options);
+}

package/src/application/sync/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Sync Application Layer Exports
+ */
+
+export * from './SyncEngine.js';

package/src/cli/commands/create-attribute.ts

@@ -16,7 +16,7 @@ export async function handleCreateAttributeCommand(
 
     // Parse arguments
     const idn = args._[1] as string;
-    const value = args.value as string || '';
+    const value = args.value !== undefined ? String(args.value) : '';
     const title = args.title as string || idn;
     const description = args.description as string || '';
     const group = args.group as string || 'General';

package/src/cli/commands/create-customer.ts

@@ -0,0 +1,185 @@
+/**
+ * Create Customer Command Handler - Creates a new NEWO customer account
+ *
+ * This command creates an empty NEWO customer using the v3 API.
+ * It requires the api_secret attribute from the source customer account.
+ */
+import { makeClient, createNewoCustomer, getCustomerAttributes } from '../../api.js';
+import { getValidAccessToken } from '../../auth.js';
+import { requireSingleCustomer } from '../customer-selection.js';
+import type {
+  MultiCustomerConfig,
+  CliArgs,
+  CreateNewoCustomerRequest,
+  CustomerMember,
+  CustomerProjectInput
+} from '../../types.js';
+
+export async function handleCreateCustomerCommand(
+  customerConfig: MultiCustomerConfig,
+  args: CliArgs,
+  verbose: boolean = false
+): Promise<void> {
+  try {
+    const selectedCustomer = requireSingleCustomer(customerConfig, args.customer as string | undefined);
+
+    // Parse arguments
+    const organizationName = args._[1] as string;
+    const email = args.email as string;
+    const tenant = (args.tenant as string) || 'newo';
+    const phone = (args.phone as string) || '';
+    const comment = (args.comment as string) || '';
+    const status = (args.status as string) || 'temporal';
+    const projectIdn = args.project as string | undefined;
+    const externalId = args['external-id'] as string | undefined;
+
+    // Validate required parameters
+    if (!organizationName) {
+      console.error('Error: Organization name is required');
+      console.error('Usage: newo create-customer <organization_name> --email <email> [options]');
+      console.error('');
+      console.error('Options:');
+      console.error('  --email <email>         Owner email (required)');
+      console.error('  --tenant <tenant>       Tenant name (default: newo)');
+      console.error('  --phone <phone>         Contact phone number');
+      console.error('  --comment <comment>     Comment or notes');
+      console.error('  --status <status>       temporal or permanent (default: temporal)');
+      console.error('  --project <idn>         Project IDN to install (e.g., naf)');
+      console.error('  --external-id <id>      External customer ID for tracking');
+      console.error('');
+      console.error('Example:');
+      console.error('  newo create-customer "Acme Corp" --email owner@acme.com --project naf');
+      process.exit(1);
+    }
+
+    if (!email) {
+      console.error('Error: Owner email is required (--email <email>)');
+      process.exit(1);
+    }
+
+    if (verbose) {
+      console.log(`📝 Creating new NEWO customer...`);
+      console.log(`   Organization: ${organizationName}`);
+      console.log(`   Owner Email: ${email}`);
+      console.log(`   Tenant: ${tenant}`);
+      console.log(`   Status: ${status}`);
+      if (phone) console.log(`   Phone: ${phone}`);
+      if (comment) console.log(`   Comment: ${comment}`);
+      if (projectIdn) console.log(`   Project: ${projectIdn}`);
+      if (externalId) console.log(`   External ID: ${externalId}`);
+    }
+
+    // Get access token and create client
+    const accessToken = await getValidAccessToken(selectedCustomer);
+    const client = await makeClient(verbose, accessToken);
+
+    // Get api_secret from customer attributes
+    console.log('🔑 Fetching API secret from customer attributes...');
+    const attributesResponse = await getCustomerAttributes(client, true);
+    const apiSecretAttr = attributesResponse.attributes.find(attr => attr.idn === 'api_secret');
+
+    if (!apiSecretAttr || !apiSecretAttr.value) {
+      console.error('Error: api_secret attribute not found in customer account');
+      console.error('This command requires the api_secret attribute to create new customers.');
+      process.exit(1);
+    }
+
+    const apiSecret = typeof apiSecretAttr.value === 'string' ? apiSecretAttr.value : String(apiSecretAttr.value);
+
+    if (verbose) {
+      console.log(`✅ API secret found (${apiSecret.substring(0, 6)}...)`);
+    }
+
+    // Build members array
+    const members: CustomerMember[] = [
+      {
+        email: email,
+        role: 'owner',
+        tenants: [tenant]
+      }
+    ];
+
+    // Build projects array if project specified
+    const projects: CustomerProjectInput[] = [];
+    if (projectIdn) {
+      projects.push({
+        idn: projectIdn
+      });
+    }
+
+    // Build customer object - only include optional fields if they have values
+    const customerData: CreateNewoCustomerRequest['customer'] = {
+      organization_name: organizationName,
+      tenant: tenant,
+      members: members,
+      contact_email: email,
+      organization_type: 'customer',
+      organization_status: status as 'temporal' | 'permanent',
+      attributes: [
+        {
+          idn: 'empty',
+          value: 'True'
+        }
+      ]
+    };
+
+    // Add optional fields only if they have values
+    if (comment) {
+      customerData.comment = comment;
+    }
+    if (phone) {
+      customerData.contact_phone = phone;
+    }
+    if (externalId) {
+      customerData.external_customer_id = externalId;
+    }
+
+    // Build customer creation request
+    const createRequest: CreateNewoCustomerRequest = {
+      secret: apiSecret,
+      customer: customerData
+    };
+
+    // Add projects only if specified
+    if (projects.length > 0) {
+      createRequest.projects = projects;
+    }
+
+    if (verbose) {
+      console.log('📤 Creating customer with request:');
+      console.log(JSON.stringify(createRequest, null, 2));
+    }
+
+    // Create the customer
+    console.log('🚀 Creating customer...');
+    const response = await createNewoCustomer(client, createRequest);
+
+    console.log('');
+    console.log('✅ Customer created successfully!');
+    console.log(`   Customer IDN: ${response.idn}`);
+    console.log(`   Customer ID: ${response.id}`);
+    console.log(`   Organization: ${organizationName}`);
+    console.log(`   Owner: ${email}`);
+    if (projectIdn) {
+      console.log(`   Project: ${projectIdn}`);
+    }
+    console.log('');
+    console.log('📝 Next steps:');
+    console.log(`   1. Add the new customer to your .env file:`);
+    console.log(`      NEWO_${response.idn}_API_KEY=<api_key>`);
+    console.log(`   2. Or use the customer_intercom integration to manage the new customer`);
+
+  } catch (error: unknown) {
+    const errMessage = error instanceof Error ? error.message : String(error);
+    console.error('❌ Failed to create customer:', errMessage);
+
+    // Provide more detailed error info if available
+    if (error && typeof error === 'object' && 'response' in error) {
+      const axiosError = error as any;
+      if (axiosError.response?.data) {
+        console.error('   API Error:', JSON.stringify(axiosError.response.data, null, 2));
+      }
+    }
+    process.exit(1);
+  }
+}