@anthropic-ai/sdk 0.40.1 → 0.50.1

package/src/resources/beta/messages/messages.ts

@@ -1,12 +1,10 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from "../../../resource.js";
-import { APIPromise } from "../../../core.js";
-import * as Core from "../../../core.js";
-import * as MessagesMessagesAPI from "./messages.js";
-import * as BetaAPI from "../beta.js";
-import * as MessagesAPI from "../../messages/messages.js";
-import * as BatchesAPI from "./batches.js";
+import { APIResource } from '../../../core/resource';
+import * as MessagesMessagesAPI from './messages';
+import * as BetaAPI from '../beta';
+import * as MessagesAPI from '../../messages/messages';
+import * as BatchesAPI from './batches';
 import {
   BatchCancelParams,
   BatchCreateParams,
@@ -25,10 +23,13 @@ import {
   BetaMessageBatchResult,
   BetaMessageBatchSucceededResult,
   BetaMessageBatchesPage,
-} from "./batches.js";
-import { Stream } from "../../../streaming.js";
-import { BetaMessageStream } from "../../../lib/BetaMessageStream.js";
-import type { Model } from "../../messages/messages.js";
+} from './batches';
+import { APIPromise } from '../../../core/api-promise';
+import { Stream } from '../../../core/streaming';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import type { Model } from '../../messages/messages';
+import { BetaMessageStream } from '../../../lib/BetaMessageStream';
 
 const DEPRECATED_MODELS: {
   [K in Model]?: string;
@@ -54,19 +55,28 @@ export class Messages extends APIResource {
    * conversations.
    *
    * Learn more about the Messages API in our [user guide](/en/docs/initial-setup)
+   *
+   * @example
+   * ```ts
+   * const betaMessage = await client.beta.messages.create({
+   *   max_tokens: 1024,
+   *   messages: [{ content: 'Hello, world', role: 'user' }],
+   *   model: 'claude-3-7-sonnet-20250219',
+   * });
+   * ```
    */
-  create(params: MessageCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<BetaMessage>;
+  create(params: MessageCreateParamsNonStreaming, options?: RequestOptions): APIPromise<BetaMessage>;
   create(
     params: MessageCreateParamsStreaming,
-    options?: Core.RequestOptions,
+    options?: RequestOptions,
   ): APIPromise<Stream<BetaRawMessageStreamEvent>>;
   create(
     params: MessageCreateParamsBase,
-    options?: Core.RequestOptions,
+    options?: RequestOptions,
   ): APIPromise<Stream<BetaRawMessageStreamEvent> | BetaMessage>;
   create(
     params: MessageCreateParams,
-    options?: Core.RequestOptions,
+    options?: RequestOptions,
   ): APIPromise<BetaMessage> | APIPromise<Stream<BetaRawMessageStreamEvent>> {
     const { betas, ...body } = params;
 
@@ -84,10 +94,10 @@ export class Messages extends APIResource {
         (this._client as any)._options.timeout ??
         (body.stream ? 600000 : this._client._calculateNonstreamingTimeout(body.max_tokens)),
       ...options,
-      headers: {
-        ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined),
-        ...options?.headers,
-      },
+      headers: buildHeaders([
+        { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
+        options?.headers,
+      ]),
       stream: params.stream ?? false,
     }) as APIPromise<BetaMessage> | APIPromise<Stream<BetaRawMessageStreamEvent>>;
   }
@@ -95,7 +105,7 @@ export class Messages extends APIResource {
   /**
    * Create a Message stream
    */
-  stream(body: BetaMessageStreamParams, options?: Core.RequestOptions): BetaMessageStream {
+  stream(body: BetaMessageStreamParams, options?: RequestOptions): BetaMessageStream {
     return BetaMessageStream.createMessage(this, body, options);
   }
 
@@ -107,19 +117,28 @@ export class Messages extends APIResource {
    *
    * Learn more about token counting in our
    * [user guide](/en/docs/build-with-claude/token-counting)
+   *
+   * @example
+   * ```ts
+   * const betaMessageTokensCount =
+   *   await client.beta.messages.countTokens({
+   *     messages: [{ content: 'string', role: 'user' }],
+   *     model: 'claude-3-7-sonnet-latest',
+   *   });
+   * ```
    */
   countTokens(
     params: MessageCountTokensParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<BetaMessageTokensCount> {
+    options?: RequestOptions,
+  ): APIPromise<BetaMessageTokensCount> {
     const { betas, ...body } = params;
     return this._client.post('/v1/messages/count_tokens?beta=true', {
       body,
       ...options,
-      headers: {
-        'anthropic-beta': [...(betas ?? []), 'token-counting-2024-11-01'].toString(),
-        ...options?.headers,
-      },
+      headers: buildHeaders([
+        { 'anthropic-beta': [...(betas ?? []), 'token-counting-2024-11-01'].toString() },
+        options?.headers,
+      ]),
     });
   }
 }
@@ -139,6 +158,9 @@ export interface BetaBase64PDFBlock {
 
   type: 'document';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 
   citations?: BetaCitationsConfigParam;
@@ -244,19 +266,49 @@ export interface BetaCitationPageLocationParam {
   type: 'page_location';
 }
 
+export interface BetaCitationWebSearchResultLocationParam {
+  cited_text: string;
+
+  encrypted_index: string;
+
+  title: string | null;
+
+  type: 'web_search_result_location';
+
+  url: string;
+}
+
 export interface BetaCitationsConfigParam {
   enabled?: boolean;
 }
 
 export interface BetaCitationsDelta {
-  citation: BetaCitationCharLocation | BetaCitationPageLocation | BetaCitationContentBlockLocation;
+  citation:
+    | BetaCitationCharLocation
+    | BetaCitationPageLocation
+    | BetaCitationContentBlockLocation
+    | BetaCitationsWebSearchResultLocation;
 
   type: 'citations_delta';
 }
 
+export interface BetaCitationsWebSearchResultLocation {
+  cited_text: string;
+
+  encrypted_index: string;
+
+  title: string | null;
+
+  type: 'web_search_result_location';
+
+  url: string;
+}
+
 export type BetaContentBlock =
   | BetaTextBlock
   | BetaToolUseBlock
+  | BetaServerToolUseBlock
+  | BetaWebSearchToolResultBlock
   | BetaThinkingBlock
   | BetaRedactedThinkingBlock;
 
@@ -264,6 +316,8 @@ export type BetaContentBlockParam =
   | BetaTextBlockParam
   | BetaImageBlockParam
   | BetaToolUseBlockParam
+  | BetaServerToolUseBlockParam
+  | BetaWebSearchToolResultBlockParam
   | BetaToolResultBlockParam
   | BetaBase64PDFBlock
   | BetaThinkingBlockParam
@@ -282,6 +336,9 @@ export interface BetaImageBlockParam {
 
   type: 'image';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 }
 
@@ -400,10 +457,30 @@ export interface BetaMessage {
 }
 
 export interface BetaMessageDeltaUsage {
+  /**
+   * The cumulative number of input tokens used to create the cache entry.
+   */
+  cache_creation_input_tokens: number | null;
+
+  /**
+   * The cumulative number of input tokens read from the cache.
+   */
+  cache_read_input_tokens: number | null;
+
+  /**
+   * The cumulative number of input tokens which were used.
+   */
+  input_tokens: number | null;
+
   /**
    * The cumulative number of output tokens which were used.
    */
   output_tokens: number;
+
+  /**
+   * The number of server tool requests.
+   */
+  server_tool_use: BetaServerToolUsage | null;
 }
 
 export interface BetaMessageParam {
@@ -455,7 +532,13 @@ export interface BetaRawContentBlockDeltaEvent {
 }
 
 export interface BetaRawContentBlockStartEvent {
-  content_block: BetaTextBlock | BetaToolUseBlock | BetaThinkingBlock | BetaRedactedThinkingBlock;
+  content_block:
+    | BetaTextBlock
+    | BetaToolUseBlock
+    | BetaServerToolUseBlock
+    | BetaWebSearchToolResultBlock
+    | BetaThinkingBlock
+    | BetaRedactedThinkingBlock;
 
   index: number;
 
@@ -531,13 +614,51 @@ export interface BetaRedactedThinkingBlockParam {
   type: 'redacted_thinking';
 }
 
+export interface BetaServerToolUsage {
+  /**
+   * The number of web search tool requests.
+   */
+  web_search_requests: number;
+}
+
+export interface BetaServerToolUseBlock {
+  id: string;
+
+  input: unknown;
+
+  name: 'web_search';
+
+  type: 'server_tool_use';
+}
+
+export interface BetaServerToolUseBlockParam {
+  id: string;
+
+  input: unknown;
+
+  name: 'web_search';
+
+  type: 'server_tool_use';
+
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cache_control?: BetaCacheControlEphemeral | null;
+}
+
 export interface BetaSignatureDelta {
   signature: string;
 
   type: 'signature_delta';
 }
 
-export type BetaStopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+export type BetaStopReason =
+  | 'end_turn'
+  | 'max_tokens'
+  | 'stop_sequence'
+  | 'tool_use'
+  | 'pause_turn'
+  | 'refusal';
 
 export interface BetaTextBlock {
   /**
@@ -559,6 +680,9 @@ export interface BetaTextBlockParam {
 
   type: 'text';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 
   citations?: Array<BetaTextCitationParam> | null;
@@ -567,12 +691,14 @@ export interface BetaTextBlockParam {
 export type BetaTextCitation =
   | BetaCitationCharLocation
   | BetaCitationPageLocation
-  | BetaCitationContentBlockLocation;
+  | BetaCitationContentBlockLocation
+  | BetaCitationsWebSearchResultLocation;
 
 export type BetaTextCitationParam =
   | BetaCitationCharLocationParam
   | BetaCitationPageLocationParam
-  | BetaCitationContentBlockLocationParam;
+  | BetaCitationContentBlockLocationParam
+  | BetaCitationWebSearchResultLocationParam;
 
 export interface BetaTextDelta {
   text: string;
@@ -648,10 +774,13 @@ export interface BetaTool {
   /**
    * Name of the tool.
    *
-   * This is how the tool will be called by the model and in tool_use blocks.
+   * This is how the tool will be called by the model and in `tool_use` blocks.
    */
   name: string;
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 
   /**
@@ -687,12 +816,15 @@ export interface BetaToolBash20241022 {
   /**
    * Name of the tool.
    *
-   * This is how the tool will be called by the model and in tool_use blocks.
+   * This is how the tool will be called by the model and in `tool_use` blocks.
    */
   name: 'bash';
 
   type: 'bash_20241022';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 }
 
@@ -700,12 +832,15 @@ export interface BetaToolBash20250124 {
   /**
    * Name of the tool.
    *
-   * This is how the tool will be called by the model and in tool_use blocks.
+   * This is how the tool will be called by the model and in `tool_use` blocks.
    */
   name: 'bash';
 
   type: 'bash_20250124';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 }
 
@@ -786,12 +921,15 @@ export interface BetaToolComputerUse20241022 {
   /**
    * Name of the tool.
    *
-   * This is how the tool will be called by the model and in tool_use blocks.
+   * This is how the tool will be called by the model and in `tool_use` blocks.
    */
   name: 'computer';
 
   type: 'computer_20241022';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 
   /**
@@ -814,12 +952,15 @@ export interface BetaToolComputerUse20250124 {
   /**
    * Name of the tool.
    *
-   * This is how the tool will be called by the model and in tool_use blocks.
+   * This is how the tool will be called by the model and in `tool_use` blocks.
    */
   name: 'computer';
 
   type: 'computer_20250124';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 
   /**
@@ -833,6 +974,9 @@ export interface BetaToolResultBlockParam {
 
   type: 'tool_result';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 
   content?: string | Array<BetaTextBlockParam | BetaImageBlockParam>;
@@ -844,12 +988,15 @@ export interface BetaToolTextEditor20241022 {
   /**
    * Name of the tool.
    *
-   * This is how the tool will be called by the model and in tool_use blocks.
+   * This is how the tool will be called by the model and in `tool_use` blocks.
    */
   name: 'str_replace_editor';
 
   type: 'text_editor_20241022';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 }
 
@@ -857,12 +1004,15 @@ export interface BetaToolTextEditor20250124 {
   /**
    * Name of the tool.
    *
-   * This is how the tool will be called by the model and in tool_use blocks.
+   * This is how the tool will be called by the model and in `tool_use` blocks.
    */
   name: 'str_replace_editor';
 
   type: 'text_editor_20250124';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 }
 
@@ -873,7 +1023,8 @@ export type BetaToolUnion =
   | BetaToolTextEditor20241022
   | BetaToolComputerUse20250124
   | BetaToolBash20250124
-  | BetaToolTextEditor20250124;
+  | BetaToolTextEditor20250124
+  | BetaWebSearchTool20250305;
 
 export interface BetaToolUseBlock {
   id: string;
@@ -894,6 +1045,9 @@ export interface BetaToolUseBlockParam {
 
   type: 'tool_use';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: BetaCacheControlEphemeral | null;
 }
 
@@ -929,6 +1083,157 @@ export interface BetaUsage {
    * The number of output tokens which were used.
    */
   output_tokens: number;
+
+  /**
+   * The number of server tool requests.
+   */
+  server_tool_use: BetaServerToolUsage | null;
+}
+
+export interface BetaWebSearchResultBlock {
+  encrypted_content: string;
+
+  page_age: string | null;
+
+  title: string;
+
+  type: 'web_search_result';
+
+  url: string;
+}
+
+export interface BetaWebSearchResultBlockParam {
+  encrypted_content: string;
+
+  title: string;
+
+  type: 'web_search_result';
+
+  url: string;
+
+  page_age?: string | null;
+}
+
+export interface BetaWebSearchTool20250305 {
+  /**
+   * Name of the tool.
+   *
+   * This is how the tool will be called by the model and in `tool_use` blocks.
+   */
+  name: 'web_search';
+
+  type: 'web_search_20250305';
+
+  /**
+   * If provided, only these domains will be included in results. Cannot be used
+   * alongside `blocked_domains`.
+   */
+  allowed_domains?: Array<string> | null;
+
+  /**
+   * If provided, these domains will never appear in results. Cannot be used
+   * alongside `allowed_domains`.
+   */
+  blocked_domains?: Array<string> | null;
+
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cache_control?: BetaCacheControlEphemeral | null;
+
+  /**
+   * Maximum number of times the tool can be used in the API request.
+   */
+  max_uses?: number | null;
+
+  /**
+   * Parameters for the user's location. Used to provide more relevant search
+   * results.
+   */
+  user_location?: BetaWebSearchTool20250305.UserLocation | null;
+}
+
+export namespace BetaWebSearchTool20250305 {
+  /**
+   * Parameters for the user's location. Used to provide more relevant search
+   * results.
+   */
+  export interface UserLocation {
+    type: 'approximate';
+
+    /**
+     * The city of the user.
+     */
+    city?: string | null;
+
+    /**
+     * The two letter
+     * [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the
+     * user.
+     */
+    country?: string | null;
+
+    /**
+     * The region of the user.
+     */
+    region?: string | null;
+
+    /**
+     * The [IANA timezone](https://nodatime.org/TimeZones) of the user.
+     */
+    timezone?: string | null;
+  }
+}
+
+export interface BetaWebSearchToolRequestError {
+  error_code:
+    | 'invalid_tool_input'
+    | 'unavailable'
+    | 'max_uses_exceeded'
+    | 'too_many_requests'
+    | 'query_too_long';
+
+  type: 'web_search_tool_result_error';
+}
+
+export interface BetaWebSearchToolResultBlock {
+  content: BetaWebSearchToolResultBlockContent;
+
+  tool_use_id: string;
+
+  type: 'web_search_tool_result';
+}
+
+export type BetaWebSearchToolResultBlockContent =
+  | BetaWebSearchToolResultError
+  | Array<BetaWebSearchResultBlock>;
+
+export interface BetaWebSearchToolResultBlockParam {
+  content: BetaWebSearchToolResultBlockParamContent;
+
+  tool_use_id: string;
+
+  type: 'web_search_tool_result';
+
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cache_control?: BetaCacheControlEphemeral | null;
+}
+
+export type BetaWebSearchToolResultBlockParamContent =
+  | Array<BetaWebSearchResultBlockParam>
+  | BetaWebSearchToolRequestError;
+
+export interface BetaWebSearchToolResultError {
+  error_code:
+    | 'invalid_tool_input'
+    | 'unavailable'
+    | 'max_uses_exceeded'
+    | 'too_many_requests'
+    | 'query_too_long';
+
+  type: 'web_search_tool_result_error';
 }
 
 export type MessageCreateParams = MessageCreateParamsNonStreaming | MessageCreateParamsStreaming;
@@ -1032,6 +1337,8 @@ export interface MessageCreateParamsBase {
    * [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use
    * the top-level `system` parameter — there is no `"system"` role for input
    * messages in the Messages API.
+   *
+   * There is a limit of 100000 messages in a single request.
    */
   messages: Array<BetaMessageParam>;
 
@@ -1327,6 +1634,8 @@ export interface MessageCountTokensParams {
    * [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use
    * the top-level `system` parameter — there is no `"system"` role for input
    * messages in the Messages API.
+   *
+   * There is a limit of 100000 messages in a single request.
    */
   messages: Array<BetaMessageParam>;
 
@@ -1444,6 +1753,7 @@ export interface MessageCountTokensParams {
     | BetaToolComputerUse20250124
     | BetaToolBash20250124
     | BetaToolTextEditor20250124
+    | BetaWebSearchTool20250305
   >;
 
   /**
@@ -1453,7 +1763,6 @@ export interface MessageCountTokensParams {
 }
 
 Messages.Batches = Batches;
-Messages.BetaMessageBatchesPage = BetaMessageBatchesPage;
 
 export declare namespace Messages {
   export {
@@ -1467,8 +1776,10 @@ export declare namespace Messages {
     type BetaCitationContentBlockLocationParam as BetaCitationContentBlockLocationParam,
     type BetaCitationPageLocation as BetaCitationPageLocation,
     type BetaCitationPageLocationParam as BetaCitationPageLocationParam,
+    type BetaCitationWebSearchResultLocationParam as BetaCitationWebSearchResultLocationParam,
     type BetaCitationsConfigParam as BetaCitationsConfigParam,
     type BetaCitationsDelta as BetaCitationsDelta,
+    type BetaCitationsWebSearchResultLocation as BetaCitationsWebSearchResultLocation,
     type BetaContentBlock as BetaContentBlock,
     type BetaContentBlockParam as BetaContentBlockParam,
     type BetaContentBlockSource as BetaContentBlockSource,
@@ -1491,6 +1802,9 @@ export declare namespace Messages {
     type BetaRawMessageStreamEvent as BetaRawMessageStreamEvent,
     type BetaRedactedThinkingBlock as BetaRedactedThinkingBlock,
     type BetaRedactedThinkingBlockParam as BetaRedactedThinkingBlockParam,
+    type BetaServerToolUsage as BetaServerToolUsage,
+    type BetaServerToolUseBlock as BetaServerToolUseBlock,
+    type BetaServerToolUseBlockParam as BetaServerToolUseBlockParam,
     type BetaSignatureDelta as BetaSignatureDelta,
     type BetaStopReason as BetaStopReason,
     type BetaTextBlock as BetaTextBlock,
@@ -1523,6 +1837,15 @@ export declare namespace Messages {
     type BetaURLImageSource as BetaURLImageSource,
     type BetaURLPDFSource as BetaURLPDFSource,
     type BetaUsage as BetaUsage,
+    type BetaWebSearchResultBlock as BetaWebSearchResultBlock,
+    type BetaWebSearchResultBlockParam as BetaWebSearchResultBlockParam,
+    type BetaWebSearchTool20250305 as BetaWebSearchTool20250305,
+    type BetaWebSearchToolRequestError as BetaWebSearchToolRequestError,
+    type BetaWebSearchToolResultBlock as BetaWebSearchToolResultBlock,
+    type BetaWebSearchToolResultBlockContent as BetaWebSearchToolResultBlockContent,
+    type BetaWebSearchToolResultBlockParam as BetaWebSearchToolResultBlockParam,
+    type BetaWebSearchToolResultBlockParamContent as BetaWebSearchToolResultBlockParamContent,
+    type BetaWebSearchToolResultError as BetaWebSearchToolResultError,
     type MessageCreateParams as MessageCreateParams,
     type MessageCreateParamsNonStreaming as MessageCreateParamsNonStreaming,
     type MessageCreateParamsStreaming as MessageCreateParamsStreaming,
@@ -1540,7 +1863,7 @@ export declare namespace Messages {
     type BetaMessageBatchRequestCounts as BetaMessageBatchRequestCounts,
     type BetaMessageBatchResult as BetaMessageBatchResult,
     type BetaMessageBatchSucceededResult as BetaMessageBatchSucceededResult,
-    BetaMessageBatchesPage as BetaMessageBatchesPage,
+    type BetaMessageBatchesPage as BetaMessageBatchesPage,
     type BatchCreateParams as BatchCreateParams,
     type BatchRetrieveParams as BatchRetrieveParams,
     type BatchListParams as BatchListParams,

package/src/resources/beta/messages.ts

@@ -1,3 +1,3 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export * from "./messages/index.js";
+export * from './messages/index';