@databricks/sdk-uc-externallocations 0.0.0-dev → 0.1.0-dev.2

package/package.json

@@ -1,7 +1,41 @@
 {
   "name": "@databricks/sdk-uc-externallocations",
-  "version": "0.0.0-dev",
-  "description": "Bootstrap placeholder; real contents in a later release.",
-  "main": "index.js",
-  "license": "Apache-2.0"
+  "version": "0.1.0-dev.2",
+  "description": "",
+  "type": "module",
+  "exports": {
+    "./v1": {
+      "types": "./dist/v1/index.d.ts",
+      "import": "./dist/v1/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "echo 'no tests'",
+    "test:browser": "echo 'no tests'"
+  },
+  "author": "Databricks",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@databricks/sdk-auth": ">=0.1.0-dev.3 <1.0.0",
+    "@databricks/sdk-core": ">=0.1.0-dev.4 <1.0.0",
+    "@databricks/sdk-options": ">=0.1.0-dev.3 <1.0.0",
+    "@js-temporal/polyfill": "^0.5.0",
+    "json-bigint": "^1.0.0",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
 }

package/src/v1/client.ts

@@ -0,0 +1,286 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+import {VERSION as AUTH_VERSION} from '@databricks/sdk-auth';
+import {createDefault} from '@databricks/sdk-core/clientinfo';
+import type {Logger} from '@databricks/sdk-core/logger';
+import {NoOpLogger} from '@databricks/sdk-core/logger';
+import type {CallOptions} from '@databricks/sdk-options/call';
+import type {ClientOptions} from '@databricks/sdk-options/client';
+import type {HttpClient} from '@databricks/sdk-core/http';
+import {newHttpClient} from './transport';
+import {
+  buildHttpRequest,
+  executeCall,
+  executeHttpCall,
+  marshalRequest,
+  parseResponse,
+} from './utils';
+import pkgJson from '../../package.json' with {type: 'json'};
+import type {
+  CreateExternalLocationRequest,
+  DeleteExternalLocationRequest,
+  DeleteExternalLocationRequest_Response,
+  ExternalLocationInfo,
+  GetExternalLocationRequest,
+  ListExternalLocationsRequest,
+  ListExternalLocationsRequest_Response,
+  UpdateExternalLocationRequest,
+} from './model';
+import {
+  marshalCreateExternalLocationRequestSchema,
+  marshalUpdateExternalLocationRequestSchema,
+  unmarshalDeleteExternalLocationRequest_ResponseSchema,
+  unmarshalExternalLocationInfoSchema,
+  unmarshalListExternalLocationsRequest_ResponseSchema,
+} from './model';
+
+// Package identity segment for this client to be used in the User-Agent header.
+const PACKAGE_SEGMENT = {
+  key: 'sdk-js-' + pkgJson.name.replace(/^@[^/]+\/sdk-/, ''),
+  value: pkgJson.version,
+};
+
+export class ExternalLocationsClient {
+  private readonly host: string;
+  // Workspace ID used to route workspace-level calls on unified hosts (SPOG).
+  // When set, workspace-level methods send X-Databricks-Org-Id on every
+  // request.
+  private readonly workspaceId: string | undefined;
+  private readonly httpClient: HttpClient;
+  private readonly logger: Logger;
+  // User-Agent header value. Composed once at construction from
+  // createDefault() merged with this package's identity and the active
+  // credential's name.
+  private readonly userAgent: string;
+
+  constructor(options: ClientOptions) {
+    if (options.host === undefined) {
+      throw new Error('Host is required.');
+    }
+    this.host = options.host.replace(/\/$/, '');
+    this.workspaceId = options.workspaceId;
+    this.logger = options.logger ?? new NoOpLogger();
+    const info = createDefault()
+      .with(PACKAGE_SEGMENT)
+      .with({key: 'sdk-js-auth', value: AUTH_VERSION})
+      .with({key: 'auth', value: options.credentials?.name() ?? 'default'});
+    this.userAgent = info.toString();
+    this.httpClient = newHttpClient(options);
+  }
+
+  /**
+   * Creates a new external location entry in the metastore.
+   * The caller must be a metastore admin or have the **CREATE_EXTERNAL_LOCATION** privilege on both the metastore and the associated storage credential.
+   */
+  async createExternalLocation(
+    req: CreateExternalLocationRequest,
+    options?: CallOptions
+  ): Promise<ExternalLocationInfo> {
+    const url = `${this.host}/api/2.1/unity-catalog/external-locations`;
+    const body = marshalRequest(
+      req,
+      marshalCreateExternalLocationRequestSchema
+    );
+    let resp: ExternalLocationInfo | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers({'Content-Type': 'application/json'});
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('POST', url, headers, callSignal, body);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(respBody, unmarshalExternalLocationInfoSchema);
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+
+  /** Deletes the specified external location from the metastore. The caller must be the owner of the external location. */
+  async deleteExternalLocation(
+    req: DeleteExternalLocationRequest,
+    options?: CallOptions
+  ): Promise<DeleteExternalLocationRequest_Response> {
+    const url = `${this.host}/api/2.1/unity-catalog/external-locations/${req.nameArg ?? ''}`;
+    const params = new URLSearchParams();
+    if (req.force !== undefined) {
+      params.append('force', String(req.force));
+    }
+    const query = params.toString();
+    const fullUrl = query !== '' ? `${url}?${query}` : url;
+    let resp: DeleteExternalLocationRequest_Response | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers();
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('DELETE', fullUrl, headers, callSignal);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(
+        respBody,
+        unmarshalDeleteExternalLocationRequest_ResponseSchema
+      );
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+
+  /**
+   * Gets an external location from the metastore.
+   * The caller must be either a metastore admin, the owner of the external location, or a user that has some privilege on the external location.
+   */
+  async getExternalLocation(
+    req: GetExternalLocationRequest,
+    options?: CallOptions
+  ): Promise<ExternalLocationInfo> {
+    const url = `${this.host}/api/2.1/unity-catalog/external-locations/${req.nameArg ?? ''}`;
+    const params = new URLSearchParams();
+    if (req.includeBrowse !== undefined) {
+      params.append('include_browse', String(req.includeBrowse));
+    }
+    const query = params.toString();
+    const fullUrl = query !== '' ? `${url}?${query}` : url;
+    let resp: ExternalLocationInfo | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers();
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('GET', fullUrl, headers, callSignal);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(respBody, unmarshalExternalLocationInfoSchema);
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+
+  /**
+   * Gets an array of external locations (__ExternalLocationInfo__ objects) from the metastore.
+   * The caller must be a metastore admin, the owner of the external location, or a user that has some privilege on the external location.
+   * There is no guarantee of a specific ordering of the elements in the array.
+   *
+   * NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.
+   *
+   * PAGINATION BEHAVIOR: When using pagination (max_results >= 0), a page may contain zero results while still providing a next_page_token.
+   * Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.
+   */
+  async listExternalLocations(
+    req: ListExternalLocationsRequest,
+    options?: CallOptions
+  ): Promise<ListExternalLocationsRequest_Response> {
+    const url = `${this.host}/api/2.1/unity-catalog/external-locations`;
+    const params = new URLSearchParams();
+    if (req.includeBrowse !== undefined) {
+      params.append('include_browse', String(req.includeBrowse));
+    }
+    if (req.maxResults !== undefined) {
+      params.append('max_results', String(req.maxResults));
+    }
+    if (req.pageToken !== undefined) {
+      params.append('page_token', req.pageToken);
+    }
+    if (req.includeUnbound !== undefined) {
+      params.append('include_unbound', String(req.includeUnbound));
+    }
+    const query = params.toString();
+    const fullUrl = query !== '' ? `${url}?${query}` : url;
+    let resp: ListExternalLocationsRequest_Response | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers();
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('GET', fullUrl, headers, callSignal);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(
+        respBody,
+        unmarshalListExternalLocationsRequest_ResponseSchema
+      );
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+
+  async *listExternalLocationsIter(
+    req: ListExternalLocationsRequest,
+    options?: CallOptions
+  ): AsyncGenerator<ExternalLocationInfo> {
+    const pageReq: ListExternalLocationsRequest = {...req};
+    for (;;) {
+      const resp = await this.listExternalLocations(pageReq, options);
+      for (const item of resp.externalLocations ?? []) {
+        yield item;
+      }
+      if (resp.nextPageToken === undefined || resp.nextPageToken === '') {
+        return;
+      }
+      pageReq.pageToken = resp.nextPageToken;
+    }
+  }
+
+  /**
+   * Updates an external location in the metastore. The caller must be the owner of the external location, or be a metastore admin.
+   * In the second case, the admin can only update the name of the external location.
+   */
+  async updateExternalLocation(
+    req: UpdateExternalLocationRequest,
+    options?: CallOptions
+  ): Promise<ExternalLocationInfo> {
+    const url = `${this.host}/api/2.1/unity-catalog/external-locations/${req.nameArg ?? ''}`;
+    const body = marshalRequest(
+      req,
+      marshalUpdateExternalLocationRequestSchema
+    );
+    let resp: ExternalLocationInfo | undefined;
+    const call = async (callSignal?: AbortSignal): Promise<void> => {
+      const headers = new Headers({'Content-Type': 'application/json'});
+      if (this.workspaceId !== undefined) {
+        headers.set('X-Databricks-Org-Id', this.workspaceId);
+      }
+      headers.set('User-Agent', this.userAgent);
+      const httpReq = buildHttpRequest('PATCH', url, headers, callSignal, body);
+      const respBody = await executeHttpCall({
+        request: httpReq,
+        httpClient: this.httpClient,
+        logger: this.logger,
+      });
+      resp = parseResponse(respBody, unmarshalExternalLocationInfoSchema);
+    };
+    await executeCall(call, options);
+    if (resp === undefined) {
+      throw new Error('operation completed without a result.');
+    }
+    return resp;
+  }
+}

package/src/v1/index.ts

@@ -0,0 +1,22 @@
+// Code generated from API definition by Databricks SDK Generator. DO NOT EDIT.
+
+export {ExternalLocationsClient} from './client';
+
+export {IsolationMode, SseEncryptionAlgorithm} from './model';
+
+export type {
+  AwsSqsQueue,
+  AzureQueueStorage,
+  CreateExternalLocationRequest,
+  DeleteExternalLocationRequest,
+  DeleteExternalLocationRequest_Response,
+  EncryptionDetails,
+  ExternalLocationInfo,
+  FileEventQueue,
+  GcpPubsub,
+  GetExternalLocationRequest,
+  ListExternalLocationsRequest,
+  ListExternalLocationsRequest_Response,
+  SseEncryptionDetails,
+  UpdateExternalLocationRequest,
+} from './model';