tdx

Appearance

SDK API Reference / ConnectionSDK

Class: ConnectionSDK ​

Connection operations API

Methods ​

buildIdToNameMap() ​

buildIdToNameMap(): Promise<Map<string, string>>

Build a map from connection ID to connection name

Uses cached connection list.

Returns ​

Promise<Map<string, string>>

Map from connection ID (string) to connection name

Example ​

typescript
const idToNameMap = await tdx.connection.buildIdToNameMap();
const name = idToNameMap.get('123'); // 'my-s3-connection'

buildNameToIdMap() ​

buildNameToIdMap(): Promise<Map<string, number>>

Build a map from connection name to connection ID

Uses cached connection list.

Returns ​

Promise<Map<string, number>>

Map from connection name to connection ID (number)

Example ​

typescript
const nameToIdMap = await tdx.connection.buildNameToIdMap();
const id = nameToIdMap.get('my-s3-connection'); // 123

clearCache() ​

clearCache(): void

Clear the connection cache for this profile

Returns ​

void

findById() ​

findById(id): Promise<Connection | undefined>

Find connection by ID

Uses cached connection list.

Parameters ​

id ​

string

Connection ID to search for

Returns ​

Promise<Connection | undefined>

Connection if found, undefined otherwise

findByName() ​

findByName(name): Promise<Connection | undefined>

Find connection by name

Uses cached connection list.

Parameters ​

name ​

string

Connection name to search for

Returns ​

Promise<Connection | undefined>

Connection if found, undefined otherwise

get() ​

get(id): Promise<Connection>

Get connection by ID

Parameters ​

id ​

string

Connection ID

Returns ​

Promise<Connection>

Connection details

Example ​

typescript
const connection = await tdx.connection.get('123');
console.log(connection);

getMetadata() ​

getMetadata(connectorType): Promise<ConnectorMetadata>

Get connector metadata for a connector type

Returns metadata including settings definitions, labels, and validation hints.

Parameters ​

connectorType ​

string

The connector type (e.g., 'salesforce', 'pgsql', 's3')

Returns ​

Promise<ConnectorMetadata>

Connector metadata with settings definitions

Throws ​

SDKError if metadata not found

Example ​

typescript
const metadata = await tdx.connection.getMetadata('salesforce');
console.log(metadata.settings);

getOutputSchema() ​

getOutputSchema(connectorType): Promise<FormSchema>

Get output form schema for a connector type

Returns the schema used for validating connector_config in activations.

Parameters ​

connectorType ​

string

The connector type (e.g., 'salesforce', 'pgsql', 's3')

Returns ​

Promise<FormSchema>

Form schema for the connector's output settings

Throws ​

SDKError if schema not found

Example ​

typescript
const schema = await tdx.connection.getOutputSchema('salesforce');
console.log(schema.properties);

getOutputSchemaWithCache() ​

getOutputSchemaWithCache(connectorType): Promise<FormSchema>

Get output schema with in-memory caching

Use this when validating multiple activations to avoid redundant API calls. Cache is per SDK instance (not persisted).

Parameters ​

connectorType ​

string

The connector type

Returns ​

Promise<FormSchema>

Cached or freshly fetched schema

list() ​

list(refresh): Promise<Connection[]>

List all connections

Uses cached data if available. Use refresh=true to force API call.

Parameters ​

refresh ​

boolean = false

Force refresh from API (default: false)

Returns ​

Promise<Connection[]>

Array of connections with IDs

Example ​

typescript
const connections = await tdx.connection.list();
console.log(connections);

listTypes() ​

listTypes(): Promise<ConnectorMetadata[]>

List all available connector types

Returns ​

Promise<ConnectorMetadata[]>

Array of connector metadata for all available types

Example ​

typescript
const types = await tdx.connection.listTypes();
for (const t of types) {
  console.log(`${t.type}: ${t.name}`);
}

resolve() ​

resolve(name): Promise<Connection>

Resolve a connection by name

Returns the connection details from the list that matches the given name. Uses cached connection list, with auto-refresh on cache miss.

Parameters ​

name ​

string

Connection name

Returns ​

Promise<Connection>

Connection details

Throws ​

SDKError if connection not found

Example ​

typescript
const connection = await tdx.connection.resolve('my-connection');
console.log(connection);

validateConfig() ​

validateConfig(connectorType, config): Promise<ConnectorConfigValidationResult>

Validate connector_config against the schema for a connector type

Performs client-side validation using the form schema from TD API.

Parameters ​

connectorType ​

string

The connector type (e.g., 'salesforce', 'pgsql')

config ​

Record<string, unknown>

The connector_config object to validate

Returns ​

Promise<ConnectorConfigValidationResult>

Validation result with errors and warnings

Example ​

typescript
const result = await tdx.connection.validateConfig('salesforce', {
  object: 'Contact',
  mode: 'upsert',
});
if (!result.valid) {
  console.error(result.errors);
}

validateConfigOrThrow() ​

validateConfigOrThrow(connectorType, config, activationName?): Promise<void>

Validate connector_config and throw on errors

Performs client-side validation and throws SDKError if validation fails. Warnings are logged but don't cause errors.

Parameters ​

connectorType ​

string

The connector type

config ​

Record<string, unknown>

The connector_config object to validate

activationName? ​

string

Optional activation name for better error messages

Returns ​

Promise<void>

Throws ​

SDKError with CONNECTOR_INVALID_CONFIG if validation fails

Example ​

typescript
await tdx.connection.validateConfigOrThrow('salesforce', config, 'My Activation');
// Throws if invalid, otherwise continues

validateConfigServer() ​

validateConfigServer(connectorType, connectionId, config): Promise<void>

Validate connector_config using server-side validation

Calls the TD API to validate connector configuration. This can catch business logic errors like "table doesn't exist".

Parameters ​

connectorType ​

string

The connector type

connectionId ​

number

Connection ID to validate against

config ​

Record<string, unknown>

The connector_config object to validate

Returns ​

Promise<void>

Throws ​

SDKError from API client if validation fails (e.g., INVALID_REQUEST for 400 errors)

Example ​

typescript
await tdx.connection.validateConfigServer('salesforce', 123, config);

Copyright 2024-present Treasure Data