defineConnector()

defineConnector() is the single entry point of the Connector SDK. You hand it one declarative object, a ConnectorDef, and that object is the entire contract: the tools the connector exposes, the events it emits, how it authenticates, and how the platform checks its health. The runtime supplies everything else: per-tenant credentials, rate-limited HTTP, idempotency, and tracing. This page documents every field of the def, with types taken directly from @fibric/connector-sdk.

#Signature

defineConnector() takes a ConnectorDef and returns it unchanged. It exists so the compiler checks your def against the contract and so the CLI, the registry, and the marketplace can all read the same shape. There is no hidden registration step and no runtime magic. The def is data.

export function defineConnector(def: ConnectorDef): ConnectorDef;

export interface ConnectorDef {
  id: string;
  version: string;
  category: ConnectorCategory;
  publisher?: 'first-party' | 'partner' | 'private';
  auth: AuthSchema;
  tools: Record<string, ToolDef>;
  events?: Record<string, { kind: 'webhook' | 'poll'; topic?: string }>;
  probe?: (ctx: ConnectorCtx) => { status: string; metric?: { label: string; value: unknown } };
}

#ConnectorDef fields

#ConnectorCategory

The category is a closed union. It tells the marketplace where the connector lives and tells policy tooling what kind of blast radius its side effects have. A hardware connector gets a more conservative default policy template than a data connector.

export type ConnectorCategory =
  | 'crm'
  | 'commerce'
  | 'voice'
  | 'shipping'
  | 'comms'
  | 'data'
  | 'hardware'
  | 'ai-operator';

#ConnectorCtx

Tool handlers, event pollers, and probes receive a ConnectorCtx. The reference context supplies tenant-scoped services for the integration.

export interface ConnectorCtx {
  tenant_id: string;
  reseller_id: string | null;
  config: Record<string, unknown>;
  log: (msg: string, extra?: Record<string, unknown>) => void;
}

The reference runtime provides a tenant-scoped HTTP client through ctx.http. It resolves the configured credentials and applies its rate and retry policy. Validate those services in the actual runtime before depending on them.

#A complete worked example

The connector below integrates a helpdesk in the shape of the live Kustomer connector: conversations flow in as events, reads run inline, and the one write, adding a note to a conversation, is side-effecting and therefore routes through the governed executor. This is a full, publishable def, not a fragment.

import { defineConnector, tool, apiKey } from '@fibric/connector-sdk';

export default defineConnector({
  id: 'cn-brightdesk',
  version: '1.0.0',
  category: 'comms',
  publisher: 'partner',

  // The def declares the auth SHAPE. The runtime resolves the actual key
  // per tenant from the secret store at call time.
  auth: apiKey(),

  tools: {
    // Read: runs inline, no policy check, no idempotency needed.
    'conversation.read': tool({
      input: (args) => {
        const a = args as { conversation_id?: unknown };
        if (typeof a.conversation_id !== 'string') {
          throw new Error('conversation_id: string required');
        }
        return { conversation_id: a.conversation_id };
      },
      handler: async (ctx, args) => {
        ctx.log('reading conversation', { id: args.conversation_id });
        // ctx.http is pre-authenticated and rate-limited by the runtime
        // return await ctx.http.get(`/v1/conversations/${args.conversation_id}`);
        return { id: args.conversation_id, status: 'open', messages: [] };
      },
    }),

    // Write: sideEffecting routes this through the deterministic
    // executor, behind the trust policy and idempotency dedup.
    'note.write': tool({
      sideEffecting: true,
      input: (args) => {
        const a = args as { conversation_id?: unknown; body?: unknown };
        if (typeof a.conversation_id !== 'string') {
          throw new Error('conversation_id: string required');
        }
        if (typeof a.body !== 'string' || a.body.length === 0) {
          throw new Error('body: non-empty string required');
        }
        return { conversation_id: a.conversation_id, body: a.body };
      },
      handler: async (ctx, args) => {
        ctx.log('writing note', { id: args.conversation_id });
        // return await ctx.http.post(`/v1/conversations/${args.conversation_id}/notes`,
        //   { body: args.body });
        return { ok: true };
      },
    }),
  },

  // The sense side: streams that become event envelopes.
  events: {
    'conversation.created': { kind: 'webhook', topic: 'conversations' },
    'conversation.updated': { kind: 'webhook', topic: 'conversations' },
    'sla.breached':         { kind: 'poll' },
  },

  // Health, shown on the connector's status card.
  probe: (ctx) => ({
    status: 'ok',
    metric: { label: 'open conversations', value: 42 },
  }),
});

The example uses capability names rather than vendor endpoints, marks side-effecting tools explicitly, and leaves credential resolution to the runtime. A connector must accurately declare whether a tool can change the target system.

#Lifecycle

A connector moves through four phases from source file to serving traffic. Each phase reads only the def; there is no separate manifest to keep in sync.

#1. Register

You add the connector to a workspace, from a local directory during development (fibric connectors add ./connectors/brightdesk) or from the marketplace by id. The platform reads the def, records the tool and event names, and indexes the capabilities so operators can bind against them. Nothing has authenticated yet and nothing can run.

#2. Handshake

A connection is created for one account of the target system. The auth declaration drives what happens: apiKey() prompts for a key that goes straight into the tenant's secret store, oauth2() runs the authorization flow with the declared scopes. On success the platform calls probe once to confirm the credentials actually work before marking the connection healthy.

#3. Sense stream

Declared events go live. Webhook streams get a per-connection endpoint; poll streams get a schedule. Every emission is normalized into an EventEnvelope, stamped with tenant_id, reseller_id, source, and event_type, and published to the bus, where the router matches it against operator triggers like conversation.*.

#4. Act tools

Tools become invocable. Reads are called inline by operators sensing state. Side-effecting tools are reachable only through a validated ExecutionPlan: the deterministic executor checks the trust policy, takes the single-flight lock on the action's entity_key, dedupes on its idempotency_key, and only then invokes your handler. Every disposed action leaves a receipt.

#Connectors are MCP servers

A Fibric connector is an MCP server. The tools record maps directly to MCP tool declarations, the events record to its notification streams, and the def's metadata to the server's self-description. This is why one SDK shape covers a helpdesk, a Modbus gateway, and an AI operator: the kernel never hardcodes an integration, it speaks MCP to all of them, and the governed executor sits in front of every side-effecting tool regardless of what is on the other end.

The practical consequence is symmetry. Anything that can present an MCP tool surface can be a connector, and every connector is automatically usable by anything that speaks MCP, subject to the same trust policy. The moat is not the protocol; it is the governance wrapped around it.

#Keep going

• Tools & auth: the tool() helper and auth declarations in depth, including validation and secret handling.
• Testing connectors: replay recorded envelopes and assert on proposed plans without executing anything.
• Publishing to the marketplace: listing metadata, review, and the status lifecycle.
• Governance & trust: what the executor does with a side-effecting tool call.