Building Custom Connectors

// src/index.ts
import {
  Connector,
  ConnectorConfig,
  ConnectorMetadata,
  SyncResult,
  HealthCheckResult,
  WebhookEvent,
  Identity,
  Group,
} from '@tigeridentity/connector-sdk';

/**
 * Custom connector for internal HR system
 */
export class HRSystemConnector implements Connector {
  private config: ConnectorConfig;
  private apiClient: any; // Your API client

  constructor(config: ConnectorConfig) {
    this.config = config;
    this.initializeClient();
  }

  /**
   * Initialize API client with configuration
   */
  private initializeClient(): void {
    const { apiUrl, apiKey } = this.config;

    // Initialize your API client here
    this.apiClient = {
      baseURL: apiUrl,
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
    };
  }

  /**
   * Return connector metadata
   */
  getMetadata(): ConnectorMetadata {
    return {
      name: 'hr-system',
      displayName: 'Internal HR System',
      description: 'Sync employees and departments from internal HR system',
      version: '1.0.0',
      author: 'Your Company',

      // Configuration schema
      configSchema: {
        type: 'object',
        required: ['apiUrl', 'apiKey'],
        properties: {
          apiUrl: {
            type: 'string',
            title: 'API URL',
            description: 'Base URL of the HR system API',
          },
          apiKey: {
            type: 'string',
            title: 'API Key',
            description: 'API key for authentication',
            secret: true,
          },
          syncDepartments: {
            type: 'boolean',
            title: 'Sync Departments',
            description: 'Include department information in sync',
            default: true,
          },
        },
      },

      // Supported features
      capabilities: {
        sync: true,
        webhook: true,
        incremental: true,
        realtime: false,
      },

      // Resource types
      resourceTypes: ['users', 'groups'],
    };
  }

  /**
   * Perform health check
   */
  async healthCheck(): Promise<HealthCheckResult> {
    try {
      // Test API connectivity
      const response = await fetch(`${this.config.apiUrl}/health`, {
        headers: this.apiClient.headers,
      });

      if (!response.ok) {
        return {
          healthy: false,
          message: `API returned status ${response.status}`,
        };
      }

      return {
        healthy: true,
        message: 'Connection successful',
      };
    } catch (error) {
      return {
        healthy: false,
        message: `Connection failed: ${error.message}`,
        error: error,
      };
    }
  }

  /**
   * Sync identities from the source system
   */
  async onSync(lastSyncTime?: Date): Promise<SyncResult> {
    const startTime = Date.now();
    const identities: Identity[] = [];
    const groups: Group[] = [];
    const errors: any[] = [];

    try {
      // Fetch employees
      const employees = await this.fetchEmployees(lastSyncTime);

      // Transform to Identity objects
      for (const employee of employees) {
        try {
          const identity = this.transformEmployee(employee);
          identities.push(identity);
        } catch (error) {
          errors.push({
            id: employee.id,
            error: error.message,
          });
        }
      }

      // Fetch departments if enabled
      if (this.config.syncDepartments) {
        const departments = await this.fetchDepartments();

        for (const dept of departments) {
          try {
            const group = this.transformDepartment(dept);
            groups.push(group);
          } catch (error) {
            errors.push({
              id: dept.id,
              error: error.message,
            });
          }
        }
      }

      return {
        success: true,
        identities,
        groups,
        syncTime: new Date(),
        duration: Date.now() - startTime,
        stats: {
          identitiesProcessed: identities.length,
          groupsProcessed: groups.length,
          errors: errors.length,
        },
        errors,
      };
    } catch (error) {
      return {
        success: false,
        identities: [],
        groups: [],
        syncTime: new Date(),
        duration: Date.now() - startTime,
        error: error.message,
      };
    }
  }

