@tetral-ai/sdk 0.110.0-alpha.1

package/src/core/README.md

@@ -0,0 +1,3 @@
+# `core`
+
+This directory holds public modules implementing non-resource-specific SDK functionality.

package/src/core/api-promise.ts

@@ -0,0 +1,101 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { type BaseAnthropic } from '../client';
+
+import { type PromiseOrValue } from '../internal/types';
+import {
+  type APIResponseProps,
+  type WithRequestID,
+  defaultParseResponse,
+  addRequestID,
+} from '../internal/parse';
+
+/**
+ * A subclass of `Promise` providing additional helper methods
+ * for interacting with the SDK.
+ */
+export class APIPromise<T> extends Promise<WithRequestID<T>> {
+  private parsedPromise: Promise<WithRequestID<T>> | undefined;
+  #client: BaseAnthropic;
+
+  constructor(
+    client: BaseAnthropic,
+    private responsePromise: Promise<APIResponseProps>,
+    private parseResponse: (
+      client: BaseAnthropic,
+      props: APIResponseProps,
+    ) => PromiseOrValue<WithRequestID<T>> = defaultParseResponse,
+  ) {
+    super((resolve) => {
+      // this is maybe a bit weird but this has to be a no-op to not implicitly
+      // parse the response body; instead .then, .catch, .finally are overridden
+      // to parse the response
+      resolve(null as any);
+    });
+    this.#client = client;
+  }
+
+  _thenUnwrap<U>(transform: (data: T, props: APIResponseProps) => U): APIPromise<U> {
+    return new APIPromise(this.#client, this.responsePromise, async (client, props) =>
+      addRequestID(transform(await this.parseResponse(client, props), props), props.response),
+    );
+  }
+
+  /**
+   * Gets the raw `Response` instance instead of parsing the response
+   * data.
+   *
+   * If you want to parse the response body but still get the `Response`
+   * instance, you can use {@link withResponse()}.
+   *
+   * 👋 Getting the wrong TypeScript type for `Response`?
+   * Try setting `"moduleResolution": "NodeNext"` or add `"lib": ["DOM"]`
+   * to your `tsconfig.json`.
+   */
+  asResponse(): Promise<Response> {
+    return this.responsePromise.then((p) => p.response);
+  }
+
+  /**
+   * Gets the parsed response data, the raw `Response` instance and the ID of the request,
+   * returned via the `request-id` header which is useful for debugging requests and resporting
+   * issues to Anthropic.
+   *
+   * If you just want to get the raw `Response` instance without parsing it,
+   * you can use {@link asResponse()}.
+   *
+   * 👋 Getting the wrong TypeScript type for `Response`?
+   * Try setting `"moduleResolution": "NodeNext"` or add `"lib": ["DOM"]`
+   * to your `tsconfig.json`.
+   */
+  async withResponse(): Promise<{ data: T; response: Response; request_id: string | null | undefined }> {
+    const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
+    return { data, response, request_id: response.headers.get('request-id') };
+  }
+
+  private parse(): Promise<WithRequestID<T>> {
+    if (!this.parsedPromise) {
+      this.parsedPromise = this.responsePromise.then(
+        (data) => this.parseResponse(this.#client, data) as any as Promise<WithRequestID<T>>,
+      );
+    }
+    return this.parsedPromise;
+  }
+
+  override then<TResult1 = WithRequestID<T>, TResult2 = never>(
+    onfulfilled?: ((value: WithRequestID<T>) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+  ): Promise<TResult1 | TResult2> {
+    return this.parse().then(onfulfilled, onrejected);
+  }
+
+  override catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
+  ): Promise<WithRequestID<T> | TResult> {
+    return this.parse().catch(onrejected);
+  }
+
+  override finally(onfinally?: (() => void) | undefined | null): Promise<WithRequestID<T>> {
+    return this.parse().finally(onfinally);
+  }
+}

package/src/core/api.ts

@@ -0,0 +1,11 @@
+import type { FinalizedRequestInit } from '../internal/types';
+
+/**
+ * An HTTP request as it will be passed to `fetch`, the `RequestInit` plus the request `url`.
+ *
+ * `headers` is always a `Headers` instance and may be mutated in place.
+ */
+export type APIRequest = FinalizedRequestInit & {
+  /** The fully-built request URL, including query parameters. */
+  url: string;
+};

package/src/core/credentials.ts

@@ -0,0 +1,379 @@
+import { getPlatformHeaders } from '../internal/detect-platform';
+import { readEnv } from '../internal/utils';
+
+/** Current schema version written to `configs/<profile>.json`. Absent on read ⇒ "1.0". */
+export const CONFIG_FILE_VERSION = '1.0';
+/** Current schema version written to `credentials/<profile>.json`. Absent on read ⇒ "1.0". */
+export const CREDENTIALS_FILE_VERSION = '1.0';
+
+/**
+ * Authentication-mode-specific configuration. On the wire (configs/<profile>.json)
+ * this is a flat JSON object under the top-level `authentication` key — `type`,
+ * `credentials_path`, and the variant-specific fields all sit at the same level.
+ *
+ * Unknown fields are silently ignored for forward compatibility. Unknown
+ * authentication types are rejected because the SDK has no way to resolve
+ * credentials for them.
+ */
+export type AuthenticationInfo = {
+  /**
+   * Filesystem path to the credentials JSON that stores access/refresh tokens.
+   * Defaults to `<config_dir>/credentials/<profile>.json` when omitted.
+   */
+  credentials_path?: string | undefined;
+} & (
+  | {
+      type: 'oidc_federation';
+      /** Tagged ID (`fdrl_...`) of the federation rule. Required. */
+      federation_rule_id: string;
+      /** Optional `svac_...` expected-target check. */
+      service_account_id?: string | undefined;
+      identity_token?:
+        | {
+            source: 'file';
+            path: string;
+          }
+        | undefined;
+      /** Display-only; the SDK does not send this on the jwt-bearer exchange. */
+      scope?: string | undefined;
+    }
+  | {
+      type: 'user_oauth';
+      /** OAuth client ID for refresh. Empty → access token is treated as static. */
+      client_id?: string | undefined;
+      /** Display-only; the SDK does not send this on refresh. */
+      scope?: string | undefined;
+      /** Console URL the profile was created against. Display-only. */
+      console_url?: string | undefined;
+    }
+);
+
+export type AnthropicConfig = {
+  version?: string;
+  authentication: AuthenticationInfo;
+  base_url?: string | undefined;
+  organization_id?: string | undefined;
+  workspace_id?: string | undefined;
+};
+
+export type AnthropicCredentials = {
+  version?: string;
+  type: 'oauth_token';
+  access_token: string;
+  expires_at?: number;
+  refresh_token?: string;
+  scope?: string;
+  organization_uuid?: string;
+  organization_name?: string;
+  account_email?: string;
+};
+
+const PROFILE_NAME_PATTERN = /^[A-Za-z0-9_.-]+$/;
+
+function validateProfileName(name: string): void {
+  if (!name) {
+    throw new Error('profile name is empty');
+  }
+  if (name === '.' || name === '..') {
+    throw new Error(`profile name "${name}" is not allowed`);
+  }
+  if (name.includes('/') || name.includes('\\')) {
+    throw new Error(`profile name "${name}" must not contain path separators`);
+  }
+  if (!PROFILE_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `profile name "${name}" contains disallowed characters (allowed: letters, digits, '_', '.', '-')`,
+    );
+  }
+}
+
+/**
+ * Loads the Anthropic configuration for the given (or active) profile.
+ *
+ * Returns `null` when running in a browser or no configuration can be resolved.
+ * Otherwise, returns the configuration based on the config file and environment variables.
+ *
+ * **Profile resolution** (first match wins):
+ *   1. Explicit `profile` argument
+ *   2. `ANTHROPIC_PROFILE` environment variable
+ *   3. Contents of `<config_dir>/active_config` file
+ *   4. `"default"`
+ *
+ * **Config resolution:**
+ *   - If `<config_dir>/configs/<profile>.json` exists, it is loaded and
+ *     missing fields are filled from environment variables. Values present
+ *     in the file take precedence — env vars only fill gaps:
+ *       - `TETRAL_BASE_URL` → `base_url`
+ *       - `ANTHROPIC_ORGANIZATION_ID` → `organization_id`
+ *       - `ANTHROPIC_WORKSPACE_ID` → `workspace_id`
+ *       - `ANTHROPIC_SCOPE` → `authentication.scope`
+ *       - `ANTHROPIC_FEDERATION_RULE_ID` → `authentication.federation_rule_id` (oidc_federation)
+ *       - `ANTHROPIC_IDENTITY_TOKEN_FILE` → `authentication.identity_token` (oidc_federation)
+ *       - `ANTHROPIC_SERVICE_ACCOUNT_ID` → `authentication.service_account_id` (oidc_federation)
+ *   - If no config file exists, an `oidc_federation` config is synthesized
+ *     entirely from environment variables when both `ANTHROPIC_FEDERATION_RULE_ID`
+ *     and `ANTHROPIC_ORGANIZATION_ID` are set.
+ */
+export const loadConfig = async (profile?: string): Promise<AnthropicConfig | null> => {
+  return (await loadConfigWithSource(profile))?.config ?? null;
+};
+
+/**
+ * Source-tagged result of {@link loadConfigWithSource}. `fromFile` is `true`
+ * when `<config_dir>/configs/<profile>.json` exists on disk; `false` when the
+ * config was synthesized purely from environment variables.
+ *
+ * The credential chain uses this distinction to decide whether to back the
+ * federation exchange with a disk cache: file-backed profiles get a cache at
+ * `<config_dir>/credentials/<profile>.json`, env-only configs do not.
+ */
+export type LoadedConfig = { config: AnthropicConfig; fromFile: boolean };
+
+/**
+ * Same as {@link loadConfig}, but also reports whether the config was loaded
+ * from a profile file on disk (`fromFile: true`) or synthesized entirely from
+ * environment variables (`fromFile: false`).
+ */
+export const loadConfigWithSource = async (profile?: string): Promise<LoadedConfig | null> => {
+  const rootConfigPath = await getRootConfigPath();
+  if (rootConfigPath === null) {
+    return null;
+  }
+
+  const profileName = profile ?? (await getActiveProfileName());
+  if (profileName === null) {
+    return null;
+  }
+  validateProfileName(profileName);
+
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const configPath = path.join(rootConfigPath, 'configs', `${profileName}.json`);
+  let configRaw: string | null;
+  try {
+    configRaw = await fs.promises.readFile(configPath, 'utf-8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+      throw new Error(`failed to read config file ${configPath}: ${err}`);
+    }
+    configRaw = null;
+  }
+  if (configRaw === null) {
+    const organizationId = readEnv('ANTHROPIC_ORGANIZATION_ID');
+    const identityTokenFile = readEnv('ANTHROPIC_IDENTITY_TOKEN_FILE');
+    const federationRuleId = readEnv('ANTHROPIC_FEDERATION_RULE_ID');
+    if (federationRuleId && organizationId) {
+      return {
+        fromFile: false,
+        config: {
+          organization_id: organizationId,
+          // A defaulted-but-empty CI variable (`ANTHROPIC_WORKSPACE_ID=""`) is
+          // treated as unset — readEnv coerces empty to undefined, and the body
+          // builder's truthy check skips it — so `"workspace_id": ""` never goes
+          // on the wire.
+          workspace_id: readEnv('ANTHROPIC_WORKSPACE_ID'),
+          base_url: readEnv('TETRAL_BASE_URL'),
+          authentication: {
+            type: 'oidc_federation',
+            federation_rule_id: federationRuleId,
+            service_account_id: readEnv('ANTHROPIC_SERVICE_ACCOUNT_ID'),
+            identity_token: identityTokenFile ? { source: 'file', path: identityTokenFile } : undefined,
+            scope: readEnv('ANTHROPIC_SCOPE'),
+          },
+        },
+      };
+    }
+    return null;
+  }
+
+  let config: AnthropicConfig;
+  try {
+    config = JSON.parse(configRaw);
+  } catch (err) {
+    throw new Error(`failed to parse config file ${configPath}: ${err}`);
+  }
+  if (!config.authentication) {
+    throw new Error(`config file ${configPath} is missing "authentication"`);
+  }
+  const authType = config.authentication.type;
+  if (authType !== 'oidc_federation' && authType !== 'user_oauth') {
+    throw new Error(`authentication.type "${authType}" is not a known authentication type`);
+  }
+
+  // File values are authoritative; env vars only fill fields the file left unset.
+  config.organization_id ??= readEnv('ANTHROPIC_ORGANIZATION_ID');
+  config.workspace_id ??= readEnv('ANTHROPIC_WORKSPACE_ID');
+  config.base_url ??= readEnv('TETRAL_BASE_URL');
+  config.authentication.scope ??= readEnv('ANTHROPIC_SCOPE');
+
+  if (config.authentication.type === 'oidc_federation') {
+    if (!config.authentication.identity_token) {
+      const identityTokenFile = readEnv('ANTHROPIC_IDENTITY_TOKEN_FILE');
+      if (identityTokenFile) {
+        config.authentication.identity_token = {
+          source: 'file',
+          path: identityTokenFile,
+        };
+      }
+    }
+
+    // Unlike siblings using `??= readEnv()` (which leaves `undefined`), coerce
+    // to '' so the type stays `string` (always set). The downstream required
+    // check in credential-chain rejects empty, so semantics match but types are
+    // cleaner.
+    if (!config.authentication.federation_rule_id) {
+      config.authentication.federation_rule_id = readEnv('ANTHROPIC_FEDERATION_RULE_ID') ?? '';
+    }
+    config.authentication.service_account_id ??= readEnv('ANTHROPIC_SERVICE_ACCOUNT_ID');
+  }
+
+  return { config, fromFile: true };
+};
+
+/**
+ * Loads the credential material for the active profile.
+ *
+ * Returns the parsed credentials or `null` when running in a browser or
+ * no credentials file can be found.
+ *
+ * **Profile resolution** (first match wins):
+ *   1. `ANTHROPIC_PROFILE` environment variable
+ *   2. Contents of `<config_dir>/active_config` file
+ *   3. `"default"`
+ *
+ * **Credentials path resolution** (first match wins):
+ *   1. `authentication.credentials_path` from the active profile's config (via {@link loadConfig})
+ *   2. `<config_dir>/credentials/<profile>.json`
+ */
+export const loadCredentials = async (): Promise<AnthropicCredentials | null> => {
+  const config = await loadConfig();
+  const credentialsPath = await getCredentialsPath(config);
+  if (!credentialsPath) {
+    return null;
+  }
+
+  const fs = await import('node:fs');
+  let raw: string;
+  try {
+    raw = await fs.promises.readFile(credentialsPath, 'utf-8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+      throw new Error(`failed to read credentials file ${credentialsPath}: ${err}`);
+    }
+    return null;
+  }
+
+  let creds: AnthropicCredentials;
+  try {
+    creds = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`failed to parse credentials file ${credentialsPath}: ${err}`);
+  }
+  if (creds.type && creds.type !== 'oauth_token') {
+    throw new Error(
+      `credentials file ${credentialsPath} has unsupported type "${creds.type}" (want "oauth_token")`,
+    );
+  }
+  return creds;
+};
+
+/**
+ * Resolves the credentials file path for the given config.
+ *
+ * Uses `authentication.credentials_path` from the config if set, otherwise
+ * falls back to `<config_dir>/credentials/<profile>.json`.
+ *
+ * Returns `null` when running in a browser or the path cannot be resolved.
+ */
+export const getCredentialsPath = async (
+  config: AnthropicConfig | null,
+  profile?: string,
+): Promise<string | null> => {
+  if (config?.authentication.credentials_path) {
+    return config.authentication.credentials_path;
+  }
+
+  const rootConfigPath = await getRootConfigPath();
+  if (!rootConfigPath) {
+    return null;
+  }
+
+  const profileName = profile ?? (await getActiveProfileName());
+  if (!profileName) {
+    return null;
+  }
+  validateProfileName(profileName);
+
+  const path = await import('node:path');
+  return path.join(rootConfigPath, 'credentials', `${profileName}.json`);
+};
+
+const getRootConfigPath = async (): Promise<string | null> => {
+  if (!supportsLocalConfigFiles()) {
+    return null;
+  }
+
+  const path = await import('node:path');
+
+  // ANTHROPIC_CONFIG_DIR is treated as a trusted path: it is set by the
+  // process operator, not by remote input, so it is not validated.
+  const configDir = readEnv('ANTHROPIC_CONFIG_DIR');
+  if (configDir) {
+    return configDir;
+  }
+
+  const os = getPlatformHeaders()['X-Stainless-OS'];
+  if (os === 'Windows') {
+    const appData = readEnv('APPDATA');
+    if (appData) {
+      return path.join(appData, 'Anthropic');
+    }
+    const userProfile = readEnv('USERPROFILE');
+    if (userProfile) {
+      return path.join(userProfile, 'AppData', 'Roaming', 'Anthropic');
+    }
+    // No usable Windows config root — return null so callers fall through to
+    // "no config available" rather than silently writing under C:\.
+    return null;
+  }
+
+  const xdgConfigHome = readEnv('XDG_CONFIG_HOME');
+  if (xdgConfigHome) {
+    return path.join(xdgConfigHome, 'anthropic');
+  }
+
+  const home = readEnv('HOME');
+  if (home) {
+    return path.join(home, '.config', 'anthropic');
+  }
+  return null;
+};
+
+const supportsLocalConfigFiles = (): boolean => {
+  const runtime = getPlatformHeaders()['X-Stainless-Runtime'];
+  return runtime === 'node' || runtime === 'deno';
+};
+
+const getActiveProfileName = async (): Promise<string | null> => {
+  const rootConfigPath = await getRootConfigPath();
+  if (!rootConfigPath) {
+    return null;
+  }
+
+  const profileName = readEnv('ANTHROPIC_PROFILE');
+  if (profileName) {
+    return profileName;
+  }
+
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const filePath = path.join(rootConfigPath, 'active_config');
+  try {
+    return (await fs.promises.readFile(filePath, 'utf-8')).trim() || 'default';
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+      throw new Error(`failed to read ${filePath}: ${err}`);
+    }
+    return 'default';
+  }
+};

