twelvelabs-js 0.1.0

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

@@ -0,0 +1,135 @@
+import { RequestOptions } from '../../core';
+import * as Resources from '../../resources';
+import { GenerateGistResult, GenerateOpenEndedTextResult } from '../generate';
+import { PageInfo } from '../interfaces';
+
+export interface VideoResponse {
+  id: string;
+  metadata: VideoMetadata;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export class Video {
+  private readonly _resource: Resources.Video;
+  private readonly _indexId: string;
+  id: string;
+  metadata: VideoMetadata & Record<string, any>;
+  createdAt: string;
+  updatedAt?: string;
+
+  constructor(resource: Resources.Video, indexId: string, data: VideoResponse) {
+    this._resource = resource;
+    this._indexId = indexId;
+    this.id = data.id;
+    this.metadata = data.metadata;
+    this.createdAt = data.createdAt;
+    this.updatedAt = data.updatedAt;
+  }
+
+  // Video related methods
+
+  async update(params: Resources.UpdateVideoParams, options: RequestOptions = {}): Promise<void> {
+    return await this._resource.update(this._indexId, this.id, params, options);
+  }
+
+  async delete(options: RequestOptions = {}): Promise<void> {
+    return await this._resource.delete(this._indexId, this.id, options);
+  }
+
+  async transcription(
+    filter?: Resources.VideoFilterOptions,
+    options: RequestOptions = {},
+  ): Promise<VideoValue[]> {
+    return await this._resource.transcription(this._indexId, this.id, filter, options);
+  }
+
+  async textInVideo(
+    filter: Resources.VideoFilterOptions = {},
+    options: RequestOptions = {},
+  ): Promise<VideoValue[]> {
+    return await this._resource.textInVideo(this._indexId, this.id, filter, options);
+  }
+
+  async logo(filter: Resources.VideoFilterOptions = {}, options: RequestOptions = {}): Promise<VideoValue[]> {
+    return await this._resource.logo(this._indexId, this.id, filter, options);
+  }
+
+  async thumbnail(time?: number, options: RequestOptions = {}): Promise<string> {
+    return await this._resource.thumbnail(this._indexId, this.id, time, options);
+  }
+
+  // Generate related methods
+
+  async generateGist(
+    types: Resources.GenerateGistType[],
+    options: RequestOptions = {},
+  ): Promise<GenerateGistResult> {
+    return await this._resource._client.generate.gist(this.id, types, options);
+  }
+
+  async generateSummarize(
+    type: Resources.GenerateSummarizeType,
+    prompt?: string,
+    temperature?: number,
+    options: RequestOptions = {},
+  ): Promise<GenerateGistResult> {
+    return await this._resource._client.generate.summarize(this.id, type, prompt, temperature, options);
+  }
+
+  async generateText(
+    prompt: string,
+    temperature?: number,
+    options: RequestOptions = {},
+  ): Promise<GenerateOpenEndedTextResult> {
+    return await this._resource._client.generate.text(this.id, prompt, temperature, options);
+  }
+}
+
+export class VideoListWithPagination {
+  private readonly _resource: Resources.Video;
+  private readonly _originParams: Resources.ListVideoParams;
+  private readonly _indexId: string;
+  data: Video[];
+  pageInfo: PageInfo;
+
+  constructor(
+    resource: Resources.Video,
+    originParams: Resources.ListVideoParams,
+    indexId: string,
+    data: VideoResponse[],
+    pageInfo: PageInfo,
+  ) {
+    this._resource = resource;
+    this._originParams = originParams;
+    this._indexId = indexId;
+    this.data = data.map((v) => new Video(resource, indexId, v));
+    this.pageInfo = pageInfo;
+  }
+
+  async next(): Promise<Video[] | 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(this._indexId, params);
+    this.pageInfo = res.pageInfo;
+    return res.data;
+  }
+}
+
+interface VideoMetadata {
+  filename: string;
+  duration: number;
+  fps: number;
+  width: number;
+  height: number;
+  size: number;
+}
+
+export interface VideoValue {
+  start: number;
+  end: number;
+  value: string;
+}

