@anthropic-ai/sdk 0.40.1 → 0.41.0

package/src/resources/messages/messages.ts

@@ -36,6 +36,15 @@ export class Messages extends APIResource {
    * conversations.
    *
    * Learn more about the Messages API in our [user guide](/en/docs/initial-setup)
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.create({
+   *   max_tokens: 1024,
+   *   messages: [{ content: 'Hello, world', role: 'user' }],
+   *   model: 'claude-3-7-sonnet-20250219',
+   * });
+   * ```
    */
   create(body: MessageCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Message>;
   create(
@@ -82,6 +91,15 @@ export class Messages extends APIResource {
    *
    * Learn more about token counting in our
    * [user guide](/en/docs/build-with-claude/token-counting)
+   *
+   * @example
+   * ```ts
+   * const messageTokensCount =
+   *   await client.messages.countTokens({
+   *     messages: [{ content: 'string', role: 'user' }],
+   *     model: 'claude-3-7-sonnet-latest',
+   *   });
+   * ```
    */
   countTokens(
     body: MessageCountTokensParams,
@@ -195,22 +213,58 @@ export interface CitationPageLocationParam {
   type: 'page_location';
 }
 
+export interface CitationWebSearchResultLocationParam {
+  cited_text: string;
+
+  encrypted_index: string;
+
+  title: string | null;
+
+  type: 'web_search_result_location';
+
+  url: string;
+}
+
 export interface CitationsConfigParam {
   enabled?: boolean;
 }
 
 export interface CitationsDelta {
-  citation: CitationCharLocation | CitationPageLocation | CitationContentBlockLocation;
+  citation:
+    | CitationCharLocation
+    | CitationPageLocation
+    | CitationContentBlockLocation
+    | CitationsWebSearchResultLocation;
 
   type: 'citations_delta';
 }
 
-export type ContentBlock = TextBlock | ToolUseBlock | ThinkingBlock | RedactedThinkingBlock;
+export interface CitationsWebSearchResultLocation {
+  cited_text: string;
+
+  encrypted_index: string;
+
+  title: string | null;
+
+  type: 'web_search_result_location';
+
+  url: string;
+}
+
+export type ContentBlock =
+  | TextBlock
+  | ToolUseBlock
+  | ServerToolUseBlock
+  | WebSearchToolResultBlock
+  | ThinkingBlock
+  | RedactedThinkingBlock;
 
 export type ContentBlockParam =
   | TextBlockParam
   | ImageBlockParam
   | ToolUseBlockParam
+  | ServerToolUseBlockParam
+  | WebSearchToolResultBlockParam
   | ToolResultBlockParam
   | DocumentBlockParam
   | ThinkingBlockParam
@@ -229,6 +283,9 @@ export interface DocumentBlockParam {
 
   type: 'document';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: CacheControlEphemeral | null;
 
   citations?: CitationsConfigParam;
@@ -243,6 +300,9 @@ export interface ImageBlockParam {
 
   type: 'image';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: CacheControlEphemeral | null;
 }
 
@@ -362,13 +422,33 @@ export interface Message {
   usage: Usage;
 }
 
-export type MessageCountTokensTool = Tool | ToolBash20250124 | ToolTextEditor20250124;
+export type MessageCountTokensTool = Tool | ToolBash20250124 | ToolTextEditor20250124 | WebSearchTool20250305;
 
 export interface MessageDeltaUsage {
+  /**
+   * 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: ServerToolUsage | null;
 }
 
 export interface MessageParam {
@@ -454,7 +534,13 @@ export interface RawContentBlockDeltaEvent {
 }
 
 export interface RawContentBlockStartEvent {
-  content_block: TextBlock | ToolUseBlock | ThinkingBlock | RedactedThinkingBlock;
+  content_block:
+    | TextBlock
+    | ToolUseBlock
+    | ServerToolUseBlock
+    | WebSearchToolResultBlock
+    | ThinkingBlock
+    | RedactedThinkingBlock;
 
   index: number;
 
@@ -530,13 +616,45 @@ export interface RedactedThinkingBlockParam {
   type: 'redacted_thinking';
 }
 
+export interface ServerToolUsage {
+  /**
+   * The number of web search tool requests.
+   */
+  web_search_requests: number;
+}
+
+export interface ServerToolUseBlock {
+  id: string;
+
+  input: unknown;
+
+  name: 'web_search';
+
+  type: 'server_tool_use';
+}
+
+export interface ServerToolUseBlockParam {
+  id: string;
+
+  input: unknown;
+
+  name: 'web_search';
+
+  type: 'server_tool_use';
+
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cache_control?: CacheControlEphemeral | null;
+}
+
 export interface SignatureDelta {
   signature: string;
 
   type: 'signature_delta';
 }
 
-export type StopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+export type StopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal';
 
 export interface TextBlock {
   /**
@@ -558,17 +676,25 @@ export interface TextBlockParam {
 
   type: 'text';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: CacheControlEphemeral | null;
 
   citations?: Array<TextCitationParam> | null;
 }
 
-export type TextCitation = CitationCharLocation | CitationPageLocation | CitationContentBlockLocation;
+export type TextCitation =
+  | CitationCharLocation
+  | CitationPageLocation
+  | CitationContentBlockLocation
+  | CitationsWebSearchResultLocation;
 
 export type TextCitationParam =
   | CitationCharLocationParam
   | CitationPageLocationParam
-  | CitationContentBlockLocationParam;
+  | CitationContentBlockLocationParam
+  | CitationWebSearchResultLocationParam;
 
 export interface TextDelta {
   text: string;
@@ -644,10 +770,13 @@ export interface Tool {
   /**
    * 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?: CacheControlEphemeral | null;
 
   /**
@@ -659,6 +788,8 @@ export interface Tool {
    * aspects of the tool input JSON schema.
    */
   description?: string;
+
+  type?: 'custom' | null;
 }
 
 export namespace Tool {
@@ -681,12 +812,15 @@ export interface ToolBash20250124 {
   /**
    * 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?: CacheControlEphemeral | null;
 }
 
@@ -758,6 +892,9 @@ export interface ToolResultBlockParam {
 
   type: 'tool_result';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: CacheControlEphemeral | null;
 
   content?: string | Array<TextBlockParam | ImageBlockParam>;
@@ -769,16 +906,19 @@ export interface ToolTextEditor20250124 {
   /**
    * 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?: CacheControlEphemeral | null;
 }
 
-export type ToolUnion = Tool | ToolBash20250124 | ToolTextEditor20250124;
+export type ToolUnion = Tool | ToolBash20250124 | ToolTextEditor20250124 | WebSearchTool20250305;
 
 export interface ToolUseBlock {
   id: string;
@@ -799,6 +939,9 @@ export interface ToolUseBlockParam {
 
   type: 'tool_use';
 
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
   cache_control?: CacheControlEphemeral | null;
 }
 
@@ -834,6 +977,155 @@ export interface Usage {
    * The number of output tokens which were used.
    */
   output_tokens: number;
+
+  /**
+   * The number of server tool requests.
+   */
+  server_tool_use: ServerToolUsage | null;
+}
+
+export interface WebSearchResultBlock {
+  encrypted_content: string;
+
+  page_age: string | null;
+
+  title: string;
+
+  type: 'web_search_result';
+
+  url: string;
+}
+
+export interface WebSearchResultBlockParam {
+  encrypted_content: string;
+
+  title: string;
+
+  type: 'web_search_result';
+
+  url: string;
+
+  page_age?: string | null;
+}
+
+export interface WebSearchTool20250305 {
+  /**
+   * 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?: CacheControlEphemeral | 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?: WebSearchTool20250305.UserLocation | null;
+}
+
+export namespace WebSearchTool20250305 {
+  /**
+   * 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 WebSearchToolRequestError {
+  error_code:
+    | 'invalid_tool_input'
+    | 'unavailable'
+    | 'max_uses_exceeded'
+    | 'too_many_requests'
+    | 'query_too_long';
+
+  type: 'web_search_tool_result_error';
+}
+
+export interface WebSearchToolResultBlock {
+  content: WebSearchToolResultBlockContent;
+
+  tool_use_id: string;
+
+  type: 'web_search_tool_result';
+}
+
+export type WebSearchToolResultBlockContent = WebSearchToolResultError | Array<WebSearchResultBlock>;
+
+export interface WebSearchToolResultBlockParam {
+  content: WebSearchToolResultBlockParamContent;
+
+  tool_use_id: string;
+
+  type: 'web_search_tool_result';
+
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cache_control?: CacheControlEphemeral | null;
+}
+
+export type WebSearchToolResultBlockParamContent =
+  | Array<WebSearchResultBlockParam>
+  | WebSearchToolRequestError;
+
+export interface WebSearchToolResultError {
+  error_code:
+    | 'invalid_tool_input'
+    | 'unavailable'
+    | 'max_uses_exceeded'
+    | 'too_many_requests'
+    | 'query_too_long';
+
+  type: 'web_search_tool_result_error';
 }
 
 export type MessageStreamEvent = RawMessageStreamEvent;
@@ -951,6 +1243,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<MessageParam>;
 
@@ -1260,6 +1554,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<MessageParam>;
 
@@ -1386,8 +1682,10 @@ export declare namespace Messages {
     type CitationContentBlockLocationParam as CitationContentBlockLocationParam,
     type CitationPageLocation as CitationPageLocation,
     type CitationPageLocationParam as CitationPageLocationParam,
+    type CitationWebSearchResultLocationParam as CitationWebSearchResultLocationParam,
     type CitationsConfigParam as CitationsConfigParam,
     type CitationsDelta as CitationsDelta,
+    type CitationsWebSearchResultLocation as CitationsWebSearchResultLocation,
     type ContentBlock as ContentBlock,
     type ContentBlockParam as ContentBlockParam,
     type ContentBlockSource as ContentBlockSource,
@@ -1414,6 +1712,9 @@ export declare namespace Messages {
     type RawMessageStreamEvent as RawMessageStreamEvent,
     type RedactedThinkingBlock as RedactedThinkingBlock,
     type RedactedThinkingBlockParam as RedactedThinkingBlockParam,
+    type ServerToolUsage as ServerToolUsage,
+    type ServerToolUseBlock as ServerToolUseBlock,
+    type ServerToolUseBlockParam as ServerToolUseBlockParam,
     type SignatureDelta as SignatureDelta,
     type StopReason as StopReason,
     type TextBlock as TextBlock,
@@ -1442,6 +1743,15 @@ export declare namespace Messages {
     type URLImageSource as URLImageSource,
     type URLPDFSource as URLPDFSource,
     type Usage as Usage,
+    type WebSearchResultBlock as WebSearchResultBlock,
+    type WebSearchResultBlockParam as WebSearchResultBlockParam,
+    type WebSearchTool20250305 as WebSearchTool20250305,
+    type WebSearchToolRequestError as WebSearchToolRequestError,
+    type WebSearchToolResultBlock as WebSearchToolResultBlock,
+    type WebSearchToolResultBlockContent as WebSearchToolResultBlockContent,
+    type WebSearchToolResultBlockParam as WebSearchToolResultBlockParam,
+    type WebSearchToolResultBlockParamContent as WebSearchToolResultBlockParamContent,
+    type WebSearchToolResultError as WebSearchToolResultError,
     type MessageStreamEvent as MessageStreamEvent,
     type MessageStartEvent as MessageStartEvent,
     type MessageDeltaEvent as MessageDeltaEvent,

package/src/resources/models.ts

@@ -3,6 +3,7 @@
 import { APIResource } from "../resource.js";
 import { isRequestOptions } from "../core.js";
 import * as Core from "../core.js";
+import * as BetaAPI from "./beta/beta.js";
 import { Page, type PageParams } from "../pagination.js";
 
 export class Models extends APIResource {
@@ -12,8 +13,28 @@ export class Models extends APIResource {
    * The Models API response can be used to determine information about a specific
    * model or resolve a model alias to a model ID.
    */
-  retrieve(modelId: string, options?: Core.RequestOptions): Core.APIPromise<ModelInfo> {
-    return this._client.get(`/v1/models/${modelId}`, options);
+  retrieve(
+    modelId: string,
+    params?: ModelRetrieveParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ModelInfo>;
+  retrieve(modelId: string, options?: Core.RequestOptions): Core.APIPromise<ModelInfo>;
+  retrieve(
+    modelId: string,
+    params: ModelRetrieveParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ModelInfo> {
+    if (isRequestOptions(params)) {
+      return this.retrieve(modelId, {}, params);
+    }
+    const { betas } = params;
+    return this._client.get(`/v1/models/${modelId}`, {
+      ...options,
+      headers: {
+        ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined),
+        ...options?.headers,
+      },
+    });
   }
 
   /**
@@ -22,16 +43,24 @@ export class Models extends APIResource {
    * The Models API response can be used to determine which models are available for
    * use in the API. More recently released models are listed first.
    */
-  list(query?: ModelListParams, options?: Core.RequestOptions): Core.PagePromise<ModelInfosPage, ModelInfo>;
+  list(params?: ModelListParams, options?: Core.RequestOptions): Core.PagePromise<ModelInfosPage, ModelInfo>;
   list(options?: Core.RequestOptions): Core.PagePromise<ModelInfosPage, ModelInfo>;
   list(
-    query: ModelListParams | Core.RequestOptions = {},
+    params: ModelListParams | Core.RequestOptions = {},
     options?: Core.RequestOptions,
   ): Core.PagePromise<ModelInfosPage, ModelInfo> {
-    if (isRequestOptions(query)) {
-      return this.list({}, query);
+    if (isRequestOptions(params)) {
+      return this.list({}, params);
     }
-    return this._client.getAPIList('/v1/models', ModelInfosPage, { query, ...options });
+    const { betas, ...query } = params;
+    return this._client.getAPIList('/v1/models', ModelInfosPage, {
+      query,
+      ...options,
+      headers: {
+        ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined),
+        ...options?.headers,
+      },
+    });
   }
 }
 
@@ -62,7 +91,19 @@ export interface ModelInfo {
   type: 'model';
 }
 
-export interface ModelListParams extends PageParams {}
+export interface ModelRetrieveParams {
+  /**
+   * Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+export interface ModelListParams extends PageParams {
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
 
 Models.ModelInfosPage = ModelInfosPage;
 
@@ -70,6 +111,7 @@ export declare namespace Models {
   export {
     type ModelInfo as ModelInfo,
     ModelInfosPage as ModelInfosPage,
+    type ModelRetrieveParams as ModelRetrieveParams,
     type ModelListParams as ModelListParams,
   };
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.40.1'; // x-release-please-version
+export const VERSION = '0.41.0'; // x-release-please-version

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.40.1";
+export declare const VERSION = "0.41.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.40.1'; // x-release-please-version
+exports.VERSION = '0.41.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.40.1'; // x-release-please-version
+export const VERSION = '0.41.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map