twelvelabs-js 0.1.0

package/dist/src/core.ts

@@ -0,0 +1,138 @@
+import fetch, { RequestInit, Response } from 'node-fetch';
+import FormData from 'form-data';
+import { API_KEY_HEADER } from './constants';
+import * as Errors from './error';
+import { convertKeysToCamelCase } from './util';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+export type RequestOptions = RequestInit & { params?: Record<string, any>; skipCamelKeys?: string[] };
+
+export interface APIClientOptions {
+  baseUrl: string;
+  apiKey: string;
+}
+
+export class APIClient {
+  baseUrl: string;
+  apiKey: string;
+
+  constructor({ baseUrl, apiKey }: APIClientOptions) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+
+  private async _request(
+    method: HttpMethod,
+    endpoint: string,
+    { params, body, skipCamelKeys, ...options }: RequestOptions = {},
+  ): Promise<any> {
+    const url = new URL(endpoint, this.baseUrl);
+    if (params) {
+      Object.keys(params).forEach((key) => url.searchParams.append(key, params![key]));
+    }
+
+    let headers = {
+      [API_KEY_HEADER]: this.apiKey,
+      ['content-type']: 'application/json',
+      ...options.headers,
+    };
+    if (body instanceof FormData) {
+      headers = {
+        ...headers,
+        ...body.getHeaders(),
+      };
+    }
+
+    const config: RequestInit = {
+      method,
+      headers,
+      body:
+        body ?
+          body instanceof FormData ?
+            body
+          : JSON.stringify(body)
+        : undefined,
+      ...options,
+    };
+
+    try {
+      const response = await fetch(url, config);
+      const contentType = response.headers.get('Content-Type');
+      let body = null;
+
+      if (contentType && contentType.includes('application/json')) {
+        const rawBody = await response.json();
+        body = convertKeysToCamelCase(rawBody, skipCamelKeys);
+      } else {
+        body = await response.text();
+      }
+
+      handleResponse(response, body, config);
+
+      return body;
+    } catch (error) {
+      if (error instanceof fetch.FetchError) {
+        if (error.code === 'ENOTFOUND') {
+          throw new Errors.APIConnectionError('API Connection Error', error);
+        } else if (error.type === 'request-timeout') {
+          throw new Errors.APITimeoutError('API Timeout Error', error);
+        }
+      }
+      if (error instanceof Error) {
+        throw error;
+      } else {
+        throw new Errors.APIError('An unknown error occurred');
+      }
+    }
+  }
+
+  async _get<T>(endpoint: string, params?: Record<string, any>, options: RequestOptions = {}) {
+    return (await this._request('GET', endpoint, { ...options, params })) as T;
+  }
+
+  async _post<T>(endpoint: string, data?: any, options: RequestOptions = {}) {
+    return (await this._request('POST', endpoint, { ...options, body: data })) as T;
+  }
+
+  async _patch<T>(endpoint: string, data?: any, options: RequestOptions = {}) {
+    return (await this._request('PATCH', endpoint, { ...options, body: data })) as T;
+  }
+
+  async _put<T>(endpoint: string, data?: any, options: RequestOptions = {}) {
+    return (await this._request('PUT', endpoint, { ...options, body: data })) as T;
+  }
+
+  async _delete<T>(endpoint: string, options: RequestOptions = {}) {
+    return (await this._request('DELETE', endpoint, options)) as T;
+  }
+}
+
+export function handleResponse(response: Response, body: any, request?: RequestInit): void {
+  if (!response.ok) {
+    const message = body && body.message ? body.message : response.statusText;
+    const headers = response.headers as unknown as Headers;
+    if (response.status >= 400 && response.status < 500) {
+      switch (response.status) {
+        case 400:
+          throw new Errors.BadRequestError(message, response.status, body, headers, request);
+        case 401:
+          throw new Errors.UnauthorizedError(message, response.status, body, headers, request);
+        case 403:
+          throw new Errors.ForbiddenError(message, response.status, body, headers, request);
+        case 404:
+          throw new Errors.NotFoundError(message, response.status, body, headers, request);
+        case 405:
+          throw new Errors.MethodNotAllowedError(message, response.status, body, headers, request);
+        case 409:
+          throw new Errors.ConflictError(message, response.status, body, headers, request);
+        case 429:
+          throw new Errors.TooManyRequestsError(message, response.status, body, headers, request);
+        default:
+          throw new Errors.APIError(message, response.status, body, headers, request);
+      }
+    } else if (response.status >= 500) {
+      throw new Errors.InternalServerError(message, response.status, body, headers, request);
+    }
+    throw new Errors.APIError(message, response.status, body, headers, request);
+  }
+}

