SDK JavaScript / TypeScript

@videas/sdk est le client JavaScript/TypeScript officiel de l’API externe Videas. Il encapsule chaque endpoint dans une surface compacte et typée : vous n’avez plus à construire les URLs, définir les en-têtes ni analyser les réponses à la main. Il n’a aucune dépendance à l’exécution et fonctionne partout où fetch est disponible globalement — Node.js 18+, Bun, Deno et les navigateurs modernes.

Installation

npm install @videas/sdk
# ou : bun add @videas/sdk   /   yarn add @videas/sdk

Démarrage rapide

Créez un client avec la clé API de votre organisation, puis appelez n’importe quelle ressource :

import { createVideasClient } from '@videas/sdk'

const videas = createVideasClient({ apiKey: process.env.VIDEAS_API_KEY! })

// Lister les vidéos « prêtes » de votre organisation
const page = await videas.videos.list({ status: 'ready', limit: 50 })
console.log(`${page.count} vidéos`)
for (const video of page.results) {
  console.log(video.uid, video.name)
}

Vous créez une clé API depuis Paramètres → Clés API — voir Créer une clé API. La clé identifie à la fois l’organisation concernée par les appels et les portées qu’ils peuvent utiliser.

Authentification

La clé passée à createVideasClient est envoyée sous forme de jeton Bearer sur chaque requête. Chaque client est lié à une seule clé : vous pouvez donc créer plusieurs clients avec des clés différentes dans le même processus, sans risque :

const orgA = createVideasClient({ apiKey: cleA })
const orgB = createVideasClient({ apiKey: cleB })

Options du client : délais, annulation et réessais

Outre apiKey, createVideasClient accepte aussi :

timeout — délai d’expiration par requête en millisecondes. La requête est annulée et la promesse rejetée au dépassement. S’applique à toutes les requêtes, y compris le transfert d’octets de l’upload.
signal — un AbortSignal qui annule les requêtes en cours (partagé par toutes les requêtes du client).
retries — réessaie les requêtes idempotentes (GET/HEAD) ce nombre de fois supplémentaires sur erreur réseau ou 429/503, avec un court back-off. Les appels mutants (create/update/delete/upload) ne sont jamais réessayés.

const videas = createVideasClient({
  apiKey: process.env.VIDEAS_API_KEY!,
  timeout: 10_000, // 10 s
  retries: 2,
})

// Annuler les requêtes en cours avec un AbortController
const controller = new AbortController()
const scoped = createVideasClient({ apiKey, signal: controller.signal })
// controller.abort() annule toute requête encore en cours

Manipuler les vidéos

// Récupérer une vidéo
const video = await videas.videos.get('vid_123')

// Mettre à jour les champs éditoriaux (partiel — n'envoyez que ce qui change)
await videas.videos.update('vid_123', {
  name: 'Onboarding — v2',
  tags: ['onboarding', 'produit'],
})

// Supprimer (déplace vers la corbeille)
await videas.videos.delete('vid_123')

// Métadonnées du player + un jeton de lecture signé
const player = await videas.videos.getPlayer('vid_123')

videos.list() accepte les mêmes filtres que l’endpoint REST : search, status, tag, created_after, created_before, ordering, ainsi que limit (1 à 100) et offset pour la pagination.

Autres ressources

Le client est organisé par ressource ; chaque méthode renvoie directement le corps de la réponse (déjà analysé et typé).

// Assets — tous les types de médias (vidéo, audio, image, document)
await videas.assets.list({ limit: 20 })
await videas.assets.get('ast_123')

// Dossiers dans un espace de travail
await videas.folders.list('ws_123')
await videas.folders.create('ws_123', { name: 'Cours' })
await videas.folders.update('ws_123', 'fld_1', { name: 'Cours archivés' })
await videas.folders.delete('ws_123', 'fld_1')

// Espaces de travail et leurs réglages de domaines d'embed
await videas.workspaces.list()
await videas.workspaces.getEmbedSettings('ws_123')
await videas.workspaces.addEmbedDomain('ws_123', { domain: 'example.com' })

Les champs URL sont absolus. Les champs de réponse comme thumbnail_url sont renvoyés en URLs complètes, résolues contre l’URL de base de l’API Videas — utilisez-les directement, aucun hôte à préfixer.