package/dist/src/resource.ts

@@ -0,0 +1,21 @@
+import { TwelveLabs } from '.';
+import { APIClient, RequestOptions } from './core';
+
+export class APIResource extends APIClient {
+  readonly _client: TwelveLabs;
+  readonly _get: <T>(endpoint: string, params?: Record<string, any>, options?: RequestOptions) => Promise<T>;
+  readonly _post: <T>(endpoint: string, data?: any, options?: RequestOptions) => Promise<T>;
+  readonly _patch: <T>(endpoint: string, data?: any, options?: RequestOptions) => Promise<T>;
+  readonly _put: <T>(endpoint: string, data?: any, options?: RequestOptions) => Promise<T>;
+  readonly _delete: <T>(endpoint: string, options?: RequestOptions) => Promise<T>;
+
+  constructor(client: TwelveLabs) {
+    super(client);
+    this._client = client;
+    this._get = client._get;
+    this._post = client._post;
+    this._patch = client._patch;
+    this._put = client._put;
+    this._delete = client._delete;
+  }
+}

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

@@ -0,0 +1,17 @@
+import { RequestOptions } from '../../core';
+import * as Models from '../../models';
+import { APIResource } from '../../resource';
+
+export class Engine extends APIResource {
+  async retrieve(id: string, options: RequestOptions = {}): Promise<Models.Engine> {
+    const endpoint = `engines/${id}`;
+    const res = await this._get<Models.EngineResponse>(endpoint, {}, options);
+    return new Models.Engine(res);
+  }
+
+  async list(options: RequestOptions = {}): Promise<Models.Engine[]> {
+    const endpoint = 'engines';
+    const res = await this._get<{ data: Models.EngineResponse[] }>(endpoint, {}, options);
+    return res.data.map((v) => new Models.Engine(v));
+  }
+}

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

@@ -0,0 +1,56 @@
+import { RequestOptions } from '../../core';
+import * as Models from '../../models';
+import { APIResource } from '../../resource';
+import { convertKeysToSnakeCase, removeUndefinedValues } from '../../util';
+import { GenerateGistType, GenerateSummarizeType } from './interfaces';
+
+export class Generate extends APIResource {
+  async gist(
+    videoId: string,
+    types: GenerateGistType[],
+    options: RequestOptions = {},
+  ): Promise<Models.GenerateGistResult> {
+    const _body = convertKeysToSnakeCase({
+      videoId,
+      types,
+    });
+    const res = await this._post<Models.GenerateGistResult>('gist', _body, options);
+    return res;
+  }
+
+  async summarize(
+    videoId: string,
+    type: GenerateSummarizeType,
+    prompt?: string,
+    temperature?: number,
+    options: RequestOptions = {},
+  ): Promise<Models.GenerateSummarizeResult> {
+    const _body = convertKeysToSnakeCase({
+      videoId,
+      type,
+      prompt,
+      temperature,
+    });
+    const res = await this._post<Models.GenerateSummarizeResult>(
+      'summarize',
+      removeUndefinedValues(_body),
+      options,
+    );
+    return res;
+  }
+
+  async text(
+    videoId: string,
+    prompt: string,
+    temperature?: number,
+    options: RequestOptions = {},
+  ): Promise<Models.GenerateOpenEndedTextResult> {
+    const _body = convertKeysToSnakeCase({
+      videoId,
+      prompt,
+      temperature,
+    });
+    const res = await this._post<Models.GenerateOpenEndedTextResult>('generate', _body, options);
+    return res;
+  }
+}

package/dist/src/resources/generate/interfaces.ts

@@ -0,0 +1,2 @@
+export type GenerateGistType = 'topic' | 'hashtag' | 'title';
+export type GenerateSummarizeType = 'summary' | 'chapter' | 'highlight';

package/dist/src/resources/index/index.ts

