@jskit-ai/connector-google-calendar 0.1.1

package/README.md

@@ -0,0 +1,34 @@
+# Google Calendar
+
+Import `googleCalendarDefinition` from `@jskit-ai/connector-google-calendar/shared`
+for configuration and UI. Import `googleCalendarProvider` from
+`@jskit-ai/connector-google-calendar/server` in server code.
+
+The initial operations are `calendars.list` and `events.list`. Both return the
+provider's page, including `nextPageToken`; callers decide whether and when to
+fetch another page. Event lists accept `calendarId` (default `primary`),
+`pageToken`, `maxResults`, `timeMin` and `timeMax`. They expand recurring events
+and order by start time. Writes are available through `events.create`, `events.update` (PATCH) and `events.cancel`; `events.get` retrieves one event and its ETag. See the setup guide for inputs, scopes and attendee effects.
+
+The recommended scopes are `calendar.calendarlist.readonly` and
+`calendar.events.readonly`, both under `https://www.googleapis.com/auth/`.
+Connection verification lists calendars, so retain a permission accepted by
+`calendars.list`. Additional Calendar scopes are represented in metadata for
+application-authored operations; selecting them does not implement those
+operations. Calendar add-on scopes also require a Calendar add-on host.
+
+Account ownership modes are shared, per app user, and assistant. The
+application's authorization policy determines who can use each connection.
+This package does not replace the application's login or user identity system.
+
+Start with [provider setup](docs/setup.md) and the
+[app-owned CLI pattern](patterns/calendar-cli/PATTERN.md).
+
+## Verification state
+
+Simulated Google responses verify request construction, grants, token exchange,
+refresh and failures through the shared runtime tests. No Google account has
+been connected during implementation. Live consent, Workspace administrator
+restrictions and production verification remain open. Each application owns its
+registration, callback and runtime grants; no shared editor gateway is required.
+Configuration and UI metadata are not claims of live provider approval.

package/docs/setup.md

