ai 7.0.95 → 7.0.96

package/dist/internal/index.js

@@ -91,7 +91,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "7.0.95" : "0.0.0-test";
+var VERSION = true ? "7.0.96" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/docs/03-ai-sdk-core/42-batch.mdx

@@ -18,7 +18,7 @@ summarization, and content generation that do not need an immediate response.
 The batch API is designed to support multiple request types. Currently, only
 `type: 'text'` is supported.
 
-The AI SDK provides three functions for the batch lifecycle:
+The AI SDK provides five functions for the batch lifecycle:
 
 - [`experimental_startBatch`](/docs/reference/ai-sdk-core/start-batch)
   submits a batch and returns its initial status and a serializable reference.
@@ -26,18 +26,30 @@ The AI SDK provides three functions for the batch lifecycle:
   retrieves the latest status and request counts.
 - [`experimental_getBatchResults`](/docs/reference/ai-sdk-core/get-batch-results)
   asynchronously iterates over the terminal result for each request.
+- [`experimental_cancelBatch`](/docs/reference/ai-sdk-core/cancel-batch)
+  requests cancellation of a batch.
+- [`experimental_listBatches`](/docs/reference/ai-sdk-core/list-batches)
+  lists batches and their latest statuses.
 
-All three functions are exported from `ai`. The examples below use aliases so
+All five functions are exported from `ai`. The examples below use aliases so
 the shorter names can be used in application code:
 
 ```ts
 import {
+  experimental_cancelBatch as cancelBatch,
   experimental_getBatchResults as getBatchResults,
   experimental_getBatchStatus as getBatchStatus,
+  experimental_listBatches as listBatches,
   experimental_startBatch as startBatch,
 } from 'ai';
 ```
 
+Cancellation and listing are optional provider capabilities. Calling either
+function with a provider that does not implement it throws an
+`UnsupportedFunctionalityError`. In the cancellation and listing examples
+below, `provider` represents a batch provider that implements the respective
+capability.
+
 ## Supported providers
 
 Batch processing requires a provider that implements the batch interface.
@@ -218,6 +230,55 @@ support and payloads are provider-specific. The provider pages linked above
 describe their webhook behavior; providers that do not support webhooks return
 an unsupported warning and continue without one.
 
+## Cancelling a batch
+
+Use `cancelBatch` to ask the provider to stop processing a batch:
+
+```ts
+const result = await cancelBatch({
+  provider,
+  batch,
+});
+
+console.log(result.providerMetadata);
+```
+
+A successful call means that the provider accepted the cancellation request.
+It does not guarantee that cancellation has finished or that every pending
+request will be cancelled. Use `getBatchStatus` to retrieve the latest status
+after requesting cancellation.
+
+The result can include provider metadata with additional information from the
+cancellation response.
+
+## Listing batches
+
+Use `listBatches` to retrieve batches from the provider. Results are paginated.
+Pass the returned `nextCursor` as `cursor` to retrieve the next page:
+
+```ts
+let cursor: string | undefined;
+
+do {
+  const page = await listBatches({
+    provider,
+    limit: 20,
+    cursor,
+  });
+
+  for (const batch of page.batches) {
+    console.log(batch.id, batch.status);
+  }
+
+  cursor = page.nextCursor;
+} while (cursor != null);
+```
+
+Each item is a serializable batch reference with its latest normalized status,
+so it can be passed directly to `getBatchStatus`, `getBatchResults`, or
+`cancelBatch`. Cursors are opaque and provider-specific; applications should
+store or pass them unchanged rather than inspect their contents.
+
 ## Retrieving results
 
 After the batch is complete, `getBatchResults` returns an async iterable. Each
@@ -257,14 +318,14 @@ sensitive data.
 
 ## Request controls
 
-`getBatchStatus` and `getBatchResults` accept `providerOptions`, `headers`,
-`timeout`, `abortSignal`, and `maxRetries` for the current status or result
-retrieval operation:
+All batch lifecycle functions accept `providerOptions`, `headers`, `timeout`,
+and `abortSignal` for the current operation. `getBatchStatus`,
+`getBatchResults`, and `listBatches` also accept `maxRetries`:
 