package/src/core/error.ts

@@ -0,0 +1,160 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { castToError } from '../internal/errors';
+import type { ErrorType } from '../resources/shared';
+
+export class AnthropicError extends Error {}
+
+export class APIError<
+  TStatus extends number | undefined = number | undefined,
+  THeaders extends Headers | undefined = Headers | undefined,
+  TError extends Object | undefined = Object | undefined,
+> extends AnthropicError {
+  /** HTTP status for the response that caused the error */
+  readonly status: TStatus;
+  /** HTTP headers for the response that caused the error */
+  readonly headers: THeaders;
+  /** JSON body of the response that caused the error */
+  readonly error: TError;
+
+  readonly requestID: string | null | undefined;
+
+  /** The `error.type` from the API response body, e.g. `"rate_limit_error"` */
+  readonly type: ErrorType | null;
+
+  constructor(
+    status: TStatus,
+    error: TError,
+    message: string | undefined,
+    headers: THeaders,
+    type?: ErrorType | null,
+  ) {
+    super(`${APIError.makeMessage(status, error, message)}`);
+    this.status = status;
+    this.headers = headers;
+    this.requestID = headers?.get('request-id');
+    this.error = error;
+    this.type = type ?? null;
+  }
+
+  private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
+    const msg =
+      error?.message ?
+        typeof error.message === 'string' ?
+          error.message
+        : JSON.stringify(error.message)
+      : error ? JSON.stringify(error)
+      : message;
+
+    if (status && msg) {
+      return `${status} ${msg}`;
+    }
+    if (status) {
+      return `${status} status code (no body)`;
+    }
+    if (msg) {
+      return msg;
+    }
+    return '(no status code or body)';
+  }
+
+  static generate(
+    status: number | undefined,
+    errorResponse: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ): APIError {
+    if (!status || !headers) {
+      return new APIConnectionError({ message, cause: castToError(errorResponse) });
+    }
+
+    const error = errorResponse as Record<string, any>;
+    const type = error?.['error']?.['type'] as ErrorType | undefined;
+
+    if (status === 400) {
+      return new BadRequestError(status, error, message, headers, type);
+    }
+
+    if (status === 401) {
+      return new AuthenticationError(status, error, message, headers, type);
+    }
+
+    if (status === 403) {
+      return new PermissionDeniedError(status, error, message, headers, type);
+    }
+
+    if (status === 404) {
+      return new NotFoundError(status, error, message, headers, type);
+    }
+
+    if (status === 409) {
+      return new ConflictError(status, error, message, headers, type);
+    }
+
+    if (status === 422) {
+      return new UnprocessableEntityError(status, error, message, headers, type);
+    }
+
+    if (status === 429) {
+      return new RateLimitError(status, error, message, headers, type);
+    }
+
+    if (status >= 500) {
+      return new InternalServerError(status, error, message, headers, type);
+    }
+
+    return new APIError(status, error, message, headers, type);
+  }
+}
+
+export class APIUserAbortError extends APIError<undefined, undefined, undefined> {
+  constructor({ message }: { message?: string } = {}) {
+    super(undefined, undefined, message || 'Request was aborted.', undefined);
+  }
+}
+
+export class APIConnectionError extends APIError<undefined, undefined, undefined> {
+  constructor({ message, cause }: { message?: string | undefined; cause?: Error | undefined }) {
+    super(undefined, undefined, message || 'Connection error.', undefined);
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause) this.cause = cause;
+  }
+}
+
+export class APIConnectionTimeoutError extends APIConnectionError {
+  constructor({ message }: { message?: string } = {}) {
+    super({ message: message ?? 'Request timed out.' });
+  }
+}
+
+/**
+ * An error that opts into the SDK's retry policy: throw it (e.g. from
+ * middleware) to have the attempt retried.
+ *
+ * Note that the request will only be retried when `maxRetries` has not been exhausted.
+ */
+export class RetryableError extends AnthropicError {
+  constructor(message?: string, { cause }: { cause?: unknown } = {}) {
+    super(message ?? 'Retryable error.');
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+export class BadRequestError extends APIError<400, Headers> {}
+
+export class AuthenticationError extends APIError<401, Headers> {}
+
+export class PermissionDeniedError extends APIError<403, Headers> {}
+
+export class NotFoundError extends APIError<404, Headers> {}
+
+export class ConflictError extends APIError<409, Headers> {}
+
+export class UnprocessableEntityError extends APIError<422, Headers> {}
+
+export class RateLimitError extends APIError<429, Headers> {}
+
+export class InternalServerError extends APIError<number, Headers> {}