feat(api): add new usage response fields (#281)

api.md

@@ -22,12 +22,14 @@ Types:
 - <code><a href="./src/resources/beta/messages.ts">ContentBlockStopEvent</a></code>
 - <code><a href="./src/resources/beta/messages.ts">Message</a></code>
 - <code><a href="./src/resources/beta/messages.ts">MessageDeltaEvent</a></code>
+- <code><a href="./src/resources/beta/messages.ts">MessageDeltaUsage</a></code>
 - <code><a href="./src/resources/beta/messages.ts">MessageParam</a></code>
 - <code><a href="./src/resources/beta/messages.ts">MessageStartEvent</a></code>
 - <code><a href="./src/resources/beta/messages.ts">MessageStopEvent</a></code>
 - <code><a href="./src/resources/beta/messages.ts">MessageStreamEvent</a></code>
 - <code><a href="./src/resources/beta/messages.ts">TextBlock</a></code>
 - <code><a href="./src/resources/beta/messages.ts">TextDelta</a></code>
+- <code><a href="./src/resources/beta/messages.ts">Usage</a></code>
 
 Methods:
 

src/resources/beta/beta.ts

@@ -15,12 +15,14 @@ export namespace Beta {
   export import ContentBlockStopEvent = MessagesAPI.ContentBlockStopEvent;
   export import Message = MessagesAPI.Message;
   export import MessageDeltaEvent = MessagesAPI.MessageDeltaEvent;
+  export import MessageDeltaUsage = MessagesAPI.MessageDeltaUsage;
   export import MessageParam = MessagesAPI.MessageParam;
   export import MessageStartEvent = MessagesAPI.MessageStartEvent;
   export import MessageStopEvent = MessagesAPI.MessageStopEvent;
   export import MessageStreamEvent = MessagesAPI.MessageStreamEvent;
   export import TextBlock = MessagesAPI.TextBlock;
   export import TextDelta = MessagesAPI.TextDelta;
+  export import Usage = MessagesAPI.Usage;
   export import MessageCreateParams = MessagesAPI.MessageCreateParams;
   export import MessageCreateParamsNonStreaming = MessagesAPI.MessageCreateParamsNonStreaming;
   export import MessageCreateParamsStreaming = MessagesAPI.MessageCreateParamsStreaming;

src/resources/beta/index.ts

@@ -8,12 +8,14 @@ export {
   ContentBlockStopEvent,
   Message,
   MessageDeltaEvent,
+  MessageDeltaUsage,
   MessageParam,
   MessageStartEvent,
   MessageStopEvent,
   MessageStreamEvent,
   TextBlock,
   TextDelta,
+  Usage,
   MessageCreateParams,
   MessageCreateParamsNonStreaming,
   MessageCreateParamsStreaming,

src/resources/beta/messages.ts

@@ -12,7 +12,15 @@ export class Messages extends APIResource {
   /**
    * Create a Message.
    *
-   * The Messages API is currently in beta.
+   * Send a structured list of input messages, and the model will generate the next
+   * message in the conversation.
+   *
+   * Messages can be used for either single queries to the model or for multi-turn
+   * conversations.
+   *
+   * The Messages API is currently in beta. During beta, you must send the
+   * `anthropic-beta: messages-2023-12-15` header in your requests. If you are using
+   * our client SDKs, this is handled for you automatically.
    */
   create(body: MessageCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Message>;
   create(
@@ -156,12 +164,22 @@ export interface Message {
   stop_sequence: string | null;
 
   type: 'message';
+
+  /**
+   * Container for the number of tokens used.
+   */
+  usage: Usage;
 }
 
 export interface MessageDeltaEvent {
   delta: MessageDeltaEvent.Delta;
 
   type: 'message_delta';
+
+  /**
+   * Container for the number of tokens used.
+   */
+  usage: MessageDeltaUsage;
 }
 
 export namespace MessageDeltaEvent {
@@ -172,6 +190,13 @@ export namespace MessageDeltaEvent {
   }
 }
 
+export interface MessageDeltaUsage {
+  /**
+   * The cumulative number of output tokens which were used.
+   */
+  output_tokens: number;
+}
+
 export interface MessageParam {
   content: string | Array<TextBlock>;
 
@@ -208,6 +233,18 @@ export interface TextDelta {
   type: 'text_delta';
 }
 
+export interface Usage {
+  /**
+   * The number of input tokens which were used.
+   */
+  input_tokens: number;
+
+  /**
+   * The number of output tokens which were used.
+   */
+  output_tokens: number;
+}
+
 export type MessageCreateParams = MessageCreateParamsNonStreaming | MessageCreateParamsStreaming;
 
 export interface MessageCreateParamsBase {
@@ -283,6 +320,11 @@ export interface MessageCreateParamsBase {
    * See our
    * [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
    * for more details on how to best construct prompts.
+   *
+   * Note that if you want to include a
+   * [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+   * you can use the top-level `system` parameter — there is no `"system"` role for
+   * input messages in the Messages API.
    */
   messages: Array<MessageParam>;
 
@@ -321,8 +363,8 @@ export interface MessageCreateParamsBase {
   /**
    * Whether to incrementally stream the response using server-sent events.
    *
-   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-   * details.
+   * See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+   * for details.
    */
   stream?: boolean;
 
@@ -374,7 +416,7 @@ export namespace MessageCreateParams {
      * this id to help detect abuse. Do not include any identifying information such as
      * name, email address, or phone number.
      */
-    user_id?: string;
+    user_id?: string | null;
   }
 
   export type MessageCreateParamsNonStreaming = MessagesAPI.MessageCreateParamsNonStreaming;
@@ -385,8 +427,8 @@ export interface MessageCreateParamsNonStreaming extends MessageCreateParamsBase
   /**
    * Whether to incrementally stream the response using server-sent events.
    *
-   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-   * details.
+   * See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+   * for details.
    */
   stream?: false;
 }
@@ -395,8 +437,8 @@ export interface MessageCreateParamsStreaming extends MessageCreateParamsBase {
   /**
    * Whether to incrementally stream the response using server-sent events.
    *
-   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-   * details.
+   * See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+   * for details.
    */
   stream: true;
 }
@@ -474,6 +516,11 @@ export interface MessageStreamParams {
    * See our
    * [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
    * for more details on how to best construct prompts.
+   *
+   * Note that if you want to include a
+   * [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+   * you can use the top-level `system` parameter — there is no `"system"` role for
+   * input messages in the Messages API.
    */
   messages: Array<MessageParam>;
 
@@ -557,7 +604,7 @@ export namespace MessageStreamParams {
      * this id to help detect abuse. Do not include any identifying information such as
      * name, email address, or phone number.
      */
-    user_id?: string;
+    user_id?: string | null;
   }
 }
 
@@ -568,12 +615,14 @@ export namespace Messages {
   export import ContentBlockStopEvent = MessagesAPI.ContentBlockStopEvent;
   export import Message = MessagesAPI.Message;
   export import MessageDeltaEvent = MessagesAPI.MessageDeltaEvent;
+  export import MessageDeltaUsage = MessagesAPI.MessageDeltaUsage;
   export import MessageParam = MessagesAPI.MessageParam;
   export import MessageStartEvent = MessagesAPI.MessageStartEvent;
   export import MessageStopEvent = MessagesAPI.MessageStopEvent;
   export import MessageStreamEvent = MessagesAPI.MessageStreamEvent;
   export import TextBlock = MessagesAPI.TextBlock;
   export import TextDelta = MessagesAPI.TextDelta;
+  export import Usage = MessagesAPI.Usage;
   export import MessageCreateParams = MessagesAPI.MessageCreateParams;
   export import MessageCreateParamsNonStreaming = MessagesAPI.MessageCreateParamsNonStreaming;
   export import MessageCreateParamsStreaming = MessagesAPI.MessageCreateParamsStreaming;

src/resources/completions.ts

@@ -8,7 +8,7 @@ import { Stream } from '@anthropic-ai/sdk/streaming';
 
 export class Completions extends APIResource {
   /**
-   * Create a Completion
+   * Create a Text Completion
    */
   create(body: CompletionCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Completion>;
   create(
@@ -59,7 +59,7 @@ export interface Completion {
    *   `stop_sequences` parameter, or a stop sequence built into the model
    * - `"max_tokens"`: we exceeded `max_tokens_to_sample` or the model's maximum
    */
-  stop_reason: string;
+  stop_reason: string | null;
 
   type: 'completion';
 }
@@ -124,8 +124,9 @@ export interface CompletionCreateParamsBase {
   /**
    * Whether to incrementally stream the response using server-sent events.
    *
-   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-   * details.
+   * See
+   * [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+   * for details.
    */
   stream?: boolean;
 
@@ -168,7 +169,7 @@ export namespace CompletionCreateParams {
      * this id to help detect abuse. Do not include any identifying information such as
      * name, email address, or phone number.
      */
-    user_id?: string;
+    user_id?: string | null;
   }
 
   export type CompletionCreateParamsNonStreaming = CompletionsAPI.CompletionCreateParamsNonStreaming;
@@ -179,8 +180,9 @@ export interface CompletionCreateParamsNonStreaming extends CompletionCreatePara
   /**
    * Whether to incrementally stream the response using server-sent events.
    *
-   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-   * details.
+   * See
+   * [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+   * for details.
    */
   stream?: false;
 }
@@ -189,8 +191,9 @@ export interface CompletionCreateParamsStreaming extends CompletionCreateParamsB
   /**
    * Whether to incrementally stream the response using server-sent events.
    *
-   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-   * details.
+   * See
+   * [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+   * for details.
    */
   stream: true;
 }