-- `maxRetries` controls retries for status and result retrieval. It does not
-  retry batch creation, which could create a duplicate batch. It defaults to 2;
-  set it to 0 to disable retries.
-- `abortSignal` cancels the current status or result request.
+- `maxRetries` controls retries for status, result retrieval, and listing. It
+  does not retry batch creation or cancellation. It defaults to 2; set it to 0
+  to disable retries.
+- `abortSignal` cancels the current API request.
 - `timeout` limits the current HTTP operation.
 
 These controls affect communication with the provider. They do not change the

package/docs/07-reference/01-ai-sdk-core/23-cancel-batch.mdx

@@ -0,0 +1,96 @@
+---
+title: experimental_cancelBatch
+description: API Reference for experimental_cancelBatch.
+---
+
+# `experimental_cancelBatch()`
+
+<Note type="warning">
+  Batch support is experimental and the API may change in patch releases.
+</Note>
+
+Requests cancellation of an asynchronous batch. A successful call means that
+the provider accepted the cancellation request, not that cancellation has
+finished. For a complete guide to the batch lifecycle, see
+[Batch](/docs/ai-sdk-core/batch).
+
+```ts
+import { experimental_cancelBatch as cancelBatch } from 'ai';
+
+const result = await cancelBatch({
+  provider,
+  batch,
+});
+
+console.log(result.providerMetadata);
+```
+
+## Import
+
+<Snippet
+  text={`import { experimental_cancelBatch } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'provider',
+      type: 'Experimental_BatchProvider',
+      isOptional: true,
+      description:
+        'The provider used to access the batch. Defaults to the global provider, or the AI Gateway when no global provider is configured.',
+    },
+    {
+      name: 'batch',
+      type: 'Experimental_BatchReference',
+      description:
+        'The serializable reference returned by experimental_startBatch.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description:
+        'Additional provider-specific options for the cancellation request.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description: 'An optional abort signal to cancel the API request.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isOptional: true,
+      description: 'Maximum time allowed for the cancellation request.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string | undefined>',
+      isOptional: true,
+      description: 'Additional HTTP headers for the request.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata',
+      isOptional: true,
+      description: 'Provider-specific metadata from the cancellation response.',
+    },
+  ]}
+/>
+
+Calling this function with a provider that does not support batch cancellation
+throws an `UnsupportedFunctionalityError`.

package/docs/07-reference/01-ai-sdk-core/24-list-batches.mdx

@@ -0,0 +1,121 @@
+---
+title: experimental_listBatches
+description: API Reference for experimental_listBatches.
+---
+
+# `experimental_listBatches()`
+
+<Note type="warning">
+  Batch support is experimental and the API may change in patch releases.
+</Note>
+
+Lists a page of asynchronous batches and their latest normalized statuses. For
+a complete guide to the batch lifecycle, see [Batch](/docs/ai-sdk-core/batch).
+
+```ts
+import { experimental_listBatches as listBatches } from 'ai';
+
+const page = await listBatches({
+  provider,
+  limit: 20,
+  cursor,
+});
+
+console.log(page.batches, page.nextCursor);
+```
+
+## Import
+
+<Snippet
+  text={`import { experimental_listBatches } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'provider',
+      type: 'Experimental_BatchProvider',
+      isOptional: true,
+      description:
+        'The provider whose batches should be listed. Defaults to the global provider, or the AI Gateway when no global provider is configured.',
+    },
+    {
+      name: 'limit',
+      type: 'number',
+      isOptional: true,
+      description: 'Maximum number of batches to return in this page.',
+    },
+    {
+      name: 'cursor',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Opaque cursor returned as nextCursor by the previous list operation.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description: 'Additional provider-specific options for listing batches.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of retries for listing batches. Set to 0 to disable retries. Default: 2.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description: 'An optional abort signal to cancel the request.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isOptional: true,
+      description: 'Maximum time allowed for the list request.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string | undefined>',
+      isOptional: true,
+      description: 'Additional HTTP headers for the request.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'batches',
+      type: 'Array<Experimental_Batch>',
+      description:
+        'The batches in this page. Each item contains a serializable batch reference and its latest normalized status.',
+    },
+    {
+      name: 'nextCursor',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Opaque cursor to pass as cursor to retrieve the next page. Omitted when there are no more batches.',
+    },
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata',
+      isOptional: true,
+      description: 'Provider-specific metadata for the list operation.',
+    },
+  ]}
+/>
+
+Calling this function with a provider that does not support listing batches
+throws an `UnsupportedFunctionalityError`.

