@anthropic-ai/sdk 0.40.0 → 0.41.0

package/src/resources/completions.ts

@@ -4,6 +4,7 @@ import { APIResource } from "../resource.js";
 import { APIPromise } from "../core.js";
 import * as Core from "../core.js";
 import * as CompletionsAPI from "./completions.js";
+import * as BetaAPI from "./beta/beta.js";
 import * as MessagesAPI from "./messages/messages.js";
 import { Stream } from "../streaming.js";
 
@@ -17,25 +18,39 @@ export class Completions extends APIResource {
    * Future models and features will not be compatible with Text Completions. See our
    * [migration guide](https://docs.anthropic.com/en/api/migrating-from-text-completions-to-messages)
    * for guidance in migrating from Text Completions to Messages.
+   *
+   * @example
+   * ```ts
+   * const completion = await client.completions.create({
+   *   max_tokens_to_sample: 256,
+   *   model: 'claude-3-7-sonnet-latest',
+   *   prompt: '\n\nHuman: Hello, world!\n\nAssistant:',
+   * });
+   * ```
    */
-  create(body: CompletionCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Completion>;
+  create(params: CompletionCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Completion>;
   create(
-    body: CompletionCreateParamsStreaming,
+    params: CompletionCreateParamsStreaming,
     options?: Core.RequestOptions,
   ): APIPromise<Stream<Completion>>;
   create(
-    body: CompletionCreateParamsBase,
+    params: CompletionCreateParamsBase,
     options?: Core.RequestOptions,
   ): APIPromise<Stream<Completion> | Completion>;
   create(
-    body: CompletionCreateParams,
+    params: CompletionCreateParams,
     options?: Core.RequestOptions,
   ): APIPromise<Completion> | APIPromise<Stream<Completion>> {
+    const { betas, ...body } = params;
     return this._client.post('/v1/complete', {
       body,
       timeout: (this._client as any)._options.timeout ?? 600000,
       ...options,
-      stream: body.stream ?? false,
+      headers: {
+        ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined),
+        ...options?.headers,
+      },
+      stream: params.stream ?? false,
     }) as APIPromise<Completion> | APIPromise<Stream<Completion>>;
   }
 }
@@ -83,7 +98,7 @@ export type CompletionCreateParams = CompletionCreateParamsNonStreaming | Comple
 
 export interface CompletionCreateParamsBase {
   /**
-   * The maximum number of tokens to generate before stopping.
+   * Body param: The maximum number of tokens to generate before stopping.
    *
    * Note that our models may stop _before_ reaching this maximum. This parameter
    * only specifies the absolute maximum number of tokens to generate.
@@ -91,14 +106,14 @@ export interface CompletionCreateParamsBase {
   max_tokens_to_sample: number;
 
   /**
-   * The model that will complete your prompt.\n\nSee
+   * Body param: The model that will complete your prompt.\n\nSee
    * [models](https://docs.anthropic.com/en/docs/models-overview) for additional
    * details and options.
    */
   model: MessagesAPI.Model;
 
   /**
-   * The prompt that you want Claude to complete.
+   * Body param: The prompt that you want Claude to complete.
    *
    * For proper response generation you will need to format your prompt using
    * alternating `\n\nHuman:` and `\n\nAssistant:` conversational turns. For example:
@@ -115,12 +130,12 @@ export interface CompletionCreateParamsBase {
   prompt: string;
 
   /**
-   * An object describing metadata about the request.
+   * Body param: An object describing metadata about the request.
    */
   metadata?: MessagesAPI.Metadata;
 
   /**
-   * Sequences that will cause the model to stop generating.
+   * Body param: Sequences that will cause the model to stop generating.
    *
    * Our models stop on `"\n\nHuman:"`, and may include additional built-in stop
    * sequences in the future. By providing the stop_sequences parameter, you may
@@ -129,14 +144,15 @@ export interface CompletionCreateParamsBase {
   stop_sequences?: Array<string>;
 
   /**
-   * Whether to incrementally stream the response using server-sent events.
+   * Body param: Whether to incrementally stream the response using server-sent
+   * events.
    *
    * See [streaming](https://docs.anthropic.com/en/api/streaming) for details.
    */
   stream?: boolean;
 
   /**
-   * Amount of randomness injected into the response.
+   * Body param: Amount of randomness injected into the response.
    *
    * Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0`
    * for analytical / multiple choice, and closer to `1.0` for creative and
@@ -148,7 +164,7 @@ export interface CompletionCreateParamsBase {
   temperature?: number;
 
   /**
-   * Only sample from the top K options for each subsequent token.
+   * Body param: Only sample from the top K options for each subsequent token.
    *
    * Used to remove "long tail" low probability responses.
    * [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
@@ -159,7 +175,7 @@ export interface CompletionCreateParamsBase {
   top_k?: number;
 
   /**
-   * Use nucleus sampling.
+   * Body param: Use nucleus sampling.
    *
    * In nucleus sampling, we compute the cumulative distribution over all the options
    * for each subsequent token in decreasing probability order and cut it off once it
@@ -170,6 +186,11 @@ export interface CompletionCreateParamsBase {
    * `temperature`.
    */
   top_p?: number;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
 }
 
 export namespace CompletionCreateParams {
@@ -184,7 +205,8 @@ export namespace CompletionCreateParams {
 
 export interface CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase {
   /**
-   * Whether to incrementally stream the response using server-sent events.
+   * Body param: Whether to incrementally stream the response using server-sent
+   * events.
    *
    * See [streaming](https://docs.anthropic.com/en/api/streaming) for details.
    */
@@ -193,7 +215,8 @@ export interface CompletionCreateParamsNonStreaming extends CompletionCreatePara
 
 export interface CompletionCreateParamsStreaming extends CompletionCreateParamsBase {
   /**
-   * Whether to incrementally stream the response using server-sent events.
+   * Body param: Whether to incrementally stream the response using server-sent
+   * events.
    *
    * See [streaming](https://docs.anthropic.com/en/api/streaming) for details.
    */

package/src/resources/index.ts

@@ -34,8 +34,10 @@ export {
   type CitationContentBlockLocationParam,
   type CitationPageLocation,
   type CitationPageLocationParam,
+  type CitationWebSearchResultLocationParam,
   type CitationsConfigParam,
   type CitationsDelta,
+  type CitationsWebSearchResultLocation,
   type ContentBlock,
   type ContentBlockParam,
   type ContentBlockSource,
@@ -63,6 +65,9 @@ export {
   type RawMessageStreamEvent,
   type RedactedThinkingBlock,
   type RedactedThinkingBlockParam,
+  type ServerToolUsage,
+  type ServerToolUseBlock,
+  type ServerToolUseBlockParam,
   type SignatureDelta,
   type StopReason,
   type TextBlock,
@@ -91,6 +96,15 @@ export {
   type URLImageSource,
   type URLPDFSource,
   type Usage,
+  type WebSearchResultBlock,
+  type WebSearchResultBlockParam,
+  type WebSearchTool20250305,
+  type WebSearchToolRequestError,
+  type WebSearchToolResultBlock,
+  type WebSearchToolResultBlockContent,
+  type WebSearchToolResultBlockParam,
+  type WebSearchToolResultBlockParamContent,
+  type WebSearchToolResultError,
   type MessageStreamEvent,
   type MessageStartEvent,
   type MessageDeltaEvent,
@@ -103,4 +117,10 @@ export {
   type MessageCreateParamsStreaming,
   type MessageCountTokensParams,
 } from "./messages/messages.js";
-export { ModelInfosPage, Models, type ModelInfo, type ModelListParams } from "./models.js";
+export {
+  ModelInfosPage,
+  Models,
+  type ModelInfo,
+  type ModelRetrieveParams,
+  type ModelListParams,
+} from "./models.js";

package/src/resources/messages/batches.ts

@@ -20,6 +20,24 @@ export class Batches extends APIResource {
    *
    * Learn more about the Message Batches API in our
    * [user guide](/en/docs/build-with-claude/batch-processing)
+   *
+   * @example
+   * ```ts
+   * const messageBatch = await client.messages.batches.create({
+   *   requests: [
+   *     {
+   *       custom_id: 'my-custom-id-1',
+   *       params: {
+   *         max_tokens: 1024,
+   *         messages: [
+   *           { content: 'Hello, world', role: 'user' },
+   *         ],
+   *         model: 'claude-3-7-sonnet-20250219',
+   *       },
+   *     },
+   *   ],
+   * });
+   * ```
    */
   create(body: BatchCreateParams, options?: Core.RequestOptions): Core.APIPromise<MessageBatch> {
     return this._client.post('/v1/messages/batches', { body, ...options });
@@ -32,6 +50,13 @@ export class Batches extends APIResource {
    *
    * Learn more about the Message Batches API in our
    * [user guide](/en/docs/build-with-claude/batch-processing)
+   *
+   * @example
+   * ```ts
+   * const messageBatch = await client.messages.batches.retrieve(
+   *   'message_batch_id',
+   * );
+   * ```
    */
   retrieve(messageBatchId: string, options?: Core.RequestOptions): Core.APIPromise<MessageBatch> {
     return this._client.get(`/v1/messages/batches/${messageBatchId}`, options);
@@ -43,6 +68,14 @@ export class Batches extends APIResource {
    *
    * Learn more about the Message Batches API in our
    * [user guide](/en/docs/build-with-claude/batch-processing)
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const messageBatch of client.messages.batches.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: BatchListParams,
@@ -67,6 +100,12 @@ export class Batches extends APIResource {
    *
    * Learn more about the Message Batches API in our
    * [user guide](/en/docs/build-with-claude/batch-processing)
+   *
+   * @example
+   * ```ts
+   * const deletedMessageBatch =
+   *   await client.messages.batches.delete('message_batch_id');
+   * ```
    */
   delete(messageBatchId: string, options?: Core.RequestOptions): Core.APIPromise<DeletedMessageBatch> {
     return this._client.delete(`/v1/messages/batches/${messageBatchId}`, options);
@@ -85,6 +124,13 @@ export class Batches extends APIResource {
    *
    * Learn more about the Message Batches API in our
    * [user guide](/en/docs/build-with-claude/batch-processing)
+   *
+   * @example
+   * ```ts
+   * const messageBatch = await client.messages.batches.cancel(
+   *   'message_batch_id',
+   * );
+   * ```
    */
   cancel(messageBatchId: string, options?: Core.RequestOptions): Core.APIPromise<MessageBatch> {
     return this._client.post(`/v1/messages/batches/${messageBatchId}/cancel`, options);
@@ -99,6 +145,12 @@ export class Batches extends APIResource {
    *
    * Learn more about the Message Batches API in our
    * [user guide](/en/docs/build-with-claude/batch-processing)
+   *
+   * @example
+   * ```ts
+   * const messageBatchIndividualResponse =
+   *   await client.messages.batches.results('message_batch_id');
+   * ```
    */
   async results(
     messageBatchId: string,

package/src/resources/messages/index.ts

@@ -26,8 +26,10 @@ export {
   type CitationContentBlockLocationParam,
   type CitationPageLocation,
   type CitationPageLocationParam,
+  type CitationWebSearchResultLocationParam,
   type CitationsConfigParam,
   type CitationsDelta,
+  type CitationsWebSearchResultLocation,
   type ContentBlock,
   type ContentBlockParam,
   type ContentBlockSource,
@@ -53,6 +55,9 @@ export {
   type RawMessageStreamEvent,
   type RedactedThinkingBlock,
   type RedactedThinkingBlockParam,
+  type ServerToolUsage,
+  type ServerToolUseBlock,
+  type ServerToolUseBlockParam,
   type SignatureDelta,
   type StopReason,
   type TextBlock,
@@ -81,6 +86,15 @@ export {
   type URLImageSource,
   type URLPDFSource,
   type Usage,
+  type WebSearchResultBlock,
+  type WebSearchResultBlockParam,
+  type WebSearchTool20250305,
+  type WebSearchToolRequestError,
+  type WebSearchToolResultBlock,
+  type WebSearchToolResultBlockContent,
+  type WebSearchToolResultBlockParam,
+  type WebSearchToolResultBlockParamContent,
+  type WebSearchToolResultError,
   type MessageStreamEvent,
   type MessageStartEvent,
   type MessageDeltaEvent,