@industream/datacatalog-client

TypeScript/JavaScript client library for the Industream DataCatalog REST API.

Installation

npm install @industream/datacatalog-client

Quick Start

import { DataCatalogClient } from '@industream/datacatalog-client';

const client = new DataCatalogClient({
  baseUrl: 'http://localhost:8002',
});

// List all catalog entries
const { items } = await client.catalogEntries.get();
console.log(`Found ${items.length} entries`);

Configuration

const client = new DataCatalogClient({
  baseUrl: 'https://datacatalog.example.com', // Required
  token: 'my-bearer-token',                   // Optional — sent as Authorization header
  userAgentPrefix: 'MyApp/1.0',               // Optional — prepended to User-Agent
  fetch: customFetchFn,                       // Optional — override global fetch
});

// Token can also be set later
client.setToken('new-token');

Services

Catalog Entries

import type { CatalogEntryCreateRequest } from '@industream/datacatalog-client/dto';

// List (with optional filters)
const entries = await client.catalogEntries.get({ sourceTypes: ['DataBridge'] });

// Create
const created = await client.catalogEntries.create([{
  name: 'Temperature Supply',
  dataType: 'Float64',
  sourceConnectionId: '...',
  sourceParams: { database: 'production', dataset: 'analog', column: 'temp_supply' },
  metadata: { unit: 'degC' },
  labelNames: ['analog', 'production'],
}]);

// Replace (upsert)
const result = await client.catalogEntries.replace([{ id: '...', name: 'Updated', ... }]);
// result.status === PersistenceStatus.Created | Updated

// Amend (partial update)
await client.catalogEntries.amend([{ id: '...', metadata: { unit: 'K' } }]);

// Delete
await client.catalogEntries.delete({ ids: ['...'] });
await client.catalogEntries.delete({ names: ['Temperature Supply'] });

Source Connections

const connections = await client.sourceConnections.get({ sourceTypes: ['DataBridge'] });

await client.sourceConnections.create([{
  name: 'DataBridge-Plant',
  sourceTypeId: '...',
  extensionData: { host: '10.0.0.1' },
}]);

await client.sourceConnections.delete({ ids: ['...'] });

Source Types

const types = await client.sourceTypes.get();

await client.sourceTypes.create([{ name: 'OPC-UA' }]);
await client.sourceTypes.delete({ names: ['OPC-UA'] });

Labels

const labels = await client.labels.get();

await client.labels.create([{ name: 'production' }]);
await client.labels.replace([{ id: '...', name: 'renamed-label' }]);
await client.labels.delete({ ids: ['...'] });

Asset Dictionaries & Nodes

// Dictionaries
const dicts = await client.assetDictionaries.get({ includeNodes: true, asTree: true });
const dict = await client.assetDictionaries.getById('...', { includeNodes: true, asTree: true });

await client.assetDictionaries.create([{ name: 'Plant Hierarchy' }]);
await client.assetDictionaries.amend({ id: '...', name: 'Renamed' });
await client.assetDictionaries.delete({ ids: ['...'] });

// Nodes
const nodes = await client.assetDictionaries.getNodes('dict-id');

const node = await client.assetDictionaries.createNode('dict-id', {
  name: 'Production Line 1',
  parentId: 'parent-node-id',
  order: 0,
});

await client.assetDictionaries.moveNode('dict-id', 'node-id', {
  newParentId: 'other-parent-id',
  newOrder: 2,
});

await client.assetDictionaries.deleteNode('dict-id', 'node-id');

// Entry assignments
await client.assetDictionaries.assignEntriesToNode('dict-id', 'node-id', {
  entryIds: ['entry-1', 'entry-2'],
});
await client.assetDictionaries.addEntriesToNode('dict-id', 'node-id', {
  entryIds: ['entry-3'],
});
await client.assetDictionaries.removeEntryFromNode('dict-id', 'node-id', 'entry-1');

Export / Import

import { ConflictStrategy } from '@industream/datacatalog-client/dto';

// Export as ZIP
const blob = await client.exportImport.export({
  include: ['sourceTypes', 'sourceConnections', 'labels', 'catalogEntries', 'assetDictionaries'],
  sourceConnectionIds: ['...'], // Optional — filter by connections
});

// Import from ZIP or CSV file
const report = await client.exportImport.import(file, ConflictStrategy.Replace);

console.log(`Created: ${report.catalogEntries.created}`);
console.log(`Replaced: ${report.catalogEntries.replaced}`);
console.log(`Skipped: ${report.catalogEntries.skipped}`);
console.log(`Warnings: ${report.warnings.length}`);

Health & Info

const info = await client.info.get();
// { name, version, databaseName, databaseVersion }

const health = await client.health.get();
// { status: 'Healthy', totalDuration, entries: { ... } }

Request Cancellation

All methods accept an optional AbortSignal:

const controller = new AbortController();

const entries = await client.catalogEntries.get(undefined, controller.signal);

// Cancel if needed
controller.abort();

Error Handling

import { ApiError, ProblemDetailsError } from '@industream/datacatalog-client';

try {
  await client.catalogEntries.create([...]);
} catch (error) {
  if (error instanceof ProblemDetailsError) {
    // Structured API error (application/problem+json)
    console.error(error.title);       // "Validation Error"
    console.error(error.status);      // 400
    console.error(error.detail);      // "Name is required"
    console.error(error.errors);      // [{ detail, code, pointer }]
  } else if (error instanceof ApiError) {
    // Raw HTTP error
    console.error(error.status, error.statusText);
  }
}

Module Exports

| Import path | Contents | |---|---| | @industream/datacatalog-client | DataCatalogClient, error classes, service types | | @industream/datacatalog-client/dto | All DTOs, enums, request/response types |

Both CommonJS (require) and ESM (import) are supported.