  /**
   * Handle webhook events
   */
  async onWebhook(event: WebhookEvent): Promise<void> {
    const { type, payload } = event;

    switch (type) {
      case 'employee.created':
      case 'employee.updated':
        const identity = this.transformEmployee(payload);
        await this.emitIdentity(identity);
        break;

      case 'employee.terminated':
        await this.emitIdentityDeletion(payload.id);
        break;

      case 'department.created':
      case 'department.updated':
        const group = this.transformDepartment(payload);
        await this.emitGroup(group);
        break;

      default:
        console.log(`Unhandled webhook event type: ${type}`);
    }
  }

  /**
   * Fetch employees from HR system
   */
  private async fetchEmployees(since?: Date): Promise<any[]> {
    const params = new URLSearchParams();
    if (since) {
      params.append('updatedSince', since.toISOString());
    }

    const response = await fetch(
      `${this.config.apiUrl}/employees?${params}`,
      {
        headers: this.apiClient.headers,
      }
    );

    if (!response.ok) {
      throw new Error(`Failed to fetch employees: ${response.statusText}`);
    }

    const data = await response.json();
    return data.employees || [];
  }

  /**
   * Fetch departments from HR system
   */
  private async fetchDepartments(): Promise<any[]> {
    const response = await fetch(`${this.config.apiUrl}/departments`, {
      headers: this.apiClient.headers,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch departments: ${response.statusText}`);
    }

    const data = await response.json();
    return data.departments || [];
  }

  /**
   * Transform employee to Identity
   */
  private transformEmployee(employee: any): Identity {
    return {
      id: employee.id,
      email: employee.email,
      username: employee.email.split('@')[0],
      firstName: employee.firstName,
      lastName: employee.lastName,
      displayName: `${employee.firstName} ${employee.lastName}`,
      department: employee.department?.name,
      title: employee.jobTitle,
      manager: employee.managerId,
      status: employee.status === 'active' ? 'active' : 'inactive',

      // Custom attributes
      attributes: {
        employeeId: employee.employeeNumber,
        hireDate: employee.hireDate,
        location: employee.office,
        employeeType: employee.type,
      },

      // Group memberships
      groups: [
        employee.department?.id,
        ...employee.teams?.map((t: any) => t.id) || [],
      ].filter(Boolean),

      source: 'hr-system',
      sourceId: employee.id,
      lastSyncTime: new Date(),
    };
  }

  /**
   * Transform department to Group
   */
  private transformDepartment(dept: any): Group {
    return {
      id: dept.id,
      name: dept.name,
      description: dept.description,

      // Members
      members: dept.employees?.map((e: any) => e.id) || [],

      // Parent group
      parentGroup: dept.parentDepartmentId,

      // Custom attributes
      attributes: {
        costCenter: dept.costCenter,
        location: dept.location,
        manager: dept.managerId,
      },

      source: 'hr-system',
      sourceId: dept.id,
      lastSyncTime: new Date(),
    };
  }

  /**
   * Emit identity update
   */
  private async emitIdentity(identity: Identity): Promise<void> {
    // SDK handles sending to TigerIdentity
    console.log('Emitting identity:', identity.id);
  }

  /**
   * Emit identity deletion
   */
  private async emitIdentityDeletion(id: string): Promise<void> {
    console.log('Emitting identity deletion:', id);
  }

  /**
   * Emit group update
   */
  private async emitGroup(group: Group): Promise<void> {
    console.log('Emitting group:', group.id);
  }
}

// Export the connector
export default HRSystemConnector;

my-custom-connector/
├── src/
│   ├── index.ts              # Main connector implementation
│   ├── types.ts              # Type definitions
│   ├── client.ts             # API client
│   ├── transforms.ts         # Data transformations
│   └── __tests__/
│       ├── connector.test.ts # Connector tests
│       └── transforms.test.ts # Transform tests
├── dist/                     # Build output
├── package.json              # Package configuration
├── tsconfig.json             # TypeScript configuration
├── connector.yaml            # Local test config
├── README.md                 # Documentation
└── LICENSE                   # License file