@@ -0,0 +1,144 @@
+# Register Google Calendar access
+
+Checked against Google's documentation on 2026-09-08. Portal labels and provider
+requirements can change; the links below are the source for those details.
+
+## Own registration
+
+1. Open [Google Cloud Console](https://console.cloud.google.com/). Select the
+   target project, or use the project selector's **New Project** action. Choose
+   your organization/location when required.
+2. Open **APIs & Services → Library**, find **Google Calendar API**, then enable
+   it for that project. [API enablement](https://developers.google.com/workspace/guides/enable-apis).
+3. Open **Google Auth platform → Branding**. On a new project, choose **Get
+   Started**. Enter the app name and support email; choose the audience, provide
+   the contact email, review the terms and create the configuration.
+4. Use **Audience** to add your test accounts for an external app in testing.
+   Use **Data Access → Add or Remove Scopes** to select the two recommended
+   read permissions listed in this package's README. Complete branding/domain
+   information required for your intended audience.
+   [Consent configuration](https://developers.google.com/workspace/guides/configure-oauth-consent).
+5. Open **Google Auth platform → Clients → Create Client**. Choose **Web
+   application**, name it, and add the exact backend callback under
+   **Authorized redirect URIs**. For the CLI example use
+   `http://127.0.0.1:8080/integrations/google/callback`. Create the client.
+   [Client creation](https://developers.google.com/workspace/guides/create-credentials).
+6. Put its client ID into `registrations.google.clientId`. Store the client
+   secret on the server as `GOOGLE_CLIENT_SECRET`, and set
+   `GOOGLE_CALLBACK_URL` to the exact registered callback. Keep only the
+   `env:` references in `integrations.json`. The server-side authorization
+   code flow uses the secret during exchange; browser code must not receive
+   it. [Web-server OAuth](https://developers.google.com/identity/protocols/oauth2/web-server).
+7. Run the application and connect a test account. Verify calendar listing,
+   event listing and reconnect behavior. Before public use, complete Google's
+   applicable publishing/verification requirements; a test connection does
+   not establish production approval.
+
+## Application and environment ownership
+
+The application owns its registration, client secret and callback. Hosted and
+installed editors configure the same application-owned fields; neither supplies
+a shared Google client or gateway. Use `source: "own"` and keep secret values in
+the application's environment. See the
+[callback guide](../../connectors-core/docs/oauth-callbacks.md) for callback
+routes, domain changes and preserving runtime state when moving the app.
+
+The chosen Google Cloud project owns Calendar project quotas. Two OAuth clients
+inside one project do not isolate those quotas. Google also applies other limits;
+check the actual project's [Calendar usage limits](https://developers.google.com/workspace/calendar/api/guides/quota).
+Changing the client requires fresh consent; do not move grants between clients.
+
+## What an AI can automate
+
+| Work | Automation assessment |
+|---|---|
+| Create the application's Cloud project | Resource Manager has `projects.create`; requires an authenticated operator with the required parent permissions. [API](https://docs.cloud.google.com/resource-manager/reference/rest/v3/projects/create). |
+| Enable Calendar API | Service Usage has `services.enable`; use `calendar-json.googleapis.com` and operator authority for the project. [API](https://docs.cloud.google.com/service-usage/docs/reference/rest/v1/services/enable). |
+| Create a general Calendar OAuth web client, configure branding and consent | This packet does not establish a supported public API for all those steps. Use the console instructions; do not substitute IAP-specific client creation or service-account credentials. |
+| Write configuration and app wiring | Fully scriptable using this package, ordinary files and the application's secret bindings. |
+| Grant mailbox/calendar access | The account owner completes provider consent; an agent cannot manufacture that grant. |
+| Verification, organization consent and quota approval | Human/provider decisions remain necessary where Google requires them. An agent can prepare configuration and evidence. |
+
+## Field ownership
+
+| Input or display | Owner/destination |
+|---|---|
+| Integration display name | `integrations.<slot>.displayName` |
+| Shared account / each user / assistant | `integrations.<slot>.accountMode`; server policy enforces ownership |
+| Selected scopes | `integrations.<slot>.scopes`; actual grants live in encrypted connection state |
+| Client ID | `registrations.<id>.clientId` |
+| Client secret | Server secret storage; source contains `clientSecretRef` |
+| Callback URL | Server environment; source contains `callbackUrlRef`; UI may display its resolved value |
+| People allowed to use a connection or client | Application permission records; not a provider OAuth scope and not a grant created by editing source |
+| Connected account, verification time, reconnect status | Runtime metadata after successful provider verification |
+
+See Google's [complete scope list](https://developers.google.com/workspace/calendar/api/auth)
+for permission meanings. The shared form carries every documented Calendar
+scope, including scopes for advanced operations that this initial fragment does
+not implement.
+
+## Event operations and framework wiring
+
+For writes select **Manage events** (`calendar.events`) alongside **List
+calendars**, add the scope to Google Data Access, and reconnect. A saved scope
+change does not upgrade an existing grant. The connected account must also have
+write access to the selected calendar; Google enforces organizer/guest rules.
+
+Use the existing connection service in a JSKIT backend or CLI:
+
+```js
+await connections.invoke({ context, integrationId: "calendar",
+  operation: "events.create", input: {
+    calendarId: "primary", sendUpdates: "all",
+    event: { summary: "Grooming appointment",
+      start: { dateTime: "2026-10-05T09:00:00+08:00", timeZone: "Australia/Perth" },
+      end: { dateTime: "2026-10-05T10:00:00+08:00", timeZone: "Australia/Perth" },
+      attendees: [{ email: "customer@example.com" }] }
+  } });
+```
+
+Other frameworks use the same project configuration/Env and their native Google
+Calendar client or HTTP transport. Vibe64 stores configuration, not events.
+The application authorizes the caller and chooses a connection, calendar and
+notification policy. It owns appointment screens, scheduling and conflict rules.
+
+- `calendars.list` exposes calendar IDs and access roles. `primary` means the
+  connected person's primary calendar, not a global application calendar.
+- `events.list` returns expanded occurrences with `nextPageToken`; use its
+  instance ID for a one-occurrence change. `events.get` accepts `calendarId`
+  and `eventId` and returns the provider event, including ETag and recurrence.
+- `events.create`: `calendarId`, explicit `sendUpdates`, and `event`. The event
+  requires start/end. Supported fields are summary, description, location,
+  start/end, recurrence, attendees, transparency and visibility.
+- `events.update`: same target plus `eventId`, a partial `event`, explicit
+  `sendUpdates`, and optional `ifMatch` from the latest ETag. Fetch current data
+  first. PATCH replaces whole attendee/recurrence arrays, not individual entries.
+  Supply both start/end when changing time; setting nonempty recurrence also
+  requires both. Google's 412 means refetch and review the concurrent edit.
+- `events.cancel`: calendar/event IDs, explicit `sendUpdates`, optional `ifMatch`.
+  Successful deletion returns null. Cancelling the master affects the series;
+  an instance ID affects that occurrence. Application confirmation is required
+  before choosing a cancellation target.
+- `sendUpdates` is **all**, **externalOnly** or **none**. The adapter requires an
+  explicit choice. Google warns that none can prevent external-calendar sync;
+  it is not a promise that Google sends no email. Review attendee effects before
+  writing. The adapter does not silently retry an uncertain write: reconcile
+  against the calendar before repeating an appointment creation.
+- All-day events use `{date: "2026-10-05"}` and an **exclusive** end date (the next
+  day for a one-day event). Timed events require explicit offsets; recurring
+  timed events additionally require IANA timeZone on both ends so Google can
+  expand local times across daylight-saving changes. Recurrence is RFC5545
+  RRULE/RDATE/EXRULE/EXDATE text; the provider validates rule semantics.
+- Display description HTML safely. Do not assume event invitation, consent or
+  notification delivery merely because an API response succeeded.
+
+**Limitations:** no calendar/ACL administration, free/busy scheduling engine,
+Meet creation, attachments, special event types, watch/history synchronization,
+or recurring “this and following” series splitting. For example, an app can
+create a weekly appointment and cancel one occurrence, but a booking conflict
+solver or automatic rescheduler remains app code. Editor assistant attachment
+is deferred. Fixtures do not prove live notifications or Google approval.
+
+References: [insert](https://developers.google.com/workspace/calendar/api/v3/reference/events/insert),
+[patch](https://developers.google.com/workspace/calendar/api/v3/reference/events/patch),
+[delete](https://developers.google.com/workspace/calendar/api/v3/reference/events/delete).

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@jskit-ai/connector-google-calendar",
+  "version": "0.1.1",
+  "description": "Google Calendar account configuration and event operations for JSKIT connectors.",
+  "type": "module",
+  "scripts": {
+    "test": "node --test --test-concurrency=1"
+  },
+  "exports": {
+    "./shared": "./src/shared/definition.js",
+    "./server": "./src/server/provider.js"
+  },
+  "dependencies": {
+    "@jskit-ai/connectors-core": "0.1.1",
+    "json-rest-schema": "^1.0.17"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [],
+      "requires": []
+    },
+    "runtime": {
+      "server": {
+        "providers": []
+      },
+      "client": {
+        "providers": []
+      }
+    }
+  },
+  "peerDependencies": {
+    "@jskit-ai/kernel": "0.1.184"
+  }
+}

package/patterns/calendar-cli/PATTERN.md

@@ -0,0 +1,106 @@
+---
+id: connectors/calendar-cli
+title: Google Calendar from an application-owned CLI
+summary: Compose reusable connection libraries with portable configuration, application ownership and durable storage.
+keywords: connectors, integrations, google, calendar, oauth, cli, permissions
+requires: @jskit-ai/connectors-core, @jskit-ai/connector-google-calendar, @jskit-ai/database-runtime-mysql
+---
+
+# Google Calendar from an application-owned CLI
+
+## Use when
+
+Use this pattern for a local operator command that connects an account and reads
+Calendar pages. The example deliberately selects MySQL/MariaDB. A web app should
+use its existing selected database client and authenticated callback routes.
+
+## Do not use when
+
+Do not use the local operator identity or loopback listener as a public web
+application's authentication. Do not use this example for managed gateway
+registrations, native public OAuth clients or service accounts.
+
+## Product decisions
+
+Adapt the example's `integrations.json`, environment bindings, command names,
+ownership policy and output handling. Install its dependencies with ordinary
+`npm install`; no JSKIT CLI, generator or template installation is involved.
+The example's loopback HTTP callback is local command wiring. OAuth exchange,
+PKCE, state checks, refresh, provider requests, encryption and storage remain
+imports from the libraries.
+
+The example trusts the local process owner. `CONNECTOR_APPLICATION_ID` and
+`CONNECTOR_SUBJECT_ID` identify its persistent connection. Do not copy that
+environment-based identity policy into an HTTP API: derive its owner from the
+authenticated user and check membership/operation permissions there.
+
+## Invariants
+
+- One configuration file is read by CLI and UI.
+- Credential values and connection grants stay outside source.
+- The application authorizes owners and executes package-owned migrations.
+- OAuth and persistence machinery is imported from the library.
+- Provider consent and a successful account check precede Connected.
+
+## Framework APIs
+
+The script imports `parseIntegrationConfiguration`, `createConnectionService`,
+`createEnvironmentReferenceResolver`, `createCredentialProtection`,
+`createKnexConnectionStore` and `googleCalendarProvider`. `knexfile.js` uses
+`createKnexMigrationConfigFromApp` with the selected MySQL dialect.
+
+## Example files
+
+`example/integrations.json` is portable source. `example/.env.example` lists
+private runtime bindings. `example/scripts/calendar.js` owns command parsing
+and local callback wiring. `example/package.json` and `example/knexfile.js`
+provide ordinary npm and migration operations.
+
+## Verification
+
+1. Follow the package's provider setup guide. Register the exact loopback URL
+   from `.env.example` on your own Google OAuth web client.
+2. Adapt `example/package.json`, `knexfile.js`, `integrations.json` and
+   `scripts/calendar.js` into your application. Make `.env` from `.env.example`,
+   supply database and provider credentials, and exclude it from Git. Create
+   the application's migration directories with `mkdir -p migrations/constraints`.
+3. Generate a private storage key with
+   `node -e 'console.log(require("node:crypto").randomBytes(32).toString("base64"))'`.
+   Save it as `CONNECTOR_STORAGE_KEY`. Preserve it across restarts and backups.
+4. Run `npm install`, then `npm run db:migrate` against your application's
+   database. Package migrations are discovered directly; do not copy them.
+5. Run `npm run calendar -- validate`. This needs no database or provider
+   credentials and uses exactly the validator used by the UI.
+6. Run `npm run calendar -- connect`, open the displayed URL in your normal
+   browser and approve the account permissions. A local callback completes the
+   command. Ctrl-C cancels the pending attempt.
+7. Run `npm run calendar -- calendars`, then
+   `npm run calendar -- events '{"calendarId":"primary","maxResults":10}'`.
+   The output includes the provider's next-page token when present.
+8. Restart the process and run `npm run calendar -- status`. Run
+   `npm run calendar -- disconnect` to remove this application's local grant.
+
+For command output, apply your application's privacy requirements before
+retaining or sharing calendar data. The example prints operation results, not
+credentials.
+
+## Variation points
+
+Use `createConnectorsFeature()` with the ordinary JSKIT action runtime, or call
+`createConnectionService()` from an existing Feature. Keep business operations
+named, such as `calendar.events.list`. Use the app's authenticated context in
+the authorization policy. A web callback recovers the initiating owner's
+context and passes the full registered callback URL to `completeAuthorization`.
+
+Use `IntegrationConfigurationFields` from `@jskit-ai/connectors-web/client` for
+the form. The parent uses the normal resource/add-edit seam to save the same
+file, detect concurrent edits and expose the existing secret-entry control.
+Saving configuration and connecting an account are different operations.
+
+## Avoid
+
+The source pattern is validated locally; live Google consent still requires
+your credentials and account approval. The initial runtime implements own web
+client registrations. The editor configures the generated application's own registration. Its backend
+resolves the secret from the application environment; never ship a client secret
+inside a desktop binary or browser bundle.

package/patterns/calendar-cli/example/.env.example

@@ -0,0 +1,6 @@
+DATABASE_URL=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_CALLBACK_URL=http://127.0.0.1:8080/integrations/google/callback
+CONNECTOR_STORAGE_KEY=
+CONNECTOR_APPLICATION_ID=calendar-example-development
+CONNECTOR_SUBJECT_ID=local-operator

package/patterns/calendar-cli/example/integrations.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "integrations": {
+    "calendar": {
+      "provider": "google-calendar",
+      "displayName": "My calendar",
+      "accountMode": "per-user",
+      "scopes": [
+        "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+        "https://www.googleapis.com/auth/calendar.events.readonly"
+      ],
+      "authentication": { "method": "oauth2", "registrationRef": "google" }
+    }
+  },
+  "registrations": {
+    "google": {
+      "source": "own",
+      "clientId": "YOUR_GOOGLE_CLIENT_ID",
+      "clientSecretRef": "env:GOOGLE_CLIENT_SECRET",
+      "callbackUrlRef": "env:GOOGLE_CALLBACK_URL"
+    }
+  }
+}

package/patterns/calendar-cli/example/knexfile.js

@@ -0,0 +1,5 @@
+import { existsSync } from "node:fs";
+import { createKnexMigrationConfigFromApp } from "@jskit-ai/database-runtime/server/knexMigrationConfig";
+
+if (existsSync(".env")) process.loadEnvFile(".env");
+export default await createKnexMigrationConfigFromApp({ client: "mysql2" });

package/patterns/calendar-cli/example/package.json

@@ -0,0 +1,16 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "calendar": "node --env-file-if-exists=.env scripts/calendar.js",
+    "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+  },
+  "dependencies": {
+    "@jskit-ai/connectors-core": "0.1.1",
+    "@jskit-ai/connector-google-calendar": "0.1.1",
+    "@jskit-ai/database-runtime": "0.1.184",
+    "@jskit-ai/database-runtime-mysql": "0.1.182",
+    "knex": "^3.1.0"
+  }
+}

package/patterns/calendar-cli/example/scripts/calendar.js

@@ -0,0 +1,102 @@
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { once } from "node:events";
+import createKnex from "knex";
+import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
+import { createConnectionService, createEnvironmentReferenceResolver } from "@jskit-ai/connectors-core/server";
+import { createCredentialProtection, createKnexConnectionStore } from "@jskit-ai/connectors-core/server/storage";
+import { googleCalendarProvider } from "@jskit-ai/connector-google-calendar/server";
+
+// A local operator command owns this HTTP listener; web apps use authenticated routes.
+async function connectInBrowser(service, context) {
+  const callback = new URL(process.env.GOOGLE_CALLBACK_URL);
+  if (callback.protocol !== "http:" || callback.hostname !== "127.0.0.1" || !callback.port) {
+    throw new Error("This CLI requires a registered http://127.0.0.1:PORT callback.");
+  }
+  let state;
+  let finish;
+  let fail;
+  let completed = false;
+  const controller = new AbortController();
+  const finished = new Promise((resolve, reject) => { finish = resolve; fail = reject; });
+  const outcome = finished.then((result) => ({ result }), (error) => ({ error }));
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, callback.origin);
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("Cache-Control", "no-store");
+    if (request.method !== "GET" || url.pathname !== callback.pathname || !state || url.searchParams.get("state") !== state) {
+      response.writeHead(400).end("This is not the pending authorization callback.");
+      return;
+    }
+    try {
+      const result = await service.completeAuthorization({ context, integrationId: "calendar", callbackUrl: url.href, signal: controller.signal });
+      completed = true;
+      response.end("Connected. You can close this window.");
+      finish(result);
+    } catch (error) {
+      response.writeHead(400).end("Connection failed. Return to the terminal.");
+      fail(error);
+    }
+  });
+  server.listen(Number(callback.port), "127.0.0.1");
+  await once(server, "listening");
+  const cancel = () => { controller.abort(); fail(new Error("Authorization cancelled.")); };
+  process.once("SIGINT", cancel);
+  const timeout = setTimeout(cancel, 10 * 60 * 1000);
+  try {
+    const start = await service.beginAuthorization({ context, integrationId: "calendar", signal: controller.signal });
+    state = new URL(start.authorizationUrl).searchParams.get("state");
+    console.log(`Open this URL in your browser:\n${start.authorizationUrl}`);
+    const completed = await outcome;
+    if (completed.error) throw completed.error;
+    return completed.result;
+  } finally {
+    clearTimeout(timeout);
+    process.off("SIGINT", cancel);
+    try {
+      if (state && !completed) await service.cancelAuthorization({ context, integrationId: "calendar", state });
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  }
+}
+
+async function main() {
+  const command = process.argv[2] || "validate";
+  const configuration = parseIntegrationConfiguration(await readFile("integrations.json", "utf8"), { providers: [googleCalendarProvider] });
+  if (command === "validate") {
+    console.log("Integration configuration is valid.");
+    return;
+  }
+  if (!["connect", "status", "calendars", "events", "disconnect"].includes(command)) {
+    throw new Error("Use validate, connect, status, calendars, events or disconnect.");
+  }
+  for (const name of ["DATABASE_URL", "CONNECTOR_STORAGE_KEY", "CONNECTOR_APPLICATION_ID", "CONNECTOR_SUBJECT_ID"]) {
+    if (!process.env[name]) throw new Error(`Set ${name} before using connections.`);
+  }
+  const context = { applicationId: process.env.CONNECTOR_APPLICATION_ID, subjectId: process.env.CONNECTOR_SUBJECT_ID };
+  const protection = createCredentialProtection({ keys: { current: Buffer.from(process.env.CONNECTOR_STORAGE_KEY, "base64") }, activeKeyId: "current" });
+  const knex = createKnex({ client: "mysql2", connection: process.env.DATABASE_URL });
+  try {
+    const service = createConnectionService({
+      configuration, providers: [googleCalendarProvider],
+      store: createKnexConnectionStore({ knex, protection }),
+      resolveReference: createEnvironmentReferenceResolver(process.env),
+      authorize: async () => context
+    });
+    const request = { context, integrationId: "calendar" };
+    let result;
+    if (command === "connect") result = await connectInBrowser(service, context);
+    else if (command === "status") result = await service.status(request);
+    else if (command === "disconnect") result = await service.disconnect(request);
+    else result = await service.invoke({ ...request, operation: command === "events" ? "events.list" : "calendars.list", input: JSON.parse(process.argv[3] || "{}") });
+    console.log(JSON.stringify(result, null, 2));
+  } finally { await knex.destroy(); }
+}
+
+main().catch((error) => {
+  console.error(error.code || "calendar_command_failed");
+  if (error.fieldErrors) console.error(JSON.stringify(error.fieldErrors));
+  else if (!error.code) console.error(error.message);
+  process.exitCode = 1;
+});

package/src/server/provider.js

@@ -0,0 +1,113 @@
+import { createSchema } from "json-rest-schema";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { googleCalendarDefinition } from "../shared/definition.js";
+
+const scope = (name) => `https://www.googleapis.com/auth/${name}`;
+const listSchema = createSchema({
+  pageToken: { type: "string", maxLength: 4096 },
+  maxResults: { type: "integer", min: 1, max: 250, defaultTo: 100 }
+});
+const eventsSchema = createSchema({
+  calendarId: { type: "string", minLength: 1, maxLength: 1024, defaultTo: "primary" },
+  pageToken: { type: "string", maxLength: 4096 },
+  maxResults: { type: "integer", min: 1, max: 2500, defaultTo: 100 },
+  timeMin: { type: "dateTime" },
+  timeMax: { type: "dateTime" }
+});
+
+function queryUrl(path, input) {
+  const url = new URL(`https://www.googleapis.com/calendar/v3/${path}`);
+  for (const [key, value] of Object.entries(input)) if (value !== undefined) url.searchParams.set(key, String(value));
+  return { method: "GET", url: url.href };
+}
+
+const writeScopes = ["calendar.events", "calendar", "calendar.events.owned", "calendar.app.created"].map(scope);
+const readScopes = ["calendar.events.readonly", "calendar.events", "calendar.readonly", "calendar", "calendar.events.owned", "calendar.events.owned.readonly", "calendar.app.created"].map(scope);
+const targetSchema = createSchema({
+  calendarId: { type: "string", minLength: 1, maxLength: 1024, defaultTo: "primary" },
+  eventId: { type: "string", minLength: 1, maxLength: 1024, required: true }
+});
+function invalid(message) { throw Object.assign(new Error(message), { statusCode: 422 }); }
+function eventBody(body, creating) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) invalid("event must be an object.");
+  const allowed = ["summary", "description", "location", "start", "end", "recurrence", "attendees", "transparency", "visibility"];
+  if (!Object.keys(body).length || Object.keys(body).some(key => !allowed.includes(key))) invalid("Use supported event fields only.");
+  for (const key of ["summary", "description", "location"]) if (body[key] !== undefined && (typeof body[key] !== "string" || body[key].length > 16384)) invalid(`${key} must be text of at most 16384 characters.`);
+  if (creating && (!body.start || !body.end)) invalid("start and end are required.");
+  if (Boolean(body.start) !== Boolean(body.end)) invalid("Supply start and end together when changing event times.");
+  for (const point of [body.start, body.end].filter(Boolean)) {
+    if (typeof point !== "object" || Array.isArray(point) || Object.keys(point).some(key => !["date", "dateTime", "timeZone"].includes(key))) invalid("Use date or dateTime and optional timeZone.");
+    if (Boolean(point.date) === Boolean(point.dateTime)) invalid("Choose an all-day date or a timed dateTime.");
+    if (point.date && (typeof point.date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(point.date) || !Number.isFinite(Date.parse(point.date)) || new Date(point.date).toISOString().slice(0, 10) !== point.date)) invalid("Invalid all-day date.");
+    if (point.dateTime && (typeof point.dateTime !== "string" || !/T.*(?:Z|[+-]\d{2}:\d{2})$/.test(point.dateTime) || !Number.isFinite(Date.parse(point.dateTime)))) invalid("dateTime requires an explicit timezone offset.");
+    if (point.timeZone !== undefined) { try { if (typeof point.timeZone !== "string") throw new Error(); new Intl.DateTimeFormat("en", { timeZone: point.timeZone }); } catch { invalid("Use an IANA timeZone."); } }
+  }
+  if (body.start && (Boolean(body.start.date) !== Boolean(body.end.date) || Date.parse(body.end.date || body.end.dateTime) <= Date.parse(body.start.date || body.start.dateTime))) invalid("Use matching date types with end after start; all-day end is exclusive.");
+  if (body.recurrence !== undefined) {
+    if (!Array.isArray(body.recurrence) || body.recurrence.length > 100 || body.recurrence.some(line => typeof line !== "string" || line.length > 2048 || !/^(RRULE|RDATE|EXRULE|EXDATE)[:;]/.test(line) || /[\r\n]/.test(line))) invalid("recurrence must be an array of RFC5545 recurrence lines.");
+    if (body.recurrence.length && body.start?.dateTime && (!body.start.timeZone || !body.end.timeZone)) invalid("Timed recurrence requires start/end timeZone.");
+    if (body.recurrence.length && !body.start) invalid("Supply start and end when setting recurrence.");
+  }
+  if (body.attendees !== undefined && (!Array.isArray(body.attendees) || body.attendees.length > 200 || body.attendees.some(person => !person || typeof person.email !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(person.email) || Object.keys(person).some(key => !["email", "displayName", "optional"].includes(key)) || (person.displayName !== undefined && typeof person.displayName !== "string") || (person.optional !== undefined && typeof person.optional !== "boolean")))) invalid("attendees requires up to 200 email entries with optional displayName/optional.");
+  if (body.transparency !== undefined && !["opaque", "transparent"].includes(body.transparency)) invalid("Invalid transparency.");
+  if (body.visibility !== undefined && !["default", "public", "private", "confidential"].includes(body.visibility)) invalid("Invalid visibility.");
+  return body;
+}
+function writeEvent(method) {
+  return {
+    scopes: writeScopes,
+    validateResult: result => method === "DELETE" ? result === null : result?.kind === "calendar#event" && typeof result.id === "string",
+    request(input = {}) {
+      const { event, sendUpdates, ifMatch, ...target } = input;
+      if (!["all", "externalOnly", "none"].includes(sendUpdates)) invalid("Choose sendUpdates explicitly: all, externalOnly or none.");
+      if (ifMatch !== undefined && (typeof ifMatch !== "string" || !ifMatch || ifMatch.length > 1024 || /[\r\n]/.test(ifMatch))) invalid("Invalid event ETag.");
+      if (method === "DELETE" && event !== undefined) invalid("Cancellation has no event body.");
+      const { calendarId, eventId } = validateSchemaPayload({ schema: method === "POST" ? createSchema({ calendarId: { type: "string", minLength: 1, maxLength: 1024, defaultTo: "primary" } }) : targetSchema, mode: "replace" }, target, { statusCode: 422 });
+      const request = queryUrl(`calendars/${encodeURIComponent(calendarId)}/events${eventId ? `/${encodeURIComponent(eventId)}` : ""}`, { sendUpdates });
+      return { ...request, method, ...(ifMatch ? { headers: { "If-Match": ifMatch } } : {}), ...(method !== "DELETE" ? { body: eventBody(event, method === "POST") } : {}) };
+    }
+  };
+}
+
+const googleCalendarProvider = Object.freeze({
+  ...googleCalendarDefinition,
+  oauth: {
+    issuer: "https://accounts.google.com",
+    authorization_endpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+    token_endpoint: "https://oauth2.googleapis.com/token",
+    revocation_endpoint: "https://oauth2.googleapis.com/revoke"
+  },
+  authorizationParameters: { access_type: "offline", prompt: "consent" },
+  apiOrigins: ["https://www.googleapis.com"],
+  checkOperation: "calendars.list",
+  operations: {
+    "events.create": writeEvent("POST"),
+    "events.update": writeEvent("PATCH"),
+    "events.cancel": writeEvent("DELETE"),
+    "events.get": {
+      scopes: readScopes,
+      validateResult: result => result?.kind === "calendar#event" && typeof result.id === "string",
+      request(input) {
+        const { calendarId, eventId } = validateSchemaPayload({ schema: targetSchema, mode: "replace" }, input, { statusCode: 422 });
+        return queryUrl(`calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`, {});
+      }
+    },
+    "calendars.list": {
+      scopes: [scope("calendar.calendarlist.readonly"), scope("calendar.calendarlist"), scope("calendar.readonly"), scope("calendar")],
+      validateResult: (result) => result?.kind === "calendar#calendarList" && (result.items === undefined || Array.isArray(result.items)),
+      request(input) {
+        return queryUrl("users/me/calendarList", validateSchemaPayload({ schema: listSchema, mode: "replace" }, input, { statusCode: 422 }));
+      }
+    },
+    "events.list": {
+      scopes: [scope("calendar.events.readonly"), scope("calendar.events"), scope("calendar.readonly"), scope("calendar")],
+      validateResult: (result) => result?.kind === "calendar#events" && (result.items === undefined || Array.isArray(result.items)),
+      request(input) {
+        const { calendarId, ...query } = validateSchemaPayload({ schema: eventsSchema, mode: "replace" }, input, { statusCode: 422 });
+        return queryUrl(`calendars/${encodeURIComponent(calendarId)}/events`, { ...query, singleEvents: true, orderBy: "startTime" });
+      }
+    }
+  }
+});
+
+export { googleCalendarProvider };

package/src/shared/definition.js

@@ -0,0 +1,52 @@
+const GOOGLE_SCOPE_BASE = "https://www.googleapis.com/auth/";
+const googleCalendarDefinition = Object.freeze({
+  id: "google-calendar",
+  name: "Google Calendar",
+  description: "Read calendars and create, edit or cancel events.",
+  categories: ["Google", "Productivity"],
+  accountModes: ["shared", "per-user", "assistant"],
+  authenticationMethods: ["oauth2"],
+  setup: {
+    callbackPath: "/integrations/google/callback",
+    url: "https://developers.google.com/identity/protocols/oauth2/web-server",
+    steps: [
+      "In Google Cloud, select the project for this application. Open APIs & Services > Library, search for Google Calendar API, open it and choose Enable.",
+      "Open Google Auth Platform > Branding. If setup has not started, choose Get Started; enter the app name, support email and contact email, choose the audience, review the policy and finish with Create.",
+      "Choose External if people outside your Google Workspace organization will connect. During testing, open Audience > Test users > Add users, enter the allowed Google accounts and Save. Internal is only for your organization. External Testing refresh tokens for these API permissions expire after seven days; reconnect during testing. Public release also requires completing the applicable Google review.",
+      "For an external app, open Data Access > Add or Remove Scopes. Add the permissions selected in this integration and Save. Sensitive or restricted scopes can require Google verification before public use; creating a client does not complete that review.",
+      "Keep List calendars for the initial connection check and Read events if the application will read events. Event-only or availability-only permissions do not authorize the calendar-list check. Use an account that can access the intended calendars; selecting a scope does not grant calendar sharing access.",
+      "To create, edit or cancel events, select Manage events, add calendar.events in Google Data Access, and reconnect for fresh consent. Keep List calendars for verification. Calendar sharing must independently allow the connected account to write.",
+      "Choose the destination calendar and attendee notification policy explicitly. All-day end dates are exclusive; timed recurring events need an IANA time zone. Editing or cancelling a recurring master affects the series; use an expanded occurrence ID for one instance. Changing attendee arrays replaces the list; read the latest event first.",
+      "Open Clients > Create Client. Choose Web application and name it. Under Authorized redirect URIs, choose Add URI and paste the application callback shown here, then Create. The editor dashboard URL is not the callback.",
+      "Copy the Client ID into this form and copy or download the full client secret immediately; Google only shows it at creation. Save configuration, then use Set credential in Env to put the secret value in the variable named by Client secret reference. If lost, open Clients, select this client and Add Secret; save the new value before disabling the old secret.",
+      "Use Set callback in Env to save the same application callback URL. If a Configured callback URL is shown, preserve it unless intentionally changing both Env and Google. Scheme, path, case and trailing slash must match exactly.",
+      "For a shared account, return here and check or connect the account once the application runtime is ready. For per-user connections, each person authorizes inside your application. Saving this registration neither connects every user nor installs the callback route."
+    ]
+  },
+  scopes: [
+    { value: `${GOOGLE_SCOPE_BASE}calendar.calendarlist.readonly`, label: "List calendars", recommended: true },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.events.readonly`, label: "Read events", recommended: true },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.readonly`, label: "Read all calendar data" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar`, label: "Manage calendars and events" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.calendarlist`, label: "Manage calendar subscriptions" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.events`, label: "Manage events" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.freebusy`, label: "Read your availability" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.settings.readonly`, label: "Read calendar settings" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.events.owned`, label: "Manage events in calendars you own" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.events.owned.readonly`, label: "Read events in calendars you own" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.events.freebusy`, label: "Read availability in accessible calendars" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.app.created`, label: "Create and manage app-created calendars" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.calendars`, label: "Manage calendar properties" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.calendars.readonly`, label: "Read calendar properties" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.acls`, label: "Manage calendar sharing permissions" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.acls.readonly`, label: "Read calendar sharing permissions" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.events.public.readonly`, label: "Read public calendar events" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.addons.execute`, label: "Run a Calendar add-on" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.addons.current.event.read`, label: "Read the event open in a Calendar add-on" },
+    { value: `${GOOGLE_SCOPE_BASE}calendar.addons.current.event.write`, label: "Edit the event open in a Calendar add-on" }
+  ],
+  settingsFields: [],
+  documentationUrl: "https://developers.google.com/workspace/calendar/api/guides/overview"
+});
+
+export { googleCalendarDefinition };