SDK 概要

drop.mov は公式の TypeScript SDK を提供しています。

@dropmov/client

@dropmov/client は drop.mov API のための型安全な HTTP クライアントです。

特徴

• 型安全: すべてのリクエスト/レスポンスに TypeScript 型定義
• 3つのコンテキスト: User / Manager / Viewer の使い分け
• エラーハンドリング: 構造化されたエラーオブジェクト
• カスタマイズ可能: カスタム fetch 関数のサポート
• AbortSignal 対応: リクエストのキャンセルをサポート

インストール

pnpm add @dropmov/client

または

npm install @dropmov/client

クイックスタート

import { DropClient } from '@dropmov/client';

// クライアントの初期化
const client = new DropClient({
  origin: 'https://api.drop.mov',
  getAccessToken: async () => {
    // JWT トークンを取得して返す
    const session = await supabase.auth.getSession();
    return session.data.session?.access_token ?? null;
  },
});

// User コンテキスト（JWT 認証）
const userCtx = client.user();
const { user, tenant, quota } = await userCtx.profile.get();

// Manager コンテキスト（Manager Token）
const managerCtx = client.manager(managerToken);
const { group, sources } = await managerCtx.group.get();

// Viewer コンテキスト（Viewer Token）
const viewerCtx = client.viewer(viewerToken);
const { url } = await viewerCtx.media.getPlayUrl(sourceId, { 
  key: 'playlist.mpd' 
});

詳細ドキュメント

詳しい使い方は @dropmov/client のドキュメント を参照してください。

SDK を使用するメリット

1. 型安全

IDE の補完が効き、コンパイル時にエラーを検出できます：

// ✅ 型エラーがあればコンパイル時に検出
const { comment } = await managerCtx.comments.create(sourceId, {
  content: 'Hello!',
  timestampSeconds: 30, // number 型が必須
});

2. 認証の自動処理

コンテキストに応じて適切なヘッダーが自動的に付与されます：

// Manager Token が自動的にヘッダーに設定される
const managerCtx = client.manager(managerToken);
await managerCtx.shares.list(); // Drop-Manager-Token ヘッダーが付与

3. エラーハンドリング

構造化されたエラーオブジェクトで詳細な情報を取得：

import { isApiError } from '@dropmov/client';

try {
  await managerCtx.comments.create(sourceId, { content: '' });
} catch (error) {
  if (isApiError(error)) {
    console.error(error.errorType);    // 'bad_request'
    console.error(error.message);      // 'Content is required'
    console.error(error.statusCode);   // 400
  }
}

直接 API を呼ぶ場合

SDK を使わずに直接 API を呼ぶことも可能です：

// fetch を直接使用
const response = await fetch('https://api.drop.mov/v1/manager', {
  headers: {
    'Drop-Manager-Token': managerToken,
  },
});

const data = await response.json();

ただし、型安全性やエラーハンドリングは自分で実装する必要があります。