@google/adk 2.2.0 → 2.3.0

package/dist/esm/tools/application_integration_tool/clients/connections_client.js

@@ -0,0 +1,561 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { experimental } from "../../../utils/experimental.js";
+import { toJsonObject } from "../../../utils/json_utils.js";
+import { CloudPlatformTokenSource, sendCloudRequest } from "./cloud_request.js";
+const CONNECTOR_URL = "https://connectors.googleapis.com";
+const OPERATION_POLL_INTERVAL_MS = 1e3;
+function toStringValue(value) {
+  return typeof value === "string" ? value : "";
+}
+__name(toStringValue, "toStringValue");
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+__name(sleep, "sleep");
+function schemaRef(name) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+__name(schemaRef, "schemaRef");
+const CONNECTOR_BASE_SPEC = {
+  openapi: "3.0.1",
+  info: {
+    title: "ExecuteConnection",
+    description: "This tool can execute a query on connection",
+    version: "4"
+  },
+  servers: [{ url: "https://integrations.googleapis.com" }],
+  security: [{ google_auth: ["https://www.googleapis.com/auth/cloud-platform"] }],
+  paths: {},
+  components: {
+    schemas: {
+      operation: {
+        type: "string",
+        default: "LIST_ENTITIES",
+        description: "Operation to execute. Possible values are LIST_ENTITIES, GET_ENTITY, CREATE_ENTITY, UPDATE_ENTITY, DELETE_ENTITY in case of entities. EXECUTE_ACTION in case of actions. and EXECUTE_QUERY in case of custom queries."
+      },
+      entityId: {
+        type: "string",
+        description: "Name of the entity"
+      },
+      connectorInputPayload: { type: "object" },
+      filterClause: {
+        type: "string",
+        default: "",
+        description: "WHERE clause in SQL query"
+      },
+      pageSize: {
+        type: "integer",
+        default: 50,
+        description: "Number of entities to return in the response"
+      },
+      pageToken: {
+        type: "string",
+        default: "",
+        description: "Page token to return the next page of entities"
+      },
+      connectionName: {
+        type: "string",
+        default: "",
+        description: "Connection resource name to run the query for"
+      },
+      serviceName: {
+        type: "string",
+        default: "",
+        description: "Service directory for the connection"
+      },
+      host: {
+        type: "string",
+        default: "",
+        description: "Host name in case of tls service directory"
+      },
+      entity: {
+        type: "string",
+        default: "Issues",
+        description: "Entity to run the query for"
+      },
+      action: {
+        type: "string",
+        default: "ExecuteCustomQuery",
+        description: "Action to run the query for"
+      },
+      query: {
+        type: "string",
+        default: "",
+        description: "Custom Query to execute on the connection"
+      },
+      dynamicAuthConfig: {
+        type: "object",
+        default: {},
+        description: "Dynamic auth config for the connection"
+      },
+      timeout: {
+        type: "integer",
+        default: 120,
+        description: "Timeout in seconds for execution of custom query"
+      },
+      connectorOutputPayload: { type: "object" },
+      nextPageToken: { type: "string" },
+      "execute-connector_Response": {
+        required: ["connectorOutputPayload"],
+        type: "object",
+        properties: {
+          connectorOutputPayload: schemaRef("connectorOutputPayload"),
+          nextPageToken: schemaRef("nextPageToken")
+        }
+      }
+    },
+    securitySchemes: {
+      google_auth: {
+        type: "oauth2",
+        flows: {
+          implicit: {
+            authorizationUrl: "https://accounts.google.com/o/oauth2/auth",
+            scopes: {
+              "https://www.googleapis.com/auth/cloud-platform": "Auth for google cloud services"
+            }
+          }
+        }
+      }
+    }
+  }
+};
+function connectorPayload(jsonSchema) {
+  const openApiSchema = {};
+  if ("description" in jsonSchema) {
+    openApiSchema["description"] = jsonSchema["description"];
+  }
+  if ("type" in jsonSchema) {
+    const type = jsonSchema["type"];
+    if (Array.isArray(type)) {
+      if (type.includes("null")) {
+        openApiSchema["nullable"] = true;
+        const otherTypes = type.filter((t) => t !== "null");
+        if (otherTypes.length > 0) {
+          openApiSchema["type"] = otherTypes[0];
+        }
+      } else if (type.length > 0) {
+        openApiSchema["type"] = type[0];
+      }
+    } else {
+      openApiSchema["type"] = type;
+    }
+  }
+  if (openApiSchema["type"] === "object" && "properties" in jsonSchema) {
+    const properties = {};
+    for (const [name, schema] of Object.entries(
+      toJsonObject(jsonSchema["properties"])
+    )) {
+      properties[name] = connectorPayload(toJsonObject(schema));
+    }
+    openApiSchema["properties"] = properties;
+  } else if (openApiSchema["type"] === "array" && "items" in jsonSchema) {
+    const items = jsonSchema["items"];
+    openApiSchema["items"] = Array.isArray(items) ? items.map((item) => connectorPayload(toJsonObject(item))) : connectorPayload(toJsonObject(items));
+  }
+  return openApiSchema;
+}
+__name(connectorPayload, "connectorPayload");
+function postOperation(options) {
+  const { summary, description, operationId, requestSchemaRef, responseSchema } = options;
+  return {
+    post: {
+      summary,
+      description,
+      operationId,
+      requestBody: {
+        content: {
+          "application/json": {
+            schema: { $ref: requestSchemaRef }
+          }
+        }
+      },
+      responses: {
+        "200": {
+          description: "Success response",
+          content: {
+            "application/json": {
+              schema: responseSchema
+            }
+          }
+        }
+      }
+    }
+  };
+}
+__name(postOperation, "postOperation");
+function entityIdRequest() {
+  return {
+    type: "object",
+    required: [
+      "entityId",
+      "operation",
+      "connectionName",
+      "serviceName",
+      "host",
+      "entity"
+    ],
+    properties: {
+      entityId: schemaRef("entityId"),
+      operation: schemaRef("operation"),
+      connectionName: schemaRef("connectionName"),
+      serviceName: schemaRef("serviceName"),
+      host: schemaRef("host"),
+      entity: schemaRef("entity")
+    }
+  };
+}
+__name(entityIdRequest, "entityIdRequest");
+function getActionOperation(options) {
+  const {
+    action,
+    operation,
+    actionDisplayName,
+    toolName = "",
+    toolInstructions = ""
+  } = options;
+  let description = `Use this tool with action = "${action}" and operation = "${operation}" only. Don't ask these values from user.`;
+  if (operation === "EXECUTE_QUERY") {
+    description += " Use pageSize = 50 and timeout = 120 until user specifies a different value otherwise. If user provides a query in natural language, convert it to SQL query and then execute it using the tool.";
+  }
+  return postOperation({
+    summary: actionDisplayName,
+    description: `${description} ${toolInstructions}`,
+    operationId: `${toolName}_${actionDisplayName}`,
+    requestSchemaRef: `#/components/schemas/${actionDisplayName}_Request`,
+    responseSchema: schemaRef(`${actionDisplayName}_Response`)
+  });
+}
+__name(getActionOperation, "getActionOperation");
+function listOperation(options) {
+  const {
+    entity,
+    schemaAsString = "",
+    toolName = "",
+    toolInstructions = ""
+  } = options;
+  return postOperation({
+    summary: `List ${entity}`,
+    description: `Returns all entities of type ${entity}. Use this tool with entity = "${entity}" and operation = "LIST_ENTITIES" only. Don't ask these values from user. Always use "" as filter clause and "" as page token and 50 as page size until user specifies a different value otherwise. Use single quotes for strings in filter clause. ${toolInstructions}`,
+    operationId: `${toolName}_list_${entity}`,
+    requestSchemaRef: `#/components/schemas/list_${entity}_Request`,
+    responseSchema: {
+      description: `Returns a list of ${entity} of json schema: ${schemaAsString}`,
+      $ref: "#/components/schemas/execute-connector_Response"
+    }
+  });
+}
+__name(listOperation, "listOperation");
+function getOperation(options) {
+  const {
+    entity,
+    schemaAsString = "",
+    toolName = "",
+    toolInstructions = ""
+  } = options;
+  return postOperation({
+    summary: `Get ${entity}`,
+    description: `Returns the details of the ${entity}. Use this tool with entity = "${entity}" and operation = "GET_ENTITY" only. Don't ask these values from user.  ${toolInstructions}`,
+    operationId: `${toolName}_get_${entity}`,
+    requestSchemaRef: `#/components/schemas/get_${entity}_Request`,
+    responseSchema: {
+      description: `Returns ${entity} of json schema: ${schemaAsString}`,
+      $ref: "#/components/schemas/execute-connector_Response"
+    }
+  });
+}
+__name(getOperation, "getOperation");
+function createOperation(options) {
+  const { entity, toolName = "", toolInstructions = "" } = options;
+  return postOperation({
+    summary: `Create ${entity}`,
+    description: `Creates a new entity of type ${entity}. Use this tool with entity = "${entity}" and operation = "CREATE_ENTITY" only. Don't ask these values from user. Follow the schema of the entity provided in the instructions to create ${entity}.  ${toolInstructions}`,
+    operationId: `${toolName}_create_${entity}`,
+    requestSchemaRef: `#/components/schemas/create_${entity}_Request`,
+    responseSchema: schemaRef("execute-connector_Response")
+  });
+}
+__name(createOperation, "createOperation");
+function updateOperation(options) {
+  const { entity, toolName = "", toolInstructions = "" } = options;
+  return postOperation({
+    summary: `Update ${entity}`,
+    description: `Updates an entity of type ${entity}. Use this tool with entity = "${entity}" and operation = "UPDATE_ENTITY" only. Don't ask these values from user. Use entityId to uniquely identify the entity to update. Follow the schema of the entity provided in the instructions to update ${entity}.  ${toolInstructions}`,
+    operationId: `${toolName}_update_${entity}`,
+    requestSchemaRef: `#/components/schemas/update_${entity}_Request`,
+    responseSchema: schemaRef("execute-connector_Response")
+  });
+}
+__name(updateOperation, "updateOperation");
+function deleteOperation(options) {
+  const { entity, toolName = "", toolInstructions = "" } = options;
+  return postOperation({
+    summary: `Delete ${entity}`,
+    description: `Deletes an entity of type ${entity}. Use this tool with entity = "${entity}" and operation = "DELETE_ENTITY" only. Don't ask these values from user.  ${toolInstructions}`,
+    operationId: `${toolName}_delete_${entity}`,
+    requestSchemaRef: `#/components/schemas/delete_${entity}_Request`,
+    responseSchema: schemaRef("execute-connector_Response")
+  });
+}
+__name(deleteOperation, "deleteOperation");
+function createOperationRequest(entity) {
+  return {
+    type: "object",
+    required: [
+      "connectorInputPayload",
+      "operation",
+      "connectionName",
+      "serviceName",
+      "host",
+      "entity"
+    ],
+    properties: {
+      connectorInputPayload: schemaRef(`connectorInputPayload_${entity}`),
+      operation: schemaRef("operation"),
+      connectionName: schemaRef("connectionName"),
+      serviceName: schemaRef("serviceName"),
+      host: schemaRef("host"),
+      entity: schemaRef("entity")
+    }
+  };
+}
+__name(createOperationRequest, "createOperationRequest");
+function updateOperationRequest(entity) {
+  return {
+    type: "object",
+    required: [
+      "connectorInputPayload",
+      "entityId",
+      "operation",
+      "connectionName",
+      "serviceName",
+      "host",
+      "entity"
+    ],
+    properties: {
+      connectorInputPayload: schemaRef(`connectorInputPayload_${entity}`),
+      entityId: schemaRef("entityId"),
+      operation: schemaRef("operation"),
+      connectionName: schemaRef("connectionName"),
+      serviceName: schemaRef("serviceName"),
+      host: schemaRef("host"),
+      entity: schemaRef("entity")
+    }
+  };
+}
+__name(updateOperationRequest, "updateOperationRequest");
+function getOperationRequest() {
+  return entityIdRequest();
+}
+__name(getOperationRequest, "getOperationRequest");
+function deleteOperationRequest() {
+  return entityIdRequest();
+}
+__name(deleteOperationRequest, "deleteOperationRequest");
+function listOperationRequest() {
+  return {
+    type: "object",
+    required: ["operation", "connectionName", "serviceName", "host", "entity"],
+    properties: {
+      filterClause: schemaRef("filterClause"),
+      pageSize: schemaRef("pageSize"),
+      pageToken: schemaRef("pageToken"),
+      operation: schemaRef("operation"),
+      connectionName: schemaRef("connectionName"),
+      serviceName: schemaRef("serviceName"),
+      host: schemaRef("host"),
+      entity: schemaRef("entity")
+    }
+  };
+}
+__name(listOperationRequest, "listOperationRequest");
+function actionRequest(action) {
+  return {
+    type: "object",
+    required: [
+      "operation",
+      "connectionName",
+      "serviceName",
+      "host",
+      "action",
+      "connectorInputPayload"
+    ],
+    properties: {
+      operation: schemaRef("operation"),
+      connectionName: schemaRef("connectionName"),
+      serviceName: schemaRef("serviceName"),
+      host: schemaRef("host"),
+      action: schemaRef("action"),
+      connectorInputPayload: schemaRef(`connectorInputPayload_${action}`)
+    }
+  };
+}
+__name(actionRequest, "actionRequest");
+function actionResponse(action) {
+  return {
+    type: "object",
+    properties: {
+      connectorOutputPayload: schemaRef(`connectorOutputPayload_${action}`)
+    }
+  };
+}
+__name(actionResponse, "actionResponse");
+function executeCustomQueryRequest() {
+  return {
+    type: "object",
+    required: [
+      "operation",
+      "connectionName",
+      "serviceName",
+      "host",
+      "action",
+      "query",
+      "timeout",
+      "pageSize"
+    ],
+    properties: {
+      operation: schemaRef("operation"),
+      connectionName: schemaRef("connectionName"),
+      serviceName: schemaRef("serviceName"),
+      host: schemaRef("host"),
+      action: schemaRef("action"),
+      query: schemaRef("query"),
+      timeout: schemaRef("timeout"),
+      pageSize: schemaRef("pageSize")
+    }
+  };
+}
+__name(executeCustomQueryRequest, "executeCustomQueryRequest");
+let ConnectionsClient = class {
+  constructor(options) {
+    this.project = options.project;
+    this.location = options.location;
+    this.connection = options.connection;
+    this.tokenSource = new CloudPlatformTokenSource(options.serviceAccountJson);
+  }
+  /**
+   * Reads the service name and host of the connection, and whether it allows
+   * an authentication override.
+   */
+  async getConnectionDetails() {
+    const url = `${CONNECTOR_URL}/v1/projects/${this.project}/locations/${this.location}/connections/${this.connection}?view=BASIC`;
+    const connectionData = toJsonObject(await this.executeApiCall(url));
+    const host = toStringValue(connectionData["host"]);
+    const serviceName = host ? toStringValue(connectionData["tlsServiceDirectory"]) : toStringValue(connectionData["serviceDirectory"]);
+    const authOverrideEnabled = connectionData["authOverrideEnabled"] === true;
+    return { serviceName, host, authOverrideEnabled };
+  }
+  /**
+   * Reads the JSON schema of an entity and the operations it supports.
+   *
+   * @param entity The entity name.
+   * @throws Error When the API starts no operation for the entity.
+   */
+  async getEntitySchemaAndOperations(entity) {
+    const url = `${CONNECTOR_URL}/v1/projects/${this.project}/locations/${this.location}/connections/${this.connection}/connectionSchemaMetadata:getEntityType?entityId=${entity}`;
+    const operationId = toStringValue(
+      toJsonObject(await this.executeApiCall(url))["name"]
+    );
+    if (!operationId) {
+      throw new Error(
+        `Failed to get entity schema and operations for entity: ${entity}`
+      );
+    }
+    const response = toJsonObject(
+      (await this.pollOperation(operationId))["response"]
+    );
+    const operations = response["operations"];
+    return {
+      schema: toJsonObject(response["jsonSchema"]),
+      operations: Array.isArray(operations) ? operations.filter((op) => typeof op === "string") : []
+    };
+  }
+  /**
+   * Reads the input and output JSON schemas of an action.
+   *
+   * @param action The action name.
+   * @throws Error When the API starts no operation for the action.
+   */
+  async getActionSchema(action) {
+    const url = `${CONNECTOR_URL}/v1/projects/${this.project}/locations/${this.location}/connections/${this.connection}/connectionSchemaMetadata:getAction?actionId=${action}`;
+    const operationId = toStringValue(
+      toJsonObject(await this.executeApiCall(url))["name"]
+    );
+    if (!operationId) {
+      throw new Error(`Failed to get action schema for action: ${action}`);
+    }
+    const response = toJsonObject(
+      (await this.pollOperation(operationId))["response"]
+    );
+    return {
+      inputSchema: toJsonObject(response["inputJsonSchema"]),
+      outputSchema: toJsonObject(response["outputJsonSchema"]),
+      description: toStringValue(response["description"]),
+      displayName: toStringValue(response["displayName"])
+    };
+  }
+  /**
+   * Converts the JSON schema of an entity or an action payload into the
+   * OpenAPI schema the connector spec carries.
+   */
+  connectorPayload(jsonSchema) {
+    return connectorPayload(jsonSchema);
+  }
+  executeApiCall(url) {
+    return sendCloudRequest({
+      url,
+      method: "GET",
+      tokenSource: this.tokenSource,
+      invalidRequestMessage: `Invalid request. Please check the provided values of project(${this.project}), location(${this.location}), connection(${this.connection}).`
+    });
+  }
+  /** Polls a long-running operation until it reports `done`. */
+  async pollOperation(operationId) {
+    const url = `${CONNECTOR_URL}/v1/${operationId}`;
+    let operation = toJsonObject(await this.executeApiCall(url));
+    while (operation["done"] !== true) {
+      await sleep(OPERATION_POLL_INTERVAL_MS);
+      operation = toJsonObject(await this.executeApiCall(url));
+    }
+    return operation;
+  }
+};
+__name(ConnectionsClient, "ConnectionsClient");
+ConnectionsClient = __decorateClass([
+  experimental
+], ConnectionsClient);
+export {
+  CONNECTOR_BASE_SPEC,
+  ConnectionsClient,
+  actionRequest,
+  actionResponse,
+  connectorPayload,
+  createOperation,
+  createOperationRequest,
+  deleteOperation,
+  deleteOperationRequest,
+  executeCustomQueryRequest,
+  getActionOperation,
+  getOperation,
+  getOperationRequest,
+  listOperation,
+  listOperationRequest,
+  updateOperation,
+  updateOperationRequest
+};