@anthropic-ai/sdk
Version:
The official TypeScript library for the Anthropic API
210 lines (175 loc) • 8.23 kB
text/typescript
import { AnthropicError } from '../core/error';
// Standard Schema spec types, copied from `@standard-schema/spec@1.1.0` (MIT) as the spec
// recommends. See https://standardschema.dev
/** The Standard Typed interface. This is a base type extended by other specs. */
export interface StandardTypedV1<Input = unknown, Output = Input> {
/** The Standard properties. */
readonly '~standard': StandardTypedV1.Props<Input, Output>;
}
export declare namespace StandardTypedV1 {
/** The Standard Typed properties interface. */
interface Props<Input = unknown, Output = Input> {
/** The version number of the standard. */
readonly version: 1;
/** The vendor name of the schema library. */
readonly vendor: string;
/** Inferred types associated with the schema. */
readonly types?: Types<Input, Output> | undefined;
}
/** The Standard Typed types interface. */
interface Types<Input = unknown, Output = Input> {
/** The input type of the schema. */
readonly input: Input;
/** The output type of the schema. */
readonly output: Output;
}
/** Infers the input type of a Standard Typed. */
type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema['~standard']['types']>['input'];
/** Infers the output type of a Standard Typed. */
type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema['~standard']['types']>['output'];
}
/** The Standard Schema interface. */
export interface StandardSchemaV1<Input = unknown, Output = Input> {
/** The Standard Schema properties. */
readonly '~standard': StandardSchemaV1.Props<Input, Output>;
}
export declare namespace StandardSchemaV1 {
/** The Standard Schema properties interface. */
interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
/** Validates unknown input values. */
readonly validate: (
value: unknown,
options?: StandardSchemaV1.Options | undefined,
) => Result<Output> | Promise<Result<Output>>;
}
/** The result interface of the validate function. */
type Result<Output> = SuccessResult<Output> | FailureResult;
/** The result interface if validation succeeds. */
interface SuccessResult<Output> {
/** The typed output value. */
readonly value: Output;
/** A falsy value for `issues` indicates success. */
readonly issues?: undefined;
}
interface Options {
/** Explicit support for additional vendor-specific parameters, if needed. */
readonly libraryOptions?: Record<string, unknown> | undefined;
}
/** The result interface if validation fails. */
interface FailureResult {
/** The issues of failed validation. */
readonly issues: ReadonlyArray<Issue>;
}
/** The issue interface of the failure output. */
interface Issue {
/** The error message of the issue. */
readonly message: string;
/** The path of the issue, if any. */
readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
}
/** The path segment interface of the issue. */
interface PathSegment {
/** The key representing a path segment. */
readonly key: PropertyKey;
}
/** The Standard types interface. */
interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
/** Infers the input type of a Standard. */
type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
/** Infers the output type of a Standard. */
type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
}
/** The Standard JSON Schema interface. */
export interface StandardJSONSchemaV1<Input = unknown, Output = Input> {
/** The Standard JSON Schema properties. */
readonly '~standard': StandardJSONSchemaV1.Props<Input, Output>;
}
export declare namespace StandardJSONSchemaV1 {
/** The Standard JSON Schema properties interface. */
interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
/** Methods for generating the input/output JSON Schema. */
readonly jsonSchema: StandardJSONSchemaV1.Converter;
}
/** The Standard JSON Schema converter interface. */
interface Converter {
/** Converts the input type to JSON Schema. May throw if conversion is not supported. */
readonly input: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
/** Converts the output type to JSON Schema. May throw if conversion is not supported. */
readonly output: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
}
/**
* The target version of the generated JSON Schema.
*
* It is *strongly recommended* that implementers support `"draft-2020-12"` and `"draft-07"`, as they
* are both in wide use. All other targets can be implemented on a best-effort basis. Libraries should
* throw if they don't support a specified target.
*
* The `"openapi-3.0"` target is intended as a standardized specifier for OpenAPI 3.0 which is a
* superset of JSON Schema `"draft-04"`.
*/
type Target = 'draft-2020-12' | 'draft-07' | 'openapi-3.0' | ({} & string);
/** The options for the input/output methods. */
interface Options {
/** Specifies the target version of the generated JSON Schema. Support for all versions is on a best-effort basis. If a given version is not supported, the library should throw. */
readonly target: Target;
/** Explicit support for additional vendor-specific parameters, if needed. */
readonly libraryOptions?: Record<string, unknown> | undefined;
}
/** The Standard types interface. */
interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
/** Infers the input type of a Standard. */
type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
/** Infers the output type of a Standard. */
type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
}
/**
* Returns `jsonSchema` if given, otherwise the schema's Standard JSON Schema `input`
* representation (the model produces the value that the validator consumes).
*/
export function standardSchemaToJSONSchema(
schema: StandardSchemaV1,
jsonSchema?: Record<string, unknown> | undefined,
): Record<string, unknown> {
if (jsonSchema) {
return jsonSchema;
}
const std: StandardSchemaV1.Props & Partial<StandardJSONSchemaV1.Props> = schema['~standard'];
if (std.jsonSchema) {
return std.jsonSchema.input({ target: 'draft-2020-12' });
}
throw new AnthropicError(
`Could not derive a JSON Schema from this ${std.vendor} schema as it does not implement Standard JSON Schema (\`~standard.jsonSchema\`). Pass the \`jsonSchema\` option, or use a library version that implements it (e.g. zod >= 4.2, or valibot via \`toStandardJsonSchema()\`).`,
);
}
/**
* Validates `value` with `~standard.validate` and returns the typed output, throwing an
* `AnthropicError` on issues. Validation must be synchronous because `parse` hooks are.
*/
export function parseWithStandardSchema<Schema extends StandardSchemaV1>(
schema: Schema,
value: unknown,
): StandardSchemaV1.InferOutput<Schema> {
const result = schema['~standard'].validate(value);
if (result instanceof Promise) {
// avoid an unhandled rejection from the discarded result
result.catch(() => {});
throw new AnthropicError(
`Async validation is not supported: the ${schema['~standard'].vendor} schema's \`~standard.validate()\` returned a Promise.`,
);
}
if (result.issues) {
const formattedIssues = result.issues.slice(0, 5).map(formatIssue).join('\n');
const issueCount = result.issues.length;
const suffix = issueCount > 5 ? `\n ... and ${issueCount - 5} more issue(s)` : '';
throw new AnthropicError(
`Schema validation failed with ${issueCount} issue(s):\n${formattedIssues}${suffix}`,
);
}
return result.value;
}
function formatIssue(issue: StandardSchemaV1.Issue): string {
const path = (issue.path ?? [])
.map((segment) => String(typeof segment === 'object' ? segment.key : segment))
.join('.');
return path ? ` - ${path}: ${issue.message}` : ` - ${issue.message}`;
}