openplay-sdk

Type-safe TypeScript SDK for the OpenPlay Music API.

Installation

npm install openplay-sdk
# or
pnpm add openplay-sdk
# or
yarn add openplay-sdk

Quick Start

import { createClient } from 'openplay-sdk'

const client = createClient({
  apiKeyId: process.env.OPENPLAY_API_KEY_ID!,
  apiSecretKey: process.env.OPENPLAY_API_SECRET_KEY!,
})

// Search releases
const releases = await client.releases.search({ q: 'album name' })

// Get a specific artist
const artist = await client.artists.get('artist-id')

// Auto-paginate through all artists
for await (const artist of client.artists.searchAll()) {
  console.log(artist.name)
}

Features

• Full TypeScript support with complete type definitions
• Auto-pagination helpers for large result sets
• Webhook signature verification
• Bulk job utilities with polling
• Presigned URL upload support
• Comprehensive error handling

API Coverage

The SDK covers the following OpenPlay API resources:

• Artists - Create, read, update, delete, and search artists
• Labels - Manage record labels
• Publishers - Manage publishing entities
• Projects - Handle project/album metadata
• Releases - Manage release metadata and distribution
• Tracks - Track-level operations
• Works - Musical work/composition management
• Cover Art - Upload and manage artwork
• Art Resources - Additional artwork management

Environment Variables

You can use createClientFromEnv() which reads from these environment variables:

• OPENPLAY_API_KEY_ID - Your API key ID
• OPENPLAY_API_SECRET_KEY - Your API secret key
• OPENPLAY_BASE_URL (optional) - Custom API base URL

import { createClientFromEnv } from 'openplay-sdk'

const client = createClientFromEnv()

Pagination

Manual Pagination

const page1 = await client.artists.search({ limit: 50 })
const page2 = await client.artists.search({ limit: 50, offset: 50 })

Auto-Pagination

// Iterate through all results
for await (const artist of client.artists.searchAll()) {
  console.log(artist.name)
}

// Collect all results into an array
import { collectAll } from 'openplay-sdk'

const allArtists = await collectAll(client.artists.searchAll())

Error Handling

The SDK provides typed errors for different failure scenarios:

import {
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ValidationError,
  OpenPlayError,
} from 'openplay-sdk'

try {
  await client.artists.get('invalid-id')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Artist not found')
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${error.retryAfter}s`)
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid credentials')
  }
}

Webhooks

Verify incoming webhook signatures:

import { verifyWebhookSignature } from 'openplay-sdk/webhooks'

const isValid = verifyWebhookSignature({
  payload: requestBody,
  signature: request.headers['x-openplay-signature'],
  secret: process.env.OPENPLAY_WEBHOOK_SECRET!,
})

Bulk Operations

Submit bulk jobs and poll for completion:

import { submitAndWait } from 'openplay-sdk'

const result = await submitAndWait(
  () => client.releases.bulkCreate(releases),
  (jobId) => client.releases.getBulkStatus(jobId),
  { timeoutMs: 60000, pollIntervalMs: 2000 }
)

License

MIT