Skip to content

Class: ConnectorDefinitionBuilder

A class that assists in constructing a connector definition. Use newConnector to create one.

Extends

  • BaseDefinitionBuilder

Extended by

Implements

Constructors

Constructor

new ConnectorDefinitionBuilder(definition?): ConnectorDefinitionBuilder

Constructs a ConnectorDefinitionBuilder. However, sdk.newConnector() should be used instead rather than constructing a builder directly.

Parameters

Parameter Type
definition? Partial<Omit<PackVersionDefinition, "agent" | "defaultTriggers" | "defaultRoutines">>

Returns

ConnectorDefinitionBuilder

Overrides

BaseDefinitionBuilder.constructor

Properties

defaultAuthentication?

optional defaultAuthentication: Authentication

See ComponentVersionDefinition.defaultAuthentication.

Implementation of

ComponentVersionDefinition.defaultAuthentication


formats

formats: Format[]

See ComponentVersionDefinition.formats.

Implementation of

ComponentVersionDefinition.formats


formulaNamespace?

optional formulaNamespace: string

Deprecated

Implementation of

ComponentVersionDefinition.formulaNamespace


formulas

formulas: Formula[]

See ComponentVersionDefinition.formulas.

Implementation of

ComponentVersionDefinition.formulas


networkDomains

networkDomains: string[]

See ComponentVersionDefinition.networkDomains.

Implementation of

ComponentVersionDefinition.networkDomains


skillEntrypoints?

optional skillEntrypoints: SkillEntrypoints

See ComponentVersionDefinition.skillEntrypoints.

Deprecated

No longer used, now that agents are connectors.

Implementation of

ComponentVersionDefinition.skillEntrypoints


skills

skills: Skill[]

See ComponentVersionDefinition.skills.

Deprecated

Skills are no longer used. Connectors should not set tools.

Implementation of

ComponentVersionDefinition.skills


syncTables

syncTables: SyncTable[]

See ComponentVersionDefinition.syncTables.

Implementation of

ComponentVersionDefinition.syncTables


systemConnectionAuthentication?

optional systemConnectionAuthentication: SystemAuthentication

See ComponentVersionDefinition.systemConnectionAuthentication.

Implementation of

ComponentVersionDefinition.systemConnectionAuthentication


version?

optional version: string

See ComponentVersionDefinition.version.

Inherited from

BaseDefinitionBuilder.version

Methods

addColumnFormat()

addColumnFormat(format): this

Adds a column format definition to this connector.

In the web editor, the /ColumnFormat shortcut will insert a snippet of a skeleton format.

Example

connector.addColumnFormat({
  name: 'MyColumn',
  formulaName: 'MyFormula',
});

Only supported in Superhuman Docs.

Parameters

Parameter Type
format Format

Returns

this


addDynamicSyncTable()

addDynamicSyncTable<K, L, ParamDefsT, SchemaT, ContextT, PermissionsContextT>(definition): this

Adds a dynamic sync table definition to this connector.

In the web editor, the /DynamicSyncTable shortcut will insert a snippet of a skeleton sync table.

Example

connector.addDynamicSyncTable({
  name: "MySyncTable",
  getName: async funciton (context) => {
    const response = await context.fetcher.fetch({method: "GET", url: context.sync.dynamicUrl});
    return response.body.name;
  },
  getName: async function (context) => {
    const response = await context.fetcher.fetch({method: "GET", url: context.sync.dynamicUrl});
    return response.body.browserLink;
  },
  ...
});

Type Parameters

Type Parameter
K extends string
L extends string
ParamDefsT extends ParamDefs
SchemaT extends ObjectSchemaDefinition<K, L>
ContextT extends SyncExecutionContext<any, any, any>
PermissionsContextT extends SyncPassthroughData

Parameters

Parameter Type
definition DynamicSyncTableOptions<K, L, ParamDefsT, SchemaT, ContextT, PermissionsContextT>

Returns

this


addFormula()

addFormula<ParamDefsT, ResultT, SchemaT>(definition): this

Adds a formula definition to this connector.

In the web editor, the /Formula shortcut will insert a snippet of a skeleton formula.

Example

connector.addFormula({
  resultType: ValueType.String,
  name: 'MyFormula',
  description: 'My description.',
  parameters: [
    makeParameter({
      type: ParameterType.String,
      name: 'myParam',
      description: 'My param description.',
    }),
  ],
  execute: async ([param]) => {
    return `Hello ${param}`;
  },
});

Type Parameters

Type Parameter
ParamDefsT extends ParamDefs
ResultT extends ValueType
SchemaT extends Schema

Parameters

Parameter Type
definition object & FormulaDefinitionOptions<ParamDefsT, ResultT, SchemaT>

Returns

this


addMCPServer()

addMCPServer(server): this

Adds an MCP server to this connector.

Example

connector.addMCPServer({name: 'MyMCPServer', endpointUrl: 'https://my-mcp-server.com'});

Only supported in Superhuman Go.

Parameters

Parameter Type
server MCPServer

Returns

this


addNetworkDomain()

addNetworkDomain(...domain): this

Adds the domain that this connector makes HTTP requests to. For example, if your connector makes HTTP requests to "api.example.com", use "example.com" as your network domain.

If your connector makes HTTP requests, it must declare a network domain, for security purposes. The platform enforces that your connector cannot make requests to any undeclared domains.

