Full-featured SDK for Node.js applications with TypeScript support
npm install @jewelmusic/sdk// ESM
import { JewelMusic } from '@jewelmusic/sdk';
// CommonJS
const { JewelMusic } = require('@jewelmusic/sdk');
// Initialize the client
const client = new JewelMusic({
apiKey: process.env.JEWELMUSIC_API_KEY,
environment: 'production', // or 'sandbox' for testing
timeout: 30000, // optional: request timeout in ms
maxRetries: 3 // optional: max retry attempts
});
// TypeScript types are included
import type { Track, Release, Artist } from '@jewelmusic/sdk';Full TypeScript definitions with IntelliSense support
Modern async/await syntax for all operations
Import only what you need for smaller bundles
// Upload a track with metadata
const track = await client.tracks.upload({
file: fs.createReadStream('./song.mp3'),
metadata: {
title: 'My Song',
artist: 'Artist Name',
album: 'Album Name',
genre: 'Electronic',
releaseDate: '2025-09-01',
copyright: '© 2025 Artist Name',
isrc: 'USJML2500001' // optional: we can generate one
},
artwork: fs.createReadStream('./cover.jpg')
});
console.log('Track uploaded:', track.id);
console.log('Processing status:', track.status);// Request transcription for multiple languages
const transcription = await client.transcription.create({
trackId: track.id,
languages: ['en', 'ka', 'es', 'fr'],
options: {
includeTimestamps: true,
wordLevelTimestamps: true,
speakerDiarization: true,
punctuation: true
}
});
// Get transcription status
const status = await client.transcription.getStatus(transcription.id);
// Download transcription in different formats
const srt = await client.transcription.download(transcription.id, 'srt');
const vtt = await client.transcription.download(transcription.id, 'vtt');
const json = await client.transcription.download(transcription.id, 'json');// Create a release for distribution
const release = await client.distribution.createRelease({
type: 'album', // or 'single', 'ep'
title: 'My Album',
artist: 'Artist Name',
tracks: [track.id, track2.id, track3.id],
releaseDate: '2025-09-01',
label: 'Independent',
copyright: {
text: '© 2025 Artist Name',
year: 2025
},
territories: ['worldwide'], // or specific country codes
platforms: [
'spotify',
'apple-music',
'youtube-music',
'amazon-music',
'tidal',
'deezer'
]
});
// Monitor distribution status
const distributionStatus = await client.distribution.getStatus(release.id);
console.log('Distribution progress:', distributionStatus.progress);// Get royalty reports
const reports = await client.royalties.getReports({
startDate: '2025-01-01',
endDate: '2025-01-31',
groupBy: 'platform' // or 'track', 'territory', 'day'
});
// Get detailed analytics
const analytics = await client.analytics.getTrackAnalytics(track.id, {
metrics: ['streams', 'revenue', 'listeners'],
period: 'last_30_days',
breakdown: 'daily'
});
// Download royalty statement
const statement = await client.royalties.downloadStatement({
year: 2025,
month: 1,
format: 'pdf' // or 'csv', 'xlsx'
});// Configure webhook endpoint
await client.webhooks.configure({
url: 'https://your-domain.com/webhooks',
events: [
'track.processed',
'release.live',
'royalty.reported'
],
secret: process.env.WEBHOOK_SECRET
});
// Verify webhook signature (in your webhook handler)
const isValid = client.webhooks.verifySignature(
payload,
signature,
secret
);
// Parse webhook event
const event = client.webhooks.parseEvent(payload);
switch(event.type) {
case 'track.processed':
console.log('Track processed:', event.data.trackId);
break;
case 'release.live':
console.log('Release is live:', event.data.releaseId);
break;
}import { JewelMusicError, ValidationError, RateLimitError } from '@jewelmusic/sdk';
try {
const track = await client.tracks.upload({
file: audioFile,
metadata: metadata
});
} catch (error) {
if (error instanceof ValidationError) {
console.error('Validation failed:', error.errors);
} else if (error instanceof RateLimitError) {
console.error('Rate limited. Retry after:', error.retryAfter);
} else if (error instanceof JewelMusicError) {
console.error('API error:', error.message, error.code);
} else {
console.error('Unexpected error:', error);
}
}const client = new JewelMusic({
// Required
apiKey: 'jml_live_your_api_key',
// Optional configurations
environment: 'production', // 'production' | 'sandbox'
apiVersion: 'v1', // API version
timeout: 30000, // Request timeout in milliseconds
maxRetries: 3, // Maximum retry attempts
retryDelay: 1000, // Initial retry delay in ms
// Advanced options
httpAgent: customAgent, // Custom HTTP agent
httpsAgent: customHttpsAgent, // Custom HTTPS agent
proxy: {
host: 'proxy.example.com',
port: 8080,
auth: {
username: 'user',
password: 'pass'
}
},
// Logging
logger: console, // Custom logger instance
logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
// Hooks
onRequest: (config) => {
console.log('Request:', config);
return config;
},
onResponse: (response) => {
console.log('Response:', response);
return response;
},
onError: (error) => {
console.error('Error:', error);
throw error;
}
});