feat: add @agentic/google-docs Google Docs client

docs/mint.json

@@ -71,6 +71,7 @@
         "tools/hacker-news",
         "tools/gravatar",
         "tools/google-custom-search",
+        "tools/google-docs",
         "tools/google-drive",
         "tools/hunter",
         "tools/jina",

docs/tools/google-docs.mdx

@@ -0,0 +1,45 @@
+---
+title: Google Docs
+description: Simplified Google Docs API.
+---
+
+- package: `@agentic/google-docs`
+- exports: `class GoogleDocsClient`, `namespace googleDocs`
+- [source](https://github.com/transitive-bullshit/agentic/blob/main/packages/google-docs/src/google-docs-client.ts)
+- [google docs docs](https://developers.google.com/workspace/docs/api)
+
+## Install
+
+<CodeGroup>
+```bash npm
+npm install @agentic/google-docs googleapis @google-cloud/local-auth
+```
+
+```bash yarn
+yarn add @agentic/google-docs googleapis @google-cloud/local-auth
+```
+
+```bash pnpm
+pnpm add @agentic/google-docs googleapis @google-cloud/local-auth
+```
+
+</CodeGroup>
+
+## Example Usage
+
+```ts
+import { GoogleDriveClient } from '@agentic/google-drive'
+import { authenticate } from '@google-cloud/local-auth'
+import { google } from 'googleapis'
+
+// (in a real app, store these auth credentials and reuse them)
+const auth = await authenticate({
+  scopes: ['https://www.googleapis.com/auth/documents.readonly'],
+  keyfilePath: process.env.GOOGLE_CREDENTIALS_PATH
+})
+const docs = google.docs({ version: 'v1', auth })
+const client = new GoogleDocsClient({ docs })
+
+const document = await client.getDocument({ documentId: 'TODO' })
+console.log(document)
+```

docs/tools/google-drive.mdx

@@ -12,15 +12,15 @@ description: Simplified Google Drive API.
 
 <CodeGroup>
 ```bash npm
-npm install @agentic/google-drive google-auth-library googleapis
+npm install @agentic/google-drive googleapis google-auth-library
 ```
 
 ```bash yarn
-yarn add @agentic/google-drive google-auth-library googleapis
+yarn add @agentic/google-drive googleapis google-auth-library
 ```
 
 ```bash pnpm
-pnpm add @agentic/google-drive google-auth-library googleapis
+pnpm add @agentic/google-drive googleapis google-auth-library
 ```
 
 </CodeGroup>
@@ -36,11 +36,11 @@ const auth = new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/drive' })
 const drive = google.drive({ version: 'v3', auth })
 const client = new GoogleDriveClient({ drive })
 
-const result = await googleDrive.listFiles()
+const result = await client.listFiles()
 
 const file = result.files[0]!
-const metadata = await googleDrive.getFile({ fileId: file.id })
+const metadata = await client.getFile({ fileId: file.id })
-const content = await googleDrive.exportFile({
+const content = await client.exportFile({
   fileId: file.id,
   mimeType: 'application/pdf'
 })

packages/google-docs/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@agentic/google-docs",
+  "version": "7.6.3",
+  "description": "Agentic SDK for Google Docs.",
+  "author": "Travis Fischer <travis@transitivebullsh.it>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transitive-bullshit/agentic.git",
+    "directory": "packages/google-docs"
+  },
+  "type": "module",
+  "source": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "del dist",
+    "test": "run-s test:*",
+    "test:lint": "eslint .",
+    "test:typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentic/core": "workspace:*",
+    "type-fest": "catalog:"
+  },
+  "devDependencies": {
+    "googleapis": "catalog:"
+  },
+  "peerDependencies": {
+    "googleapis": "catalog:",
+    "zod": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/google-docs/readme.md

@@ -0,0 +1,24 @@
+<p align="center">
+  <a href="https://agentic.so">
+    <img alt="Agentic" src="https://raw.githubusercontent.com/transitive-bullshit/agentic/main/docs/media/agentic-header.jpg" width="308">
+  </a>
+</p>
+
+<p align="center">
+  <em>AI agent stdlib that works with any LLM and TypeScript AI SDK.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/transitive-bullshit/agentic/actions/workflows/main.yml"><img alt="Build Status" src="https://github.com/transitive-bullshit/agentic/actions/workflows/main.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@agentic/stdlib"><img alt="NPM" src="https://img.shields.io/npm/v/@agentic/stdlib.svg" /></a>
+  <a href="https://github.com/transitive-bullshit/agentic/blob/main/license"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://prettier.io"><img alt="Prettier Code Formatting" src="https://img.shields.io/badge/code_style-prettier-brightgreen.svg" /></a>
+</p>
+
+# Agentic
+
+**See the [github repo](https://github.com/transitive-bullshit/agentic) or [docs](https://agentic.so) for more info.**
+
+## License
+
+MIT © [Travis Fischer](https://x.com/transitive_bs)

packages/google-docs/src/google-docs-client.ts

@@ -0,0 +1,76 @@
+import type * as google from 'googleapis'
+import type { SetNonNullable, Simplify } from 'type-fest'
+import {
+  aiFunction,
+  AIFunctionsProvider,
+  pruneNullOrUndefinedDeep,
+  type SetRequired
+} from '@agentic/core'
+import { z } from 'zod'
+
+export namespace googleDocs {
+  export type Document = Simplify<
+    SetNonNullable<google.docs_v1.Schema$Document>
+  >
+}
+
+/**
+ * Simplified Google Docs API client.
+ *
+ * @see https://developers.google.com/workspace/drive/api
+ *
+ * @example
+ * ```ts
+ * import { GoogleDocsClient } from '@agentic/google-docs'
+ * import { authenticate } from '@google-cloud/local-auth'
+ * import { google } from 'googleapis'
+ *
+ * // (in a real app, store these auth credentials and reuse them)
+ * const auth = await authenticate({
+ *   scopes: ['https://www.googleapis.com/auth/documents.readonly'],
+ *   keyfilePath: process.env.GOOGLE_CREDENTIALS_PATH
+ * })
+ * const docs = google.docs({ version: 'v1', auth })
+ * const client = new GoogleDocsClient({ docs })
+ * ```
+ */
+export class GoogleDocsClient extends AIFunctionsProvider {
+  protected readonly docs: google.docs_v1.Docs
+
+  constructor({ docs }: { docs: google.docs_v1.Docs }) {
+    super()
+
+    this.docs = docs
+  }
+
+  /**
+   * Gets a Google Docs document by ID.
+   */
+  @aiFunction({
+    name: 'google_docs_get_document',
+    description: 'Gets a Google Docs document by ID.',
+    inputSchema: z.object({
+      documentId: z.string()
+    })
+  })
+  async getDocument(
+    args: Simplify<
+      SetRequired<google.docs_v1.Params$Resource$Documents$Get, 'documentId'>
+    >
+  ): Promise<googleDocs.Document> {
+    const { documentId, ...opts } = args
+
+    const { data } = await this.docs.documents.get({
+      ...opts,
+      documentId
+    })
+
+    return convertDocument(data)
+  }
+}
+
+function convertDocument(
+  data: google.docs_v1.Schema$Document
+): googleDocs.Document {
+  return pruneNullOrUndefinedDeep(data)
+}

packages/google-docs/src/index.ts

@@ -0,0 +1 @@
+export * from './google-docs-client'

packages/google-docs/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@fisch0920/config/tsconfig-node",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

packages/google-drive/package.json

@@ -32,14 +32,13 @@
     "test:typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agentic/core": "workspace:*"
+    "@agentic/core": "workspace:*",
+    "type-fest": "catalog:"
   },
   "devDependencies": {
-    "google-auth-library": "catalog:",
     "googleapis": "catalog:"
   },
   "peerDependencies": {
-    "google-auth-library": "catalog:",
     "googleapis": "catalog:",
     "zod": "catalog:"
   },

packages/google-drive/src/google-drive-client.ts

@@ -1,4 +1,5 @@
 import type * as google from 'googleapis'
+import type { SetNonNullable, Simplify } from 'type-fest'
 import {
   aiFunction,
   AIFunctionsProvider,
@@ -9,17 +10,22 @@ import {
 import { z } from 'zod'
 
 export namespace googleDrive {
-  export interface File {
+  export type File = Simplify<
-    id?: string
+    SetNonNullable<
-    name: string
+      Pick<
-    mimeType: string
+        google.drive_v3.Schema$File,
-    webViewLink?: string
+        | 'id'
-    webContentLink?: string
+        | 'name'
-    size?: string
+        | 'mimeType'
-    createdTime?: string
+        | 'webViewLink'
-    modifiedTime?: string
+        | 'webContentLink'
-    parents?: string[]
+        | 'size'
-  }
+        | 'createdTime'
+        | 'modifiedTime'
+        | 'parents'
+      >
+    >
+  >
 
   export const fileFields: readonly (keyof File)[] = [
     'id',
@@ -53,7 +59,7 @@ export namespace googleDrive {
 }
 
 /**
- * Simplified Drive API client.
+ * Simplified Google Drive API client.
  *
  * @see https://developers.google.com/workspace/drive/api
  *

packages/stdlib/package.json

@@ -48,6 +48,7 @@
     "@agentic/firecrawl": "workspace:*",
     "@agentic/github": "workspace:*",
     "@agentic/google-custom-search": "workspace:*",
+    "@agentic/google-docs": "workspace:*",
     "@agentic/google-drive": "workspace:*",
     "@agentic/gravatar": "workspace:*",
     "@agentic/hacker-news": "workspace:*",

packages/stdlib/src/index.ts

@@ -13,6 +13,7 @@ export * from '@agentic/exa'
 export * from '@agentic/firecrawl'
 export * from '@agentic/github'
 export * from '@agentic/google-custom-search'
+export * from '@agentic/google-docs'
 export * from '@agentic/google-drive'
 export * from '@agentic/gravatar'
 export * from '@agentic/hacker-news'

pnpm-lock.yaml

@@ -96,9 +96,6 @@ catalogs:
     genkitx-openai:
       specifier: ^0.20.2
       version: 0.20.2
-    google-auth-library:
-      specifier: ^9.15.1
-      version: 9.15.1
     googleapis:
       specifier: ^148.0.0
       version: 148.0.0
@@ -702,23 +699,39 @@ importers:
         version: link:../core
       '@googleapis/customsearch':
         specifier: 'catalog:'
-        version: 3.2.0
+        version: 3.2.0(encoding@0.1.13)
       zod:
         specifier: 'catalog:'
         version: 3.24.2
 
+  packages/google-docs:
+    dependencies:
+      '@agentic/core':
+        specifier: workspace:*
+        version: link:../core
+      type-fest:
+        specifier: 'catalog:'
+        version: 4.39.1
+      zod:
+        specifier: 'catalog:'
+        version: 3.24.2
+    devDependencies:
+      googleapis:
+        specifier: 'catalog:'
+        version: 148.0.0(encoding@0.1.13)
+
   packages/google-drive:
     dependencies:
       '@agentic/core':
         specifier: workspace:*
         version: link:../core
+      type-fest:
+        specifier: 'catalog:'
+        version: 4.39.1
       zod:
         specifier: 'catalog:'
         version: 3.24.2
     devDependencies:
-      google-auth-library:
-        specifier: 'catalog:'
-        version: 9.15.1(encoding@0.1.13)
       googleapis:
         specifier: 'catalog:'
         version: 148.0.0(encoding@0.1.13)
@@ -1150,6 +1163,9 @@ importers:
       '@agentic/google-custom-search':
         specifier: workspace:*
         version: link:../google-custom-search
+      '@agentic/google-docs':
+        specifier: workspace:*
+        version: link:../google-docs
       '@agentic/google-drive':
         specifier: workspace:*
         version: link:../google-drive
@@ -6502,10 +6518,6 @@ packages:
     resolution: {integrity: sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==}
     engines: {node: '>=10'}
 
-  type-fest@4.39.0:
-    resolution: {integrity: sha512-w2IGJU1tIgcrepg9ZJ82d8UmItNQtOFJG0HCUE3SzMokKkTsruVDALl2fAdiEzJlfduoU+VyXJWIIUZ+6jV+nw==}
-    engines: {node: '>=16'}
-
   type-fest@4.39.1:
     resolution: {integrity: sha512-uW9qzd66uyHYxwyVBYiwS4Oi0qZyUqwjU+Oevr6ZogYiXt99EOYtwvzMSLw1c3lYo2HzJsep/NB23iEVEgjG/w==}
     engines: {node: '>=16'}
@@ -7670,7 +7682,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@googleapis/customsearch@3.2.0':
+  '@googleapis/customsearch@3.2.0(encoding@0.1.13)':
     dependencies:
       googleapis-common: 7.2.0(encoding@0.1.13)
     transitivePeerDependencies:
@@ -11229,7 +11241,7 @@ snapshots:
       decircular: 0.1.1
       is-obj: 3.0.0
       sort-keys: 5.1.0
-      type-fest: 4.39.0
+      type-fest: 4.39.1
 
   hasown@2.0.2:
     dependencies:
@@ -12119,7 +12131,7 @@ snapshots:
     dependencies:
       '@babel/code-frame': 7.26.2
       index-to-position: 0.1.2
-      type-fest: 4.39.0
+      type-fest: 4.39.1
 
   parse-ms@4.0.0: {}
 
@@ -12382,14 +12394,14 @@ snapshots:
     dependencies:
       find-up-simple: 1.0.1
       read-pkg: 9.0.1
-      type-fest: 4.39.0
+      type-fest: 4.39.1
 
   read-pkg@9.0.1:
     dependencies:
       '@types/normalize-package-data': 2.4.4
       normalize-package-data: 6.0.2
       parse-json: 8.1.0
-      type-fest: 4.39.0
+      type-fest: 4.39.1
       unicorn-magic: 0.1.0
 
   readable-stream@4.7.0:
@@ -13081,8 +13093,6 @@ snapshots:
 
   type-fest@0.13.1: {}
 
-  type-fest@4.39.0: {}
-
   type-fest@4.39.1: {}
 
   type-flag@3.0.0: {}

readme.md

@@ -195,6 +195,7 @@ Full docs are available at [agentic.so](https://agentic.so).
 | [Firecrawl](https://www.firecrawl.dev)                                          | `@agentic/firecrawl`            | [docs](https://agentic.so/tools/firecrawl)            | Website scraping and structured data extraction.                                                                                                                                                                                                               |
 | [Google Custom Search](https://developers.google.com/custom-search/v1/overview) | `@agentic/google-custom-search` | [docs](https://agentic.so/tools/google-custom-search) | Official Google Custom Search API.                                                                                                                                                                                                                             |
 | [Google Drive](https://developers.google.com/workspace/drive/api)               | `@agentic/google-drive`         | [docs](https://agentic.so/tools/google-drive)         | Simplified Google Drive API.                                                                                                                                                                                                                                   |
+| [Google Docs](https://developers.google.com/workspace/docs/api)                 | `@agentic/google-docs`          | [docs](https://agentic.so/tools/google-docs)          | Simplified Google Docs API.                                                                                                                                                                                                                                    |
 | [Gravatar](https://docs.gravatar.com/api/profiles/rest-api/)                    | `@agentic/gravatar`             | [docs](https://agentic.so/tools/gravatar)             | Gravatar profile API.                                                                                                                                                                                                                                          |
 | [HackerNews](https://github.com/HackerNews/API)                                 | `@agentic/hacker-news`          | [docs](https://agentic.so/tools/hacker-news)          | Official HackerNews API.                                                                                                                                                                                                                                       |
 | [Hunter](https://hunter.io)                                                     | `@agentic/hunter`               | [docs](https://agentic.so/tools/hunter)               | Email finder, verifier, and enrichment.                                                                                                                                                                                                                        |