@open-neko/connector-google-workspace 0.1.0

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@open-neko/connector-google-workspace",
+  "version": "0.1.0",
+  "description": "Google Workspace connector for OpenNeko — per-operator OAuth via PKCE against the operator's own Google Cloud OAuth client. Provides Gmail, Calendar, Drive, Docs, and Sheets actions backed by each operator's authorised account. Runs in a microsandbox VM with network egress limited to accounts.google.com and *.googleapis.com.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-neko/plugins.git",
+    "directory": "packages/google-workspace"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "skill"
+  ],
+  "openneko": {
+    "runner": "./dist/run.js",
+    "skill": "./skill",
+    "permissions": {
+      "network": [
+        "accounts.google.com",
+        "oauth2.googleapis.com",
+        "gmail.googleapis.com",
+        "www.googleapis.com",
+        "sheets.googleapis.com",
+        "docs.googleapis.com"
+      ],
+      "env": [
+        {
+          "key": "GOOGLE_CLIENT_ID",
+          "required": true,
+          "secret": false,
+          "description": "OAuth 2.0 Client ID from your Google Cloud Console project. Deployment-wide — every operator who connects uses the same client. Create at https://console.cloud.google.com/apis/credentials → Create credentials → OAuth client ID → Web application. Set Authorized redirect URI to https://<your-deployment>/api/integrations/connect/%40open-neko%2Fconnector-google-workspace/callback."
+        },
+        {
+          "key": "GOOGLE_CLIENT_SECRET",
+          "required": true,
+          "secret": true,
+          "description": "OAuth 2.0 Client Secret paired with the client ID above. Stored in the per-user secrets file, never echoed."
+        }
+      ]
+    },
+    "capabilities": {
+      "connect": {
+        "providerLabel": "Google Workspace",
+        "scopes": [
+          "openid",
+          "https://www.googleapis.com/auth/userinfo.email",
+          "https://www.googleapis.com/auth/gmail.send",
+          "https://www.googleapis.com/auth/calendar.events.readonly",
+          "https://www.googleapis.com/auth/spreadsheets",
+          "https://www.googleapis.com/auth/documents"
+        ],
+        "flow": "oauth2-pkce"
+      },
+      "action": {
+        "kinds": [
+          {
+            "kind": "send_gmail",
+            "description": "Send an email from the connected user's Gmail account.",
+            "default_mode": "ask",
+            "example": {
+              "to": "amit@example.com",
+              "subject": "Weekly revenue summary",
+              "body": "Hi Amit,\n\nQ3 revenue is in — see the dashboard for details.\n\n— OpenNeko"
+            }
+          },
+          {
+            "kind": "list_calendar_events",
+            "description": "List upcoming events on the connected user's primary calendar.",
+            "default_mode": "auto",
+            "example": {
+              "maxResults": 10,
+              "timeMin": "2026-05-24T00:00:00Z"
+            }
+          },
+          {
+            "kind": "append_sheet_row",
+            "description": "Append a row to a Google Sheet the connected user can edit.",
+            "default_mode": "ask",
+            "example": {
+              "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
+              "range": "Sheet1!A1",
+              "values": [
+                "2026-05-24",
+                "Revenue",
+                "12000"
+              ]
+            }
+          }
+        ]
+      }
+    }
+  },
+  "dependencies": {
+    "@open-neko/plugin-types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/bundle.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: google-workspace
+description: Patterns for using the @open-neko/connector-google-workspace actions — Gmail send, Calendar list, Sheets append — against the currently-connected operator's account. Use whenever the agent needs to send email, look up upcoming meetings, or log a finding to a spreadsheet on the operator's behalf. The operator must have already connected via /integrations; this skill assumes that's done.
+license: Apache-2.0
+metadata:
+  authoredBy: open-neko
+  pairsWith: "@open-neko/connector-google-workspace"
+---
+
+# Google Workspace patterns
+
+The `@open-neko/connector-google-workspace` plugin contributes three
+sandboxed actions, each scoped to the **currently connected operator**:
+
+| Action | Mode | Use when |
+|---|---|---|
+| `send_gmail` | `ask` | Operator wants OpenNeko to send a real email on their behalf. |
+| `list_calendar_events` | `auto` | Operator asks about their schedule, or you need calendar context for a finding. |
+| `append_sheet_row` | `ask` | Logging a finding to an external Sheets log the operator maintains. |
+
+## Prerequisites the agent must verify
+
+1. **The operator has connected.** Check the `/integrations` status
+   before assuming a Google action is available. If they haven't,
+   prompt them: *"Connect Google Workspace at /integrations first."*
+2. **The action you need is in scope.** Some operators connect with a
+   narrower set of OAuth scopes than the plugin declares. If
+   `send_gmail` returns `insufficient_authentication_scopes`, ask the
+   operator to reconnect with the gmail.send scope checked.
+
+## `send_gmail` drafting rules
+
+The same `ask`-mode → approval-queue → fire flow as Slack. Draft to be
+operator-readable on a phone screen.
+
+1. **Subject lines under 60 chars.** Mobile preview clips at ~60.
+2. **One ask per email.** If a finding requires two follow-ups, draft
+   two emails. The operator can approve both independently.
+3. **Sign off with the operator's name, not "OpenNeko".** You're acting
+   on their behalf — the recipient should see the operator as the sender.
+4. **Include the source.** "(Detected by your OpenNeko Revenue Drop
+   watcher at 14:03 UTC.)" at the bottom of the body. Operators in
+   regulated industries need traceability.
+
+## `list_calendar_events` consumption
+
+Returns up to N upcoming events sorted by start time. For "what's on my
+calendar tomorrow?" prompts:
+
+- Filter client-side to events whose `start.dateTime` falls in the next
+  24-48h — don't ask Google for more than you need.
+- Render times in the operator's timezone if known; otherwise use ISO
+  with `Z` and let the UI localize.
+- Suppress the standing weekly recurring stand-up unless the operator
+  asked specifically about it; it's noise.
+
+## `append_sheet_row` patterns
+
+Operators who run "findings logs" in Sheets benefit from this. The
+shape that works:
+
+```
+spreadsheetId: "1AbC..."   (from the URL of the sheet)
+range:         "Findings!A:E"
+values:        [
+  "2026-05-21T14:03:00Z",  // ISO timestamp
+  "germany-revenue-drop",  // watcher slug
+  "Germany hourly revenue down 62% vs baseline",  // description
+  "approved",              // outcome
+  "https://app/work/runs/abc"  // link back
+]
+```
+
+Use ISO timestamps in the first column; operators sort by it. The
+plugin's `range` argument uses A1 notation — `Sheet1!A:E` lets Sheets
+auto-find the next empty row.
+
+## Failure modes the operator should see
+
+- **`invalid_grant`** (refresh): the operator's refresh token was
+  revoked (account password change, OAuth client deleted, scope
+  removed). Prompt: *"Your Google connection expired — reconnect at
+  /integrations."*
+- **`insufficient_authentication_scopes`** (action): the connected
+  scope set doesn't include the one this action needs. Prompt the
+  operator to reconnect with the right scope checked.
+- **`quotaExceeded`**: Google's daily quota for that API. Surface the
+  exact API ("Gmail send quota") so the operator knows which one to
+  request an increase for.
+
+## What this skill is NOT for
+
+- One-off email to a person not in Gmail — that's a webhook or the
+  built-in `send_webhook` action.
+- Long Google Doc authoring — the connector's scopes include `documents`
+  but no `create_doc` action is shipped yet. (Coming after M10 ships.)