@anthropic-ai/sdk 0.68.0 → 0.69.0

package/src/lib/BetaMessageStream.ts

@@ -1,22 +1,24 @@
-import { isAbortError } from '../internal/errors';
+import { partialParse } from '../_vendor/partial-json-parser/parser';
 import { AnthropicError, APIUserAbortError } from '../error';
+import { isAbortError } from '../internal/errors';
+import { type RequestOptions } from '../internal/request-options';
 import {
   type BetaContentBlock,
-  Messages as BetaMessages,
+  type BetaMCPToolUseBlock,
   type BetaMessage,
-  type BetaRawMessageStreamEvent as BetaMessageStreamEvent,
   type BetaMessageParam,
-  type MessageCreateParams as BetaMessageCreateParams,
-  type MessageCreateParamsBase as BetaMessageCreateParamsBase,
+  Messages as BetaMessages,
+  type BetaRawMessageStreamEvent as BetaMessageStreamEvent,
+  type BetaServerToolUseBlock,
   type BetaTextBlock,
   type BetaTextCitation,
   type BetaToolUseBlock,
-  type BetaServerToolUseBlock,
-  type BetaMCPToolUseBlock,
+  type MessageCreateParams,
+  type MessageCreateParamsBase,
+  MessageCreateParamsStreaming,
 } from '../resources/beta/messages/messages';
 import { Stream } from '../streaming';
-import { partialParse } from '../_vendor/partial-json-parser/parser';
-import { type RequestOptions } from '../internal/request-options';
+import { maybeParseBetaMessage, type ParsedBetaMessage } from './beta-parser';
 
 export interface MessageStreamEvents {
   connect: () => void;
@@ -47,10 +49,11 @@ function tracksToolInput(content: BetaContentBlock): content is TracksToolInput
   return content.type === 'tool_use' || content.type === 'server_tool_use' || content.type === 'mcp_tool_use';
 }
 
