@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.

Development

Building

npm run build

This runs prebuild (clean + generate package-info), compiles CJS and ESM targets into dist/, then runs postbuild (copies package.json, README, and module markers into dist/).

Publishing to npm

Always use the release script — never run npm publish directly from the project root.

npm run release

This script does everything in the correct order:

1. Cleans dist/ and removes tsconfig.tsbuildinfo
2. Builds CJS, ESM, and type declarations into dist/
3. Verifies that dist/ contains all required files (cjs/, esm/, types/)
4. Publishes from dist/ (not from root)

Running npm publish from the root directory is blocked by prepublishOnly — it will exit with an error reminding you to use npm run release.

Versioning

Bump the version in package.json before running npm run release. The build step automatically propagates the version to dist/package.json.