You are allowed one network domain per connector by default. If your connector needs to connect to multiple domains, contact Superhuman for approval.

Example

connector.addNetworkDomain('example.com');

Parameters

Parameter Type
...domain string[]

Returns

this


addSkill()

addSkill(skill): this

Adds a skill definition to this connector.

In the web editor, the /Skill shortcut will insert a snippet of a skeleton skill.

Example

connector.addSkill({
  name: "MySkill",
  displayName: "My Display Name",
  description: "My description.",
  prompt: `My prompt.`,
  tools: [
    { type: sdk.ToolType.Pack },
  ],
});

Deprecated

Skills are no longer used. Connectors should not set tools.

Parameters

Parameter Type
skill Skill

Returns

this


addSuggestedPrompt()

addSuggestedPrompt(prompt): this

Adds a suggested prompt that appears as a button when the agent is opened in chat.

Example

connector.addSuggestedPrompt({
  name: "TicketStatus",
  displayName: "Check ticket status",
  prompt: `
    Show me the status of all open support tickets.
  `,
});

Deprecated

No longer used, now that agents are connectors.

Parameters

Parameter Type
prompt SuggestedPrompt

Returns

this


addSyncTable()

addSyncTable<K, L, ParamDefsT, SchemaT, ContextT, PermissionsContextT>(definition): this

Adds a sync table definition to this connector.

In the web editor, the /SyncTable shortcut will insert a snippet of a skeleton sync table.

Example

connector.addSyncTable({
  name: 'MySyncTable',
  identityName: 'EntityName',
  schema: sdk.makeObjectSchema({
    ...
  }),
  formula: {
    ...
  },
});

Type Parameters

Type Parameter
K extends string
L extends string
ParamDefsT extends ParamDefs
SchemaT extends ObjectSchema<K, L>
ContextT extends SyncExecutionContext<any, any, any>
PermissionsContextT extends SyncPassthroughData

Parameters

Parameter Type
definition SyncTableOptions<K, L, ParamDefsT, SchemaT, ContextT, PermissionsContextT>

Returns

this


setBenchInitializationSkill()

setBenchInitializationSkill(skill): this

Sets the skill used when the agent is first opened in the agent bench. All fields are optional - omitted fields will use defaults at runtime.

Example

connector.setBenchInitializationSkill({
  prompt: `
    Say hello to the user, referencing the time of day and a friendly nickname.
    For example: 10AM, Kramer => "Good morning K-man!"
  `,
  tools: [],
});

Deprecated

No longer used, now that agents are connectors.

Parameters

Parameter Type
skill PartialSkillDef

Returns

this


setChatSkill()

setChatSkill(skill): this

Sets the chat skill for agent.

The chat skill controls the behavior when users chat with the agent. It defines the prompts, available tools, and optionally the model to use.

All fields are optional — omitted fields use defaults at runtime. When tools is omitted, the agent automatically gets:

Specifying tools replaces these defaults entirely.

Example

// Override just the prompt — default tools are preserved
connector.setChatSkill({
  prompt: "End every reply with 'Moo!'",
});

// Override tools — replaces the defaults
connector.setChatSkill({
  tools: [
    { type: sdk.ToolType.Pack },
    { type: sdk.ToolType.ContactResolution },
  ],
});

Deprecated

No longer used, now that agents are connectors.

Parameters

Parameter Type
skill PartialSkillDef

Returns

this


setSkillEntrypoints()

setSkillEntrypoints(entrypoints): this

Maps entrypoints to skills in the connector.

Example

connector.setSkillEntrypoints({
  defaultChat: { skillName: "MySkill" },
});

Deprecated

No longer used, now that agents are connectors.

Parameters

Parameter Type
entrypoints SkillEntrypoints

Returns

this


setSystemAuthentication()

setSystemAuthentication(systemAuthentication): this

Sets this connector to use authentication provided by you as the maker of this connector.

You will need to register credentials to use with this connector. When users use the connector, their requests will be authenticated with those system credentials, they need not register their own account.

In the web editor, the /SystemAuthentication shortcut will insert a snippet of a skeleton authentication definition.

Example

connector.setSystemAuthentication({
  type: AuthenticationType.HeaderBearerToken,
});

Parameters

Parameter Type
systemAuthentication SystemAuthenticationDef

Returns

this


setUserAuthentication()

setUserAuthentication(authDef): this

Sets this connector to use authentication for individual users, using the authentication method is the given definition.

Each user will need to register an account in order to use this connector.

In the web editor, the /UserAuthentication shortcut will insert a snippet of a skeleton authentication definition.

By default, this will set a default connection (account) requirement, making a user account required to invoke all formulas in this connector unless you specify differently on a particular formula. To change the default, you can pass a defaultConnectionRequirement option into this method.

Example

connector.setUserAuthentication({
  type: AuthenticationType.HeaderBearerToken,
});

Parameters

Parameter Type
authDef UserAuthenticationDef

Returns

this


setVersion()

setVersion(version): this

Sets the semantic version of this definition version, e.g. '1.2.3'.

This is optional, and you only need to provide a version if you are manually doing semantic versioning, or using the CLI. If using the web editor, you can omit this and the web editor will automatically provide an appropriate semantic version each time you build a version.

Example

builder.setVersion('1.2.3');

Parameters

Parameter Type
version string

Returns

this

Inherited from

BaseDefinitionBuilder.setVersion