@theholocron/google-client 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +46 -109
  2. package/package.json +34 -35
package/README.md CHANGED
@@ -1,128 +1,65 @@
1
- # Google
2
-
3
- Interact with Google Drive products, programmatically.
4
-
5
- ```javascript
6
- import { node } from "@theholocron/client-google";
7
-
8
- async function main () {
9
- const [, , sheetId] = process.argv;
10
-
11
- try {
12
- const [err, data] = await google.spreadsheets.get(sheetId);
13
- const [ firstSheet ] = data.sheets[0].data[0];
14
- const { rowData } = firstSheet.data[0];
15
- const [ header, ...rest ] = rowData;
16
- const output = rest.map(item => ({
17
- name: item.values[0].formattedValue,
18
- value: item.values[1].formattedValue
19
- }));
20
-
21
- if (err) {
22
- console.error("Error:", err);
23
- process.exit(1);
24
- }
25
-
26
- console.log(output);
27
- }
28
- catch (error) {
29
- console.error("An error occurred:", error);
30
- process.exit(1);
31
- }
32
- }
33
-
34
- main();
35
- ```
36
-
37
- ## API
38
-
39
- ### `.spreadsheets`
40
-
41
- #### `.get(id: string)`
42
-
43
- Grab data from a spreadsheet.
44
-
45
- ##### id
46
-
47
- The ID of the spreadsheet. Its in the URL.
48
-
49
- Type: `string`
50
-
51
- ## How To…?
52
-
53
- ### Get a Token for OAuth2
54
-
55
- To get the necessary information for setting up OAuth2 with Google APIs (like the client ID, client secret, and redirect URI), you need to go to the [Google Cloud Console](https://console.cloud.google.com/welcome?project=chewy-428805).
56
-
57
- #### Create a New Project (if you don't have one already)
1
+ # @theholocron/google-client
58
2
 
59
- 1. Click on the project dropdown at the top of the page.
60
- 2. Click on "New Project".
61
- 3. Give your project a name and click "Create".
3
+ TypeScript client for Google Workspace APIs — Docs and Sheets. Supports both OAuth2 (user auth) and service account auth.
62
4
 
63
- #### Enable the API
5
+ ## Installation
64
6
 
65
- 1. Navigate to the "APIs & Services" section on the left-hand menu.
66
- 2. Click on "Library".
67
- 3. Search for the API you need (e.g., "Google Sheets API", "Google Drive API").
68
- 4. Click on the API and then click "Enable".
69
-
70
- #### Create OAuth 2.0 Credentials
71
-
72
- 1. Go to the "APIs & Services" > "Credentials" page.
73
- 2. Click on "Create Credentials" and select "OAuth client ID".
74
- 3. If prompted to set up the OAuth consent screen, do so by providing the necessary information.
75
- 4. Once the consent screen is set up, select "Web application" as the application type.
76
-
77
- #### Configure the OAuth Consent Screen
78
-
79
- Set up the OAuth consent screen by providing the required information such as application name, support email, and developer contact information.
80
-
81
- #### Create OAuth 2.0 Client ID
82
-
83
- Under "Authorized redirect URIs", enter your redirect URI (e.g., http://localhost:4000/oauth2callback). Click "Create".
84
-
85
- #### Get Client ID and Client Secret
7
+ ```bash
8
+ pnpm add @theholocron/google-client
9
+ ```
86
10
 
87
- After creating the credentials, you will see a dialog with your client ID and client secret. Copy these values and use them in your application code. Here’s what the settings look like in the console:
11
+ ## Usage
88
12
 
89
- * Client ID: This will be a string similar to `<digits>.apps.googleusercontent.com`.
90
- * Client Secret: This will be a string similar to `GOCSPX-<random-characters>`.
91
- * Redirect URI: This should match the URI you specified in the console, such as `http://localhost:4000/oauth2callback`.
13
+ ```ts
14
+ import { google, googleAuth } from "@theholocron/google-client";
92
15
 
93
- ### Setup a Service Account for Authorization
16
+ // Service account auth (env vars — see Auth section)
17
+ const authClient = await googleAuth([
18
+ "https://www.googleapis.com/auth/spreadsheets.readonly",
19
+ ]);
94
20
 
95
- Here’s a step-by-step guide to set up and use Service Account credentials in [Google Cloud Console](https://console.cloud.google.com/welcome?project=chewy-428805).
21
+ // Read a spreadsheet
22
+ const [err, data] = await google.spreadsheets.get("1BxiMVs0XRA...");
23
+ if (err) throw err;
96
24
 
97
- #### Create a Service Account
25
+ // Read a document
26
+ const [err, doc] = await google.documents.get("1BxiMVs0XRA...");
27
+ ```
98
28
 
99
- 1. Select your project or create a new one.
100
- 2. Navigate to "IAM & Admin" > "Service Accounts".
101
- 3. Click "Create Service Account".
102
- 4. Provide a name and description for the Service Account, then click "Create".
29
+ ## Auth
103
30
 
104
- #### Assign Roles to the Service Account
31
+ ### Service Account
105
32
 
106
- 1. Select roles that grant the necessary permissions for the API you want to access. For example, to access Google Sheets, you might assign the "Editor" role.
107
- 2. Click "Continue" and then "Done".
33
+ Set credentials via environment variables:
108
34
 
109
- #### Create and Download a Key
35
+ ```bash
36
+ # Option 1 — full JSON key file
37
+ GOOGLE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'
110
38
 
111
- 1. In the "Service Accounts" page, find the Service Account you created.
112
- 2. Click on the options menu (three dots) next to the Service Account and select "Manage keys".
113
- 3. Click "Add key" > "Create new key".
114
- 4. Select "JSON" and click "Create".
115
- 5. Download the JSON key file to your local machine.
39
+ # Option 2 — individual fields
40
+ GOOGLE_PROJECT_ID=my-project
41
+ GOOGLE_PRIVATE_KEY_ID=abc123
42
+ GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
43
+ GOOGLE_CLIENT_EMAIL=my-service@my-project.iam.gserviceaccount.com
44
+ GOOGLE_CLIENT_ID=123456789
45
+ ```
116
46
 
117
- ### Resolve "The caller does not have permission" Error
47
+ ### OAuth2 (user auth)
118
48
 
119
- #### Verify Permissions and Roles
49
+ ```bash
50
+ GOOGLE_CLIENT_ID=<oauth-client-id>
51
+ GOOGLE_CLIENT_SECRET=<oauth-client-secret>
52
+ GOOGLE_REDIRECT_URI=http://localhost:4000/oauth2callback # optional
53
+ ```
120
54
 
121
- Ensure that the service account has the appropriate roles assigned. For Google Sheets API, the service account needs at least the Editor role. For Google Drive API, it needs the Viewer, Commenter, or Editor role, depending on what actions you intend to perform.
122
- You can assign roles in the Google Cloud Console IAM & Admin section.
55
+ ```ts
56
+ import { oauth } from "@theholocron/google-client";
123
57
 
124
- #### Share the Resource with the Service Account
58
+ const authClient = await oauth([
59
+ "https://www.googleapis.com/auth/spreadsheets",
60
+ ]);
61
+ ```
125
62
 
126
- For Google Sheets, make sure the service account email is added as a collaborator with the necessary permissions (e.g., Viewer or Editor) on the specific Google Sheets file.
127
- Similarly, for Google Drive, share the necessary files or folders with the service account email.
63
+ ## License
128
64
 
65
+ GPL-3.0 © [Newton Koumantzelis](https://github.com/iamnewton)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/google-client",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "A TypeScript client for Google Workspace APIs (Docs, Sheets)",
5
5
  "homepage": "https://github.com/theholocron/clients/tree/main/packages/google-client#readme",
6
6
  "bugs": "https://github.com/theholocron/clients/issues",
@@ -12,17 +12,13 @@
12
12
  "license": "GPL-3.0",
13
13
  "author": "Newton Koumantzelis",
14
14
  "type": "module",
15
- "main": "./src/index.ts",
15
+ "main": "./dist/index.mjs",
16
16
  "exports": {
17
- ".": "./src/index.ts"
18
- },
19
- "scripts": {
20
- "build": "tsdown",
21
- "lint": "eslint .",
22
- "test": "vitest run",
23
- "test:watch": "vitest",
24
- "test:coverage": "vitest run --coverage",
25
- "typecheck": "tsc --noEmit"
17
+ ".": {
18
+ "types": "./dist/index.d.mts",
19
+ "import": "./dist/index.mjs",
20
+ "default": "./dist/index.mjs"
21
+ }
26
22
  },
27
23
  "dependencies": {
28
24
  "google-auth-library": "^9.15.1",
@@ -31,36 +27,39 @@
31
27
  "server-destroy": "^1.0.1"
32
28
  },
33
29
  "devDependencies": {
34
- "@theholocron/eslint-config": "catalog:",
35
- "@theholocron/tsconfig": "catalog:",
36
- "@theholocron/tsdown-config": "catalog:",
37
- "@theholocron/vitest-config": "catalog:",
30
+ "@theholocron/eslint-config": "^6.0.0",
31
+ "@theholocron/tsconfig": "^6.0.0",
32
+ "@theholocron/tsdown-config": "^6.0.0",
33
+ "@theholocron/vitest-config": "^6.0.0",
38
34
  "@types/server-destroy": "^1.0.4",
39
- "@vitest/coverage-v8": "catalog:",
40
- "@vitest/eslint-plugin": "catalog:",
41
- "eslint": "catalog:",
42
- "eslint-plugin-n": "catalog:",
43
- "globals": "catalog:",
44
- "tsdown": "catalog:",
45
- "typescript": "catalog:",
46
- "vitest": "catalog:"
35
+ "@vitest/coverage-v8": "^4.1.10",
36
+ "@vitest/eslint-plugin": "^1.6.23",
37
+ "eslint": "^10.7.0",
38
+ "eslint-plugin-n": "^18.2.2",
39
+ "globals": "^17.7.0",
40
+ "tsdown": "^0.22.5",
41
+ "typescript": "^5.9.3",
42
+ "vitest": "^4.1.10"
47
43
  },
48
44
  "publishConfig": {
49
- "access": "public",
50
- "main": "./dist/index.mjs",
51
- "types": "./dist/index.d.mts",
52
- "exports": {
53
- ".": {
54
- "types": "./dist/index.d.mts",
55
- "import": "./dist/index.mjs",
56
- "default": "./dist/index.mjs"
57
- }
58
- }
45
+ "access": "public"
59
46
  },
60
47
  "files": [
61
48
  "dist",
62
49
  "README.md"
63
50
  ],
51
+ "engines": {
52
+ "node": ">=22.0.0"
53
+ },
64
54
  "releases": "https://github.com/theholocron/clients/releases",
65
- "wiki": "https://github.com/theholocron/clients/wiki"
66
- }
55
+ "wiki": "https://github.com/theholocron/clients/wiki",
56
+ "scripts": {
57
+ "build": "tsdown",
58
+ "lint": "eslint .",
59
+ "test": "vitest run",
60
+ "test:watch": "vitest",
61
+ "test:coverage": "vitest run --coverage",
62
+ "typecheck": "tsc --noEmit"
63
+ },
64
+ "types": "./dist/index.d.mts"
65
+ }