@@ -0,0 +1,91 @@
+import { TwelveLabs } from '../..';
+import { RequestOptions } from '../../core';
+import * as Models from '../../models';
+import { APIResource } from '../../resource';
+import { convertKeysToSnakeCase, handleComparisonParams, removeUndefinedValues } from '../../util';
+import { Video as VideoResource } from '../video';
+import { CreateIndexParams, ListIndexParams } from './interfaces';
+
+export class Index extends APIResource {
+  video: VideoResource;
+
+  constructor(client: TwelveLabs) {
+    super(client);
+    this.video = new VideoResource(client);
+  }
+
+  async retrieve(id: string, options: RequestOptions = {}): Promise<Models.Index> {
+    const res = await this._get<Models.IndexResponse>(`indexes/${id}`, {}, options);
+    return new Models.Index(this, res);
+  }
+
+  async list(
+    { id, name, createdAt, updatedAt, ...restParams }: ListIndexParams = {},
+    options: RequestOptions = {},
+  ): Promise<Models.Index[]> {
+    const _params = convertKeysToSnakeCase({
+      ...restParams,
+      _id: id,
+      indexName: name,
+    });
+    handleComparisonParams(_params, 'createdAt', createdAt);
+    handleComparisonParams(_params, 'updatedAt', updatedAt);
+    const res = await this._get<{ data: Models.IndexResponse[] }>(
+      'indexes',
+      removeUndefinedValues(_params),
+      options,
+    );
+    return res.data.map((v) => new Models.Index(this, v));
+  }
+
+  async listPagination(
+    { id, name, createdAt, updatedAt, ...restParams }: ListIndexParams = {},
+    options: RequestOptions = {},
+  ): Promise<Models.IndexListWithPagination> {
+    const originParams = { id, name, ...restParams };
+    const _params = convertKeysToSnakeCase({
+      ...restParams,
+      _id: id,
+      indexName: name,
+    });
+    handleComparisonParams(_params, 'createdAt', createdAt);
+    handleComparisonParams(_params, 'updatedAt', updatedAt);
+    const res = await this._get<{ data: Models.IndexResponse[]; pageInfo: Models.PageInfo }>(
+      'indexes',
+      removeUndefinedValues(_params),
+      options,
+    );
+    return new Models.IndexListWithPagination(this, originParams, res.data, res.pageInfo);
+  }
+
+  async create(
+    { name, engines, addons }: CreateIndexParams,
+    options: RequestOptions = {},
+  ): Promise<Models.Index> {
+    const _body = {
+      indexName: name,
+      engines: engines.map(({ name, options }) => ({ engineName: name, engineOptions: options })),
+      addons,
+    };
+    const res = await this._post<{ id: string }>(
+      'indexes',
+      removeUndefinedValues(convertKeysToSnakeCase(_body)),
+      options,
+    );
+    return await this.retrieve(res.id);
+  }
+
+  async update(id: string, name: string, options: RequestOptions = {}): Promise<void> {
+    await this._put<void>(
+      `indexes/${id}`,
+      convertKeysToSnakeCase({
+        indexName: name,
+      }),
+      options,
+    );
+  }
+
+  async delete(id: string, options: RequestOptions = {}): Promise<void> {
+    await this._delete<void>(`indexes/${id}`, options);
+  }
+}

package/dist/src/resources/index/interfaces.ts

@@ -0,0 +1,16 @@
+import { PageOptions } from '../../interfaces';
+
+export interface ListIndexParams extends PageOptions {
+  id?: string;
+  name?: string;
+  engineOptions?: string[];
+  engineFamily?: 'marengo' | 'pegasus';
+  createdAt?: string | Record<string, string>;
+  updatedAt?: string | Record<string, string>;
+}
+
+export interface CreateIndexParams {
+  name: string;
+  engines: { name: string; options: string[] }[];
+  addons?: string[];
+}

package/dist/src/resources/index.ts

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

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

