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

package/README.md

@@ -1 +1,11 @@
-This is a placeholder release used to enable OIDC trusted publishing. Real code lands in a later version.
+# Databricks SDK Core for JavaScript
+
+> [!WARNING]
+> ## PREVIEW - NOT FOR PRODUCTION USE
+>
+> **This SDK is in preview and is subject to change without notice.**
+>
+> - **Do NOT use in production environments**
+> - **Breaking changes may occur at any time**
+> - **APIs are experimental and unstable**
+> - **Use for development and testing only**

package/dist/api/execute.d.ts

@@ -0,0 +1,12 @@
+import type { Options } from './options';
+/** Call represents a call to a Databricks API. */
+export type Call = (signal?: AbortSignal) => Promise<void>;
+/**
+ * Sleeps for the given duration. It is mostly equivalent to setTimeout, but
+ * can be interrupted by the AbortSignal if the signal aborts before the
+ * duration elapses.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** Makes a call to a Databricks API using the given options. */
+export declare function execute(signal: AbortSignal | undefined, call: Call, options?: Options): Promise<void>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/api/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/api/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAGvC,kDAAkD;AAClD,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAO3D;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBrE;AAKD,gEAAgE;AAChE,wBAAsB,OAAO,CAC3B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/api/execute.js

@@ -0,0 +1,77 @@
+// Coerces an unknown value to an Error instance.
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+/**
+ * Sleeps for the given duration. It is mostly equivalent to setTimeout, but
+ * can be interrupted by the AbortSignal if the signal aborts before the
+ * duration elapses.
+ */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(toError(signal.reason));
+            return;
+        }
+        if (signal === undefined) {
+            setTimeout(resolve, ms);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(toError(signal.reason));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** Makes a call to a Databricks API using the given options. */
+export async function execute(signal, call, options) {
+    const opts = { ...options };
+    return executeImpl(signal, call, opts, sleep);
+}
+/**
+ * The actual implementation of execute. Its purpose is to ease testing by
+ * providing a convenient way to mock the sleeping logic.
+ */
+async function executeImpl(signal, apiCall, opts, sleep) {
+    // Optionally combine the signal with a timeout signal. If the signal
+    // already has a deadline, that deadline is updated to the minimum of the
+    // signal's deadline and the timeout.
+    if (opts.timeout !== undefined && opts.timeout > 0) {
+        const timeoutSignal = AbortSignal.timeout(opts.timeout);
+        signal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+    }
+    // Get a new retrier for this specific execution. This is instantiated
+    // lazily if and when the first call execution returns an error.
+    let retrier;
+    for (;;) {
+        if (opts.rateLimiter) {
+            await opts.rateLimiter.wait(signal);
+        }
+        try {
+            await apiCall(signal);
+            return; // Nothing to retry.
+        }
+        catch (err) {
+            const error = toError(err);
+            if (retrier === undefined) {
+                if (opts.retrier) {
+                    retrier = opts.retrier(); // Lazily instantiate the retrier.
+                }
+                if (retrier === undefined) {
+                    throw error; // No retrier == no retry.
+                }
+            }
+            const delay = retrier.isRetriable(error);
+            if (delay === undefined) {
+                throw error; // Not retriable.
+            }
+            await sleep(delay, signal);
+        }
+    }
+}
+//# sourceMappingURL=execute.js.map

package/dist/api/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/api/execute.ts"],"names":[],"mappings":"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"}

package/dist/api/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Databricks API client utilities.
+ *
+ * @packageDocumentation
+ */
+export { execute } from './execute';
+export type { Call } from './execute';
+export type { Limiter } from './limiter';
+export type { Options } from './options';
+export { BackoffPolicy, retryOn } from './retrier';
+export type { BackoffPolicyOptions, Retrier } from './retrier';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAClC,YAAY,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AACpC,YAAY,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,YAAY,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,EAAC,aAAa,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AACjD,YAAY,EAAC,oBAAoB,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,8 @@
+/**
+ * Databricks API client utilities.
+ *
+ * @packageDocumentation
+ */
+export { execute } from './execute';
+export { BackoffPolicy, retryOn } from './retrier';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAIlC,OAAO,EAAC,aAAa,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC"}

package/dist/api/limiter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Limiter is anything that can wait. It is typically used to implement
+ * client-side rate limiting. Implementations of this interface must be
+ * safe to call concurrently.
+ */
+export interface Limiter {
+    wait(signal?: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=limiter.d.ts.map

package/dist/api/limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../src/api/limiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C"}

package/dist/api/limiter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=limiter.js.map

package/dist/api/limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.js","sourceRoot":"","sources":["../../src/api/limiter.ts"],"names":[],"mappings":""}

package/dist/api/options.d.ts

@@ -0,0 +1,22 @@
+import type { Limiter } from './limiter';
+import type { Retrier } from './retrier';
+/** Options to control the behavior of an API call. */
+export interface Options {
+    /**
+     * Provides a new Retrier to be used to execute a Call. The function is
+     * called for each Call and must be safe to call concurrently. The retrier
+     * must be fresh within the context of an execute call (e.g. no need to
+     * reset a BackoffPolicy).
+     */
+    retrier?: (() => Retrier) | undefined;
+    /** The rate limiter used to potentially rate limit the API call. */
+    rateLimiter?: Limiter | undefined;
+    /**
+     * Timeout duration in milliseconds. If the signal already has a deadline,
+     * that deadline is updated to the minimum of the signal's deadline and the
+     * timeout. The timeout covers the whole Call execution; it is not a timeout
+     * for each intermediary API call.
+     */
+    timeout?: number | undefined;
+}
+//# sourceMappingURL=options.d.ts.map

package/dist/api/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/api/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAEvC,sDAAsD;AACtD,MAAM,WAAW,OAAO;IACtB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS,CAAC;IACtC,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B"}

package/dist/api/options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=options.js.map

package/dist/api/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/api/options.ts"],"names":[],"mappings":""}

package/dist/api/retrier.d.ts

@@ -0,0 +1,58 @@
+/** Options for configuring a {@link BackoffPolicy}. */
+export interface BackoffPolicyOptions {
+    /** Initial delay in milliseconds; defaults to 1000. */
+    initial?: number;
+    /** Maximum delay in milliseconds; defaults to 60000. */
+    maximum?: number;
+    /**
+     * Factor by which the delay is multiplied after each retry. The value must
+     * be greater or equal to 1. If not, it defaults to 2.
+     */
+    factor?: number;
+}
+export declare const rand: {
+    int(n: number): number;
+};
+/**
+ * BackoffPolicy implements an exponential backoff policy. The delay between
+ * retries is randomly computed between 0 and the "exponential delay" as
+ * recommended in [Exponential Backoff And Jitter]. The retry delay starts from
+ * initial and grows exponentially by factor at every retry. The maximum retry
+ * delay is capped by maximum.
+ *
+ * There is no parameter to limit the number of retries. This is intended as
+ * such logic should be implemented upstream (e.g. in a Retrier).
+ *
+ * [Exponential Backoff And Jitter]: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+ */
+export declare class BackoffPolicy {
+    /** Initial delay in milliseconds. */
+    readonly initial: number;
+    /** Maximum delay in milliseconds. */
+    readonly maximum: number;
+    /** Factor by which the delay is multiplied after each retry. */
+    readonly factor: number;
+    private current;
+    constructor(options?: BackoffPolicyOptions);
+    /** Returns a random delay in [0, current] and grows the current delay. */
+    delay(): number;
+}
+/** Retrier defines a retry behavior. */
+export interface Retrier {
+    /**
+     * Returns the delay in milliseconds before the next retry, or undefined if
+     * the error is not retriable. Implementations should assume that the given
+     * error is never undefined.
+     */
+    isRetriable(err: Error): number | undefined;
+}
+/**
+ * Returns a Retrier that retries based on the isRetriable predicate and relies
+ * on an internal backoff policy to decide how long to wait between retries.
+ *
+ * Important: the retrier has its own backoff policy which cannot be trivially
+ * reset by design. Users who need to reset the backoff policy should rather
+ * create a new retrier.
+ */
+export declare function retryOn(options: BackoffPolicyOptions, isRetriable: (err: Error) => boolean): Retrier;
+//# sourceMappingURL=retrier.d.ts.map

package/dist/api/retrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrier.d.ts","sourceRoot":"","sources":["../../src/api/retrier.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,eAAO,MAAM,IAAI;WAER,MAAM,GAAG,MAAM;CAGvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAGxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,CAAC,EAAE,oBAAoB;IAgB1C,0EAA0E;IAC1E,KAAK,IAAI,MAAM;CAShB;AAED,wCAAwC;AACxC,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,oBAAoB,EAC7B,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,GACnC,OAAO,CAUT"}

package/dist/api/retrier.js

@@ -0,0 +1,70 @@
+// Random number generation, wrapped in an object for testability.
+export const rand = {
+    // Returns a random integer in [0, n).
+    int(n) {
+        return Math.floor(Math.random() * n);
+    },
+};
+/**
+ * BackoffPolicy implements an exponential backoff policy. The delay between
+ * retries is randomly computed between 0 and the "exponential delay" as
+ * recommended in [Exponential Backoff And Jitter]. The retry delay starts from
+ * initial and grows exponentially by factor at every retry. The maximum retry
+ * delay is capped by maximum.
+ *
+ * There is no parameter to limit the number of retries. This is intended as
+ * such logic should be implemented upstream (e.g. in a Retrier).
+ *
+ * [Exponential Backoff And Jitter]: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+ */
+export class BackoffPolicy {
+    /** Initial delay in milliseconds. */
+    initial;
+    /** Maximum delay in milliseconds. */
+    maximum;
+    /** Factor by which the delay is multiplied after each retry. */
+    factor;
+    // Current delay before the next retry.
+    current;
+    constructor(options) {
+        let initial = options?.initial ?? 1000; // Default initial delay of 1 second.
+        const maximum = options?.maximum ?? 60000; // Default maximum delay of 60 seconds.
+        if (initial > maximum) {
+            // Initial cannot be greater than maximum.
+            initial = maximum;
+        }
+        this.initial = initial;
+        this.maximum = maximum;
+        this.factor =
+            options?.factor !== undefined && options.factor >= 1 ? options.factor : 2;
+        this.current = this.initial;
+    }
+    /** Returns a random delay in [0, current] and grows the current delay. */
+    delay() {
+        // Random duration in the range [0, this.current].
+        const d = rand.int(this.current + 1);
+        // Grow delay for the next call.
+        this.current = Math.min(this.current * this.factor, this.maximum);
+        return d;
+    }
+}
+/**
+ * Returns a Retrier that retries based on the isRetriable predicate and relies
+ * on an internal backoff policy to decide how long to wait between retries.
+ *
+ * Important: the retrier has its own backoff policy which cannot be trivially
+ * reset by design. Users who need to reset the backoff policy should rather
+ * create a new retrier.
+ */
+export function retryOn(options, isRetriable) {
+    const bp = new BackoffPolicy(options);
+    return {
+        isRetriable(err) {
+            if (!isRetriable(err)) {
+                return undefined;
+            }
+            return bp.delay();
+        },
+    };
+}
+//# sourceMappingURL=retrier.js.map

package/dist/api/retrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrier.js","sourceRoot":"","sources":["../../src/api/retrier.ts"],"names":[],"mappings":"AAeA,kEAAkE;AAClE,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,sCAAsC;IACtC,GAAG,CAAC,CAAS;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;CACF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,aAAa;IACxB,qCAAqC;IAC5B,OAAO,CAAS;IAEzB,qCAAqC;IAC5B,OAAO,CAAS;IAEzB,gEAAgE;IACvD,MAAM,CAAS;IAExB,uCAAuC;IAC/B,OAAO,CAAS;IAExB,YAAY,OAA8B;QACxC,IAAI,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,CAAC,qCAAqC;QAC7E,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC,CAAC,uCAAuC;QAElF,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;YACtB,0CAA0C;YAC1C,OAAO,GAAG,OAAO,CAAC;QACpB,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM;YACT,OAAO,EAAE,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,0EAA0E;IAC1E,KAAK;QACH,kDAAkD;QAClD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;QAErC,gCAAgC;QAChC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAElE,OAAO,CAAC,CAAC;IACX,CAAC;CACF;AAYD;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACrB,OAA6B,EAC7B,WAAoC;IAEpC,MAAM,EAAE,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO;QACL,WAAW,CAAC,GAAU;YACpB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/apierror/apierror.d.ts

@@ -0,0 +1,53 @@
+import { Code } from './codes';
+import type { ErrorDetails } from './details';
+interface APIErrorOptions {
+    code: Code;
+    message: string;
+    details: ErrorDetails;
+    httpStatusCode?: number | undefined;
+    httpHeader?: Headers | undefined;
+    httpBody?: Uint8Array | undefined;
+    cause?: unknown;
+}
+/** APIError is a transport-agnostic error representing a Databricks API error. */
+export declare class APIError extends Error {
+    /** The canonical error code of the error. */
+    readonly code: Code;
+    /**
+     * The structured error details of the error. This is left empty if the
+     * error response is not a standard Databricks API error.
+     */
+    readonly details: ErrorDetails;
+    private readonly httpErr?;
+    /**
+     * Do not use this constructor directly. Use {@link APIError.fromHttpError}
+     * instead. This constructor is only meant for internal and testing use.
+     * TODO: Make this constructor private.
+     *
+     * @private
+     */
+    constructor(options: APIErrorOptions);
+    /**
+     * HTTPStatusCode returns the APIError's HTTP status code. If the APIError
+     * is not an HTTP error, it returns -1.
+     */
+    get httpStatusCode(): number;
+    /**
+     * HTTPHeader returns the APIError's HTTP headers. If the APIError is not
+     * an HTTP error, it returns undefined.
+     */
+    get httpHeader(): Headers | undefined;
+    /**
+     * HTTPBody returns the APIError's HTTP body. If the APIError is not an HTTP
+     * error, it returns undefined.
+     */
+    get httpBody(): Uint8Array | undefined;
+    /**
+     * Parses an HTTP error response into an APIError. Returns undefined if the
+     * status code is 2xx.
+     */
+    static fromHttpError(statusCode: number, header: Headers | undefined, body: Uint8Array | undefined): APIError | undefined;
+}
+export declare function toCode(httpCode: number): Code;
+export {};
+//# sourceMappingURL=apierror.d.ts.map

package/dist/apierror/apierror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apierror.d.ts","sourceRoot":"","sources":["../../src/apierror/apierror.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,IAAI,EAAiB,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,WAAW,CAAC;AA8B5C,UAAU,eAAe;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,kFAAkF;AAClF,qBAAa,QAAS,SAAQ,KAAK;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAG/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAIvB;IAEF;;;;;;OAMG;gBACS,OAAO,EAAE,eAAe;IAcpC;;;OAGG;IACH,IAAI,cAAc,IAAI,MAAM,CAK3B;IAED;;;OAGG;IACH,IAAI,UAAU,IAAI,OAAO,GAAG,SAAS,CAKpC;IAED;;;OAGG;IACH,IAAI,QAAQ,IAAI,UAAU,GAAG,SAAS,CAKrC;IAED;;;OAGG;IACH,MAAM,CAAC,aAAa,CAClB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,IAAI,EAAE,UAAU,GAAG,SAAS,GAC3B,QAAQ,GAAG,SAAS;CAmFxB;AAGD,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CA2C7C"}

package/dist/apierror/apierror.js

@@ -0,0 +1,217 @@
+import { z } from 'zod';
+import { Code, codeFromString } from './codes';
+import { parseErrorDetails } from './details';
+// Reusable schema fragment for nullish string fields.
+const nullishString = z
+    .string()
+    .nullish()
+    .transform(v => v ?? '');
+// Zod schema for parsing the JSON error response body. The schema is lenient
+// to handle the various Databricks API error formats (standard, legacy, SCIM).
+const errorResponseSchema = z.object({
+    message: nullishString,
+    details: z
+        .array(z.unknown())
+        .nullish()
+        .transform(v => v ?? []),
+    // Some Databricks APIs incorrectly return the HTTP status code as an
+    // integer rather than the actual error code as a string.
+    error_code: z.unknown().optional(),
+    // Legacy Databricks APIs (e.g. version 1.2 and earlier) used "error"
+    // instead of "message".
+    error: nullishString,
+    // SCIM error fields (RFC7644 section 3.7.3).
+    // The "status" field is intentionally omitted; it duplicates HTTP status.
+    detail: nullishString,
+    scimType: nullishString,
+});
+/** APIError is a transport-agnostic error representing a Databricks API error. */
+export class APIError extends Error {
+    /** The canonical error code of the error. */
+    code;
+    /**
+     * The structured error details of the error. This is left empty if the
+     * error response is not a standard Databricks API error.
+     */
+    details;
+    // The raw HTTP error details, undefined if this is not an HTTP error.
+    httpErr;
+    /**
+     * Do not use this constructor directly. Use {@link APIError.fromHttpError}
+     * instead. This constructor is only meant for internal and testing use.
+     * TODO: Make this constructor private.
+     *
+     * @private
+     */
+    constructor(options) {
+        super(options.message, { cause: options.cause });
+        this.name = 'APIError';
+        this.code = options.code;
+        this.details = options.details;
+        if (options.httpStatusCode !== undefined) {
+            this.httpErr = {
+                statusCode: options.httpStatusCode,
+                header: options.httpHeader,
+                body: options.httpBody,
+            };
+        }
+    }
+    /**
+     * HTTPStatusCode returns the APIError's HTTP status code. If the APIError
+     * is not an HTTP error, it returns -1.
+     */
+    get httpStatusCode() {
+        if (this.httpErr === undefined) {
+            return -1;
+        }
+        return this.httpErr.statusCode;
+    }
+    /**
+     * HTTPHeader returns the APIError's HTTP headers. If the APIError is not
+     * an HTTP error, it returns undefined.
+     */
+    get httpHeader() {
+        if (this.httpErr === undefined) {
+            return undefined;
+        }
+        return this.httpErr.header;
+    }
+    /**
+     * HTTPBody returns the APIError's HTTP body. If the APIError is not an HTTP
+     * error, it returns undefined.
+     */
+    get httpBody() {
+        if (this.httpErr === undefined) {
+            return undefined;
+        }
+        return this.httpErr.body;
+    }
+    /**
+     * Parses an HTTP error response into an APIError. Returns undefined if the
+     * status code is 2xx.
+     */
+    static fromHttpError(statusCode, header, body) {
+        if (statusCode >= 200 && statusCode < 300) {
+            return undefined;
+        }
+        const emptyDetails = { unknownDetails: [] };
+        if (body === undefined || body.length === 0) {
+            return new APIError({
+                code: toCode(statusCode),
+                message: '',
+                details: emptyDetails,
+                httpStatusCode: statusCode,
+                httpHeader: header,
+                httpBody: body,
+            });
+        }
+        // Decode the body to a string for JSON parsing.
+        let parsed;
+        try {
+            parsed = JSON.parse(new TextDecoder().decode(body));
+        }
+        catch (e) {
+            // The JSON error is simply swallowed, this typically happens when the
+            // error does not come directly from a Databricks API. A typical example
+            // is when the error is returned by a proxy.
+            return new APIError({
+                code: toCode(statusCode),
+                message: '',
+                details: emptyDetails,
+                httpStatusCode: statusCode,
+                httpHeader: header,
+                httpBody: body,
+                cause: e instanceof Error ? e : undefined,
+            });
+        }
+        const result = errorResponseSchema.safeParse(parsed);
+        if (!result.success) {
+            return new APIError({
+                code: toCode(statusCode),
+                message: '',
+                details: emptyDetails,
+                httpStatusCode: statusCode,
+                httpHeader: header,
+                httpBody: body,
+                cause: result.error,
+            });
+        }
+        const errResp = result.data;
+        // Error codes may be missing or be an integer (legacy APIs). In such
+        // cases, defer to the HTTP status code to infer the closest canonical
+        // error code.
+        let errorCode;
+        if (typeof errResp.error_code === 'string') {
+            errorCode = codeFromString(errResp.error_code);
+        }
+        else {
+            errorCode = toCode(statusCode);
+        }
+        // Determine the error message from available fields.
+        let errorMessage = '';
+        if (errResp.message !== '') {
+            errorMessage = errResp.message;
+        }
+        else if (errResp.error !== '') {
+            errorMessage = errResp.error;
+        }
+        else if (errResp.detail !== '') {
+            errorMessage = errResp.detail;
+        }
+        else if (errResp.scimType !== '') {
+            errorMessage = errResp.scimType;
+        }
+        return new APIError({
+            code: errorCode,
+            message: errorMessage,
+            details: parseErrorDetails(errResp.details),
+            httpStatusCode: statusCode,
+            httpHeader: header,
+            httpBody: body,
+        });
+    }
+}
+// Maps an HTTP status code to the closest canonical error code.
+export function toCode(httpCode) {
+    // Canonical mappings.
+    switch (httpCode) {
+        case 200:
+            return Code.OK;
+        case 400:
+            return Code.INVALID_ARGUMENT;
+        case 401:
+            return Code.UNAUTHENTICATED;
+        case 403:
+            return Code.PERMISSION_DENIED;
+        case 404:
+            return Code.NOT_FOUND;
+        case 409:
+            return Code.ABORTED;
+        case 416:
+            return Code.OUT_OF_RANGE;
+        case 429:
+            return Code.RESOURCE_EXHAUSTED;
+        case 501:
+            return Code.UNIMPLEMENTED;
+        case 503:
+            return Code.UNAVAILABLE;
+        case 504:
+            return Code.DEADLINE_EXCEEDED;
+        default:
+            break;
+    }
+    // Fallback for status codes without a direct canonical mapping.
+    if (httpCode >= 200 && httpCode < 300) {
+        return Code.OK;
+    }
+    if (httpCode >= 400 && httpCode < 500) {
+        // Most non-canonical 4xx status codes are state related and map
+        // to the definition of FailedPrecondition.
+        return Code.FAILED_PRECONDITION;
+    }
+    if (httpCode >= 500 && httpCode < 600) {
+        return Code.INTERNAL;
+    }
+    return Code.UNKNOWN;
+}
+//# sourceMappingURL=apierror.js.map

package/dist/apierror/apierror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apierror.js","sourceRoot":"","sources":["../../src/apierror/apierror.ts"],"names":[],"mappings":"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"}