@yotoplay/yoto-sdk

A TypeScript SDK for Yoto's public API.

Installation

npm install @yotoplay/yoto-sdk

Quick Start

Basic Usage

import { yotoSdk, createYotoSdk } from '@yotoplay/yoto-sdk';

// Option 1: Use default instance
const devices = await yotoSdk.devices.getMyDevices();

// Option 2: Create custom configured instance
const customSdk = createYotoSdk({
  clientId: 'your-client-id' // Obtain from https://dashboard.yoto.dev/
});

JWT Authentication (Server-side Usage)

For server-side usage (e.g., API Gateway Lambda functions), you can provide a JWT token directly:

import { createYotoSdk } from '@yotoplay/yoto-sdk';

// Server-side usage with JWT
const sdk = createYotoSdk({
  jwt: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', // JWT token from event.headers
});

// No need to call login() - JWT is already provided
const devices = await sdk.devices.getMyDevices();
const cards = await sdk.content.getMyCards();

Main SDK Usage

The SDK is organized into logical namespaces that mirror the Yoto API structure:

import { yotoSdk } from '@yotoplay/yoto-sdk';

// Content API - manage cards and content
const cards = await yotoSdk.content.getMyCards();
const card = await yotoSdk.content.getCard('card-id');
const updatedCard = await yotoSdk.content.updateCard(cardData);

// Devices API - manage Yoto devices
const devices = await yotoSdk.devices.getMyDevices();

// Media API - handle media uploads and URLs
const uploadUrl = await yotoSdk.media.getUploadUrlForTranscode(sha256, filename);
await yotoSdk.media.uploadFile(uploadUrl.url, audioBuffer);
const mediaUrl = await yotoSdk.media.getMediaUrl(cardId, mediaId);

// Icons API - manage display icons
const icons = await yotoSdk.icons.getDisplayIcons();

// Family API - manage family images
const familyImages = await yotoSdk.family.getFamilyImages();
const familyImage = await yotoSdk.family.getFamilyImage('image-id');
await yotoSdk.family.uploadFamilyImage(imageBuffer, 'My Family Photo', true, ['family', 'photo']);

// Family Library Groups API - manage card groups
const groups = await yotoSdk.familyLibraryGroups.getGroups();
const group = await yotoSdk.familyLibraryGroups.createGroup({
  title: 'Bedtime Stories',
  description: 'Our favorite bedtime stories',
  cards: ['card1', 'card2', 'card3']
});

Error Handling

The SDK provides custom error types for better error handling:

import { YotoSdkError } from '@yotoplay/yoto-sdk';

try {
  await yotoSdk.devices.getMyDevices();
} catch (error) {
  if (error instanceof YotoSdkError) {
    console.error('SDK Error:', error.message);
    console.error('Status:', error.status);
    console.error('Response:', error.response);
  }
}

Utility Methods

// Extract media ID from track URL
const mediaId = yotoSdk.extractMediaId('yoto:#media123');
// Returns: 'media123'

Examples

Media Upload and Processing

import { yotoSdk } from '@yotoplay/yoto-sdk';
import fs from 'fs';

async function uploadAndProcessMedia() {
  // Read audio file
  const audioBuffer = fs.readFileSync('audio.mp3');
  const sha256 = 'your-file-hash';
  const filename = 'audio.mp3';

  // Get upload URL
  const uploadUrl = await yotoSdk.media.getUploadUrlForTranscode(sha256, filename);
  
  // Upload file
  await yotoSdk.media.uploadFile(uploadUrl.url, audioBuffer);
  
  // Get transcoded result
  const transcoded = await yotoSdk.media.getTranscodedUpload(uploadUrl.uploadId, true);
  
  console.log('Transcoded URL:', transcoded.url);
}

Family Management

import { yotoSdk } from '@yotoplay/yoto-sdk';
import fs from 'fs';

async function manageFamilyContent() {
  // Get all family images
  const familyImages = await yotoSdk.family.getFamilyImages();
  console.log('Family images:', familyImages);
  
  // Upload a new family image
  const imageBuffer = fs.readFileSync('family-photo.jpg');
  const newImage = await yotoSdk.family.uploadFamilyImage(
    imageBuffer, 
    'Our Family Photo', 
    true, // public
    ['family', 'photo', 'memories']
  );
  
  console.log('Uploaded image:', newImage.imageId);
  
  // Get a specific family image
  const image = await yotoSdk.family.getFamilyImage(newImage.imageId);
  console.log('Image details:', image);
}

Family Library Groups

import { yotoSdk } from '@yotoplay/yoto-sdk';

async function manageFamilyLibraryGroups() {
  // Get all groups
  const groups = await yotoSdk.familyLibraryGroups.getGroups();
  console.log('Existing groups:', groups);
  
  // Create a new group
  const newGroup = await yotoSdk.familyLibraryGroups.createGroup({
    title: 'Bedtime Stories',
    description: 'Our favorite bedtime stories collection',
    public: true,
    publicTags: ['bedtime', 'stories', 'kids'],
    cards: ['card1', 'card2', 'card3']
  });
  
  console.log('Created group:', newGroup.groupId);
  
  // Get group details
  const group = await yotoSdk.familyLibraryGroups.getGroup(newGroup.groupId);
  console.log('Group details:', group);
  
  // Update the group
  const updatedGroup = await yotoSdk.familyLibraryGroups.updateGroup(newGroup.groupId, {
    title: 'Updated Bedtime Stories',
    description: 'Updated description',
    cards: ['card1', 'card2', 'card3', 'card4'] // Add more cards
  });
  
  console.log('Updated group:', updatedGroup);
  
  // Delete the group
  await yotoSdk.familyLibraryGroups.deleteGroup(newGroup.groupId);
  console.log('Group deleted');
}

License

MIT