core/packages/sdk/README.md

Core SDK

The Core SDK provides tools and utilities for building integrations with the Core platform.

Integration System

The Core integration system uses a CLI-based approach where each integration is a command-line tool that responds to specific events. This makes integrations portable, testable, and easy to debug.

Integration Event Types

Each integration CLI handles 5 core event types:

1. spec

Returns the integration's metadata and configuration.

Usage:

my-integration spec

Returns: Integration specification including name, description, auth config, etc.

2. setup

Processes authentication data and returns tokens/credentials to be saved.

Usage:

my-integration setup --event-body '{"code":"oauth_code","state":"state"}' --integration-definition '{}'

Returns: Configuration data (tokens, credentials) to be stored for the account.

3. identify

Extracts accountId from webhook data to route webhooks to the correct account.

Usage:

my-integration identify --webhook-data '{"team_id":"T123","event":{}}'

Returns: Account identifier for webhook routing.

4. process

Handles webhook events and returns activity data.

Usage:

my-integration process --event-data '{"type":"reaction_added","reaction":"=M"}' --config '{"access_token":"token"}'

Returns: Activity messages representing user actions.

5. sync

Performs scheduled data synchronization for integrations that don't support webhooks.

Usage:

my-integration sync --config '{"access_token":"token","last_sync":"2023-01-01T00:00:00Z"}'

Returns: Activity messages and updated state for next sync.

Message Types

All integration responses are wrapped in a Message object with a type field:

• spec - Integration metadata and configuration
• activity - User actions/events from the integration
• state - Sync state for polling integrations
• identifier - Account identification for webhook routing

Building an Integration

1. Install the SDK:

npm install @Core/core-sdk

2. Create your integration class:

import { IntegrationCLI } from '@Core/core-sdk';

class MyIntegration extends IntegrationCLI {
  constructor() {
    super('my-integration', '1.0.0');
  }

  protected async handleEvent(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    switch (eventPayload.event) {
      case 'SETUP':
        return this.handleSetup(eventPayload);
      case 'PROCESS':
        return this.handleProcess(eventPayload);
      case 'IDENTIFY':
        return this.handleIdentify(eventPayload);
      case 'SYNC':
        return this.handleSync(eventPayload);
      default:
        throw new Error(`Unknown event type: ${eventPayload.event}`);
    }
  }

  protected async getSpec(): Promise<Spec> {
    return {
      name: 'My Integration',
      key: 'my-integration',
      description: 'Integration with My Service',
      icon: 'https://example.com/icon.png',
      auth: {
        OAuth2: {
          token_url: 'https://api.example.com/oauth/token',
          authorization_url: 'https://api.example.com/oauth/authorize',
          scopes: ['read', 'write'],
        },
      },
    };
  }

  private async handleSetup(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Process OAuth response and return tokens to save
    const { code } = eventPayload.eventBody;
    // Exchange code for tokens...
    return {
      access_token: 'token',
      refresh_token: 'refresh_token',
      expires_at: Date.now() + 3600000,
    };
  }

  private async handleProcess(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Handle webhook events
    const { eventData } = eventPayload.eventBody;
    // Process event and return activity...
    return {
      type: 'message',
      user: 'user123',
      content: 'Hello world',
      timestamp: new Date(),
    };
  }

  private async handleIdentify(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Extract account ID from webhook
    const { team_id } = eventPayload.eventBody;
    return { id: team_id };
  }

  private async handleSync(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Perform scheduled sync
    const { config } = eventPayload;
    // Fetch data since last sync...
    return {
      activities: [
        /* activity data */
      ],
      state: { last_sync: new Date().toISOString() },
    };
  }
}

// CLI entry point
const integration = new MyIntegration();
integration.parse();

3. Build and package your integration:

npm run build
npm pack

Integration Development

The IntegrationCLI base class provides:

• Automatic CLI setup with all required commands
• JSON input/output handling for all event types
• Error handling with proper exit codes
• Consistent message formatting for all responses

Testing

Test your integration by running commands directly:

# Test spec
node dist/index.js spec

# Test setup
node dist/index.js setup --event-body '{"code":"test"}' --integration-definition '{}'

# Test webhook processing
node dist/index.js process --event-data '{"type":"test"}' --config '{"token":"test"}'

Best Practices

1. Always validate input data before processing
2. Handle errors gracefully with meaningful error messages
3. Use consistent data structures for activities
4. Include proper timestamps in all activity data
5. Store minimal state for sync operations
6. Test all event types thoroughly

For more examples, see the integrations in the integrations/ directory.