TypeScript SDK

@galaxy-io/filament-ts is the generated TypeScript client for Filament’s API. It ships as ES modules with type declarations, has no runtime dependencies, and runs on Node 18 or newer or any runtime with fetch.

Installation

npm install @galaxy-io/filament-ts

Connect

import { FilamentClient } from "@galaxy-io/filament-ts";

const filament = new FilamentClient({
  baseUrl: process.env.FILAMENT_URL ?? "http://localhost:8080",
  auth: false,
});

const { connectors } = await filament.connector.list({});
for (const connector of connectors ?? []) {
  console.log(connector.name);
}

This connects to a server with authentication disabled; see Authentication for a deployed server. Request timeouts are set with timeoutInSeconds and retries with maxRetries, on the client or per call.

Authentication

When the server runs with an identity provider, the SDK authenticates as a service account. Create one on the Members page of the web app, or with filament.serviceAccount.create(...) while signed in as an admin. Both return a client id and a client secret; the secret is shown once. Pass them to the client. It mints an access token through the server and mints again as the token nears expiry, so nothing about the identity provider reaches your code:

const filament = new FilamentClient({
  baseUrl: process.env.FILAMENT_URL ?? "http://localhost:8080",
  clientId: process.env.FILAMENT_CLIENT_ID!,
  clientSecret: process.env.FILAMENT_CLIENT_SECRET!,
});

A token minted elsewhere still works as token. For a local server with authentication disabled, pass auth: false instead; the client refuses to construct without one of the three.

Create and run a pipeline

A connector is an available integration, such as sample or stdout. A connection is a configured instance you create using that connector. The workflow is:

Create source and sink connections.
Discover the source’s resources and select which ones to include.
Create a pipeline and save its graph.
Submit a run.

This example routes five rows from each selected sample resource to stdout. It requires a running Filament deployment with a working execution backend.

import { randomUUID } from "node:crypto";
import { FilamentClient } from "@galaxy-io/filament-ts";

const filament = new FilamentClient({
  baseUrl: process.env.FILAMENT_URL ?? "http://localhost:8080",
  auth: false,
});
const name = `sample-to-stdout-${randomUUID().slice(0, 8)}`;

const { connection: source } = await filament.connection.create({
  name: `${name}-source`,
  kind: "CONNECTOR_KIND_SOURCE",
  connector: "sample",
});

const { connection: sink } = await filament.connection.create({
  name: `${name}-sink`,
  kind: "CONNECTOR_KIND_SINK",
  connector: "stdout",
});

const { resources } = await filament.connector.discoverResources({
  connectionId: source!.id,
});

// Select every available resource, or set this to ["users"].
const selectedResources = (resources ?? [])
  .filter((resource) => resource.isSelectable)
  .map((resource) => resource.name!);

const { pipeline } = await filament.pipeline.create({ name });

await filament.pipeline.version.create({
  pipelineId: pipeline!.id,
  graph: {
    nodes: [
      {
        id: "source",
        kind: "CONNECTOR_KIND_SOURCE",
        connectionId: source!.id,
        config: { rows: 5 },
      },
      {
        id: "sink",
        kind: "CONNECTOR_KIND_SINK",
        connectionId: sink!.id,
      },
    ],
    edges: selectedResources.map((resource) => ({
      fromNode: "source",
      toNode: "sink",
      resource,
    })),
  },
});

const submitted = await filament.pipeline.run({ pipelineId: pipeline!.id });

console.log("Pipeline:", pipeline!.id);
for (const edgeRun of submitted.edgeRuns ?? []) {
  console.log("Run:", edgeRun.run?.id, edgeRun.run?.status);
}

pipeline.create(...) creates the pipeline’s metadata and pipeline.version.create(...) saves its graph; the backend assigns the version. Both steps are required before the first run. The sample source discovers users and orders. To route every resource without enumerating them, save one edge with resource omitted. Submitting a run returns its id and initial status without waiting for completion. Inspect a run with filament.run.get({ runId }), or open the pipeline in the web app. The stdout sink writes rows to the worker’s logs.

API groups

Group	Examples
`connector`	`list`, `get`, `discoverResources`, `validateConfig`
`connection`	`create`, `get`, `list`, `update`, `delete`
`pipeline`	`create`, `get`, `list`, `update`, `validate`, `run`
`pipeline.version`	`create`, `get`, `list`
`pipeline.schedule`	`create`, `update`
`pipeline.notifier`	`create`, `list`, `update`, `delete`
`run`	`get`, `list`, `signal`
`metrics`	`queryTimeseries`, `queryAggregate`
`auth`	`getConfig`, `getSession`, `login`, `logout`
`member`	`list`, `invite`, `setRole`, `remove`
`serviceAccount`	`create`, `list`, `rotateSecret`, `remove`

The SDK covers unary API methods. Streaming TailRun is not included.

Responses and pagination

Methods resolve to typed responses. pipeline.create(...) resolves to an object whose pipeline property holds the created pipeline. Request and response types are exported under the Filament namespace. Fields omitted by the server are undefined, including lists, so iterate with response.pipelines ?? []. Protobuf 64-bit integer fields, such as timestamps and record counts, can be decimal strings; use Number(value) or BigInt(value) when needed. List methods paginate explicitly:

const page = await filament.pipeline.list({
  pagination: { pageSize: 25 },
});
const nextCursor = page.pagination?.nextCursor;

Pass nextCursor as pagination: { cursor: nextCursor, pageSize: 25 } to fetch the next page while a cursor is present. Omitting pagination returns the full result set.

Errors and retries

import { FilamentError } from "@galaxy-io/filament-ts";

try {
  await filament.pipeline.get({ id: "missing-pipeline" });
} catch (error) {
  if (error instanceof FilamentError) {
    console.log(error.statusCode); // e.g. 404
    console.log(error.body);       // Connect error code, message, and optional details
  }
}

Timeouts throw FilamentTimeoutError. The client retries failed requests twice by default; pass maxRetries: 0 on calls that must not repeat, since mutations are not generally idempotent.

Get started

Concepts

Usage

SDKs

Connectors

Deployment

API reference

Benchmarks

Contributing

Installation

Connect

Authentication

Create and run a pipeline

API groups

Errors and retries

​Installation

​Connect

​Authentication

​Create and run a pipeline

​API groups

​Responses and pagination

​Errors and retries

Installation

Connect

Authentication

Create and run a pipeline

API groups

Responses and pagination

Errors and retries