{"_id":"@anycast/connector-sdk","name":"@anycast/connector-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@anycast/connector-sdk","version":"0.1.0","description":"SDK for building Anycast platform connectors","main":"dist/index.js","types":"dist/index.d.ts","bin":{"anycast-connector":"dist/cli/index.js"},"scripts":{"build":"tsc","prepublishOnly":"npm run build"},"keywords":["anycast","connector","sdk","ai","agents"],"author":{"name":"Anycast Platform"},"license":"MIT","devDependencies":{"typescript":"^5.0.0"},"_id":"@anycast/connector-sdk@0.1.0","gitHead":"a3388accab5621636c569ea141f4c0667da87eb8","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-S4MEsEAaub08gCLB+nfkkdiJN+NcoseqpdS7ek9CK42otfapmwOmWb46/xoOn95rbEvl5g2IG6nT/PfU4n2jFg==","shasum":"14a3608898cbcc5f8cf8243c3b88ce3f84582921","tarball":"https://registry.npmjs.org/@anycast/connector-sdk/-/connector-sdk-0.1.0.tgz","fileCount":30,"unpackedSize":41531,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDsQLXJ9zc73eyhUigzyCBiO64h5Y8VU8NP5UgSaEWRtQIgPaPedryuYkPV5wHYtMo1kLJzJmXzPhEYX0Xdeza4H7M="}]},"_npmUser":{"name":"markmahle","email":"mm@anycast.com"},"directories":{},"maintainers":[{"name":"markmahle","email":"mm@anycast.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/connector-sdk_0.1.0_1774791153541_0.11639209272557816"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T13:32:33.436Z","0.1.0":"2026-03-29T13:32:33.703Z","modified":"2026-03-29T13:32:33.908Z"},"maintainers":[{"name":"markmahle","email":"mm@anycast.com"}],"description":"SDK for building Anycast platform connectors","keywords":["anycast","connector","sdk","ai","agents"],"author":{"name":"Anycast Platform"},"license":"MIT","readme":"# @anycast/connector-sdk\n\nSDK 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.\n\n## What are connectors?\n\nConnectors are typed integrations that bridge the Anycast platform with external services. There are two types:\n\n- **Portal connectors** run inside the Anycast portal and make outbound API calls. Best for SaaS integrations, REST APIs, and cloud services.\n- **Agent connectors** run on the edge inside the Anycast agent process. Best for databases, on-premise APIs, and services behind a firewall.\n\n## Quick start\n\nInstall the SDK:\n\n```bash\nnpm install @anycast/connector-sdk\n```\n\nCreate a connector:\n\n```typescript\nimport { PortalConnector, ConnectorConfig, ConnectorConfigSchema, ConnectorOperation, ConnectorResult, ExecutionContext, TestResult } from '@anycast/connector-sdk';\n\nexport class MyApiConnector extends PortalConnector {\n  type = 'MY_API';\n  name = 'My API';\n  description = 'Connects to My API service';\n  version = '1.0.0';\n  author = 'Your Name';\n\n  configSchema: ConnectorConfigSchema = {\n    fields: [\n      { key: 'apiUrl', label: 'API URL', type: 'text', required: true },\n      { key: 'token', label: 'Access Token', type: 'password', required: true, sensitive: true },\n    ],\n  };\n\n  operations: ConnectorOperation[] = [\n    {\n      name: 'list_items',\n      description: 'List all items',\n      params: [\n        { name: 'limit', type: 'number', required: false, description: 'Max items to return', default: 50 },\n      ],\n      execute: async (config: ConnectorConfig, params: Record<string, unknown>, ctx: ExecutionContext): Promise<ConnectorResult> => {\n        this.validateConfig(config);\n        const limit = (params.limit as number) || 50;\n        const res = await this.fetch(`${config.apiUrl}/items?limit=${limit}`, {\n          headers: { Authorization: `Bearer ${config.token}` },\n        }, ctx.timeout);\n\n        if (!res.ok) return { error: `HTTP ${res.status}` };\n        const items = await res.json();\n        return this.result(\n          items.map((item: { id: string; name: string }) => [item.id, item.name]),\n          ['id', 'name'],\n        );\n      },\n    },\n  ];\n\n  async test(config: ConnectorConfig): Promise<TestResult> {\n    try {\n      this.validateConfig(config);\n      const res = await this.fetch(`${config.apiUrl}/ping`, {\n        headers: { Authorization: `Bearer ${config.token}` },\n      });\n      return { ok: res.ok, message: res.ok ? 'Connected' : `HTTP ${res.status}` };\n    } catch (e) {\n      return { ok: false, message: e instanceof Error ? e.message : 'Failed' };\n    }\n  }\n}\n```\n\n## PortalConnector vs AgentConnector\n\n| Feature | PortalConnector | AgentConnector |\n|---------|----------------|----------------|\n| Runs in | Portal (cloud) | Agent (edge) |\n| Language | TypeScript | Go (metadata in TS) |\n| Use case | SaaS APIs, cloud services | Databases, on-prem systems |\n| Network | Outbound HTTP from portal | Local network at edge |\n\n### PortalConnector\n\nExtend `PortalConnector` for integrations that call external APIs from the portal:\n\n```typescript\nimport { PortalConnector } from '@anycast/connector-sdk';\n\nexport class SlackConnector extends PortalConnector {\n  type = 'SLACK';\n  name = 'Slack';\n  // ... define configSchema and operations\n}\n```\n\nBuilt-in helpers:\n- `this.fetch(url, options, timeoutMs)` -- HTTP fetch with timeout\n- `this.validateConfig(config)` -- validate required fields are present\n- `this.result(rows, columns?)` -- build a ConnectorResult\n- `this.stripDeniedFields(rows, columns, denied)` -- remove restricted columns\n\n### AgentConnector\n\nExtend `AgentConnector` for integrations that run on the edge:\n\n```typescript\nimport { AgentConnector } from '@anycast/connector-sdk';\n\nexport class PostgresConnector extends AgentConnector {\n  type = 'POSTGRES';\n  name = 'PostgreSQL';\n  description = 'Query PostgreSQL databases';\n  version = '1.0.0';\n}\n\n// Generate Go scaffolding:\nconst pg = new PostgresConnector();\nconsole.log(pg.toGoStruct());\n```\n\n## Config schema\n\nDefine the configuration fields your connector needs. These render as a form in the portal UI when a tenant sets up the connector.\n\n```typescript\nconfigSchema: ConnectorConfigSchema = {\n  fields: [\n    { key: 'url', label: 'URL', type: 'text', required: true, placeholder: 'https://...' },\n    { key: 'apiKey', label: 'API Key', type: 'password', required: true, sensitive: true },\n    { key: 'region', label: 'Region', type: 'select', required: true, options: [\n      { label: 'US East', value: 'us-east-1' },\n      { label: 'EU West', value: 'eu-west-1' },\n    ]},\n    { key: 'debug', label: 'Debug Mode', type: 'boolean', required: false, default: false },\n  ],\n};\n```\n\nField types: `text`, `password`, `number`, `boolean`, `select`, `textarea`\n\nFields marked `sensitive: true` are encrypted at rest in the platform database.\n\n## Operations\n\nOperations are the actions your connector can perform. Each operation has a name, description, typed parameters, and an execute function.\n\n```typescript\noperations: ConnectorOperation[] = [\n  {\n    name: 'search',\n    description: 'Search for records',\n    params: [\n      { name: 'query', type: 'string', required: true, description: 'Search query' },\n      { name: 'maxResults', type: 'number', required: false, description: 'Max results', default: 10 },\n    ],\n    execute: async (config, params, ctx) => {\n      ctx.logger.info(`Searching for: ${params.query}`);\n      // ... your logic here\n      return { rows: [[1, 'result']], columns: ['id', 'name'], count: 1 };\n    },\n  },\n];\n```\n\nThe `ConnectorResult` shape:\n- `rows` -- array of arrays (tabular data)\n- `columns` -- column header names\n- `count` -- number of rows\n- `error` -- error message if the operation failed\n- `metadata` -- arbitrary key-value metadata\n\n## Testing\n\nThe SDK provides helpers for testing your connector without a running platform:\n\n```typescript\nimport { createMockContext, createMockConfig, runOperation } from '@anycast/connector-sdk';\nimport { MyConnector } from './my-connector';\n\nconst connector = new MyConnector();\n\n// Create mock config from schema\nconst config = createMockConfig(connector.configSchema);\n// Override with real values for integration tests\nconfig.apiUrl = 'https://api.example.com';\nconfig.token = 'test-token';\n\n// Run an operation\nconst result = await runOperation(connector, 'list_items', config, { limit: 10 });\nconsole.log(result);\n\n// Use a custom context\nconst ctx = createMockContext({ tenantId: 'my-tenant', timeout: 5000 });\n```\n\n## CLI\n\nThe SDK includes a CLI tool for scaffolding and validating connectors:\n\n```bash\nnpx anycast-connector init       # Scaffold a new connector project\nnpx anycast-connector validate   # Validate connector metadata\nnpx anycast-connector test       # Run connector test function\n```\n\n## Publishing\n\nWhen your connector is ready:\n\n1. Build: `npm run build`\n2. Test: ensure `test()` passes and all operations return valid results\n3. Publish to npm (or your private registry)\n4. Register the connector in the Anycast portal admin UI\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-012d1e00ccfe83977c9cf469a23543a1"}