@tetrascience-npm/ts-connectors-sdk

TetraScience Node.js Connectors SDK.

Provides base classes and utilities for building TetraScience Connectors in Node.js.

It is primarily intended to be used by TetraScience connectors running on the Tetra Data Platform (TDP).

Installation

This SDK relies on a small set of peer dependencies that your application must provide. These are not bundled with the SDK so that you can control the exact versions used in your environment.

Required peer dependencies:

• @aws-sdk/client-cloudwatch-logs
• @aws-sdk/client-s3
• @aws-sdk/client-sqs
• @aws-sdk/client-ssm
• @aws-sdk/lib-storage
• axios

If you are not already using these packages, you can install everything together:

Using npm:

npm install @tetrascience-npm/ts-connectors-sdk \
  @aws-sdk/client-cloudwatch-logs @aws-sdk/client-s3 \
  @aws-sdk/client-sqs @aws-sdk/client-ssm @aws-sdk/lib-storage axios

Using Yarn:

yarn add @tetrascience-npm/ts-connectors-sdk \
  @aws-sdk/client-cloudwatch-logs @aws-sdk/client-s3 \
  @aws-sdk/client-sqs @aws-sdk/client-ssm @aws-sdk/lib-storage axios

If your project already depends on the AWS SDK v3 clients or axios, you only need to add @tetrascience-npm/ts-connectors-sdk and ensure that your existing versions satisfy the peer dependency ranges in package.json.

This SDK is tested with Node.js versions 16, 18, and 20 (see the engines field in package.json).

Overview

The SDK exposes the following primary building blocks:

• TDPClient – wraps the Tetra Data Platform data-acquisition API and handles datalake uploads directly to S3, including metadata options and validation.
• Connector – base class that encapsulates common connector lifecycle concerns such as initialization, health reporting, metrics, and command handling.
• PollingConnector – extends Connector with a polling loop implementation suitable for connectors that primarily poll external systems on an interval.

All of these are exported from the package root, for example:

import { Connector, PollingConnector, TDPClient } from '@tetrascience-npm/ts-connectors-sdk';

Basic usage

TDPClient

In a typical connector environment, TDPClient is initialized with configuration derived from the connector runtime (environment variables, manifests, and connector settings). At a high level you use it to make API calls and upload files into the Tetra Data Platform:

import { TDPClient } from '@tetrascience-npm/ts-connectors-sdk';

async function uploadExample() {
  const client = new TDPClient(/* see source for available options */);

  await client.uploadFile({
    content: Buffer.from('example'),
    filepath: 'path/in/datalake/example.txt',
    // Optional metadata, tags, labels, and other fields are validated
    // against the platform metadata rules.
  });
}

Refer to the TDPClient source (src/tdp-client.ts) for the full set of options and behaviors.

Connector and PollingConnector

To build a connector, extend either Connector or PollingConnector and implement the appropriate hooks for your integration.

import { PollingConnector } from '@tetrascience-npm/ts-connectors-sdk';

class MyPollingConnector extends PollingConnector {
  // Implement required hooks such as poll(), onStartup(), onShutdown(), etc.
}

The base classes handle boilerplate such as:

• Connector lifecycle and shutdown behavior
• Health and metrics reporting
• Command reception and dispatch

Versioning and changelog

All notable changes are documented in CHANGELOG.md.

Contributing

For more details, see CONTRIBUTING.md.

License

This project is licensed under the Apache License 2.0.