@databricks/sdk-core 0.0.0-dev → 0.1.0-dev.2

package/src/apierror/details.ts

@@ -0,0 +1,459 @@
+/**
+ * Defines structured error detail types for API errors.
+ *
+ * @packageDocumentation
+ */
+
+import {z} from 'zod';
+
+/**
+ * ErrorDetails contains the error details of an API error. It is the union of
+ * known error details types and unknown details.
+ */
+export interface ErrorDetails {
+  errorInfo?: ErrorInfo;
+  requestInfo?: RequestInfo;
+  retryInfo?: RetryInfo;
+  debugInfo?: DebugInfo;
+  quotaFailure?: QuotaFailure;
+  preconditionFailure?: PreconditionFailure;
+  badRequest?: BadRequest;
+  resourceInfo?: ResourceInfo;
+  help?: Help;
+
+  /**
+   * UnknownDetails contains error details that cannot be parsed into one of
+   * the known types above.
+   */
+  unknownDetails: unknown[];
+}
+
+/** ErrorInfo describes the cause of the error with structured details. */
+export interface ErrorInfo {
+  /**
+   * The reason of the error. This is a constant value that identifies the
+   * proximate cause of the error.
+   */
+  reason: string;
+
+  /** The logical grouping to which the "reason" belongs. */
+  domain: string;
+
+  /** Additional structured details about this error. */
+  metadata: Record<string, string>;
+}
+
+/**
+ * RequestInfo contains metadata about the request that clients can attach when
+ * filing a bug or providing other forms of feedback.
+ */
+export interface RequestInfo {
+  /**
+   * An opaque string that should only be interpreted by the service that
+   * generated it. For example, it can be used to identify requests in the
+   * service's logs.
+   */
+  requestId: string;
+
+  /**
+   * Any data that was used to serve this request. For example, an encrypted
+   * stack trace that can be sent back to the service provider for debugging.
+   */
+  servingData: string;
+}
+
+/**
+ * RetryInfo describes when the clients can retry a failed request. Clients
+ * could ignore the recommendation here or retry when this information is
+ * missing from error responses.
+ *
+ * It's always recommended that clients should use exponential backoff when
+ * retrying.
+ *
+ * Clients should wait until `retryDelayMs` amount of time has passed since
+ * receiving the error response before retrying. If retrying requests also
+ * fail, clients should use an exponential backoff scheme to gradually increase
+ * the delay between retries based on `retryDelayMs`, until either a maximum
+ * number of retries have been reached or a maximum retry delay cap has been
+ * reached.
+ */
+export interface RetryInfo {
+  /** Clients should wait at least this long between retrying the same request, in milliseconds. */
+  retryDelayMs: number;
+}
+
+/** Describes additional debugging info. */
+export interface DebugInfo {
+  /** The stack trace entries indicating where the error occurred. */
+  stackEntries: string[];
+
+  /** Additional debugging information provided by the server. */
+  detail: string;
+}
+
+/**
+ * Describes how a quota check failed.
+ *
+ * For example if a daily limit was exceeded for the calling project,
+ * a service could respond with a QuotaFailure detail containing the project
+ * id and the description of the quota limit that was exceeded. If the
+ * calling project hasn't enabled the service in the developer console, then
+ * a service could respond with the project id and set `service_disabled`
+ * to true.
+ *
+ * Also see RetryInfo and Help types for other details about handling a
+ * quota failure.
+ */
+export interface QuotaFailure {
+  /** Describes all quota violations. */
+  violations: QuotaFailureViolation[];
+}
+
+export interface QuotaFailureViolation {
+  /** The subject on which the quota check failed. */
+  subject: string;
+
+  /**
+   * A description of how the quota check failed. Clients can use this
+   * description to find more about the quota configuration in the service's
+   * public documentation, or find the relevant quota limit to adjust through
+   * developer console.
+   *
+   * For example: "Service disabled" or "Daily Limit for read operations
+   * exceeded".
+   */
+  description: string;
+}
+
+/** Describes what preconditions have failed. */
+export interface PreconditionFailure {
+  /** Describes all precondition violations. */
+  violations: PreconditionFailureViolation[];
+}
+
+export interface PreconditionFailureViolation {
+  /** The type of PreconditionFailure. */
+  type: string;
+
+  /** The subject, relative to the type, that failed. */
+  subject: string;
+
+  /**
+   * A description of how the precondition failed. Developers can use this
+   * description to understand how to fix the failure.
+   *
+   * For example: "Terms of service not accepted".
+   */
+  description: string;
+}
+
+/**
+ * Describes violations in a client request. This error type focuses on the
+ * syntactic aspects of the request.
+ */
+export interface BadRequest {
+  fieldViolations: BadRequestFieldViolation[];
+}
+
+export interface BadRequestFieldViolation {
+  /** A path leading to a field in the request body. */
+  field: string;
+
+  /** A description of why the request element is bad. */
+  description: string;
+}
+
+/** Describes the resource that is being accessed. */
+export interface ResourceInfo {
+  /** A name for the type of resource being accessed. */
+  resourceType: string;
+
+  /** The name of the resource being accessed. */
+  resourceName: string;
+
+  /** The owner of the resource (optional). */
+  owner: string;
+
+  /** Describes what error is encountered when accessing this resource. */
+  description: string;
+}
+
+/**
+ * Provides links to documentation or for performing an out of band action.
+ *
+ * For example, if a quota check failed with an error indicating the calling
+ * project hasn't enabled the accessed service, this can contain a URL pointing
+ * directly to the right place in the developer console to flip the bit.
+ */
+export interface Help {
+  /** URL(s) pointing to additional information on handling the current error. */
+  links: HelpLink[];
+}
+
+export interface HelpLink {
+  /** Describes what the link offers. */
+  description: string;
+
+  /** The URL of the link. */
+  url: string;
+}
+
+// ---------------------------------------------------------------------------
+// Zod schemas for the wire format (snake_case JSON from the API).
+//
+// Each schema validates the snake_case wire format from the API and transforms
+// it into the camelCase TypeScript interface. Nullish fields default to their
+// zero values (empty string, empty array, empty record) when absent or null.
+// ---------------------------------------------------------------------------
+
+// Reusable schema fragments. Nullish fields default to their zero values
+// (empty string, empty array, empty record) when absent or null.
+const nullishString = z
+  .string()
+  .nullish()
+  .transform(v => v ?? '');
+
+const errorInfoSchema = z.object({
+  reason: nullishString,
+  domain: nullishString,
+  metadata: z
+    .record(z.string(), z.string())
+    .nullish()
+    .transform(v => v ?? {}),
+});
+
+const requestInfoSchema = z
+  .object({
+    request_id: nullishString,
+    serving_data: nullishString,
+  })
+  .transform(d => ({
+    requestId: d.request_id,
+    servingData: d.serving_data,
+  }));
+
+// Parses a protobuf Duration string (e.g. "42.000000001s") into milliseconds.
+// Null/undefined defaults to 0. Invalid format causes a Zod validation failure.
+const nullishProtoDuration = z
+  .string()
+  .nullish()
+  .transform((v, ctx) => {
+    if (v === null || v === undefined) {
+      return 0;
+    }
+    const ms = parseProtoDuration(v);
+    if (ms === undefined) {
+      ctx.addIssue({code: 'custom', message: 'Invalid protobuf duration.'});
+      return z.NEVER;
+    }
+    return ms;
+  });
+
+const retryInfoSchema = z
+  .object({
+    retry_delay: nullishProtoDuration,
+  })
+  .transform(d => ({
+    retryDelayMs: d.retry_delay,
+  }));
+
+const debugInfoSchema = z
+  .object({
+    stack_entries: z
+      .array(z.string())
+      .nullish()
+      .transform(v => v ?? []),
+    detail: nullishString,
+  })
+  .transform(d => ({
+    stackEntries: d.stack_entries,
+    detail: d.detail,
+  }));
+
+const quotaViolationSchema = z.object({
+  subject: nullishString,
+  description: nullishString,
+});
+
+const quotaFailureSchema = z.object({
+  violations: z
+    .array(quotaViolationSchema)
+    .nullish()
+    .transform(v => v ?? []),
+});
+
+const preconditionViolationSchema = z.object({
+  type: nullishString,
+  subject: nullishString,
+  description: nullishString,
+});
+
+const preconditionFailureSchema = z.object({
+  violations: z
+    .array(preconditionViolationSchema)
+    .nullish()
+    .transform(v => v ?? []),
+});
+
+const fieldViolationSchema = z.object({
+  field: nullishString,
+  description: nullishString,
+});
+
+const badRequestSchema = z
+  .object({
+    field_violations: z
+      .array(fieldViolationSchema)
+      .nullish()
+      .transform(v => v ?? []),
+  })
+  .transform(d => ({
+    fieldViolations: d.field_violations,
+  }));
+
+const resourceInfoSchema = z
+  .object({
+    resource_type: nullishString,
+    resource_name: nullishString,
+    owner: nullishString,
+    description: nullishString,
+  })
+  .transform(d => ({
+    resourceType: d.resource_type,
+    resourceName: d.resource_name,
+    owner: d.owner,
+    description: d.description,
+  }));
+
+const helpLinkSchema = z.object({
+  description: nullishString,
+  url: nullishString,
+});
+
+const helpSchema = z.object({
+  links: z
+    .array(helpLinkSchema)
+    .nullish()
+    .transform(v => v ?? []),
+});
+
+// Google RPC type URLs used to identify error detail types in the wire format.
+const ERROR_INFO_TYPE = 'type.googleapis.com/google.rpc.ErrorInfo';
+const REQUEST_INFO_TYPE = 'type.googleapis.com/google.rpc.RequestInfo';
+const RETRY_INFO_TYPE = 'type.googleapis.com/google.rpc.RetryInfo';
+const DEBUG_INFO_TYPE = 'type.googleapis.com/google.rpc.DebugInfo';
+const QUOTA_FAILURE_TYPE = 'type.googleapis.com/google.rpc.QuotaFailure';
+const PRECONDITION_FAILURE_TYPE =
+  'type.googleapis.com/google.rpc.PreconditionFailure';
+const BAD_REQUEST_TYPE = 'type.googleapis.com/google.rpc.BadRequest';
+const RESOURCE_INFO_TYPE = 'type.googleapis.com/google.rpc.ResourceInfo';
+const HELP_TYPE = 'type.googleapis.com/google.rpc.Help';
+
+// Checks whether a value is a plain object (not null, not an array).
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Parses a protobuf Duration string (e.g. "42.000000001s") into milliseconds.
+// Returns undefined if the format is invalid.
+function parseProtoDuration(s: string): number | undefined {
+  if (!s.endsWith('s')) {
+    return undefined;
+  }
+  const seconds = Number(s.slice(0, -1));
+  if (Number.isNaN(seconds)) {
+    return undefined;
+  }
+  return seconds * 1000;
+}
+
+// Attempts to parse a single detail and assign it to the right ErrorDetails
+// field. Returns true if the detail was recognized and valid, false otherwise.
+function tryAssignDetail(
+  ed: ErrorDetails,
+  type: string,
+  raw: unknown
+): boolean {
+  switch (type) {
+    case ERROR_INFO_TYPE: {
+      const r = errorInfoSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.errorInfo = r.data;
+      return true;
+    }
+    case REQUEST_INFO_TYPE: {
+      const r = requestInfoSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.requestInfo = r.data;
+      return true;
+    }
+    case RETRY_INFO_TYPE: {
+      const r = retryInfoSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.retryInfo = r.data;
+      return true;
+    }
+    case DEBUG_INFO_TYPE: {
+      const r = debugInfoSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.debugInfo = r.data;
+      return true;
+    }
+    case QUOTA_FAILURE_TYPE: {
+      const r = quotaFailureSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.quotaFailure = r.data;
+      return true;
+    }
+    case PRECONDITION_FAILURE_TYPE: {
+      const r = preconditionFailureSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.preconditionFailure = r.data;
+      return true;
+    }
+    case BAD_REQUEST_TYPE: {
+      const r = badRequestSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.badRequest = r.data;
+      return true;
+    }
+    case RESOURCE_INFO_TYPE: {
+      const r = resourceInfoSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.resourceInfo = r.data;
+      return true;
+    }
+    case HELP_TYPE: {
+      const r = helpSchema.safeParse(raw);
+      if (!r.success) return false;
+      ed.help = r.data;
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * Parses an array of raw error detail values into a structured ErrorDetails
+ * object. If multiple details of the same known type are present, the last
+ * one wins.
+ */
+export function parseErrorDetails(rawDetails: unknown[]): ErrorDetails {
+  const ed: ErrorDetails = {unknownDetails: []};
+  for (const rd of rawDetails) {
+    if (!isRecord(rd)) {
+      ed.unknownDetails.push(rd);
+      continue;
+    }
+    const type = rd['@type'];
+    if (typeof type !== 'string') {
+      ed.unknownDetails.push(rd);
+      continue;
+    }
+    if (!tryAssignDetail(ed, type, rd)) {
+      ed.unknownDetails.push(rd);
+    }
+  }
+  return ed;
+}

package/src/apierror/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Databricks API error types.
+ *
+ * @packageDocumentation
+ */
+
+export {ApiError} from './apierror';
+
+export type {
+  ErrorDetails,
+  ErrorInfo,
+  RequestInfo,
+  RetryInfo,
+  DebugInfo,
+  QuotaFailure,
+  QuotaFailureViolation,
+  PreconditionFailure,
+  PreconditionFailureViolation,
+  BadRequest,
+  BadRequestFieldViolation,
+  ResourceInfo,
+  Help,
+  HelpLink,
+} from './details';

package/src/clientinfo/agent.ts

@@ -0,0 +1,125 @@
+/**
+ * Detects the AI coding agent (e.g. Claude Code, Cursor, Gemini CLI) that
+ * is running the current Node.js process. The detected product name is
+ * appended to the user-agent header so that Databricks can understand
+ * which agents are invoking the SDK.
+ *
+ * The agent list and precedence rules are kept in sync across the Go,
+ * Java, Python, and TypeScript SDKs.
+ *
+ * @module
+ */
+
+interface KnownAgent {
+  readonly envVar: string;
+  readonly product: string;
+}
+
+// Name of the agents.md standard env var. When set to a value that no
+// known agent recognizes, detection falls back to "unknown".
+const AGENT_ENV_VAR = 'AGENT';
+
+// Canonical list of AI coding agents. Keep this list in sync with the
+// Go, Java, and Python SDKs. Agents are listed alphabetically by product
+// name.
+const KNOWN_AGENTS: readonly KnownAgent[] = [
+  // The amp agent also sets AGENT=amp, handled by the central fallback.
+  {envVar: 'AMP_CURRENT_THREAD_ID', product: 'amp'},
+  {envVar: 'ANTIGRAVITY_AGENT', product: 'antigravity'},
+  {envVar: 'AUGMENT_AGENT', product: 'augment'},
+  {envVar: 'CLAUDECODE', product: 'claude-code'},
+  {envVar: 'CLINE_ACTIVE', product: 'cline'},
+  {envVar: 'CODEX_CI', product: 'codex'},
+  {envVar: 'COPILOT_CLI', product: 'copilot-cli'},
+  {envVar: 'CURSOR_AGENT', product: 'cursor'},
+  {envVar: 'GEMINI_CLI', product: 'gemini-cli'},
+  // The goose agent also sets AGENT=goose, handled by the central
+  // fallback.
+  {envVar: 'GOOSE_TERMINAL', product: 'goose'},
+  {envVar: 'KIRO', product: 'kiro'},
+  {envVar: 'OPENCLAW_SHELL', product: 'openclaw'},
+  {envVar: 'OPENCODE', product: 'opencode'},
+  // Set by VS Code 1.121+ for agent-initiated terminal commands
+  // (https://code.visualstudio.com/updates/v1_121).
+  {envVar: 'VSCODE_AGENT', product: 'vscode-agent'},
+  {envVar: 'WINDSURF_AGENT', product: 'windsurf'},
+];
+
+function agentEnvFallback(): string {
+  const v = process.env[AGENT_ENV_VAR];
+  if (v === undefined || v === '') {
+    return '';
+  }
+  if (KNOWN_AGENTS.some(a => a.product === v)) {
+    return v;
+  }
+  return 'unknown';
+}
+
+/**
+ * Checks environment variables for known AI agents and returns the
+ * detected product name.
+ *
+ * Explicit product-specific env vars always take precedence over the
+ * generic agents.md `AGENT` env var. `AGENT` is consulted only as a
+ * fallback when no explicit matcher fires, so that an explicit signal
+ * (e.g. `CLAUDECODE=1`) always wins over a conflicting `AGENT=<name>`
+ * value.
+ *
+ * Returns:
+ *
+ * - The product name when exactly one known env var is set.
+ * - `"multiple"` when multiple known env vars are set. Agent env vars
+ *   can be stacked when one agent invokes another as a subagent (e.g.
+ *   Claude Code spawning a Cursor CLI subprocess), so the child process
+ *   inherits env vars from multiple layers.
+ * - When no known env var is set and `AGENT` is a non-empty value: the
+ *   value itself if it names a known product, otherwise `"unknown"`.
+ * - `""` when nothing is set.
+ */
+export function lookupAgentProvider(): string {
+  const matches: string[] = [];
+  for (const a of KNOWN_AGENTS) {
+    if (a.envVar in process.env) {
+      matches.push(a.product);
+    }
+  }
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length > 1) {
+    return 'multiple';
+  }
+  return agentEnvFallback();
+}
+
+let cached: string | undefined;
+
+/**
+ * Returns the detected AI agent name, cached for the process lifetime.
+ *
+ * Returns one of:
+ *
+ * - The known product name when exactly one agent is detected via
+ *   explicit env matchers, or when `AGENT` is set to a known product
+ *   name and no explicit matcher fired.
+ * - `"multiple"` when multiple explicit matchers fire for different
+ *   agents (typically nested agents, e.g. Cursor CLI running as a
+ *   Claude Code subagent).
+ * - `"unknown"` when no explicit matcher fired and `AGENT` is set to a
+ *   value that is not a known product name.
+ * - `""` when no agent is detected.
+ */
+export function agentProvider(): string {
+  cached ??= lookupAgentProvider();
+  return cached;
+}
+
+/**
+ * Clears the cached agent detection result so that the next call to
+ * {@link agentProvider} re-evaluates the environment. Exported for
+ * testing only.
+ */
+export function clearAgentCache(): void {
+  cached = undefined;
+}

package/src/clientinfo/base.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared state management for {@link ClientInfo} defaults. This module
+ * is browser-safe and contains no Node.js-specific APIs.
+ *
+ * @module
+ */
+
+import {ClientInfo, ClientInfoError, isSemVer} from './clientinfo';
+import pkgJson from '../../package.json' with {type: 'json'};
+
+export const MODULE_NAME = 'sdk-js-core';
+export const VERSION: string = pkgJson.version;
+
+// Holds segments added via addToDefault, setProduct, and setPartner.
+// createDefault returns a copy of this with env detection appended.
+let base = ClientInfo.EMPTY;
+
+/**
+ * Sets the product name and version globally. The version must be a
+ * valid semver string.
+ *
+ * Must be called before any client is created. Not safe for concurrent
+ * use.
+ */
+export function setProduct(name: string, version: string): void {
+  if (!isSemVer(version)) {
+    throw new ClientInfoError(
+      'INVALID_VERSION',
+      `Invalid version: ${version}.`
+    );
+  }
+  addToDefault(name, version);
+}
+
+/**
+ * Adds a partner identifier globally. Partner attribution is a
+ * first-class concept used for support ticket routing.
+ *
+ * Must be called before any client is created. Not safe for concurrent
+ * use.
+ */
+export function setPartner(partner: string): void {
+  addToDefault('partner', partner);
+}
+
+/**
+ * Adds a global key/value segment that will be included in every
+ * {@link createDefault} call. Same key with different values is allowed
+ * (e.g., multiple partners). Exact key+value duplicates are silently
+ * ignored.
+ *
+ * Must be called before any client is created. Not safe for concurrent
+ * use.
+ */
+export function addToDefault(key: string, value: string): void {
+  base = base.with({key, value});
+}
+
+// Returns the base ClientInfo for use in createDefault.
+export function getBase(): ClientInfo {
+  return base;
+}
+
+// Resets the base segments. Exported for testing only.
+export function resetBase(): void {
+  base = ClientInfo.EMPTY;
+}
+
+// Returns the base segments as a formatted string. Exported for
+// testing only.
+export function baseToString(): string {
+  return base.toString();
+}