@@ -0,0 +1,28 @@
+import { RequestOptions } from '../../core';
+import * as Models from '../../models';
+import { APIResource } from '../../resource';
+import { convertKeysToSnakeCase, removeUndefinedValues } from '../../util';
+import { SearchOptions } from './interfaces';
+
+export class Search extends APIResource {
+  async query(
+    { options: searchOptions, ...restBody }: SearchOptions,
+    options: RequestOptions = {},
+  ): Promise<Models.SearchResult> {
+    const _body = convertKeysToSnakeCase({
+      ...restBody,
+      searchOptions,
+    });
+    const res = await this._post<Models.SearchResultResponse>(
+      'search',
+      removeUndefinedValues(_body),
+      options,
+    );
+    return new Models.SearchResult(this, res);
+  }
+
+  async byPageToken(pageToken: string, options: RequestOptions = {}): Promise<Models.SearchResult> {
+    const res = await this._get<Models.SearchResultResponse>(`search/${pageToken}`, {}, options);
+    return new Models.SearchResult(this, res);
+  }
+}

package/dist/src/resources/search/interfaces.ts

@@ -0,0 +1,12 @@
+export interface SearchOptions {
+  indexId: string;
+  query: string | Record<string, any>;
+  options?: ('visual' | 'conversation' | 'text_in_video' | 'logo')[];
+  groupBy?: 'video' | 'clip';
+  threshold?: 'high' | 'medium' | 'low';
+  operator?: 'or' | 'and';
+  conversationOption?: 'semantic' | 'exact_match';
+  filter?: Record<string, any>;
+  pageLimit?: number;
+  sortOption?: 'score' | 'clip_count';
+}

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