-export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent> {
+export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMessageStreamEvent> {
   messages: BetaMessageParam[] = [];
-  receivedMessages: BetaMessage[] = [];
+  receivedMessages: ParsedBetaMessage<ParsedT>[] = [];
   #currentMessageSnapshot: BetaMessage | undefined;
+  #params: MessageCreateParams | null = null;
 
   controller: AbortController = new AbortController();
 
@@ -71,7 +74,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
   #response: Response | null | undefined;
   #request_id: string | null | undefined;
 
-  constructor() {
+  constructor(params: MessageCreateParamsBase | null) {
     this.#connectedPromise = new Promise<Response | null>((resolve, reject) => {
       this.#resolveConnectedPromise = resolve;
       this.#rejectConnectedPromise = reject;
@@ -88,6 +91,8 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
     // any promise-returning method.
     this.#connectedPromise.catch(() => {});
     this.#endPromise.catch(() => {});
+
+    this.#params = params;
   }
 
   get response(): Response | null | undefined {
@@ -109,7 +114,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
    * as no `Response` is available.
    */
   async withResponse(): Promise<{
-    data: BetaMessageStream;
+    data: BetaMessageStream<ParsedT>;
     response: Response;
     request_id: string | null | undefined;
   }> {
@@ -133,20 +138,21 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
    * in this context.
    */
   static fromReadableStream(stream: ReadableStream): BetaMessageStream {
-    const runner = new BetaMessageStream();
+    const runner = new BetaMessageStream(null);
     runner._run(() => runner._fromReadableStream(stream));
     return runner;
   }
 
-  static createMessage(
+  static createMessage<ParsedT>(
     messages: BetaMessages,
-    params: BetaMessageCreateParamsBase,
+    params: MessageCreateParamsBase,
     options?: RequestOptions,
-  ): BetaMessageStream {
-    const runner = new BetaMessageStream();
+  ): BetaMessageStream<ParsedT> {
+    const runner = new BetaMessageStream<ParsedT>(params as MessageCreateParamsStreaming);
     for (const message of params.messages) {
       runner._addMessageParam(message);
     }
+    runner.#params = { ...params, stream: true };
     runner._run(() =>
       runner._createMessage(
         messages,
@@ -168,7 +174,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
     this.messages.push(message);
   }
 
-  protected _addMessage(message: BetaMessage, emit = true) {
+  protected _addMessage(message: ParsedBetaMessage<ParsedT>, emit = true) {
     this.receivedMessages.push(message);
     if (emit) {
       this._emit('message', message);
@@ -177,7 +183,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
 
   protected async _createMessage(
     messages: BetaMessages,
-    params: BetaMessageCreateParams,
+    params: MessageCreateParams,
     options?: RequestOptions,
   ): Promise<void> {
     const signal = options?.signal;
@@ -306,7 +312,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
     return this.#currentMessageSnapshot;
   }
 
-  #getFinalMessage(): BetaMessage {
+  #getFinalMessage(): ParsedBetaMessage<ParsedT> {
     if (this.receivedMessages.length === 0) {
       throw new AnthropicError('stream ended without producing a Message with role=assistant');
     }
@@ -316,8 +322,9 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
   /**
    * @returns a promise that resolves with the the final assistant Message response,
    * or rejects if an error occurred or the stream ended prematurely without producing a Message.
+   * If structured outputs were used, this will be a ParsedMessage with a `parsed` field.
    */
-  async finalMessage(): Promise<BetaMessage> {
+  async finalMessage(): Promise<ParsedBetaMessage<ParsedT>> {
     await this.done();
     return this.#getFinalMessage();
   }
@@ -472,7 +479,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
       }
       case 'message_stop': {
         this._addMessageParam(messageSnapshot);
-        this._addMessage(messageSnapshot, true);
+        this._addMessage(maybeParseBetaMessage(messageSnapshot, this.#params), true);
         break;
       }
       case 'content_block_stop': {
@@ -488,7 +495,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
         break;
     }
   }
-  #endRequest(): BetaMessage {
+  #endRequest(): ParsedBetaMessage<ParsedT> {
     if (this.ended) {
       throw new AnthropicError(`stream has ended, this shouldn't happen`);
     }
@@ -497,7 +504,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
       throw new AnthropicError(`request ended without sending any chunks`);
     }
     this.#currentMessageSnapshot = undefined;
-    return snapshot;
+    return maybeParseBetaMessage(snapshot, this.#params);
   }
 
   protected async _fromReadableStream(

package/src/lib/beta-parser.ts

@@ -0,0 +1,105 @@
+import { AnthropicError } from '../core/error';
+import {
+  BetaContentBlock,
+  BetaJSONOutputFormat,
+  BetaMessage,
+  BetaTextBlock,
+  MessageCreateParams,
+} from '../resources/beta/messages/messages';
+
+// vendored from typefest just to make things look a bit nicer on hover
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+
+export type BetaParseableMessageCreateParams = Simplify<
+  Omit<MessageCreateParams, 'output_format'> & {
+    output_format?: BetaJSONOutputFormat | AutoParseableBetaOutputFormat<any> | null;
+  }
+>;
+
+export type ExtractParsedContentFromBetaParams<Params extends BetaParseableMessageCreateParams> =
+  Params['output_format'] extends AutoParseableBetaOutputFormat<infer P> ? P : null;
+
+export type AutoParseableBetaOutputFormat<ParsedT> = BetaJSONOutputFormat & {
+  parse(content: string): ParsedT;
+};
+
+export type ParsedBetaMessage<ParsedT> = BetaMessage & {
+  content: Array<ParsedBetaContentBlock<ParsedT>>;
+  parsed_output: ParsedT | null;
+};
+
+export type ParsedBetaContentBlock<ParsedT> =
+  | (BetaTextBlock & { parsed: ParsedT | null })
+  | Exclude<BetaContentBlock, BetaTextBlock>;
+
+export function maybeParseBetaMessage<Params extends BetaParseableMessageCreateParams | null>(
+  message: BetaMessage,
+  params: Params,
+): ParsedBetaMessage<ExtractParsedContentFromBetaParams<NonNullable<Params>>> {
+  if (!params || !('parse' in (params.output_format ?? {}))) {
+    return {
+      ...message,
+      content: message.content.map((block) => {
+        if (block.type === 'text') {
+          return {
+            ...block,
+            parsed: null,
+          };
+        }
+        return block;
+      }),
+      parsed_output: null,
+    } as ParsedBetaMessage<ExtractParsedContentFromBetaParams<NonNullable<Params>>>;
+  }
+
+  return parseBetaMessage(message, params);
+}
+
+export function parseBetaMessage<Params extends BetaParseableMessageCreateParams>(
+  message: BetaMessage,
+  params: Params,
+): ParsedBetaMessage<ExtractParsedContentFromBetaParams<Params>> {
+  let firstParsed: ReturnType<typeof parseBetaOutputFormat<Params>> | null = null;
+
+  const content: Array<ParsedBetaContentBlock<ExtractParsedContentFromBetaParams<Params>>> =
+    message.content.map((block) => {
+      if (block.type === 'text') {
+        const parsed = parseBetaOutputFormat(params, block.text);
+
+        if (firstParsed === null) {
+          firstParsed = parsed;
+        }
+
+        return {
+          ...block,
+          parsed,
+        };
+      }
+      return block;
+    });
+
+  return {
+    ...message,
+    content,
+    parsed_output: firstParsed,
+  } as ParsedBetaMessage<ExtractParsedContentFromBetaParams<Params>>;
+}
+
+function parseBetaOutputFormat<Params extends BetaParseableMessageCreateParams>(
+  params: Params,
+  content: string,
+): ExtractParsedContentFromBetaParams<Params> | null {
+  if (params.output_format?.type !== 'json_schema') {
+    return null;
+  }
+
+  try {
+    if ('parse' in params.output_format) {
+      return params.output_format.parse(content);
+    }
+
+    return JSON.parse(content);
+  } catch (error) {
+    throw new AnthropicError(`Failed to parse structured output: ${error}`);
+  }
+}

package/src/lib/transform-json-schema.ts

@@ -0,0 +1,124 @@
+import { pop } from '../internal/utils';
+
+// Supported string formats
+const SUPPORTED_STRING_FORMATS = new Set([
+  'date-time',
+  'time',
+  'date',
+  'duration',
+  'email',
+  'hostname',
+  'uri',
+  'ipv4',
+  'ipv6',
+  'uuid',
+]);
+
+export type JSONSchema = Record<string, any>;
+
+function deepClone<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+export function transformJSONSchema(jsonSchema: JSONSchema): JSONSchema {
+  const workingCopy = deepClone(jsonSchema);
+  return _transformJSONSchema(workingCopy);
+}
+
+function _transformJSONSchema(jsonSchema: JSONSchema): JSONSchema {
+  const strictSchema: JSONSchema = {};
+
+  const ref = pop(jsonSchema, '$ref');
+  if (ref !== undefined) {
+    strictSchema['$ref'] = ref;
+    return strictSchema;
+  }
+
+  const defs = pop(jsonSchema, '$defs');
+  if (defs !== undefined) {
+    const strictDefs: Record<string, any> = {};
+    strictSchema['$defs'] = strictDefs;
+    for (const [name, defSchema] of Object.entries(defs)) {
+      strictDefs[name] = _transformJSONSchema(defSchema as JSONSchema);
+    }
+  }
+
+  const type = pop(jsonSchema, 'type');
+  const anyOf = pop(jsonSchema, 'anyOf');
+  const oneOf = pop(jsonSchema, 'oneOf');
+  const allOf = pop(jsonSchema, 'allOf');
+
+  if (Array.isArray(anyOf)) {
+    strictSchema['anyOf'] = anyOf.map((variant) => _transformJSONSchema(variant as JSONSchema));
+  } else if (Array.isArray(oneOf)) {
+    strictSchema['anyOf'] = oneOf.map((variant) => _transformJSONSchema(variant as JSONSchema));
+  } else if (Array.isArray(allOf)) {
+    strictSchema['allOf'] = allOf.map((entry) => _transformJSONSchema(entry as JSONSchema));
+  } else {
+    if (type === undefined) {
+      throw new Error('JSON schema must have a type defined if anyOf/oneOf/allOf are not used');
+    }
+    strictSchema['type'] = type;
+  }
+
+  const description = pop(jsonSchema, 'description');
+  if (description !== undefined) {
+    strictSchema['description'] = description;
+  }
+
+  const title = pop(jsonSchema, 'title');
+  if (title !== undefined) {
+    strictSchema['title'] = title;
+  }
+
+  if (type === 'object') {
+    const properties = pop(jsonSchema, 'properties') || {};
+
+    strictSchema['properties'] = Object.fromEntries(
+      Object.entries(properties).map(([key, propSchema]) => [
+        key,
+        _transformJSONSchema(propSchema as JSONSchema),
+      ]),
+    );
+
+    pop(jsonSchema, 'additionalProperties');
+    strictSchema['additionalProperties'] = false;
+
+    const required = pop(jsonSchema, 'required');
+    if (required !== undefined) {
+      strictSchema['required'] = required;
+    }
+  } else if (type === 'string') {
+    const format = pop(jsonSchema, 'format');
+    if (format !== undefined && SUPPORTED_STRING_FORMATS.has(format)) {
+      strictSchema['format'] = format;
+    } else if (format !== undefined) {
+      jsonSchema['format'] = format;
+    }
+  } else if (type === 'array') {
+    const items = pop(jsonSchema, 'items');
+    if (items !== undefined) {
+      strictSchema['items'] = _transformJSONSchema(items as JSONSchema);
+    }
+
+    const minItems = pop(jsonSchema, 'minItems');
+    if (minItems !== undefined && (minItems === 0 || minItems === 1)) {
+      strictSchema['minItems'] = minItems;
+    } else if (minItems !== undefined) {
+      jsonSchema['minItems'] = minItems;
+    }
+  }
+
+  if (Object.keys(jsonSchema).length > 0) {
+    const existingDescription = strictSchema['description'];
+    strictSchema['description'] =
+      (existingDescription ? existingDescription + '\n\n' : '') +
+      '{' +
+      Object.entries(jsonSchema)
+        .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
+        .join(', ') +
+      '}';
+  }
+
+  return strictSchema;
+}

package/src/resources/beta/beta.ts

@@ -77,6 +77,7 @@ import {
   BetaFileImageSource,
   BetaImageBlockParam,
   BetaInputJSONDelta,
+  BetaJSONOutputFormat,
   BetaInputTokensClearAtLeast,
   BetaInputTokensTrigger,
   BetaMCPToolResultBlock,
@@ -393,6 +394,7 @@ export declare namespace Beta {
     type BetaFileImageSource as BetaFileImageSource,
     type BetaImageBlockParam as BetaImageBlockParam,
     type BetaInputJSONDelta as BetaInputJSONDelta,
+    type BetaJSONOutputFormat as BetaJSONOutputFormat,
     type BetaInputTokensClearAtLeast as BetaInputTokensClearAtLeast,
     type BetaInputTokensTrigger as BetaInputTokensTrigger,
     type BetaMCPToolResultBlock as BetaMCPToolResultBlock,

package/src/resources/beta/index.ts

@@ -87,6 +87,7 @@ export {
   type BetaFileImageSource,
   type BetaImageBlockParam,
   type BetaInputJSONDelta,
+  type BetaJSONOutputFormat,
   type BetaInputTokensClearAtLeast,
   type BetaInputTokensTrigger,
   type BetaMCPToolResultBlock,

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

@@ -20,7 +20,7 @@ export class Batches extends APIResource {
    * can take up to 24 hours to complete.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -59,7 +59,7 @@ export class Batches extends APIResource {
    * `results_url` field in the response.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -89,7 +89,7 @@ export class Batches extends APIResource {
    * returned first.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -121,7 +121,7 @@ export class Batches extends APIResource {
    * like to delete an in-progress batch, you must first cancel it.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -158,7 +158,7 @@ export class Batches extends APIResource {
    * non-interruptible.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -191,7 +191,7 @@ export class Batches extends APIResource {
    * requests. Use the `custom_id` field to match results to requests.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
    *
    * @example
    * ```ts

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

@@ -80,6 +80,7 @@ export {
   type BetaFileImageSource,
   type BetaImageBlockParam,
   type BetaInputJSONDelta,
+  type BetaJSONOutputFormat,
   type BetaInputTokensClearAtLeast,
   type BetaInputTokensTrigger,
   type BetaMCPToolResultBlock,