Tsonik

A TypeScript client library for the Iconik API that makes it easy to manage media assets, collections, jobs, and metadata. Named after the original Python nsa-pythonik library, this is the TypeScript version.

Features

• 🎯 TypeScript-first with full type safety
• 🚀 Promise-based API with async/await support
• 🛡️ Comprehensive error handling with detailed error types
• 📡 Built on Axios for reliable HTTP requests
• 🏗️ Resource-based architecture (assets, collections, jobs, metadata)
• 📚 Extensive documentation with real-world examples
• ⚡ Modern ES6+ JavaScript practices

Installation

npm install tsonik
# or
yarn add tsonik

Quick Start

import { Tsonik } from 'tsonik';

// Initialize the client
const client = new Tsonik({
  appId: 'your-app-id',
  authToken: 'your-auth-token'
});

// Get all assets
const assets = await client.assets.listAssets();
console.log(`Found ${assets.data.objects.length} assets`);

// Create a new asset
const newAsset = await client.assets.createAsset({
  title: 'My Video',
  type: 'ASSET',
  description: 'A sample video file'
});

// Get a specific asset
const asset = await client.assets.getAsset('asset-id');
console.log(`Asset: ${asset.data.title}`);

// Work with collections
const collection = await client.collections.createCollection({
  title: 'Marketing Assets',
  description: 'All marketing materials'
});

// Update metadata
await client.metadata.putMetadata(
  'assets',
  newAsset.data.id,
  {
    metadata_values: {
      'custom.project': {
        field_values: [{ value: 'Marketing Campaign' }],
        mode: 'overwrite'
      }
    }
  }
);

// Search for assets
const searchResults = await client.search.search({
  query: 'marketing video',
  size: 10,
  filter: {
    terms: {
      object_type: ['assets']
    }
  }
});
console.log(`Found ${searchResults.data.hits?.total?.value || 0} matching assets`);

Documentation

📖 Getting Started - Complete setup and first steps

💡 Usage Examples - Real-world examples for all features

📚 API Reference - Complete method documentation

🛠️ Best Practices - Performance tips and patterns

🌐 Full Documentation Site - Complete hosted documentation

Authentication

You'll need your Iconik App ID and Auth Token:

// From environment variables (recommended)
const client = new Tsonik({
  appId: process.env.ICONIK_APP_ID!,
  authToken: process.env.ICONIK_AUTH_TOKEN!
});

// Or directly (not recommended for production)
const client = new Tsonik({
  appId: 'your-app-id',
  authToken: 'your-auth-token',
  baseURL: 'https://app.iconik.io' // optional
});

Error Handling

import { IconikAPIError, IconikAuthError } from 'tsonik';

try {
  const asset = await client.assets.get('asset-id');
} catch (error) {
  if (error instanceof IconikAPIError) {
    console.log(`API Error ${error.status}: ${error.message}`);
  } else if (error instanceof IconikAuthError) {
    console.log('Authentication failed');
  }
}

Available Resources

• client.assets - Asset management (create, read, update, delete)
• client.collections - Collection management and asset organization
• client.jobs - Job monitoring and management (transcoding, analysis, etc.)
• client.files - File operations and metadata
• client.filesets - Fileset management
• client.metadata - Metadata operations for any object type
• client.formats - Format information and management
• client.search - Search across assets, collections, and other objects

Development

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Run tests:

npm test

4. Run tests in watch mode:

npm run test:watch

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

Releasing New Versions

This project uses semantic-release for automated versioning and publishing. When adding new features or fixing bugs:

Automated Release Process

1. Make changes and write tests
2. Use Conventional Commits format for your commit messages:
   • feat: add new feature - for features (minor version bump)
   • fix: resolve bug - for bug fixes (patch version bump)
   • Add BREAKING CHANGE: in commit body for breaking changes (major version bump)
3. Create a pull request to the main branch
4. After merging to main, semantic-release will automatically:
   • Determine the next version number based on your commits
   • Generate/update CHANGELOG.md
   • Create a GitHub Release
   • Publish to npm

Manual Release Process

If needed, trigger a manual release:

1. Go to GitHub Actions → "Version and Release" workflow
2. Click "Run workflow" and select the version type (patch/minor/major)

For more detailed instructions, see the full release guide.

License

MIT