AbortSignal support (#144)

Add `SingleRequestOptions` with `AbortSignal` support to most of the asynchronous methods of:

 - `GenerativeModel`
 - `GoogleAIFileManager`
 - `ChatSession`

**NOTE:** `AbortSignal` is a client-only operation. Using it to cancel an operation will not cancel the request in the service. You will still be charged usage for any applicable operations.

Some methods are not supported as they would leave the server in an ambiguous state, namely `GoogleAIFileManager.uploadFile()` and `GoogleAIFileManager.deleteFile()`.

Author: DellaBitta

.changeset/tough-beds-serve.md

@@ -0,0 +1,5 @@
+---
+"@google/generative-ai": minor
+---
+
+Adds `SingleRequestOptions` with `AbortSignal` support to most of the asynchronous methods of `GenerativeModel`, `GoogleAIFileManager` and `ChatSession`.

common/api-review/generative-ai-server.api.md

@@ -355,8 +355,9 @@ export class GoogleAIFileManager {
     // (undocumented)
     apiKey: string;
     deleteFile(fileId: string): Promise<void>;
-    getFile(fileId: string): Promise<FileMetadataResponse>;
-    listFiles(listParams?: ListParams): Promise<ListFilesResponse>;
+    getFile(fileId: string, requestOptions?: SingleRequestOptions): Promise<FileMetadataResponse>;
+    // Warning: (ae-forgotten-export) The symbol "SingleRequestOptions" needs to be exported by the entry point index.d.ts
+    listFiles(listParams?: ListParams, requestOptions?: SingleRequestOptions): Promise<ListFilesResponse>;
     uploadFile(filePath: string, fileMetadata: FileMetadata): Promise<UploadFileResponse>;
 }
 

common/api-review/generative-ai.api.md

@@ -62,16 +62,14 @@ export interface CachedContentBase {
 
 // @public
 export class ChatSession {
-    constructor(apiKey: string, model: string, params?: StartChatParams, requestOptions?: RequestOptions);
+    constructor(apiKey: string, model: string, params?: StartChatParams, _requestOptions?: RequestOptions);
     getHistory(): Promise<Content[]>;
     // (undocumented)
     model: string;
     // (undocumented)
     params?: StartChatParams;
-    // (undocumented)
-    requestOptions?: RequestOptions;
-    sendMessage(request: string | Array<string | Part>): Promise<GenerateContentResult>;
-    sendMessageStream(request: string | Array<string | Part>): Promise<GenerateContentStreamResult>;
+    sendMessage(request: string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<GenerateContentResult>;
+    sendMessageStream(request: string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<GenerateContentStreamResult>;
 }
 
 // @public
@@ -462,16 +460,16 @@ export interface GenerativeContentBlob {
 
 // @public
 export class GenerativeModel {
-    constructor(apiKey: string, modelParams: ModelParams, requestOptions?: RequestOptions);
+    constructor(apiKey: string, modelParams: ModelParams, _requestOptions?: RequestOptions);
     // (undocumented)
     apiKey: string;
-    batchEmbedContents(batchEmbedContentRequest: BatchEmbedContentsRequest): Promise<BatchEmbedContentsResponse>;
+    batchEmbedContents(batchEmbedContentRequest: BatchEmbedContentsRequest, requestOptions?: SingleRequestOptions): Promise<BatchEmbedContentsResponse>;
     // (undocumented)
     cachedContent: CachedContent;
-    countTokens(request: CountTokensRequest | string | Array<string | Part>): Promise<CountTokensResponse>;
-    embedContent(request: EmbedContentRequest | string | Array<string | Part>): Promise<EmbedContentResponse>;
-    generateContent(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentResult>;
-    generateContentStream(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentStreamResult>;
+    countTokens(request: CountTokensRequest | string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<CountTokensResponse>;
+    embedContent(request: EmbedContentRequest | string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<EmbedContentResponse>;
+    generateContent(request: GenerateContentRequest | string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<GenerateContentResult>;
+    generateContentStream(request: GenerateContentRequest | string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<GenerateContentStreamResult>;
     // (undocumented)
     generationConfig: GenerationConfig;
     // (undocumented)
@@ -667,6 +665,11 @@ export interface Schema {
     type?: FunctionDeclarationSchemaType;
 }
 
+// @public
+export interface SingleRequestOptions extends RequestOptions {
+    signal?: AbortSignal;
+}
+
 // @public
 export interface StartChatParams extends BaseParams {
     cachedContent?: string;

docs/reference/files/generative-ai.googleaifilemanager.deletefile.md

@@ -4,19 +4,22 @@
 
 ## GoogleAIFileManager.deleteFile() method
 
-Delete file with given ID
+Delete file with given ID.
+
+Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.
 
 **Signature:**
 
 ```typescript
-deleteFile(fileId: string): Promise<void>;
+deleteFile(fileId: string, requestOptions?: SingleRequestOptions): Promise<void>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  fileId | string |  |
+|  requestOptions | [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | _(Optional)_ |
 
 **Returns:**
 

docs/reference/files/generative-ai.googleaifilemanager.getfile.md

@@ -4,19 +4,22 @@
 
 ## GoogleAIFileManager.getFile() method
 
-Get metadata for file with given ID
+Get metadata for file with given ID.
+
+Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.
 
 **Signature:**
 
 ```typescript
-getFile(fileId: string): Promise<FileMetadataResponse>;
+getFile(fileId: string, requestOptions?: SingleRequestOptions): Promise<FileMetadataResponse>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  fileId | string |  |
+|  requestOptions | [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | _(Optional)_ |
 
 **Returns:**
 

docs/reference/files/generative-ai.googleaifilemanager.listfiles.md

@@ -4,19 +4,22 @@
 
 ## GoogleAIFileManager.listFiles() method
 
-List all uploaded files
+List all uploaded files.
+
+Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.
 
 **Signature:**
 
 ```typescript
-listFiles(listParams?: ListParams): Promise<ListFilesResponse>;
+listFiles(listParams?: ListParams, requestOptions?: SingleRequestOptions): Promise<ListFilesResponse>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  listParams | [ListParams](./generative-ai.listparams.md) | _(Optional)_ |
+|  requestOptions | [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | _(Optional)_ |
 
 **Returns:**
 

docs/reference/files/generative-ai.googleaifilemanager.md

@@ -28,8 +28,8 @@ export declare class GoogleAIFileManager
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [deleteFile(fileId)](./generative-ai.googleaifilemanager.deletefile.md) |  | Delete file with given ID |
-|  [getFile(fileId)](./generative-ai.googleaifilemanager.getfile.md) |  | Get metadata for file with given ID |
-|  [listFiles(listParams)](./generative-ai.googleaifilemanager.listfiles.md) |  | List all uploaded files |
-|  [uploadFile(filePath, fileMetadata)](./generative-ai.googleaifilemanager.uploadfile.md) |  | Upload a file |
+|  [deleteFile(fileId, requestOptions)](./generative-ai.googleaifilemanager.deletefile.md) |  | <p>Delete file with given ID.</p><p>Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.</p> |
+|  [getFile(fileId, requestOptions)](./generative-ai.googleaifilemanager.getfile.md) |  | <p>Get metadata for file with given ID.</p><p>Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.</p> |
+|  [listFiles(listParams, requestOptions)](./generative-ai.googleaifilemanager.listfiles.md) |  | <p>List all uploaded files.</p><p>Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.</p> |
+|  [uploadFile(filePath, fileMetadata, requestOptions)](./generative-ai.googleaifilemanager.uploadfile.md) |  | <p>Upload a file.</p><p>Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.</p> |
 

docs/reference/files/generative-ai.googleaifilemanager.uploadfile.md

@@ -4,12 +4,14 @@
 
 ## GoogleAIFileManager.uploadFile() method
 
-Upload a file
+Upload a file.
+
+Any fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the [GoogleAIFileManager](./generative-ai.googleaifilemanager.md) initialization.
 
 **Signature:**
 
 ```typescript
-uploadFile(filePath: string, fileMetadata: FileMetadata): Promise<UploadFileResponse>;
+uploadFile(filePath: string, fileMetadata: FileMetadata, requestOptions?: SingleRequestOptions): Promise<UploadFileResponse>;
 ```
 
 ## Parameters
@@ -18,6 +20,7 @@ uploadFile(filePath: string, fileMetadata: FileMetadata): Promise<UploadFileResp
 |  --- | --- | --- |
 |  filePath | string |  |
 |  fileMetadata | [FileMetadata](./generative-ai.filemetadata.md) |  |
+|  requestOptions | [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | _(Optional)_ |
 
 **Returns:**
 

docs/reference/files/generative-ai.md

@@ -27,6 +27,7 @@
 |  [ListParams](./generative-ai.listparams.md) | Params to pass to [GoogleAIFileManager.listFiles()](./generative-ai.googleaifilemanager.listfiles.md) |
 |  [RequestOptions](./generative-ai.requestoptions.md) | Params passed to getGenerativeModel() or GoogleAIFileManager(). |
 |  [RpcStatus](./generative-ai.rpcstatus.md) | Standard RPC error status object. |
+|  [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | Params passed to atomic asynchronous operations. |
 |  [UploadFileResponse](./generative-ai.uploadfileresponse.md) | Response from calling [GoogleAIFileManager.uploadFile()](./generative-ai.googleaifilemanager.uploadfile.md) |
 |  [VideoMetadata](./generative-ai.videometadata.md) | Metadata populated when video has been processed. |
 

docs/reference/files/generative-ai.singlerequestoptions.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SingleRequestOptions](./generative-ai.singlerequestoptions.md)
+
+## SingleRequestOptions interface
+
+Params passed to atomic asynchronous operations.
+
+**Signature:**
+
+```typescript
+export interface SingleRequestOptions extends RequestOptions 
+```
+**Extends:** [RequestOptions](./generative-ai.requestoptions.md)
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [signal?](./generative-ai.singlerequestoptions.signal.md) |  | AbortSignal | _(Optional)_ An object that may be used to abort asynchronous requests. The request may also be aborted due to the expiration of the timeout value, if provided, and if the timeout occurs first. |
+

docs/reference/files/generative-ai.singlerequestoptions.signal.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SingleRequestOptions](./generative-ai.singlerequestoptions.md) &gt; [signal](./generative-ai.singlerequestoptions.signal.md)
+
+## SingleRequestOptions.signal property
+
+An object that may be used to abort asynchronous requests. The request may also be aborted due to the expiration of the timeout value, if provided, and if the timeout occurs first.
+
+**Signature:**
+
+```typescript
+signal?: AbortSignal;
+```

docs/reference/main/generative-ai.chatsession._constructor_.md

@@ -9,7 +9,7 @@ Constructs a new instance of the `ChatSession` class
 **Signature:**
 
 ```typescript
-constructor(apiKey: string, model: string, params?: StartChatParams, requestOptions?: RequestOptions);
+constructor(apiKey: string, model: string, params?: StartChatParams, _requestOptions?: RequestOptions);
 ```
 
 ## Parameters
@@ -19,5 +19,5 @@ constructor(apiKey: string, model: string, params?: StartChatParams, requestOpti
 |  apiKey | string |  |
 |  model | string |  |
 |  params | [StartChatParams](./generative-ai.startchatparams.md) | _(Optional)_ |
-|  requestOptions | [RequestOptions](./generative-ai.requestoptions.md) | _(Optional)_ |
+|  \_requestOptions | [RequestOptions](./generative-ai.requestoptions.md) | _(Optional)_ |
 

docs/reference/main/generative-ai.chatsession.md

@@ -16,21 +16,20 @@ export declare class ChatSession
 
 |  Constructor | Modifiers | Description |
 |  --- | --- | --- |
-|  [(constructor)(apiKey, model, params, requestOptions)](./generative-ai.chatsession._constructor_.md) |  | Constructs a new instance of the <code>ChatSession</code> class |
+|  [(constructor)(apiKey, model, params, \_requestOptions)](./generative-ai.chatsession._constructor_.md) |  | Constructs a new instance of the <code>ChatSession</code> class |
 
 ## Properties
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
 |  [model](./generative-ai.chatsession.model.md) |  | string |  |
 |  [params?](./generative-ai.chatsession.params.md) |  | [StartChatParams](./generative-ai.startchatparams.md) | _(Optional)_ |
-|  [requestOptions?](./generative-ai.chatsession.requestoptions.md) |  | [RequestOptions](./generative-ai.requestoptions.md) | _(Optional)_ |
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
 |  [getHistory()](./generative-ai.chatsession.gethistory.md) |  | Gets the chat history so far. Blocked prompts are not added to history. Blocked candidates are not added to history, nor are the prompts that generated them. |
-|  [sendMessage(request)](./generative-ai.chatsession.sendmessage.md) |  | Sends a chat message and receives a non-streaming [GenerateContentResult](./generative-ai.generatecontentresult.md) |
-|  [sendMessageStream(request)](./generative-ai.chatsession.sendmessagestream.md) |  | Sends a chat message and receives the response as a [GenerateContentStreamResult](./generative-ai.generatecontentstreamresult.md) containing an iterable stream and a response promise. |
+|  [sendMessage(request, requestOptions)](./generative-ai.chatsession.sendmessage.md) |  | <p>Sends a chat message and receives a non-streaming [GenerateContentResult](./generative-ai.generatecontentresult.md)<!-- -->.</p><p>Fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the  initialization.</p> |
+|  [sendMessageStream(request, requestOptions)](./generative-ai.chatsession.sendmessagestream.md) |  | <p>Sends a chat message and receives the response as a [GenerateContentStreamResult](./generative-ai.generatecontentstreamresult.md) containing an iterable stream and a response promise.</p><p>Fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the  initialization.</p> |
 

docs/reference/main/generative-ai.chatsession.requestoptions.md

@@ -4,19 +4,22 @@
 
 ## ChatSession.sendMessage() method
 
-Sends a chat message and receives a non-streaming [GenerateContentResult](./generative-ai.generatecontentresult.md)
+Sends a chat message and receives a non-streaming [GenerateContentResult](./generative-ai.generatecontentresult.md)<!-- -->.
+
+Fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the  initialization.
 
 **Signature:**
 
 ```typescript
-sendMessage(request: string | Array<string | Part>): Promise<GenerateContentResult>;
+sendMessage(request: string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<GenerateContentResult>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  request | string \| Array&lt;string \| [Part](./generative-ai.part.md)<!-- -->&gt; |  |
+|  requestOptions | [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | _(Optional)_ |
 
 **Returns:**
 

docs/reference/main/generative-ai.chatsession.sendmessage.md

@@ -6,17 +6,20 @@
 
 Sends a chat message and receives the response as a [GenerateContentStreamResult](./generative-ai.generatecontentstreamresult.md) containing an iterable stream and a response promise.
 
+Fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the  initialization.
+
 **Signature:**
 
 ```typescript
-sendMessageStream(request: string | Array<string | Part>): Promise<GenerateContentStreamResult>;
+sendMessageStream(request: string | Array<string | Part>, requestOptions?: SingleRequestOptions): Promise<GenerateContentStreamResult>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  request | string \| Array&lt;string \| [Part](./generative-ai.part.md)<!-- -->&gt; |  |
+|  requestOptions | [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | _(Optional)_ |
 
 **Returns:**
 

docs/reference/main/generative-ai.chatsession.sendmessagestream.md

@@ -9,7 +9,7 @@ Constructs a new instance of the `GenerativeModel` class
 **Signature:**
 
 ```typescript
-constructor(apiKey: string, modelParams: ModelParams, requestOptions?: RequestOptions);
+constructor(apiKey: string, modelParams: ModelParams, _requestOptions?: RequestOptions);
 ```
 
 ## Parameters
@@ -18,5 +18,5 @@ constructor(apiKey: string, modelParams: ModelParams, requestOptions?: RequestOp
 |  --- | --- | --- |
 |  apiKey | string |  |
 |  modelParams | [ModelParams](./generative-ai.modelparams.md) |  |
-|  requestOptions | [RequestOptions](./generative-ai.requestoptions.md) | _(Optional)_ |
+|  \_requestOptions | [RequestOptions](./generative-ai.requestoptions.md) | _(Optional)_ |
 

docs/reference/main/generative-ai.generativemodel._constructor_.md

@@ -6,17 +6,20 @@
 
 Embeds an array of [EmbedContentRequest](./generative-ai.embedcontentrequest.md)<!-- -->s.
 
+Fields set in the optional [SingleRequestOptions](./generative-ai.singlerequestoptions.md) parameter will take precedence over the [RequestOptions](./generative-ai.requestoptions.md) values provided at the time of the  initialization.
+
 **Signature:**
 
 ```typescript
-batchEmbedContents(batchEmbedContentRequest: BatchEmbedContentsRequest): Promise<BatchEmbedContentsResponse>;
+batchEmbedContents(batchEmbedContentRequest: BatchEmbedContentsRequest, requestOptions?: SingleRequestOptions): Promise<BatchEmbedContentsResponse>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  batchEmbedContentRequest | [BatchEmbedContentsRequest](./generative-ai.batchembedcontentsrequest.md) |  |
+|  requestOptions | [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | _(Optional)_ |
 
 **Returns:**