tsonik
Version:
A TypeScript client library for the Iconik API based on Swagger documentation
208 lines (157 loc) ā¢ 6 kB
Markdown
# Tsonik
[](https://www.npmjs.com/package/tsonik)
[](https://opensource.org/licenses/MIT)
[](https://github.com/NorthShoreAutomation/tsonik/actions/workflows/unit-tests.yml)
[](https://github.com/NorthShoreAutomation/tsonik/actions/workflows/lint.yml)
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
```bash
npm install tsonik
# or
yarn add tsonik
```
## Quick Start
```typescript
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](https://northshoreautomation.github.io/tsonik/docs/getting-started.html)** - Complete setup and first steps
š” **[Usage Examples](https://northshoreautomation.github.io/tsonik/docs/examples.html)** - Real-world examples for all features
š **[API Reference](https://northshoreautomation.github.io/tsonik/docs/api-reference.html)** - Complete method documentation
š ļø **[Best Practices](https://northshoreautomation.github.io/tsonik/docs/best-practices.html)** - Performance tips and patterns
š **[Full Documentation Site](https://northshoreautomation.github.io/tsonik/)** - Complete hosted documentation
## Authentication
You'll need your Iconik App ID and Auth Token:
```typescript
// 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
```typescript
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:
```bash
npm install
```
2. Build the project:
```bash
npm run build
```
3. Run tests:
```bash
npm test
```
4. Run tests in watch mode:
```bash
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](https://www.conventionalcommit.org/) 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](dev-docs/RELEASE_GUIDE.md).
## License
MIT