@colossal/sdk

SDK for building Colossal integrations.

Setup

pnpm install

Create a New Integration

1. Create directory: integrations/your-integration/

2. Create package.json:

{
  "name": "your-integration",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@colossal/sdk": "workspace:*"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

3. Create index.ts:

import type { IntegrationConfig } from '@colossal/sdk';
import { FunctionType } from '@colossal/sdk';

const config: IntegrationConfig = {
  id: 'your-integration',
  name: 'Your Integration',
  version: '1.0.0',
  description: 'Integration description',
  category: 'PAYMENT',
  authentication_type: 'API_KEY',
  frontend: {
    'payment-controller': {
      entry: './frontend/component.tsx',
      globalName: 'YourComponent'
    }
  },
  functions: [
    { type: FunctionType.PAYMENT_CREATE_INTENT, action: 'createPayment' }
  ],
  actions: {
    createPayment: {
      endpoint: {
        url: 'https://api.yourservice.com/payments',
        method: 'POST'
      },
      request_template: {
        amount: '{{payload.amount}}',
        currency: '{{payload.currency}}'
      }
    }
  }
};

export default config;

4. Create frontend component: frontend/component.tsx

Build & Seed

Build all integrations and seed to database:

pnpm sync:integrations

What it does:

• Runs pnpm install in each integration
• Builds manifests and frontend components with hashed filenames
• Copies assets to frontend-web/public/integrations/
• Seeds manifests to backend database

Local Development

1. Start backend: cd backend && just dev
2. Start frontend: cd frontend-web && pnpm dev
3. Make changes to integration
4. Run pnpm sync:integrations
5. Test at http://localhost:3000

Directory Structure

integrations/
├── your-integration/
│   ├── package.json
│   ├── index.ts           # Manifest definition
│   └── frontend/
│       └── component.tsx   # Frontend component