package/docs/07-reference/01-ai-sdk-core/index.mdx

@@ -68,6 +68,16 @@ AI SDK Core contains the following main functions:
       description: 'Retrieve terminal results from an asynchronous batch.',
       href: '/docs/reference/ai-sdk-core/get-batch-results',
     },
+    {
+      title: 'experimental_cancelBatch()',
+      description: 'Request cancellation of an asynchronous batch.',
+      href: '/docs/reference/ai-sdk-core/cancel-batch',
+    },
+    {
+      title: 'experimental_listBatches()',
+      description: 'List asynchronous batches and their latest statuses.',
+      href: '/docs/reference/ai-sdk-core/list-batches',
+    },
     {
       title: 'transcribe()',
       description: 'Generate a transcript from an audio file.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.95",
+  "version": "7.0.96",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,20 +42,20 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.76",
-    "@ai-sdk/provider": "4.0.11",
-    "@ai-sdk/provider-utils": "5.0.37"
+    "@ai-sdk/gateway": "4.0.77",
+    "@ai-sdk/provider": "4.0.12",
+    "@ai-sdk/provider-utils": "5.0.38"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.79",
-    "@ai-sdk/deepseek": "3.0.40",
-    "@ai-sdk/google": "4.0.65",
-    "@ai-sdk/groq": "4.0.38",
-    "@ai-sdk/huggingface": "2.0.45",
-    "@ai-sdk/moonshotai": "3.0.46",
-    "@ai-sdk/openai": "4.0.63",
+    "@ai-sdk/amazon-bedrock": "5.0.80",
+    "@ai-sdk/deepseek": "3.0.41",
+    "@ai-sdk/google": "4.0.66",
+    "@ai-sdk/groq": "4.0.39",
+    "@ai-sdk/huggingface": "2.0.46",
+    "@ai-sdk/moonshotai": "3.0.47",
+    "@ai-sdk/openai": "4.0.64",
     "@ai-sdk/test-server": "2.0.1",
-    "@ai-sdk/xai": "4.0.55",
+    "@ai-sdk/xai": "4.0.56",
     "@edge-runtime/vm": "^5.0.0",
     "@smithy/eventstream-codec": "^4.3.3",
     "@smithy/util-utf8": "^4.3.3",

package/src/batch/batch-types.ts

@@ -118,6 +118,42 @@ export type StartBatchResult = Batch & {
   readonly warnings: BatchV4StartResult['warnings'];
 };
 
+/**
+ * Options for requesting cancellation of a batch.
+ */
+export type CancelBatchOptions = {
+  provider?: BatchProvider;
+  batch: BatchReference;
+  providerOptions?: ProviderOptions;
+} & BatchCallOptions;
+
+/**
+ * Result of requesting cancellation of a batch.
+ */
+export type CancelBatchResult = {
+  readonly providerMetadata?: ProviderMetadata;
+};
+
+/**
+ * Options for listing batches.
+ */
+export type ListBatchesOptions = {
+  provider?: BatchProvider;
+  providerOptions?: ProviderOptions;
+  limit?: number;
+  cursor?: string;
+  maxRetries?: number;
+} & BatchCallOptions;
+
+/**
+ * One page of listed batches.
+ */
+export type ListBatchesResult = {
+  readonly batches: Array<Batch>;
+  readonly nextCursor?: string;
+  readonly providerMetadata?: ProviderMetadata;
+};
+
 /**
  * Options for retrieving batch status.
  */

package/src/batch/batch.ts

@@ -31,14 +31,114 @@ import type {
   BatchProvider,
   BatchReference,
   BatchStatus,
+  CancelBatchOptions,
+  CancelBatchResult,
   GetBatchResultsOptions,
   GetBatchStatusOptions,
+  ListBatchesOptions,
+  ListBatchesResult,
   StartBatchOptions,
   StartBatchResult,
   TextBatchGenerationResult,
   TextBatchItemResult,
 } from './batch-types';
 
+/**
+ * Requests cancellation of a batch.
+ */
+export async function cancelBatch({
+  provider,
+  batch,
+  providerOptions,
+  abortSignal,
+  headers,
+  timeout,
+}: CancelBatchOptions): Promise<CancelBatchResult> {
+  const batchApi = resolveBatchApi(provider);
+  validateBatchReference({ batchApi, batch });
+
+  if (batchApi.doCancelBatch == null) {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'batch cancellation',
+      message: 'The provider does not support batch cancellation.',
+    });
+  }
+
+  const operationAbortSignal = mergeAbortSignals(
+    abortSignal,
+    getTotalTimeoutMs(timeout),
+  );
+
+  try {
+    return await batchApi.doCancelBatch({
+      batchId: batch.id,
+      providerOptions,
+      abortSignal: operationAbortSignal,
+      headers: withUserAgentSuffix(headers ?? {}, `ai/${VERSION}`),
+    });
+  } catch (error) {
+    throw wrapGatewayError(error);
+  }
+}
+
+/**
+ * Lists a page of batches.
+ */
+export async function listBatches({
+  provider,
+  providerOptions,
+  limit,
+  cursor,
+  maxRetries,
+  abortSignal,
+  headers,
+  timeout,
+}: ListBatchesOptions = {}): Promise<ListBatchesResult> {
+  const batchApi = resolveBatchApi(provider);
+
+  const doListBatches = batchApi.doListBatches?.bind(batchApi);
+  if (doListBatches == null) {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'batch listing',
+      message: 'The provider does not support listing batches.',
+    });
+  }
+
+  const operationAbortSignal = mergeAbortSignals(
+    abortSignal,
+    getTotalTimeoutMs(timeout),
+  );
+  const { retry } = prepareRetries({
+    maxRetries,
+    abortSignal: operationAbortSignal,
+  });
+
+  try {
+    const { batches, nextCursor, providerMetadata } = await retry(() =>
+      doListBatches({
+        providerOptions,
+        abortSignal: operationAbortSignal,
+        headers: withUserAgentSuffix(headers ?? {}, `ai/${VERSION}`),
+        ...(limit != null && { limit }),
+        ...(cursor != null && { cursor }),
+      }),
+    );
+
+    return {
+      batches: batches.map(({ batchId, ...status }) => ({
+        version: 2,
+        id: batchId,
+        provider: batchApi.provider,
+        ...status,
+      })),
+      ...(nextCursor != null && { nextCursor }),
+      ...(providerMetadata != null && { providerMetadata }),
+    };
+  } catch (error) {
+    throw wrapGatewayError(error);
+  }
+}
+
 /**
  * Starts a batch.
  */

