AtoM Client JS/TS SDK

TypeScript/JavaScript client library for the AtoM (Access to Memory) REST API.

Developed by The Archive and Heritage Group (Pty) Ltd.

Installation

npm install @archiveheritagegroup/atom-client
# or
yarn add @archiveheritagegroup/atom-client
# or
pnpm add @archiveheritagegroup/atom-client

Quick Start

import { AtomClient } from '@archiveheritagegroup/atom-client';

// Initialize client
const client = new AtomClient({
  baseUrl: 'https://your-atom-instance.com',
  apiKey: 'your-api-key', // Optional for public endpoints
});

// List descriptions
const descriptions = await client.descriptions.list({ limit: 10 });
for (const desc of descriptions.results) {
  console.log(`${desc.referenceCode}: ${desc.title}`);
}

// Get a specific description
const desc = await client.descriptions.get('my-fonds-slug', true);
console.log(desc.scopeAndContent);

// Search
const results = await client.search('photographs', { entityType: 'informationObject' });
console.log(`Found ${results.total} results`);

// Iterate over all descriptions
for await (const desc of client.descriptions.iterAll(100)) {
  process(desc);
}

Browser Usage

<script type="module">
  import { AtomClient } from 'https://unpkg.com/@archiveheritagegroup/atom-client';

  const client = new AtomClient({
    baseUrl: 'https://atom.example.com'
  });

  const descriptions = await client.descriptions.list();
  console.log(descriptions);
</script>

API Resources

Descriptions (Information Objects)

// List
const descriptions = await client.descriptions.list({
  limit: 10,
  offset: 0,
  repository: 'my-repo',
  level: 'fonds',
});

// Get single
const desc = await client.descriptions.get('slug-or-id');
const fullDesc = await client.descriptions.get('slug', true); // Include nested data

// Create
const newDesc = await client.descriptions.create({
  title: 'My New Fonds',
  levelOfDescription: 'fonds',
  repository: 'my-repository-slug',
});

// Update
const updated = await client.descriptions.update('slug', { title: 'Updated Title' });

// Delete
await client.descriptions.delete('slug');

// Iterate all (async generator)
for await (const desc of client.descriptions.iterAll(100)) {
  console.log(desc.title);
}

Authorities (Actors)

// List
const authorities = await client.authorities.list({ entityType: 'corporateBody' });

// Get
const actor = await client.authorities.get('person-slug');

// Create/Update/Delete
await client.authorities.create({ authorizedFormOfName: 'John Doe', entityType: 'person' });
await client.authorities.update('slug', { history: 'Updated history' });
await client.authorities.delete('slug');

Repositories

const repos = await client.repositories.list();
const repo = await client.repositories.get('repo-slug');

Taxonomies

const taxonomies = await client.taxonomies.list();
const terms = await client.taxonomies.getTerms('subject-taxonomy');

Search

// Basic search
const results = await client.search('query');

// Filtered search
const filtered = await client.search('photographs', {
  entityType: 'informationObject',
  limit: 50,
  repository: 'my-repo',
});

Error Handling

import {
  AtomClient,
  AtomAPIError,
  AtomAuthError,
  AtomNotFoundError,
} from '@archiveheritagegroup/atom-client';

try {
  const desc = await client.descriptions.get('non-existent');
} catch (error) {
  if (error instanceof AtomNotFoundError) {
    console.log('Description not found');
  } else if (error instanceof AtomAuthError) {
    console.log('Authentication failed');
  } else if (error instanceof AtomAPIError) {
    console.log(`API error: ${error.message} (${error.statusCode})`);
  }
}

Configuration

const client = new AtomClient({
  baseUrl: 'https://atom.example.com',
  apiKey: 'your-api-key',
  timeout: 60000, // Request timeout in milliseconds
  headers: {
    'X-Custom-Header': 'value',
  },
  // Custom fetch implementation (useful for Node.js < 18 or testing)
  fetch: customFetchFunction,
});

Node.js Usage

For Node.js versions < 18, you may need to provide a fetch implementation:

import { AtomClient } from '@archiveheritagegroup/atom-client';
import fetch from 'node-fetch';

const client = new AtomClient({
  baseUrl: 'https://atom.example.com',
  fetch: fetch as unknown as typeof globalThis.fetch,
});

TypeScript

Full TypeScript support with exported types:

import type {
  Description,
  Authority,
  Repository,
  PaginatedResponse,
  SearchResult,
} from '@archiveheritagegroup/atom-client';

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run typecheck

License

GPL-3.0 - See LICENSE for details.

Support

• Issues: https://github.com/ArchiveHeritageGroup/atom-client-js/issues
• Documentation: https://theahg.co.za/docs/sdk/javascript