package/dist/src/error.ts

@@ -0,0 +1,40 @@
+import { RequestInit } from 'node-fetch';
+export class TwelveLabsError extends Error {}
+
+export class APIError extends Error {
+  status: number | undefined;
+  body: any;
+  headers: Headers | undefined;
+  request?: RequestInit;
+
+  constructor(message: string, status?: number, body?: any, headers?: Headers, request?: RequestInit) {
+    super(message);
+    this.name = this.constructor.name;
+    this.status = status;
+    this.body = body;
+    this.headers = headers;
+    this.request = request;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class APIConnectionError extends APIError {
+  constructor(message: string = 'Connection error.', body?: any) {
+    super(message, undefined, body);
+  }
+}
+
+export class APITimeoutError extends APIError {
+  constructor(message: string = 'Request timed out.', body?: any) {
+    super(message, undefined, body);
+  }
+}
+
+export class BadRequestError extends APIError {}
+export class UnauthorizedError extends APIError {}
+export class ForbiddenError extends APIError {}
+export class NotFoundError extends APIError {}
+export class MethodNotAllowedError extends APIError {}
+export class ConflictError extends APIError {}
+export class TooManyRequestsError extends APIError {}
+export class InternalServerError extends APIError {}

package/dist/src/index.ts

@@ -0,0 +1,86 @@
+import { APIClient } from './core';
+import * as Resources from './resources';
+import { BASE_URL, DEFAULT_API_VERSION } from './constants';
+
+export interface ClientOptions {
+  apiKey: string;
+  version?: 'v1.1' | 'v1.2';
+}
+
+export class TwelveLabs extends APIClient {
+  engine: Resources.Engine;
+  index: Resources.Index;
+  task: Resources.Task;
+  search: Resources.Search;
+  generate: Resources.Generate;
+
+  baseUrl: string;
+  apiKey: string;
+
+  constructor({ apiKey, version = DEFAULT_API_VERSION }: ClientOptions) {
+    if (!apiKey) {
+      throw new Error(
+        'Provide `apiKey` to initialize a client. You can see the API Key in the Dashboard page: https://dashboard.playground.io',
+      );
+    }
+
+    const customBaseUrl = process.env.TWELVELABS_BASE_URL;
+    const baseUrl = `${customBaseUrl || BASE_URL}/${version}/`;
+
+    super({ baseUrl, apiKey });
+
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+
+    this.engine = new Resources.Engine(this);
+    this.index = new Resources.Index(this);
+    this.task = new Resources.Task(this);
+    this.search = new Resources.Search(this);
+    this.generate = new Resources.Generate(this);
+  }
+}
+
+export {
+  Engine,
+  Index,
+  IndexListWithPagination,
+  Video,
+  VideoListWithPagination,
+  Task,
+  TaskListWithPagination,
+  TaskStatus,
+  SearchResult,
+  SearchData,
+  GroupByVideoSearchData,
+  GenerateGistResult,
+  GenerateSummarizeResult,
+  GenerateOpenEndedTextResult,
+  PageInfo,
+} from './models';
+
+export {
+  CreateIndexParams,
+  CreateTaskParams,
+  ListIndexParams,
+  ListTaskParams,
+  ListVideoParams,
+  SearchOptions,
+  UpdateVideoParams,
+  VideoFilterOptions,
+  GenerateGistType,
+  GenerateSummarizeType,
+} from './resources';
+
+export {
+  TwelveLabsError,
+  APIConnectionError,
+  APITimeoutError,
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  MethodNotAllowedError,
+  NotFoundError,
+  TooManyRequestsError,
+  UnauthorizedError,
+  InternalServerError,
+} from './error';

package/dist/src/interfaces.ts

@@ -0,0 +1,6 @@
+export interface PageOptions {
+  page?: number;
+  pageLimit?: number;
+  sortBy?: 'created_at' | 'updated_at';
+  sortOption?: 'asc' | 'desc';
+}

package/dist/src/models/engine/index.ts

@@ -0,0 +1,23 @@
+export interface EngineResponse {
+  id: string;
+  author: string;
+  allowedEngineOptions: string[];
+  ready: boolean;
+  finetune: boolean;
+}
+
+export class Engine {
+  id: string;
+  author: string;
+  allowedEngineOptions: string[];
+  ready: boolean;
+  finetune: boolean;
+
+  constructor(res: EngineResponse) {
+    this.id = res.id;
+    this.author = res.author;
+    this.allowedEngineOptions = res.allowedEngineOptions;
+    this.ready = res.ready;
+    this.finetune = res.finetune;
+  }
+}

package/dist/src/models/generate/index.ts

@@ -0,0 +1,32 @@
+export interface GenerateOpenEndedTextResult {
+  id: string;
+  data: string;
+}
+
+export interface GenerateSummarizeChapterResult {
+  chapterNumber: number;
+  start: number;
+  end: number;
+  chapterTitle: string;
+  chapterSummary: string;
+}
+
+export interface GenerateSummarizeHighlightResult {
+  start: number;
+  end: number;
+  highlight: string;
+}
+
+export interface GenerateSummarizeResult {
+  id: string;
+  summary?: string;
+  chapters?: GenerateSummarizeChapterResult[];
+  highlights?: GenerateSummarizeHighlightResult[];
+}
+
+export interface GenerateGistResult {
+  id: string;
+  title?: string;
+  topics?: string[];
+  hashtags?: string[];
+}

package/dist/src/models/index/index.ts

@@ -0,0 +1,135 @@
+import { RequestOptions } from '../../core';
+import * as Resources from '../../resources';
+import { PageInfo } from '../interfaces';
+import { SearchResult } from '../search';
+import { Task, TaskStatus } from '../task';
+import { Video } from '../video';
+
+export interface IndexResponse {
+  id: string;
+  indexName: string;
+  engines: IndexEngineResponse[];
+  videoCount: number;
+  totalDuration: number;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export class Index {
+  private readonly _resource: Resources.Index;
+
+  id: string;
+  name: string;
+  engines: IndexEngine[];
+  videoCount: number;
+  totalDuration: number;
+  createdAt: string;
+  updatedAt?: string;
+
+  constructor(resource: Resources.Index, data: IndexResponse) {
+    this._resource = resource;
+    this.id = data.id;
+    this.name = data.indexName;
+    this.engines = data.engines.map((v) => new IndexEngine(v));
+    this.videoCount = data.videoCount;
+    this.totalDuration = data.totalDuration;
+    this.createdAt = data.createdAt;
+    this.updatedAt = data.updatedAt;
+  }
+
+  // Index related methods
+
+  async retrieve(options: RequestOptions = {}): Promise<Index> {
+    return await this._resource.retrieve(this.id, options);
+  }
+
+  async update(name: string, options: RequestOptions = {}): Promise<void> {
+    return await this._resource.update(this.id, name, options);
+  }
+
+  async delete(options: RequestOptions = {}): Promise<void> {
+    return await this._resource.delete(this.id, options);
+  }
+
+  // Task related methods
+
+  async createTask(
+    body: Omit<Resources.CreateTaskParams, 'indexId'>,
+    options: RequestOptions = {},
+  ): Promise<Task> {
+    return await this._resource._client.task.create({ ...body, indexId: this.id }, options);
+  }
+
+  async taskStatus(options: RequestOptions = {}): Promise<TaskStatus> {
+    return await this._resource._client.task.status(this.id, options);
+  }
+
+  async taskExternalProvider(url: string, options: RequestOptions = {}): Promise<Task> {
+    return await this._resource._client.task.externalProvider(this.id, url, options);
+  }
+
+  // Video related methods
+
+  async listVideos(params: Resources.ListVideoParams = {}, options: RequestOptions = {}): Promise<Video[]> {
+    return await this._resource.video.list(this.id, params, options);
+  }
+
+  // Search related methods
+
+  async query(
+    body: Omit<Resources.SearchOptions, 'indexId'>,
+    options: RequestOptions = {},
+  ): Promise<SearchResult> {
+    return await this._resource._client.search.query({ ...body, indexId: this.id }, options);
+  }
+}
+
+export class IndexListWithPagination {
+  private readonly _resource: Resources.Index;
+  private readonly _originParams: Resources.ListIndexParams;
+  data: Index[];
+  pageInfo: PageInfo;
+
+  constructor(
+    resource: Resources.Index,
+    originParams: Resources.ListIndexParams,
+    data: IndexResponse[],
+    pageInfo: PageInfo,
+  ) {
+    this._resource = resource;
+    this._originParams = originParams;
+    this.data = data.map((v) => new Index(resource, v));
+    this.pageInfo = pageInfo;
+  }
+
+  async next(): Promise<Index[] | null> {
+    if (this.pageInfo.page >= this.pageInfo.totalPage) {
+      return null;
+    }
+    const params = { ...this._originParams };
+    params.page = this.pageInfo.page + 1;
+    const res = await this._resource.listPagination(params);
+    this.pageInfo = res.pageInfo;
+    return res.data;
+  }
+}
+
+interface IndexEngineResponse {
+  id: string;
+  engineName: string;
+  engineOptions: string[];
+  addons?: string[];
+}
+
+class IndexEngine {
+  id: string;
+  name: string;
+  options: string[];
+  addons?: string[];
+  constructor(res: IndexEngineResponse) {
+    this.id = res.id;
+    this.name = res.engineName;
+    this.options = res.engineOptions;
+    this.addons = res.addons;
+  }
+}

package/dist/src/models/index.ts

@@ -0,0 +1,7 @@
+export * from './interfaces';
+export * from './engine';
+export * from './index/';
+export * from './task';
+export * from './video';
+export * from './search';
+export * from './generate';

package/dist/src/models/interfaces.ts

@@ -0,0 +1,6 @@
+export interface PageInfo {
+  limitPerPage: number;
+  page: number;
+  totalPage: number;
+  totalResults: number;
+}

package/dist/src/models/search/index.ts

@@ -0,0 +1,66 @@
+import * as Resources from '../../resources';
+
+export interface SearchResultResponse {
+  searchPool: SearchPool;
+  data: SearchData[];
+  pageInfo: SearchPageInfo;
+}
+
+export class SearchResult {
+  private readonly _resource: Resources.Search;
+  pool: SearchPool;
+  data: SearchData[] | GroupByVideoSearchData[];
+  pageInfo: SearchPageInfo;
+  constructor(resource: Resources.Search, data: SearchResultResponse) {
+    this._resource = resource;
+    this.pool = data.searchPool;
+    this.data = data.data;
+    this.pageInfo = data.pageInfo;
+  }
+
+  async next(): Promise<SearchData[] | GroupByVideoSearchData[] | null> {
+    const { nextPageToken } = this.pageInfo;
+    if (!nextPageToken) {
+      return null;
+    }
+    const res = await this._resource.byPageToken(nextPageToken);
+    this.pageInfo = res.pageInfo;
+    return res.data;
+  }
+}
+
+export interface SearchData {
+  score: number;
+  start: number;
+  end: number;
+  videoId: string;
+  metadata?: Record<string, any>;
+  confidence: string;
+  thumbnailUrl?: string;
+  moduleConfidence?: Record<string, any>;
+  modules?: SearchModule[];
+}
+
+interface SearchModule {
+  type: 'visual' | 'conversation' | 'text_in_video' | 'logo';
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export interface GroupByVideoSearchData {
+  clips?: SearchData[];
+  id: string;
+}
+
+interface SearchPool {
+  totalCount: number;
+  totalDuration: number;
+  indexId: string;
+}
+
+interface SearchPageInfo {
+  limitPerPage: number;
+  totalResults: number;
+  pageExpiredAt: string;
+  nextPageToken?: string;
+  prevPageToken?: string;
+}

package/dist/src/models/task/index.ts

@@ -0,0 +1,132 @@
+import { RequestOptions } from '../../core';
+import * as Resources from '../../resources';
+import { PageInfo } from '../interfaces';
+
+export interface TaskResponse {
+  id: string;
+  indexId: string;
+  videoId?: string[];
+  estimatedTime?: string;
+  status: string;
+  metadata: Record<string, any>;
+  process?: Record<string, any>;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export class Task {
+  private readonly _resource: Resources.Task;
+  id: string;
+  indexId: string;
+  videoId?: string[];
+  estimatedTime?: string;
+  status: string;
+  metadata: Record<string, any>;
+  process?: TaskProcess;
+  hls?: TaskHLS;
+  createdAt: string;
+  updatedAt?: string;
+
+  constructor(resource: Resources.Task, data: TaskResponse) {
+    this._resource = resource;
+    this.id = data.id;
+    this.indexId = data.indexId;
+    this.videoId = data.videoId;
+    this.estimatedTime = data.estimatedTime;
+    this.status = data.status;
+    this.metadata = data.metadata;
+    this.process = data.process;
+    this.createdAt = data.createdAt;
+    this.updatedAt = data.updatedAt;
+  }
+
+  async retrieve(options: RequestOptions = {}): Promise<Task> {
+    return await this._resource.retrieve(this.id, options);
+  }
+
+  async delete(options: RequestOptions = {}): Promise<void> {
+    await this._resource.delete(this.id, options);
+  }
+
+  async waitForDone(sleepInterval: number = 5000, callback?: (task: Task) => void): Promise<Task> {
+    const isDone = () => this.status === 'ready' || this.status === 'failed';
+    if (sleepInterval <= 0) {
+      throw new Error('sleepInterval must be greater than 0');
+    }
+
+    let done = isDone();
+
+    while (!done) {
+      await this.sleep(sleepInterval);
+      const task = await this.retrieve();
+
+      this.estimatedTime = task.estimatedTime;
+      this.status = task.status;
+      this.metadata = task.metadata;
+      this.process = task.process;
+
+      done = isDone();
+
+      if (callback) {
+        callback(this);
+      }
+    }
+
+    return this;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+export class TaskListWithPagination {
+  private readonly _resource: Resources.Task;
+  private readonly _originParams: Resources.ListTaskParams;
+  data: Task[];
+  pageInfo: PageInfo;
+
+  constructor(
+    resource: Resources.Task,
+    originParams: Resources.ListTaskParams,
+    data: TaskResponse[],
+    pageInfo: PageInfo,
+  ) {
+    this._resource = resource;
+    this._originParams = originParams;
+    this.data = data.map((v) => new Task(resource, v));
+    this.pageInfo = pageInfo;
+  }
+
+  async next(): Promise<Task[] | null> {
+    if (this.pageInfo.page >= this.pageInfo.totalPage) {
+      return null;
+    }
+    const params = { ...this._originParams };
+    params.page = this.pageInfo.page + 1;
+    const res = await this._resource.listPagination(params);
+    this.pageInfo = res.pageInfo;
+    return res.data;
+  }
+}
+
+export interface TaskStatus {
+  indexId: string;
+  ready: number;
+  validating: number;
+  pending: number;
+  failed: number;
+  totalResult: number;
+}
+
+export interface TaskHLS {
+  videoUrl?: string;
+  thumbnailUrls?: string[];
+  status?: string;
+  updatedAt: string;
+}
+
+export interface TaskProcess {
+  percentage?: number;
+  remainSeconds?: number;
+}