package/src/batch/index.ts

@@ -1,15 +1,21 @@
 export {
+  cancelBatch as experimental_cancelBatch,
   startBatch as experimental_startBatch,
   getBatchResults as experimental_getBatchResults,
   getBatchStatus as experimental_getBatchStatus,
+  listBatches as experimental_listBatches,
 } from './batch';
 export type {
   BatchError as Experimental_BatchError,
   BatchProvider as Experimental_BatchProvider,
   BatchReference as Experimental_BatchReference,
   BatchStatus as Experimental_BatchStatus,
+  CancelBatchOptions as Experimental_CancelBatchOptions,
+  CancelBatchResult as Experimental_CancelBatchResult,
   GetBatchResultsOptions as Experimental_GetBatchResultsOptions,
   GetBatchStatusOptions as Experimental_GetBatchStatusOptions,
+  ListBatchesOptions as Experimental_ListBatchesOptions,
+  ListBatchesResult as Experimental_ListBatchesResult,
   StartBatchOptions as Experimental_StartBatchOptions,
   StartBatchResult as Experimental_StartBatchResult,
   Batch as Experimental_Batch,

package/src/util/data-url.ts

@@ -1,3 +1,8 @@
+// atob needs to be invoked as a function call, not as a method call.
+// Otherwise Cloudflare will throw a
+// "TypeError: Illegal invocation: function called with incorrect this reference"
+const { atob } = globalThis;
+
 /**
  * Converts a data URL of type text/* to a text string.
  */
@@ -10,7 +15,7 @@ export function getTextFromDataUrl(dataUrl: string): string {
   }
 
   try {
-    return globalThis.atob(base64Content);
+    return atob(base64Content);
   } catch {
     throw new Error(`Error decoding data URL`);
   }