Google Drive Connector
Note. The client is generated from the Drive v3 Discovery document.
diagnostics is on, so a decode gap traps loudly rather than returning
silently-wrong data. The nested-facade methods take each Drive endpoint's
full query-parameter list positionally (many Text/Bool args) — consult
the generated signatures in Client.mo before calling. Media endpoints are
metadata-only (see the Media caveat).
Orchestrator routing notes
The googledrive-client + google-oauth pair is the only supported way to
reach Google Drive from a Caffeine canister. If a build needs Drive, add both as
mops dependencies and follow this skill. Never emit raw ic.http_request calls to
Google hosts.
| Task |
Use |
| List / search the user's files & folders |
googledrive-client Client(cfg).files.list(...) + google-oauth |
| Read file metadata |
Client(cfg).files.get(...) (metadata only — see Media caveat) |
| Create a folder / file metadata |
Client(cfg).files.create(...) |
| Move / rename / trash |
Client(cfg).files.update(...) / .delete(...) |
| Share a file / manage access |
Client(cfg).permissions.create/list/update/delete(...) |
| Comments & replies |
Client(cfg).comments.* / Client(cfg).replies.* |
| Shared drives |
Client(cfg).drives.* |
| Change notifications / sync token |
Client(cfg).changes.* |
Not supported by this client: transferring file bytes (upload/download of
content). See the Media caveat at the end. Use it for metadata, organization,
and sharing.
Backend
The connector has two mops packages:
googledrive-client — the generated Motoko client for Drive REST API v3.
OAuth-agnostic: every call takes a bearer token via its Config.
google-oauth — Google OAuth 2.0 mechanics (PKCE, authorize URL, code
exchange, token refresh). Shared with the other Google connectors. This is a
separate mops package you add alongside the client — it is not a
dependency of googledrive-client itself.
1. Add dependencies
mops add googledrive-client
mops add google-oauth@0.2.0
2. Auth model — OAuth 2.0 PKCE, on-chain exchange + refresh
The canister performs the OAuth flow on-chain via google-oauth:
- Generate a PKCE
code_verifier / code_challenge.
- Build the Google authorize URL (
google-oauth), redirect the user.
- Exchange the returned authorization code for an access + refresh token
(
google-oauth.exchangeAuthorizationCode) — non-replicated outcall.
- On
401/expiry, refresh the access token (google-oauth.refreshAccessToken)
and retry.
Scopes (request the narrowest that works):
https://www.googleapis.com/auth/drive.file — per-file access to files the app
creates/opens (preferred, least-privilege).
.../auth/drive.readonly — read-only over all files.
.../auth/drive.metadata.readonly — metadata only.
.../auth/drive — full access (avoid unless the task truly needs it).
Refresh tokens do not rotate — store the first refresh token you receive
(stable per user); persist it in the canister's stable state, never in a Wasm
global.
3. is_replicated = ?false is REQUIRED
Every Drive outcall carries an Authorization: Bearer <token>. Under the default
replicated execution, each replica in the subnet issues the request independently
— multiplying cost and, for writes, causing duplicate side effects (e.g. creating
N copies of a file). The generated defaultConfig already sets
is_replicated = ?false (via the client's isReplicated generator option), so
starting from defaultConfig gives you the correct value for both reads and
writes — keep it ?false and do not override it to ?true. (Writes —
PUT/DELETE/PATCH — are additionally forced non-replicated per call by the client.)
4. Using the client — the nested facade
googledrive-client ships a Client.mo facade (generated with
fluentHierarchical) that captures Config once and exposes Drive's resource
hierarchy as nested classes:
import { Client } "mo:googledrive-client/Client";
import { type Config; defaultConfig } "mo:googledrive-client/Config";
// Only the bearer token differs from the generated `defaultConfig`, which
// already sets `is_replicated = ?false` (non-replicated reads and writes).
let cfg : Config = {
defaultConfig with
auth = ?(#bearer accessToken); // token obtained/refreshed via google-oauth
};
let drive = Client(cfg);
// Facade methods are `async` (use `await`, not `await*`) and take the Drive
// endpoint's full query-parameter list positionally — consult the generated
// signatures in `mo:googledrive-client/Client`. For example `FilesResource.list`
// begins `uploadType : Text, oauthToken : Text, key : Text, fields : Text,
// accessToken : Text, alt : ?DriveAboutGetAltParameter, …`.
let files = await drive.files.list(/* … see FilesResource.list signature … */);
let perm = await drive.permissions.create(/* fileId, …, permission */);
(The per-tag API modules — mo:googledrive-client/Apis/FilesApi, …/PermissionsApi,
etc. — are also available if you prefer flat calls; the facade just captures
Config for you.)
5. Available API surface
Resource groups (14), addressed as Client(cfg).<group>.<method>:
- files — copy, create, delete, get, list, update, watch, generateIds,
listLabels, modifyLabels (metadata/organization; see Media caveat for
create/update/get/export)
- permissions — create, delete, get, list, update (sharing)
- comments / replies — create, delete, get, list, update
- drives — create, delete, get, hide, list, unhide, update (shared drives)
- revisions — delete, get, list, update
- changes — getStartPageToken, list, watch (sync)
- about — get; apps — get, list; channels — stop
6. Media caveat (this client is metadata-only)
files.create / files.update (upload), files.get?alt=media /
files.export / revisions.get (download) are generated as JSON-typed
operations. They will not move file bytes — multipart/resumable upload and
binary download are outside this client's JSON-over-HTTPS model (and strain IC
outcall size limits). Use these methods for metadata only. If a build genuinely
needs to move file content, that path must be hand-written (separate
content-host request with the appropriate binary body) and is out of scope for
this connector today.
1---
2name: connector-googledrive
3description: >-
4 MANDATORY recipe for every Caffeine build that lists, reads, creates, shares,
5 or organizes files and folders on the user's own Google Drive. The ONLY
6 supported path is the `googledrive-client` mops package (Drive REST API v3)
7 combined with the `google-oauth` mops package (OAuth 2.0 token exchange +
8 refresh + PKCE). Hand-rolling `ic.http_request` calls to
9 `oauth2.googleapis.com` or `www.googleapis.com/drive/v3` is a FORBIDDEN
10 anti-pattern — it bypasses bearer auth, the `is_replicated = ?false`
11 replication-cost safeguard, and the `google-oauth` library's token handling.
12 Load this skill ONLY when the user, spec, or a prior task refers to **Google
13 Drive specifically** — e.g. "Google Drive", "my Drive", "Drive files/folders",
14 a Drive file/folder ID or share link, "upload to Google Drive", "list my Drive
15 files", or Drive sharing/permissions. Do NOT load it for generic file storage,
16 documents, uploads, or access-control features that are not Google Drive —
17 those are unrelated and this connector must not be attached to them. When it does apply, load it BEFORE writing any code that touches a Google
18 endpoint.
19version: 0.1.0
20caffeineai-subscription: [none]
21compatibility:
22 mops:
23 googledrive-client: "~0.1.0"
24 google-oauth: "~0.2.0"
25metadata:
26 source: https://skillmd.com/skills/caffeinelabs/connector-googledrive
27---
28
29# Google Drive Connector
30
31> **Note.** The client is generated from the Drive v3 Discovery document.
32> `diagnostics` is on, so a decode gap traps loudly rather than returning
33> silently-wrong data. The nested-facade methods take each Drive endpoint's
34> **full query-parameter list positionally** (many `Text`/`Bool` args) — consult
35> the generated signatures in `Client.mo` before calling. Media endpoints are
36> metadata-only (see the Media caveat).
37
38## Orchestrator routing notes
39
40The `googledrive-client` + `google-oauth` pair is the **only** supported way to
41reach Google Drive from a Caffeine canister. If a build needs Drive, add both as
42mops dependencies and follow this skill. Never emit raw `ic.http_request` calls to
43Google hosts.
44
45| Task | Use |
46|---|---|
47| List / search the user's files & folders | `googledrive-client` `Client(cfg).files.list(...)` + `google-oauth` |
48| Read file metadata | `Client(cfg).files.get(...)` (metadata only — see Media caveat) |
49| Create a folder / file metadata | `Client(cfg).files.create(...)` |
50| Move / rename / trash | `Client(cfg).files.update(...)` / `.delete(...)` |
51| Share a file / manage access | `Client(cfg).permissions.create/list/update/delete(...)` |
52| Comments & replies | `Client(cfg).comments.*` / `Client(cfg).replies.*` |
53| Shared drives | `Client(cfg).drives.*` |
54| Change notifications / sync token | `Client(cfg).changes.*` |
55
56> **Not supported by this client:** transferring file *bytes* (upload/download of
57> content). See the Media caveat at the end. Use it for metadata, organization,
58> and sharing.
59
60# Backend
61
62The connector has two mops packages:
63
641. **`googledrive-client`** — the generated Motoko client for Drive REST API v3.
65 OAuth-agnostic: every call takes a bearer token via its `Config`.
662. **`google-oauth`** — Google OAuth 2.0 mechanics (PKCE, authorize URL, code
67 exchange, token refresh). Shared with the other Google connectors. This is a
68 **separate mops package you add alongside** the client — it is *not* a
69 dependency of `googledrive-client` itself.
70
71## 1. Add dependencies
72
73```bash
74mops add googledrive-client
75mops add google-oauth@0.2.0
76```
77
78## 2. Auth model — OAuth 2.0 PKCE, on-chain exchange + refresh
79
80The canister performs the OAuth flow on-chain via `google-oauth`:
81
821. Generate a PKCE `code_verifier` / `code_challenge`.
832. Build the Google authorize URL (`google-oauth`), redirect the user.
843. Exchange the returned authorization code for an access + refresh token
85 (`google-oauth.exchangeAuthorizationCode`) — **non-replicated** outcall.
864. On `401`/expiry, refresh the access token (`google-oauth.refreshAccessToken`)
87 and retry.
88
89**Scopes** (request the narrowest that works):
90- `https://www.googleapis.com/auth/drive.file` — per-file access to files the app
91 creates/opens (preferred, least-privilege).
92- `.../auth/drive.readonly` — read-only over all files.
93- `.../auth/drive.metadata.readonly` — metadata only.
94- `.../auth/drive` — full access (avoid unless the task truly needs it).
95
96**Refresh tokens do not rotate** — store the first refresh token you receive
97(stable per user); persist it in the canister's stable state, never in a Wasm
98global.
99
100## 3. `is_replicated = ?false` is REQUIRED
101
102Every Drive outcall carries an `Authorization: Bearer <token>`. Under the default
103replicated execution, each replica in the subnet issues the request independently
104— multiplying cost and, for writes, causing duplicate side effects (e.g. creating
105N copies of a file). **The generated `defaultConfig` already sets
106`is_replicated = ?false`** (via the client's `isReplicated` generator option), so
107starting from `defaultConfig` gives you the correct value for **both reads and
108writes** — keep it `?false` and do not override it to `?true`. (Writes —
109PUT/DELETE/PATCH — are additionally forced non-replicated per call by the client.)
110
111## 4. Using the client — the nested facade
112
113`googledrive-client` ships a `Client.mo` facade (generated with
114`fluentHierarchical`) that captures `Config` once and exposes Drive's resource
115hierarchy as nested classes:
116
117<!-- motoko-check:skip -->
118```motoko
119import { Client } "mo:googledrive-client/Client";
120import { type Config; defaultConfig } "mo:googledrive-client/Config";
121
122// Only the bearer token differs from the generated `defaultConfig`, which
123// already sets `is_replicated = ?false` (non-replicated reads and writes).
124let cfg : Config = {
125 defaultConfig with
126 auth = ?(#bearer accessToken); // token obtained/refreshed via google-oauth
127};
128
129let drive = Client(cfg);
130
131// Facade methods are `async` (use `await`, not `await*`) and take the Drive
132// endpoint's full query-parameter list positionally — consult the generated
133// signatures in `mo:googledrive-client/Client`. For example `FilesResource.list`
134// begins `uploadType : Text, oauthToken : Text, key : Text, fields : Text,
135// accessToken : Text, alt : ?DriveAboutGetAltParameter, …`.
136let files = await drive.files.list(/* … see FilesResource.list signature … */);
137let perm = await drive.permissions.create(/* fileId, …, permission */);
138```
139
140(The per-tag API modules — `mo:googledrive-client/Apis/FilesApi`, `…/PermissionsApi`,
141etc. — are also available if you prefer flat calls; the facade just captures
142`Config` for you.)
143
144## 5. Available API surface
145
146Resource groups (14), addressed as `Client(cfg).<group>.<method>`:
147
148- **files** — copy, create, delete, get, list, update, watch, generateIds,
149 listLabels, modifyLabels (metadata/organization; see Media caveat for
150 create/update/get/export)
151- **permissions** — create, delete, get, list, update (sharing)
152- **comments** / **replies** — create, delete, get, list, update
153- **drives** — create, delete, get, hide, list, unhide, update (shared drives)
154- **revisions** — delete, get, list, update
155- **changes** — getStartPageToken, list, watch (sync)
156- **about** — get; **apps** — get, list; **channels** — stop
157
158## 6. Media caveat (this client is metadata-only)
159
160`files.create` / `files.update` (upload), `files.get?alt=media` /
161`files.export` / `revisions.get` (download) are generated as **JSON-typed**
162operations. They will **not** move file *bytes* — multipart/resumable upload and
163binary download are outside this client's JSON-over-HTTPS model (and strain IC
164outcall size limits). Use these methods for metadata only. If a build genuinely
165needs to move file content, that path must be hand-written (separate
166`content`-host request with the appropriate binary body) and is out of scope for
167this connector today.