Résoudre les URLs de lecture

La lecture se fait en deux étapes : obtenir un jeton signé depuis l’endpoint du player, puis l’échanger contre les vraies URLs de flux. Le helper resolvePlayback fait les deux en un seul appel :

const info = await videas.videos.resolvePlayback('vid_123')
console.log(info.hls_url) // URL HLS signée, à durée limitée

assets.resolvePlayback(uid) fait de même pour n’importe quel type d’asset. Préférez ces helpers ; si vous avez besoin du jeton lui-même, enchaînez les deux étapes à la main :

const player = await videas.videos.getPlayer('vid_123')
const info = await videas.playback.resolve({
  asset_id: 'vid_123',
  playback_token: player.playback_token,
})

Envoyer un fichier

upload.uploadFile() gère tout le flux résumable (TUS) pour vous : il crée la session d’envoi, transfère les octets, puis renvoie les métadonnées de l’asset créé (dont asset_uid, disponible immédiatement). Il accepte un Blob/File, un ArrayBuffer ou un tableau typé.

Exécutez-le sur votre serveur — il utilise votre clé secrète sk_ et ne doit pas tourner dans un navigateur. Pour un upload navigateur, créez la session côté serveur et transférez les octets vers l’URL-capacité renvoyée : voir Uploads reprenables avec un client TUS.

// Node.js — depuis le disque
import { readFile } from 'node:fs/promises'

const bytes = await readFile('intro.mp4')
await videas.upload.uploadFile({
  workspaceUid: 'ws_123',
  filename: 'intro.mp4',
  data: bytes,
  contentType: 'video/mp4',
  assetName: 'Intro onboarding',
  parentFolderUid: 'fld_1', // optionnel — par défaut la racine du workspace
})

Gros fichiers & progression

Le transfert des octets est découpé en chunks automatiquement — 32 Mio par requête par défaut, sous la limite serveur de 50 Mio par chunk — donc les vidéos de plusieurs gigaoctets s’envoient sans effort. Ajustez la taille de chunk et suivez la progression :

await videas.upload.uploadFile({
  workspaceUid: 'ws_123',
  filename: 'cours.mp4',
  data: bytes,
  chunkSize: 16 * 1024 * 1024, // optionnel — 32 Mio par défaut, doit rester ≤ 50 Mio
  onProgress: (sent, total) => console.log(`${Math.round((sent / total) * 100)} %`),
})

Besoin de piloter le transfert vous-même ? upload.createSession() expose l’appel bas niveau de création de session (vous fournissez les en-têtes TUS et transférez les octets vers la location renvoyée, manuellement).

Gestion des erreurs

Toute réponse non-2xx lève une erreur typée VideasApiError : vous pouvez utiliser try/catch au lieu de vérifier les codes de statut à la main. Elle porte le status HTTP, le code lisible par machine et le body d’erreur analysé :

import { VideasApiError } from '@videas/sdk'

try {
  await videas.videos.get('nexiste-pas')
} catch (err) {
  if (err instanceof VideasApiError) {
    console.error(err.status) // 404
    console.error(err.code)   // "NOT_FOUND"
    console.error(err.message) // message lisible
  } else {
    throw err // erreur réseau / inattendue
  }
}

Consultez le guide de l’API REST pour la liste complète des codes de statut (401, 403, 404, 429, …).

Types TypeScript

Chaque type de requête et de réponse est exporté par le paquet : vous pouvez donc annoter votre propre code :

import type { VideoDetailOut, VideoUpdateIn } from '@videas/sdk'

const changes: VideoUpdateIn = { name: 'Nouveau titre' }
const video: VideoDetailOut = await videas.videos.update('vid_123', changes)

Limitations actuelles

Pas encore de reprise entre appels. upload.uploadFile() envoie par chunks, mais un appel interrompu repart du premier chunk — reprendre une session partiellement envoyée n’est pas encore exposé. Pour une logique de reprise sur mesure, pilotez le transfert avec un client TUS dédié via upload.createSession() — voir Envoyer avec l’API REST.

Étapes suivantes

Créer une clé API
Utiliser l’API REST
Testez n’importe quel endpoint en direct avec Essayer dans la référence de l’API.