{"id":28372989,"url":"https://github.com/googleworkspace/gws-genai-addon-sample","last_synced_at":"2025-06-25T12:31:18.133Z","repository":{"id":190727651,"uuid":"678988627","full_name":"googleworkspace/gws-genai-addon-sample","owner":"googleworkspace","description":"A sample Google Workspace add-on for Gmail and Google Drive using Node.js and demonstrating how to use various Generative AI APIs","archived":false,"fork":false,"pushed_at":"2024-12-19T02:09:20.000Z","size":638,"stargazers_count":27,"open_issues_count":4,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-29T18:57:41.125Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googleworkspace.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-15T21:18:43.000Z","updated_at":"2025-04-29T12:57:28.000Z","dependencies_parsed_at":"2023-08-26T04:39:46.992Z","dependency_job_id":"491eb926-e4a8-4d50-9362-a20d820067f1","html_url":"https://github.com/googleworkspace/gws-genai-addon-sample","commit_stats":null,"previous_names":["googleworkspace/gws-genai-addon-sample"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/googleworkspace/gws-genai-addon-sample","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgws-genai-addon-sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgws-genai-addon-sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgws-genai-addon-sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgws-genai-addon-sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googleworkspace","download_url":"https://codeload.github.com/googleworkspace/gws-genai-addon-sample/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgws-genai-addon-sample/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261874333,"owners_count":23223097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-29T18:38:41.746Z","updated_at":"2025-06-25T12:31:18.124Z","avatar_url":"https://github.com/googleworkspace.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gws-genai-addon-sample\n\nA sample Google Workspace add-on for Google Drive and Gmail using Node.js and demonstrating how to use various Generative AI APIs.\n\nHere is a diagram that shows the different components in this sample solution:\n\n```mermaid\nflowchart LR\n    A[Google Workspace Add-on\\nfor Google Drive and Gmail]\u003c--\u003eB[Backend hosted on\\nGoogle Cloud Run]\n    B--\u003eC[Google Drive APIs]\n    B--\u003eD[Generative AI APIs\\ne.g. Google Cloud Vertex AI APIs]\n```\n\n## Setup\n\n### Prerequisites\n\n- [A Google Cloud Project](https://developers.google.com/workspace/guides/create-project).\n- Make sure that you turn on billing for your Cloud project. Learn how to [verify the billing status of your projects](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled).\n- The [Cloud SDK](https://cloud.google.com/sdk/docs/install-sdk) configured with the Cloud project. You can skip this step if using Cloud Shell.\n\n### Setup your environment\n\nFollows the steps in [this guide](https://developers.google.com/workspace/add-ons/quickstart/alternate-runtimes#set-environment) to setup your environment before proceeding with the next steps. \n\nOnce completed, you can use the `gcloud` command (for example in Cloud Shell) to proceed.\n\n### Authenticate\n\nRun the following command and note the `ACCOUNT` value that is provided.\n\n```sh\ngcloud auth list\n```\n\n### Set active account\n\nSet active account using the account provided in the previous step.\n\n```sh\ngcloud config set account \u003cACCOUNT\u003e\n```\n\n### Set active project\n\nSet the project ID to the project you are using.\n\n```sh\ngcloud config set project \u003cPROJECT_ID\u003e\n```\n\n### Enable Cloud APIs\n\n```sh\ngcloud services enable \\\n  appsmarket-component.googleapis.com \\\n  artifactregistry.googleapis.com \\\n  cloudbuild.googleapis.com \\\n  cloudresourcemanager.googleapis.com \\\n  drive.googleapis.com \\\n  gmail.googleapis.com \\\n  gsuiteaddons.googleapis.com \\\n  run.googleapis.com\n```\n\n## Deploy backend to Cloud Run\n\nWe will deploy the backend that handles requests from the add-on to Cloud Run.\n\n### Make a local copy of the repository\n\nFor the next steps you need a local copy of the source code in this repository. \n\nYou can either use `git clone` to [clone the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository), or [download a copy](https://docs.github.com/en/repositories/working-with-files/using-files/downloading-source-code-archives#downloading-source-code-archives-from-the-repository-view) from the repository view page.\n\n\u003e NOTE: Before continuing with the next step, make sure to change into the directory containing your local copy of the repository.\n\n### Prepare configuration file\n\nMake a copy of the `config/default-template.json` file in the `config` folder and name it `default.json`. \n\nThis file will be used later for configuring the add-on code. You will first deploy the code with the basic template configuration, and once you retrieve the deployment URL you will configure the add-on and deploy the code again.\n\n### Grant Cloud Build permission to deploy\n\n```sh\nPROJECT_ID=$(gcloud config list --format='value(core.project)')\nPROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')\ngcloud projects add-iam-policy-binding $PROJECT_ID \\\n    --member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \\\n    --role=roles/run.admin\ngcloud iam service-accounts add-iam-policy-binding \\\n    $PROJECT_NUMBER-compute@developer.gserviceaccount.com \\\n    --member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \\\n    --role=roles/iam.serviceAccountUser\n```\n\n### Start the build\n\n```sh\ngcloud builds submit\n```\n\n### Verify service is deployed\n\n```sh\ngcloud run services list --platform managed\n```\n\nNote the `URL` value in the response, as this will be your deployment URL to be used later in configuring the add-on.\n\n## Configure the add-on backend\n\nThe configuration below should be made inside the `config/default.json` file that is deployed with the code. \n\n### Security\n\n#### Service Account Email\n\nWe verify all requests that hits the endpoints are coming from the add-on. We do this by comparing the service account email in the request against the configured value in `serviceAccountEmail` under the `addOnConfig` section.\n\nTo get your service account email for the add-on, follow the steps [here](https://developers.google.com/workspace/add-ons/guides/alternate-runtimes#validate-requests-from-google) or run the following command:\n\n```sh\ngcloud workspace-add-ons get-authorization\n```\n\n#### OAuth Client ID\n\nWe verify the user ID token and extract their profile name. In order to do that, we need the OAuth client ID for the add-on.\n\nTo get the client ID, follow the steps [here](https://developers.google.com/workspace/add-ons/guides/alternate-runtimes#get_the_client_id) and then add the value to the `oauthClientId` variable in the `addOnConfig` section.\n\n### Function URLs\n\nConfigure all the variables under `urls` in the `addOnConfig` section to point to the correct endpoints.\n\nUpdate the `\u003cDEPLOYMENT_URL\u003e` variable with the deployment URL you retrieved when you deployed your Cloud Run service.\n\nFor example, if you deployed your code to `http://www.mydeployment.com/` then the value of `generateReplyUrl` will be `https://www.mydeployment.com/generateReplyUrl`\n\nThese function URLs are used for interactions between cards in the add-on.\n\n### GenAI Providers\n\nThis add-on can be used with the list of providers below. For each provider, you can configure the `enabled` flag to show in the add-on, and any applicable configuration (i.e. API key) for that provider.\n\nMake sure to set the `defaultProvider` variable to an enabled provider that you want to be selected by default.\n\n#### Google Cloud Vertex AI Gemini API\n\nThe add-on can use [Google Cloud Vertex AI Gemini API](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/overview#gemini-api) to generate and summarize text.\n\nTo use this provider, you first need to enable the service in your Google Cloud project.\n\n```sh\ngcloud services enable aiplatform.googleapis.com\n```\n\nThe code uses the service account attached to the Cloud Run deployment to generate access tokens to use the Vertex AI Gemini API. This service account by default is the  the [default Comptue Engine service account](https://cloud.google.com/compute/docs/access/service-accounts#default_service_account).\n\nYou need to grant this service account the following role in order to access the Vertex AI APIs:\n\n`Vertex AI User (roles/aiplatform.user)`\n\nYou can either do this via the [Google Cloud Console](https://cloud.google.com/iam/docs/grant-role-console), or by using the following command (make sure to update `PROJECT_NUMBER` and `PROJECT_ID` with the relevant values for your project):\n\n```sh\ngcloud projects add-iam-policy-binding PROJECT_ID \\\n      --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \\\n      --role='roles/aiplatform.user'\n```\n\u003e Learn more on service account best practices and other ways to authenticate  [here](https://cloud.google.com/iam/docs/best-practices-service-accounts). \n\nYou should configure the following parameters in the relevant section for `vertexGeminiProTextApi` in the add-on configuration file:\n\n- `project`: The Google Cloud project ID where the add-on code will run.\n- `region`: The region used for the Gemini API  (default is `us-central1`). Make sure the value corresponds to one of the [available regions for Gemini API](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini#http_request).\n\nAdditional provider configurations are available in the `modules/gen_ai_providers/vertex_ai_gemini_pro_text_api.js` file, including the model used, maximum tokens returned, and other configuration.\n\n##### Terms of Use \u0026 Privacy Policy\n\n\u003e Vertex AI Gemini API is a Preview offering, subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section of the [Service Specific Terms](https://cloud.google.com/terms/service-terms). Pre-GA products and features are available \"as is\" and might have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the [launch stage descriptions](https://cloud.google.com/products#product-launch-stages). Further, by using Vertex AI Gemini API, you agree to the [Additional Terms](https://cloud.google.com/trustedtester/aitos) for Generative AI Preview Products.\n\nCheck Google Cloud's [Terms](https://cloud.google.com/product-terms#section-3) for more information on how your data is processed.\n\n#### Google Cloud Vertex AI PaLM API\n\nThe add-on can use [Google Cloud Vertex AI PaLM API](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/overview#palm-api) to generate and summarize text. \n\nTo use this provider, you first need to enable the service in your Google Cloud project.\n\n```sh\ngcloud services enable aiplatform.googleapis.com\n```\n\nThe code uses the service account attached to the Cloud Run deployment to generate access tokens to use the Vertex AI PaLM APIs. This service account by default is the [default Comptue Engine service account](https://cloud.google.com/compute/docs/access/service-accounts#default_service_account).\n\nYou need to grant this service account the following role in order to access the Vertex AI APIs:\n\n`Vertex AI User (roles/aiplatform.user)`\n\nYou can either do this via the [Google Cloud Console](https://cloud.google.com/iam/docs/grant-role-console), or by using the following command (make sure to update `PROJECT_NUMBER` and `PROJECT_ID` with the relevant values for your project):\n\n```sh\ngcloud projects add-iam-policy-binding PROJECT_ID \\\n      --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \\\n      --role='roles/aiplatform.user'\n```\n\u003e Learn more on service account best practices and other ways to authenticate  [here](https://cloud.google.com/iam/docs/best-practices-service-accounts). \n\nYou can configure the region for the API in the `region` parameter (default is `us-central1`) in the relevant section for `vertexAiPalmApi` in the add-on configuration file. Please make sure the value you select corresponds to one of the Vertex AI service endpoint listed [here](https://cloud.google.com/vertex-ai/docs/reference/rest#service-endpoint).\n\nAdditional configurations for the provider are found in the `modules/gen_ai_providers/vertex_ai_palm_api.js` file, including the models used, maximum tokens returned, and other configuration.\n\n##### Terms of Use \u0026 Privacy Policy\n\nPlease check Google Cloud's [Terms](https://cloud.google.com/product-terms#section-3) for more information on how your data is processed.\n\n#### Google AI Gemini API\n\nThe add-on can use [Google AI Gemini API](https://ai.google.dev/docs/gemini_api_overview) to generate and summarize text.\n\n\u003e Check the list of [available languages and regions for Google AI Studio and Gemini API](https://ai.google.dev/available_regions) to confirm that Gemini API is available in your region before you continue with the next step.\n\nTo use this provider, you need to [create an API key in Google AI Studio](https://makersuite.google.com/) and save it in the `apiKey` parameter in the relevant section for `geminiApi` in the add-on configuration file. Additional configurations for the provider are found in the `modules/gen_ai_providers/gemini_api.js` file, including the model used, maximum tokens returned, and other configuration.\n\n##### Terms of Use \u0026 Privacy Policy\n\n\u003e The Gemini API is currently in public preview. Production applications are not supported yet. \n\nPlease check Google's [Terms of Use](https://policies.google.com/terms), [Privacy Policy](https://policies.google.com/privacy) for more information on how your data is processed.\n\n#### Cohere.ai\n\nThe add-on can also use [Cohere.ai](https://www.cohere.ai). To setup this provider, login to your Cohere.ai account and generate an API key, then you can save it in the `apiKey` parameter in the add-on configuration file.\n\nPlease note that we use the specialized summarization endpoint for the sumamrization feature.\n\nAdditional configurations for the provider are found in the `modules/gen_ai_providers/cohere.js` file, including the models used, maximum tokens returned, and other configuration.\n\n##### Terms of Use \u0026 Privacy Policy\n\nPlease check Cohere.ai's [Terms of Use](https://cohere.com/terms-of-use), [Privacy Policy](https://cohere.com/privacy) and [Data Usage Policy](https://cohere.com/data-usage-policy) for more information on how your data is processed.\n\n### Redeploy the code\n\nOnce you have finished configuring the code, you must redeploy the Cloud Run service again.\n\nTo do so, run the following command:\n\nYou will have to redeploy your code once you've made the changes to the file using the following command:\n\n```sh\ngcloud builds submit\n```\n\nOnce the service is deployed, you can use the add-on.\n\n## Register the Google Workspace Add-on\n\n### Prepare the deployment descriptor\n\nMake a copy of the `sample_deployment_file/deployment.json` in the main directory, and then edit the file to replace\nthe `\u003cDEPLOYMENT_URL\u003e` variables with the deployment URL for the Cloud Run service above.\n\n### Upload the deployment descriptor\n\n```sh\ngcloud workspace-add-ons deployments create genai-gmail-companion --deployment-file=deployment.json\n```\n\n### Authorize access to the add-on backend\n\n```sh\nSERVICE_ACCOUNT_EMAIL=$(gcloud workspace-add-ons get-authorization --format=\"value(serviceAccountEmail)\")\n\ngcloud run services add-iam-policy-binding \\\n    genai-gmail-companion \\\n    --member=serviceAccount:$SERVICE_ACCOUNT_EMAIL \\\n    --role=roles/run.invoker \\\n    --region=us-west1 \\\n    --platform=managed\n```\n\n### Install the add-on\n\n```sh\ngcloud workspace-add-ons deployments install genai-gmail-companion\n```\n\n### To replace deployment.json\n\nIf you later make any changes to the deployment descriptor `deployment.json` file (i.e. update logo, name of the add-on, supported integrations), use the following command to update the add-on:\n\n```sh\ngcloud workspace-add-ons deployments replace genai-gmail-companion --deployment-file=deployment.json\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleworkspace%2Fgws-genai-addon-sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogleworkspace%2Fgws-genai-addon-sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleworkspace%2Fgws-genai-addon-sample/lists"}