@anycast/connector-sdk

SDK for building connectors for the Anycast Edge Platform. Connectors allow agents and tenants to integrate with external services -- databases, APIs, SaaS platforms, and on-premise systems.

What are connectors?

Connectors are typed integrations that bridge the Anycast platform with external services. There are two types:

• Portal connectors run inside the Anycast portal and make outbound API calls. Best for SaaS integrations, REST APIs, and cloud services.
• Agent connectors run on the edge inside the Anycast agent process. Best for databases, on-premise APIs, and services behind a firewall.

Quick start

Install the SDK:

npm install @anycast/connector-sdk

Create a connector:

import { PortalConnector, ConnectorConfig, ConnectorConfigSchema, ConnectorOperation, ConnectorResult, ExecutionContext, TestResult } from '@anycast/connector-sdk';

export class MyApiConnector extends PortalConnector {
  type = 'MY_API';
  name = 'My API';
  description = 'Connects to My API service';
  version = '1.0.0';
  author = 'Your Name';

  configSchema: ConnectorConfigSchema = {
    fields: [
      { key: 'apiUrl', label: 'API URL', type: 'text', required: true },
      { key: 'token', label: 'Access Token', type: 'password', required: true, sensitive: true },
    ],
  };

  operations: ConnectorOperation[] = [
    {
      name: 'list_items',
      description: 'List all items',
      params: [
        { name: 'limit', type: 'number', required: false, description: 'Max items to return', default: 50 },
      ],
      execute: async (config: ConnectorConfig, params: Record<string, unknown>, ctx: ExecutionContext): Promise<ConnectorResult> => {
        this.validateConfig(config);
        const limit = (params.limit as number) || 50;
        const res = await this.fetch(`${config.apiUrl}/items?limit=${limit}`, {
          headers: { Authorization: `Bearer ${config.token}` },
        }, ctx.timeout);

        if (!res.ok) return { error: `HTTP ${res.status}` };
        const items = await res.json();
        return this.result(
          items.map((item: { id: string; name: string }) => [item.id, item.name]),
          ['id', 'name'],
        );
      },
    },
  ];

  async test(config: ConnectorConfig): Promise<TestResult> {
    try {
      this.validateConfig(config);
      const res = await this.fetch(`${config.apiUrl}/ping`, {
        headers: { Authorization: `Bearer ${config.token}` },
      });
      return { ok: res.ok, message: res.ok ? 'Connected' : `HTTP ${res.status}` };
    } catch (e) {
      return { ok: false, message: e instanceof Error ? e.message : 'Failed' };
    }
  }
}

PortalConnector vs AgentConnector

| Feature | PortalConnector | AgentConnector | |---------|----------------|----------------| | Runs in | Portal (cloud) | Agent (edge) | | Language | TypeScript | Go (metadata in TS) | | Use case | SaaS APIs, cloud services | Databases, on-prem systems | | Network | Outbound HTTP from portal | Local network at edge |

PortalConnector

Extend PortalConnector for integrations that call external APIs from the portal:

import { PortalConnector } from '@anycast/connector-sdk';

export class SlackConnector extends PortalConnector {
  type = 'SLACK';
  name = 'Slack';
  // ... define configSchema and operations
}

Built-in helpers:

• this.fetch(url, options, timeoutMs) -- HTTP fetch with timeout
• this.validateConfig(config) -- validate required fields are present
• this.result(rows, columns?) -- build a ConnectorResult
• this.stripDeniedFields(rows, columns, denied) -- remove restricted columns

AgentConnector

Extend AgentConnector for integrations that run on the edge:

import { AgentConnector } from '@anycast/connector-sdk';

export class PostgresConnector extends AgentConnector {
  type = 'POSTGRES';
  name = 'PostgreSQL';
  description = 'Query PostgreSQL databases';
  version = '1.0.0';
}

// Generate Go scaffolding:
const pg = new PostgresConnector();
console.log(pg.toGoStruct());

Config schema

Define the configuration fields your connector needs. These render as a form in the portal UI when a tenant sets up the connector.

configSchema: ConnectorConfigSchema = {
  fields: [
    { key: 'url', label: 'URL', type: 'text', required: true, placeholder: 'https://...' },
    { key: 'apiKey', label: 'API Key', type: 'password', required: true, sensitive: true },
    { key: 'region', label: 'Region', type: 'select', required: true, options: [
      { label: 'US East', value: 'us-east-1' },
      { label: 'EU West', value: 'eu-west-1' },
    ]},
    { key: 'debug', label: 'Debug Mode', type: 'boolean', required: false, default: false },
  ],
};

Field types: text, password, number, boolean, select, textarea

Fields marked sensitive: true are encrypted at rest in the platform database.

Operations

Operations are the actions your connector can perform. Each operation has a name, description, typed parameters, and an execute function.

operations: ConnectorOperation[] = [
  {
    name: 'search',
    description: 'Search for records',
    params: [
      { name: 'query', type: 'string', required: true, description: 'Search query' },
      { name: 'maxResults', type: 'number', required: false, description: 'Max results', default: 10 },
    ],
    execute: async (config, params, ctx) => {
      ctx.logger.info(`Searching for: ${params.query}`);
      // ... your logic here
      return { rows: [[1, 'result']], columns: ['id', 'name'], count: 1 };
    },
  },
];

The ConnectorResult shape:

• rows -- array of arrays (tabular data)
• columns -- column header names
• count -- number of rows
• error -- error message if the operation failed
• metadata -- arbitrary key-value metadata

Testing

The SDK provides helpers for testing your connector without a running platform:

import { createMockContext, createMockConfig, runOperation } from '@anycast/connector-sdk';
import { MyConnector } from './my-connector';

const connector = new MyConnector();

// Create mock config from schema
const config = createMockConfig(connector.configSchema);
// Override with real values for integration tests
config.apiUrl = 'https://api.example.com';
config.token = 'test-token';

// Run an operation
const result = await runOperation(connector, 'list_items', config, { limit: 10 });
console.log(result);

// Use a custom context
const ctx = createMockContext({ tenantId: 'my-tenant', timeout: 5000 });

CLI

The SDK includes a CLI tool for scaffolding and validating connectors:

npx anycast-connector init       # Scaffold a new connector project
npx anycast-connector validate   # Validate connector metadata
npx anycast-connector test       # Run connector test function

Publishing

When your connector is ready:

1. Build: npm run build
2. Test: ensure test() passes and all operations return valid results
3. Publish to npm (or your private registry)
4. Register the connector in the Anycast portal admin UI

License

MIT