@@ -0,0 +1,161 @@
+import path from 'path';
+import FormData from 'form-data';
+import { RequestOptions } from '../../core';
+import * as Models from '../../models';
+import { convertKeysToSnakeCase, handleComparisonParams, removeUndefinedValues } from '../../util';
+import { CreateTaskParams, ListTaskParams } from './interfaces';
+import { createReadStream } from 'fs';
+import { APIResource } from '../../resource';
+
+export class Task extends APIResource {
+  async retrieve(id: string, options: RequestOptions = {}): Promise<Models.Task> {
+    const res = await this._get<Models.TaskResponse>(`tasks/${id}`, {}, options);
+    return new Models.Task(this, res);
+  }
+
+  async list(
+    { id, createdAt, updatedAt, ...restParams }: ListTaskParams = {},
+    options: RequestOptions = {},
+  ): Promise<Models.Task[]> {
+    const _params = convertKeysToSnakeCase({
+      ...restParams,
+      _id: id,
+    });
+    handleComparisonParams(_params, 'createdAt', createdAt);
+    handleComparisonParams(_params, 'updatedAt', updatedAt);
+    const res = await this._get<{ data: Models.TaskResponse[] }>(
+      'tasks',
+      removeUndefinedValues(_params),
+      options,
+    );
+    return res.data.map((v) => new Models.Task(this, v));
+  }
+
+  async listPagination(
+    { id, createdAt, updatedAt, ...restParams }: ListTaskParams = {},
+    options: RequestOptions = {},
+  ): Promise<Models.TaskListWithPagination> {
+    const originParams = { id, ...restParams };
+    const _params = convertKeysToSnakeCase({
+      ...restParams,
+      _id: id,
+    });
+    handleComparisonParams(_params, 'updatedAt', updatedAt);
+    const res = await this._get<{ data: Models.TaskResponse[]; pageInfo: Models.PageInfo }>(
+      'tasks',
+      removeUndefinedValues(_params),
+      options,
+    );
+    return new Models.TaskListWithPagination(this, originParams, res.data, res.pageInfo);
+  }
+
+  async create(body: CreateTaskParams, options: RequestOptions = {}): Promise<Models.Task> {
+    if (!body.file && !body.url) {
+      throw new Error('Either file or url must be provided');
+    }
+
+    const formData = new FormData();
+
+    formData.append('index_id', body.indexId);
+    if (body.url) formData.append('video_url', body.url);
+    if (body.transcriptionUrl) formData.append('transcription_url', body.transcriptionUrl);
+    if (body.language) formData.append('language', body.language);
+    if (body.disableVideoStream) formData.append('disable_video_stream', body.disableVideoStream);
+
+    if (typeof body.file === 'string') {
+      const filePath = path.resolve(body.file);
+      const fileStream = createReadStream(filePath);
+      const fileName = path.basename(filePath);
+      formData.append('video_file', fileStream, fileName);
+    } else if (body.file) {
+      formData.append('video_file', body.file);
+    }
+
+    if (typeof body.transcriptionFile === 'string') {
+      const filePath = path.resolve(body.transcriptionFile);
+      const fileStream = createReadStream(filePath);
+      const fileName = path.basename(filePath);
+      formData.append('transcription_file', fileStream, fileName);
+      formData.append('provide_transcription', true);
+    } else if (body.transcriptionFile) {
+      formData.append('transcription_file', body.transcriptionFile);
+      formData.append('provide_transcription', true);
+    }
+
+    const res = await this._post<{ id: string }>('tasks', formData, options);
+
+    return await this.retrieve(res.id);
+  }
+
+  async createBulk(
+    indexId: string,
+    {
+      files,
+      urls,
+      language,
+      disableVideoStream,
+    }: {
+      files?: (string | Buffer | null)[];
+      urls?: string[];
+      language?: string;
+      disableVideoStream?: boolean;
+    },
+    options: RequestOptions = {},
+  ): Promise<Models.Task[]> {
+    if (!files && !urls) {
+      throw new Error('Either files or urls must be provided');
+    }
+
+    const tasks: Models.Task[] = [];
+
+    if (files) {
+      for (const file of files) {
+        try {
+          const task = await this.create({ indexId, file, language, disableVideoStream }, options);
+          tasks.push(task);
+        } catch (e) {
+          console.error(`Error processing file ${file}:`, e);
+        }
+      }
+    }
+
+    if (urls) {
+      for (const url of urls) {
+        try {
+          const task = await this.create({ indexId, url, language, disableVideoStream }, options);
+          tasks.push(task);
+        } catch (e) {
+          console.error(`Error processing url ${url}:`, e);
+        }
+      }
+    }
+
+    return tasks;
+  }
+
+  async delete(id: string, options: RequestOptions = {}): Promise<void> {
+    await this._delete<void>(`tasks/${id}`, options);
+  }
+
+  async status(indexId: string, options: RequestOptions = {}): Promise<Models.TaskStatus> {
+    const params = { index_id: indexId };
+    const res = await this._get<Models.TaskStatus>(`tasks/status`, convertKeysToSnakeCase(params), options);
+    return res;
+  }
+
+  async transfer(file: Buffer | NodeJS.ReadableStream, options: RequestOptions = {}): Promise<void> {
+    const formData = new FormData();
+    formData.append('file', file);
+    await this._post<void>(`tasks/transfers`, formData, options);
+  }
+
+  async externalProvider(indexId: string, url: string, options: RequestOptions = {}): Promise<Models.Task> {
+    const body = { index_id: indexId, url };
+    const res = await this._post<{ id: string }>(
+      `tasks/external-provider`,
+      convertKeysToSnakeCase(body),
+      options,
+    );
+    return await this.retrieve(res.id);
+  }
+}

package/dist/src/resources/task/interfaces.ts

@@ -0,0 +1,23 @@
+import { PageOptions } from '../../interfaces';
+
+export interface ListTaskParams extends PageOptions {
+  id?: string;
+  indexId?: string;
+  filename?: string;
+  duration?: number;
+  width?: number;
+  height?: number;
+  createdAt?: string | Record<string, string>;
+  updatedAt?: string | Record<string, string>;
+  estimatedTime?: number;
+}
+
+export interface CreateTaskParams {
+  indexId: string;
+  file?: Buffer | NodeJS.ReadableStream | string;
+  url?: string;
+  transcriptionFile?: Buffer | NodeJS.ReadableStream | string;
+  transcriptionUrl?: string;
+  language?: string;
+  disableVideoStream?: boolean;
+}