Integration Guide

External System Integration Architecture

The ABS Platform integrates seamlessly with external systems through standardized interfaces and messaging patterns.

Integration Patterns

1. API-Based Integration (FED)

GraphQL Federation

Unified access through schema federation:

type Customer @key(fields: "id") {
  id: ID!
  servicePlans: [ServicePlan!]! @requires(fields: "id")
  billingAddress: Address @external
  assignedAssets: [Asset!]! @external
}

REST API Integration

export class ExternalRestAPIClient {
  async createCustomer(customerData: CustomerInput): Promise<Customer> {
    const response = await this.post('/customers', {
      name: customerData.fullName,
      email: customerData.email,
      phone: customerData.phoneNumber
    });
    return this.mapToABSCustomer(response.data);
  }
}

2. Event-Driven Integration (BRO)

MQTT-Based Real-Time Integration

export class ExternalEventHandler {
  async subscribeToExternalEvents(): Promise<void> {
    await this.mqttClient.subscribe('/external/payments/+/processed', 
      this.handlePaymentEvent.bind(this)
    );
  }

  private async handlePaymentEvent(topic: string, payload: PaymentEvent): Promise<void> {
    const planId = this.extractPlanId(topic);
    await this.mqttClient.publish(`/dirac/abs/service/${planId}/payment_received`, {
      amount: payload.amount,
      currency: payload.currency,
      timestamp: payload.timestamp
    });
  }
}

Specific System Integrations

1. Odoo ERP Integration

export class OdooIntegrationService {
  async syncServicePlanToOdoo(servicePlan: ServicePlan): Promise<void> {
    const subscription = {
      name: `${servicePlan.templateName} - ${servicePlan.customer.name}`,
      partner_id: servicePlan.customer.odooCustomerId,
      product_id: servicePlan.template.odooProductId,
      abs_service_plan_id: servicePlan.id
    };
    await this.odooClient.create('sale.subscription', subscription);
  }
}

2. ARM Asset Management Integration

export class ARMIntegrationService {
  async requestAssetAllocation(request: AssetAllocationRequest): Promise<AssetAllocation> {
    const availableAssets = await this.armClient.query(`
      query GetAvailableAssets($location: String!, $assetType: String!) {
        availableAssets(location: $location, assetType: $assetType) {
          id type location status
        }
      }
    `, { location: request.locationId, assetType: 'battery' });

    return await this.armClient.mutate(`
      mutation AllocateAsset($assetId: ID!, $servicePlanId: ID!) {
        allocateAsset(assetId: $assetId, servicePlanId: $servicePlanId) {
          id asset { id serialNumber } expiresAt
        }
      }
    `, { assetId: availableAssets[0].id, servicePlanId: request.servicePlanId });
  }
}

3. Payment Processor Integration

interface PaymentProcessor {
  processPayment(request: PaymentRequest): Promise<PaymentResult>;
  refundPayment(transactionId: string, amount: number): Promise<RefundResult>;
}

export class StripePaymentProcessor implements PaymentProcessor {
  async processPayment(request: PaymentRequest): Promise<PaymentResult> {
    const paymentIntent = await this.stripeClient.paymentIntents.create({
      amount: request.amount * 100,
      currency: request.currency.toLowerCase(),
      customer: request.customerId,
      metadata: { service_plan_id: request.servicePlanId }
    });

    return {
      transactionId: paymentIntent.id,
      status: this.mapStripeStatus(paymentIntent.status),
      amount: request.amount,
      currency: request.currency
    };
  }
}

Integration Security

1. Authentication Strategies

export class OAuth2Client {
  async getAccessToken(scope: string[]): Promise<string> {
    const tokenResponse = await this.httpClient.post('/oauth/token', {
      grant_type: 'client_credentials',
      client_id: this.clientId,
      client_secret: this.clientSecret,
      scope: scope.join(' ')
    });
    return tokenResponse.data.access_token;
  }
}

2. Data Encryption

export class EncryptionService {
  async encryptSensitiveData(data: SensitiveDataPayload): Promise<EncryptedPayload> {
    return {
      customerId: data.customerId,
      encryptedFields: {
        phoneNumber: await this.encrypt(data.phoneNumber),
        email: await this.encrypt(data.email)
      }
    };
  }
}

Error Handling & Resilience

1. Circuit Breaker Pattern

export class CircuitBreaker {
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';

  async execute<T>(operation: () => Promise<T>): Promise<T> {
    if (this.state === 'OPEN') {
      throw new CircuitBreakerOpenError('Circuit breaker is open');
    }

    try {
      const result = await operation();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
}

2. Retry with Exponential Backoff

export class RetryableClient {
  async callWithRetry<T>(operation: () => Promise<T>, maxRetries: number = 3): Promise<T> {
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        return await operation();
      } catch (error) {
        if (attempt === maxRetries || !this.isRetryableError(error)) {
          throw error;
        }
        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
        await this.sleep(delay);
      }
    }
  }
}

Monitoring & Observability

Integration Health Checks

export class IntegrationHealthService {
  async checkOdooHealth(): Promise<HealthStatus> {
    try {
      const response = await this.odooClient.call('ir.http', 'session_info');
      return { status: 'healthy', responseTime: response.responseTime };
    } catch (error) {
      return { status: 'unhealthy', error: error.message };
    }
  }
}

This guide provides comprehensive patterns and examples for connecting the ABS Platform with external systems while maintaining security, reliability, and performance.