tessl/npm-google--genai

Google Gen AI JavaScript SDK for building applications powered by Gemini with content generation, image/video generation, function calling, caching, and real-time live sessions

Overview

Eval results

Files

Operations

Name: tessl/npm-google--genai
Author: tessl

The Operations class provides methods for managing and monitoring long-running operations in the Google Gen AI SDK. Long-running operations are used for tasks that take significant time to complete, such as video generation, file imports, and file uploads to search stores.

Capabilities

Get Operation Status (Videos)

Retrieves the current status of a video generation operation. This method is specifically designed for GenerateVideosOperation instances.

/**
 * Gets the status of a long-running video generation operation
 * @param parameters - Parameters including the operation to check
 * @returns Promise resolving to an updated GenerateVideosOperation with latest status
 * @throws Error if operation name is missing or empty
 */
function getVideosOperation(
  parameters: OperationGetParameters<GenerateVideosResponse, GenerateVideosOperation>
): Promise<GenerateVideosOperation>;

interface OperationGetParameters<T, U extends Operation<T>> {
  operation: U;
  config?: GetOperationConfig;
}

interface GetOperationConfig {
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

Usage Example:

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({
  vertexai: true,
  project: 'my-project',
  location: 'us-central1'
});

// Start a video generation
const operation = await client.models.generateVideos({
  model: 'veo-002',
  contents: 'A cat playing piano'
});

console.log('Operation started:', operation.name);

// Check operation status
const updatedOperation = await client.operations.getVideosOperation({
  operation: operation
});

if (updatedOperation.done) {
  console.log('Video generation complete!');
  console.log('Result:', updatedOperation.response);
} else {
  console.log('Still processing...');
  console.log('Metadata:', updatedOperation.metadata);
}

Get Operation Status (Generic)

Retrieves the status of any long-running operation. This is a generic method that works with all operation types.

/**
 * Gets the status of a long-running operation
 * @param parameters - Parameters including the operation to check
 * @returns Promise resolving to an updated Operation with latest status
 * @throws Error if operation name is missing or empty
 */
function get<T, U extends Operation<T>>(
  parameters: OperationGetParameters<T, U>
): Promise<Operation<T>>;

Usage Example:

// Generic operation status check
const operation = await client.fileSearchStores.importFile({
  file_search_store_name: 'fileSearchStores/abc123',
  file_name: 'files/xyz789'
});

// Check status using generic get method
const updatedOperation = await client.operations.get({
  operation: operation
});

if (updatedOperation.done) {
  console.log('Operation complete!');
  if (updatedOperation.response) {
    console.log('Response:', updatedOperation.response);
  }
} else {
  console.log('Operation in progress...');
}

// Check for errors
if (updatedOperation.error) {
  console.error('Operation failed:', updatedOperation.error.message);
}

Operation Types

Base Operation Interface

All long-running operations implement the Operation interface.

interface Operation<T> {
  name?: string;
  done?: boolean;
  response?: T;
  error?: Status;
  metadata?: Record<string, unknown>;
  _fromAPIResponse?(params: OperationFromAPIResponseParameters): Operation<T>;
}

interface OperationFromAPIResponseParameters {
  apiResponse: Record<string, unknown>;
  _isVertexAI: boolean;
}

Generate Videos Operation

Specific operation type for video generation tasks.

interface GenerateVideosOperation {
  name?: string;
  done?: boolean;
  response?: GenerateVideosResponse;
  error?: Status;
  metadata?: GenerateVideosMetadata;
  _fromAPIResponse?(params: OperationFromAPIResponseParameters): GenerateVideosOperation;
}

interface GenerateVideosResponse {
  generatedVideos?: GeneratedVideo[];
  raiMediaFilteredReasons?: string[];
  raiMediaFilteredCount?: number;
}

interface GeneratedVideo {
  video?: Blob;
  videoUri?: string;
  rai?: SafetyRating[];
}

interface GenerateVideosMetadata {
  createTime?: string;
  updateTime?: string;
  progress?: number;
}

Import File Operation

Operation type for importing files into File Search Stores.

interface ImportFileOperation {
  name?: string;
  done?: boolean;
  response?: ImportFileResponse;
  error?: Status;
  metadata?: Record<string, unknown>;
}

interface ImportFileResponse {
  document?: Document;
}

Upload to File Search Store Operation

Operation type for uploading files to File Search Stores.

interface UploadToFileSearchStoreOperation {
  name?: string;
  done?: boolean;
  response?: UploadToFileSearchStoreResponse;
  error?: Status;
  metadata?: Record<string, unknown>;
}

interface UploadToFileSearchStoreResponse {
  document?: Document;
}

Polling Patterns

Long-running operations typically require polling to check completion status. Here's a recommended pattern:

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({
  vertexai: true,
  project: 'my-project',
  location: 'us-central1'
});

async function pollOperation(
  operation: GenerateVideosOperation,
  intervalMs: number = 5000,
  timeoutMs: number = 300000
): Promise<GenerateVideosOperation> {
  const startTime = Date.now();

  while (!operation.done) {
    // Check if timeout exceeded
    if (Date.now() - startTime > timeoutMs) {
      throw new Error('Operation polling timeout exceeded');
    }

    // Wait before next check
    await new Promise(resolve => setTimeout(resolve, intervalMs));

    // Get updated operation status
    operation = await client.operations.getVideosOperation({
      operation: operation
    });

    // Check for errors
    if (operation.error) {
      throw new Error(`Operation failed: ${operation.error.message}`);
    }

    // Log progress if available
    if (operation.metadata?.progress !== undefined) {
      console.log(`Progress: ${operation.metadata.progress}%`);
    }
  }

  return operation;
}

// Usage
const videoOp = await client.models.generateVideos({
  model: 'veo-002',
  contents: 'A serene mountain landscape at sunset'
});

console.log('Video generation started...');

const completedOp = await pollOperation(videoOp);

console.log('Video generation complete!');
console.log('Generated videos:', completedOp.response?.generatedVideos);

Error Handling

Operations can fail for various reasons. Always check the error field in the operation response.

const operation = await client.operations.getVideosOperation({
  operation: myOperation
});

if (operation.error) {
  console.error('Operation failed!');
  console.error('Error code:', operation.error.code);
  console.error('Error message:', operation.error.message);

  // Handle specific error codes
  if (operation.error.code === 4) {
    console.error('Deadline exceeded - operation took too long');
  } else if (operation.error.code === 7) {
    console.error('Permission denied');
  }

  // Additional error details
  if (operation.error.details) {
    console.error('Error details:', operation.error.details);
  }
}

Type Definitions

interface Status {
  code?: number;
  message?: string;
  details?: Array<Record<string, unknown>>;
}

interface FetchPredictOperationParameters {
  operationName: string;
  resourceName: string;
  config?: FetchPredictOperationConfig;
}

interface FetchPredictOperationConfig {
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

interface GetOperationParameters {
  operationName: string;
  config?: GetOperationConfig;
}