@cyc-seattle/gsuite-sdk 0.0.0-stage → 0.1.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.
@@ -0,0 +1,225 @@
1
+ import { google } from "googleapis";
2
+ import winston from "winston";
3
+ import { getHttpStatus, safeCall } from "./common.js";
4
+ /** Ordering for `DirectoryClient.addMember`'s promotion check - never used to demote. */
5
+ const GROUP_ROLE_RANK = { MEMBER: 0, MANAGER: 1, OWNER: 2 };
6
+ /**
7
+ * Admin SDK Directory API client for groups and their members.
8
+ *
9
+ * A sub-group is added to another group the same way a user is: as a member
10
+ * with the sub-group's email address. There's no separate method for it.
11
+ */
12
+ export class DirectoryClient {
13
+ client;
14
+ constructor(auth) {
15
+ // The `directory_v1` cast is needed because `google.admin` also has overloads for
16
+ // two other API versions, which the `auth` cast below (needed for its own reasons —
17
+ // see CalendarClient) leaves TypeScript unable to discriminate between.
18
+ this.client = google.admin({ version: "directory_v1", auth });
19
+ }
20
+ /**
21
+ * Gets a group by email or ID. Returns null if the group doesn't exist.
22
+ */
23
+ async getGroup(groupKey) {
24
+ winston.debug("Getting group", { groupKey });
25
+ try {
26
+ // safeCall's generic argument must be given explicitly here: with `googleapis`
27
+ // resolved through pnpm's symlinked node_modules, TypeScript can't infer it from
28
+ // an overloaded API method passed as a callback.
29
+ const group = await safeCall(async () => {
30
+ const response = await this.client.groups.get({ groupKey });
31
+ return response.data;
32
+ });
33
+ return convertToGroup(group);
34
+ }
35
+ catch (error) {
36
+ if (getHttpStatus(error) === 404) {
37
+ winston.debug("Group not found", { groupKey });
38
+ return null;
39
+ }
40
+ throw error;
41
+ }
42
+ }
43
+ /**
44
+ * Lists every group for the given customer id, following pagination. No default: the
45
+ * `my_customer` alias resolves relative to the *authenticated user's* domain, which doesn't
46
+ * exist for a service account holding a direct admin role rather than impersonating a domain
47
+ * user - that path 404s ("Domain not found") instead of listing anything.
48
+ */
49
+ async listGroups(customer) {
50
+ winston.debug("Listing groups", { customer });
51
+ const groups = [];
52
+ let pageToken;
53
+ do {
54
+ const params = { customer };
55
+ if (pageToken) {
56
+ params.pageToken = pageToken;
57
+ }
58
+ const page = await safeCall(async () => {
59
+ const response = await this.client.groups.list(params);
60
+ return response.data;
61
+ });
62
+ groups.push(...(page.groups ?? []).map(convertToGroup));
63
+ pageToken = page.nextPageToken ?? undefined;
64
+ } while (pageToken);
65
+ return groups;
66
+ }
67
+ /**
68
+ * Creates a new group.
69
+ */
70
+ async createGroup(email, name, description) {
71
+ winston.debug("Creating group", { email });
72
+ // Built up rather than passed as a literal: under exactOptionalPropertyTypes, an
73
+ // absent optional field and one explicitly set to undefined are different types,
74
+ // and Schema$Group's fields are the former.
75
+ const requestBody = { email };
76
+ if (name) {
77
+ requestBody.name = name;
78
+ }
79
+ if (description) {
80
+ requestBody.description = description;
81
+ }
82
+ const group = await safeCall(async () => {
83
+ const response = await this.client.groups.insert({ requestBody });
84
+ return response.data;
85
+ });
86
+ winston.info("Created group", { email: group.email });
87
+ return convertToGroup(group);
88
+ }
89
+ /**
90
+ * Lists all members of a group, following pagination.
91
+ */
92
+ async listMembers(groupKey) {
93
+ winston.debug("Listing group members", { groupKey });
94
+ const members = [];
95
+ let pageToken;
96
+ do {
97
+ const params = { groupKey };
98
+ if (pageToken) {
99
+ params.pageToken = pageToken;
100
+ }
101
+ const page = await safeCall(async () => {
102
+ const response = await this.client.members.list(params);
103
+ return response.data;
104
+ });
105
+ members.push(...(page.members ?? []).map(convertToGroupMember));
106
+ pageToken = page.nextPageToken ?? undefined;
107
+ } while (pageToken);
108
+ return members;
109
+ }
110
+ /**
111
+ * Adds a member to a group with the given role. Returns "already-member"
112
+ * instead of throwing when the member is already in the group (HTTP 409),
113
+ * since the sync that calls this treats that as success - but first promotes
114
+ * them if they're already there at a lower role than intended (e.g. added by
115
+ * hand as a plain MEMBER). Never demotes: a member already at a higher role
116
+ * than planned is left alone.
117
+ */
118
+ async addMember(groupKey, email, role) {
119
+ winston.debug("Adding group member", { groupKey, email, role });
120
+ try {
121
+ await safeCall(async () => {
122
+ const response = await this.client.members.insert({ groupKey, requestBody: { email, role } });
123
+ return response.data;
124
+ });
125
+ winston.info("Added group member", { groupKey, email, role });
126
+ return "added";
127
+ }
128
+ catch (error) {
129
+ if (getHttpStatus(error) === 409) {
130
+ winston.debug("Member already in group", { groupKey, email });
131
+ await this.promoteIfBelow(groupKey, email, role);
132
+ return "already-member";
133
+ }
134
+ throw error;
135
+ }
136
+ }
137
+ /** The 409 path of `addMember`: promotes an existing member up to `role` if they're currently
138
+ * below it, and does nothing otherwise - including when they already outrank it. */
139
+ async promoteIfBelow(groupKey, email, role) {
140
+ if (role === "MEMBER") {
141
+ return;
142
+ }
143
+ const member = await safeCall(async () => {
144
+ const response = await this.client.members.get({ groupKey, memberKey: email });
145
+ return response.data;
146
+ });
147
+ const currentRole = member.role ?? "MEMBER";
148
+ if (GROUP_ROLE_RANK[currentRole] < GROUP_ROLE_RANK[role]) {
149
+ await this.updateMemberRole(groupKey, email, role);
150
+ }
151
+ }
152
+ /**
153
+ * Updates an existing member's role.
154
+ */
155
+ async updateMemberRole(groupKey, email, role) {
156
+ winston.debug("Updating group member role", { groupKey, email, role });
157
+ await safeCall(async () => {
158
+ const response = await this.client.members.update({ groupKey, memberKey: email, requestBody: { role } });
159
+ return response.data;
160
+ });
161
+ winston.info("Updated group member role", { groupKey, email, role });
162
+ }
163
+ }
164
+ function convertToGroup(group) {
165
+ const result = {
166
+ id: group.id,
167
+ email: group.email,
168
+ };
169
+ if (group.name) {
170
+ result.name = group.name;
171
+ }
172
+ if (group.description) {
173
+ result.description = group.description;
174
+ }
175
+ return result;
176
+ }
177
+ function convertToGroupMember(member) {
178
+ const result = {
179
+ email: member.email,
180
+ role: member.role,
181
+ };
182
+ if (member.type) {
183
+ result.type = member.type;
184
+ }
185
+ return result;
186
+ }
187
+ /**
188
+ * Groups Settings API client. Settings are a separate API from the Directory
189
+ * API's group resource — this covers permission-level fields like who can
190
+ * post or join, not membership.
191
+ */
192
+ export class GroupSettingsClient {
193
+ client;
194
+ constructor(auth) {
195
+ this.client = google.groupssettings({ version: "v1", auth });
196
+ }
197
+ /**
198
+ * Gets a group's settings.
199
+ */
200
+ async getSettings(groupEmail) {
201
+ winston.debug("Getting group settings", { groupEmail });
202
+ return safeCall(async () => {
203
+ // This API alone defaults to Atom XML; without alt=json, `data` is a string and every field
204
+ // reads as undefined.
205
+ const response = await this.client.groups.get({ groupUniqueId: groupEmail, alt: "json" });
206
+ return response.data;
207
+ });
208
+ }
209
+ /**
210
+ * Patches a group's settings from the given settings object.
211
+ */
212
+ async patchSettings(groupEmail, settings) {
213
+ winston.debug("Patching group settings", { groupEmail });
214
+ const result = await safeCall(async () => {
215
+ const response = await this.client.groups.patch({
216
+ groupUniqueId: groupEmail,
217
+ alt: "json",
218
+ requestBody: settings,
219
+ });
220
+ return response.data;
221
+ });
222
+ winston.info("Patched group settings", { groupEmail });
223
+ return result;
224
+ }
225
+ }
@@ -0,0 +1,13 @@
1
+ import { GroupSettings } from "./directory.js";
2
+ export declare const GROUP_SETTINGS_TEMPLATES: {
3
+ readonly announcement: import("googleapis").groupssettings_v1.Schema$Groups;
4
+ readonly crew: import("googleapis").groupssettings_v1.Schema$Groups;
5
+ readonly inbox: import("googleapis").groupssettings_v1.Schema$Groups;
6
+ readonly participants: import("googleapis").groupssettings_v1.Schema$Groups;
7
+ };
8
+ export type GroupSettingsTemplateName = keyof typeof GROUP_SETTINGS_TEMPLATES;
9
+ export declare const GROUP_SETTINGS_TEMPLATE_NAMES: GroupSettingsTemplateName[];
10
+ /** Looks up a template by name, e.g. what `google_groups.settings_template` stores. Throws on an
11
+ * unrecognized name rather than returning `null`, so a typo fails the settings pass for that group
12
+ * instead of leaving it silently unmanaged. */
13
+ export declare function resolveGroupSettingsTemplate(name: string): GroupSettings;
@@ -0,0 +1,249 @@
1
+ /**
2
+ * The four named Groups Settings templates staff choose from in the CRM, mirroring
3
+ * `gam/templates/*.json` - the break-glass GAM path's copy of these same settings. Keep the two in
4
+ * step; see `gam/README.md`.
5
+ *
6
+ * `allowExternalMembers: "true"` is load-bearing on `participants`: guardians are on personal
7
+ * Gmail, and without it they can be added to a group but receive nothing. A class group (members
8
+ * discuss among themselves) takes `participants`; a program group (a broadcast surface over its
9
+ * class sub-groups) takes `announcement`.
10
+ *
11
+ * Groups Settings fields are strings even where they read as booleans or enums - the API rejects
12
+ * real JSON booleans on several fields, so `"true"` and `"false"` here are deliberate, not typos.
13
+ * One field is `default_sender`, not `defaultSender` like the rest - `googleapis`'s generated
14
+ * `Schema$Groups` type names it that way, unlike the GAM files' camelCase copy.
15
+ */
16
+ const announcement = {
17
+ allowExternalMembers: "true",
18
+ allowWebPosting: "true",
19
+ archiveOnly: "false",
20
+ customFooterText: "",
21
+ customRolesEnabledForSettingsToBeMerged: "false",
22
+ defaultMessageDenyNotificationText: "",
23
+ default_sender: "DEFAULT_SELF",
24
+ enableCollaborativeInbox: "false",
25
+ includeCustomFooter: "false",
26
+ includeInGlobalAddressList: "true",
27
+ isArchived: "true",
28
+ maxMessageBytes: 26214400,
29
+ membersCanPostAsTheGroup: "false",
30
+ messageModerationLevel: "MODERATE_NONE",
31
+ replyTo: "REPLY_TO_IGNORE",
32
+ sendMessageDenyNotification: "true",
33
+ showInGroupDirectory: "false",
34
+ spamModerationLevel: "MODERATE",
35
+ whoCanAdd: "ALL_MANAGERS_CAN_ADD",
36
+ whoCanApproveMembers: "ALL_MANAGERS_CAN_APPROVE",
37
+ whoCanApproveMessages: "OWNERS_AND_MANAGERS",
38
+ whoCanAssignTopics: "OWNERS_AND_MANAGERS",
39
+ whoCanAssistContent: "OWNERS_AND_MANAGERS",
40
+ whoCanBanUsers: "OWNERS_AND_MANAGERS",
41
+ whoCanContactOwner: "ANYONE_CAN_CONTACT",
42
+ whoCanDeleteAnyPost: "OWNERS_AND_MANAGERS",
43
+ whoCanDeleteTopics: "OWNERS_AND_MANAGERS",
44
+ whoCanDiscoverGroup: "ALL_IN_DOMAIN_CAN_DISCOVER",
45
+ whoCanEnterFreeFormTags: "OWNERS_AND_MANAGERS",
46
+ whoCanHideAbuse: "OWNERS_AND_MANAGERS",
47
+ whoCanInvite: "ALL_MANAGERS_CAN_INVITE",
48
+ whoCanJoin: "INVITED_CAN_JOIN",
49
+ whoCanLeaveGroup: "ALL_MEMBERS_CAN_LEAVE",
50
+ whoCanLockTopics: "OWNERS_AND_MANAGERS",
51
+ whoCanMakeTopicsSticky: "OWNERS_AND_MANAGERS",
52
+ whoCanMarkDuplicate: "OWNERS_AND_MANAGERS",
53
+ whoCanMarkFavoriteReplyOnAnyTopic: "OWNERS_AND_MANAGERS",
54
+ whoCanMarkNoResponseNeeded: "OWNERS_AND_MANAGERS",
55
+ whoCanModerateContent: "OWNERS_AND_MANAGERS",
56
+ whoCanModerateMembers: "OWNERS_AND_MANAGERS",
57
+ whoCanModifyMembers: "OWNERS_AND_MANAGERS",
58
+ whoCanModifyTagsAndCategories: "OWNERS_AND_MANAGERS",
59
+ whoCanMoveTopicsIn: "OWNERS_AND_MANAGERS",
60
+ whoCanMoveTopicsOut: "OWNERS_AND_MANAGERS",
61
+ whoCanPostAnnouncements: "OWNERS_AND_MANAGERS",
62
+ whoCanPostMessage: "ALL_MANAGERS_CAN_POST",
63
+ whoCanTakeTopics: "OWNERS_AND_MANAGERS",
64
+ whoCanUnassignTopic: "OWNERS_AND_MANAGERS",
65
+ whoCanUnmarkFavoriteReplyOnAnyTopic: "OWNERS_AND_MANAGERS",
66
+ whoCanViewGroup: "ALL_MEMBERS_CAN_VIEW",
67
+ whoCanViewMembership: "ALL_MEMBERS_CAN_VIEW",
68
+ };
69
+ const crew = {
70
+ allowExternalMembers: "true",
71
+ allowWebPosting: "true",
72
+ archiveOnly: "false",
73
+ customFooterText: "",
74
+ customRolesEnabledForSettingsToBeMerged: "false",
75
+ defaultMessageDenyNotificationText: "",
76
+ default_sender: "DEFAULT_SELF",
77
+ enableCollaborativeInbox: "false",
78
+ favoriteRepliesOnTop: "true",
79
+ includeCustomFooter: "false",
80
+ includeInGlobalAddressList: "true",
81
+ isArchived: "true",
82
+ maxMessageBytes: 26214400,
83
+ membersCanPostAsTheGroup: "true",
84
+ messageDisplayFont: "DEFAULT_FONT",
85
+ messageModerationLevel: "MODERATE_NONE",
86
+ primaryLanguage: "en_US",
87
+ replyTo: "REPLY_TO_IGNORE",
88
+ sendMessageDenyNotification: "false",
89
+ showInGroupDirectory: "false",
90
+ spamModerationLevel: "REJECT",
91
+ whoCanAdd: "ALL_MANAGERS_CAN_ADD",
92
+ whoCanAddReferences: "NONE",
93
+ whoCanApproveMembers: "ALL_MANAGERS_CAN_APPROVE",
94
+ whoCanApproveMessages: "OWNERS_AND_MANAGERS",
95
+ whoCanAssignTopics: "ALL_MEMBERS",
96
+ whoCanAssistContent: "ALL_MEMBERS",
97
+ whoCanBanUsers: "OWNERS_AND_MANAGERS",
98
+ whoCanContactOwner: "ANYONE_CAN_CONTACT",
99
+ whoCanDeleteAnyPost: "OWNERS_AND_MANAGERS",
100
+ whoCanDeleteTopics: "OWNERS_AND_MANAGERS",
101
+ whoCanDiscoverGroup: "ALL_IN_DOMAIN_CAN_DISCOVER",
102
+ whoCanEnterFreeFormTags: "ALL_MEMBERS",
103
+ whoCanHideAbuse: "ALL_MEMBERS",
104
+ whoCanInvite: "ALL_MANAGERS_CAN_INVITE",
105
+ whoCanJoin: "INVITED_CAN_JOIN",
106
+ whoCanLeaveGroup: "ALL_MEMBERS_CAN_LEAVE",
107
+ whoCanLockTopics: "OWNERS_AND_MANAGERS",
108
+ whoCanMakeTopicsSticky: "ALL_MEMBERS",
109
+ whoCanMarkDuplicate: "ALL_MEMBERS",
110
+ whoCanMarkFavoriteReplyOnAnyTopic: "ALL_MEMBERS",
111
+ whoCanMarkFavoriteReplyOnOwnTopic: "ALL_MEMBERS",
112
+ whoCanMarkNoResponseNeeded: "ALL_MEMBERS",
113
+ whoCanModerateContent: "OWNERS_AND_MANAGERS",
114
+ whoCanModerateMembers: "OWNERS_AND_MANAGERS",
115
+ whoCanModifyMembers: "OWNERS_AND_MANAGERS",
116
+ whoCanModifyTagsAndCategories: "ALL_MEMBERS",
117
+ whoCanMoveTopicsIn: "OWNERS_AND_MANAGERS",
118
+ whoCanMoveTopicsOut: "OWNERS_AND_MANAGERS",
119
+ whoCanPostAnnouncements: "OWNERS_AND_MANAGERS",
120
+ whoCanPostMessage: "ANYONE_CAN_POST",
121
+ whoCanTakeTopics: "ALL_MEMBERS",
122
+ whoCanUnassignTopic: "ALL_MEMBERS",
123
+ whoCanUnmarkFavoriteReplyOnAnyTopic: "ALL_MEMBERS",
124
+ whoCanViewGroup: "ALL_MEMBERS_CAN_VIEW",
125
+ whoCanViewMembership: "ALL_MEMBERS_CAN_VIEW",
126
+ };
127
+ const inbox = {
128
+ allowExternalMembers: "true",
129
+ allowGoogleCommunication: "false",
130
+ allowWebPosting: "true",
131
+ archiveOnly: "false",
132
+ customFooterText: "",
133
+ customRolesEnabledForSettingsToBeMerged: "false",
134
+ defaultMessageDenyNotificationText: "",
135
+ default_sender: "GROUP",
136
+ enableCollaborativeInbox: "true",
137
+ favoriteRepliesOnTop: "true",
138
+ includeCustomFooter: "false",
139
+ includeInGlobalAddressList: "true",
140
+ isArchived: "true",
141
+ maxMessageBytes: 26214400,
142
+ membersCanPostAsTheGroup: "true",
143
+ messageDisplayFont: "DEFAULT_FONT",
144
+ messageModerationLevel: "MODERATE_NONE",
145
+ primaryLanguage: "en_US",
146
+ replyTo: "REPLY_TO_IGNORE",
147
+ sendMessageDenyNotification: "false",
148
+ showInGroupDirectory: "false",
149
+ spamModerationLevel: "MODERATE",
150
+ whoCanAdd: "ALL_MANAGERS_CAN_ADD",
151
+ whoCanAddReferences: "NONE",
152
+ whoCanApproveMembers: "ALL_MANAGERS_CAN_APPROVE",
153
+ whoCanApproveMessages: "ALL_MEMBERS",
154
+ whoCanAssignTopics: "OWNERS_AND_MANAGERS",
155
+ whoCanAssistContent: "OWNERS_AND_MANAGERS",
156
+ whoCanBanUsers: "OWNERS_AND_MANAGERS",
157
+ whoCanContactOwner: "ANYONE_CAN_CONTACT",
158
+ whoCanDeleteAnyPost: "ALL_MEMBERS",
159
+ whoCanDeleteTopics: "ALL_MEMBERS",
160
+ whoCanDiscoverGroup: "ALL_IN_DOMAIN_CAN_DISCOVER",
161
+ whoCanEnterFreeFormTags: "OWNERS_AND_MANAGERS",
162
+ whoCanHideAbuse: "OWNERS_AND_MANAGERS",
163
+ whoCanInvite: "ALL_MANAGERS_CAN_INVITE",
164
+ whoCanJoin: "INVITED_CAN_JOIN",
165
+ whoCanLeaveGroup: "ALL_MEMBERS_CAN_LEAVE",
166
+ whoCanLockTopics: "ALL_MEMBERS",
167
+ whoCanMakeTopicsSticky: "OWNERS_AND_MANAGERS",
168
+ whoCanMarkDuplicate: "OWNERS_AND_MANAGERS",
169
+ whoCanMarkFavoriteReplyOnAnyTopic: "OWNERS_AND_MANAGERS",
170
+ whoCanMarkFavoriteReplyOnOwnTopic: "OWNERS_AND_MANAGERS",
171
+ whoCanMarkNoResponseNeeded: "OWNERS_AND_MANAGERS",
172
+ whoCanModerateContent: "ALL_MEMBERS",
173
+ whoCanModerateMembers: "OWNERS_AND_MANAGERS",
174
+ whoCanModifyMembers: "OWNERS_AND_MANAGERS",
175
+ whoCanModifyTagsAndCategories: "OWNERS_AND_MANAGERS",
176
+ whoCanMoveTopicsIn: "ALL_MEMBERS",
177
+ whoCanMoveTopicsOut: "ALL_MEMBERS",
178
+ whoCanPostAnnouncements: "ALL_MEMBERS",
179
+ whoCanPostMessage: "ANYONE_CAN_POST",
180
+ whoCanTakeTopics: "OWNERS_AND_MANAGERS",
181
+ whoCanUnassignTopic: "OWNERS_AND_MANAGERS",
182
+ whoCanUnmarkFavoriteReplyOnAnyTopic: "OWNERS_AND_MANAGERS",
183
+ whoCanViewGroup: "ALL_MEMBERS_CAN_VIEW",
184
+ whoCanViewMembership: "ALL_MEMBERS_CAN_VIEW",
185
+ };
186
+ const participants = {
187
+ allowExternalMembers: "true",
188
+ allowWebPosting: "true",
189
+ archiveOnly: "false",
190
+ customFooterText: "",
191
+ customRolesEnabledForSettingsToBeMerged: "false",
192
+ defaultMessageDenyNotificationText: "",
193
+ default_sender: "DEFAULT_SELF",
194
+ enableCollaborativeInbox: "false",
195
+ includeCustomFooter: "false",
196
+ includeInGlobalAddressList: "true",
197
+ isArchived: "true",
198
+ maxMessageBytes: 26214400,
199
+ membersCanPostAsTheGroup: "false",
200
+ messageModerationLevel: "MODERATE_NONE",
201
+ replyTo: "REPLY_TO_IGNORE",
202
+ sendMessageDenyNotification: "true",
203
+ showInGroupDirectory: "false",
204
+ spamModerationLevel: "MODERATE",
205
+ whoCanAdd: "ALL_MANAGERS_CAN_ADD",
206
+ whoCanApproveMembers: "ALL_MANAGERS_CAN_APPROVE",
207
+ whoCanApproveMessages: "OWNERS_AND_MANAGERS",
208
+ whoCanAssignTopics: "OWNERS_AND_MANAGERS",
209
+ whoCanAssistContent: "OWNERS_AND_MANAGERS",
210
+ whoCanBanUsers: "OWNERS_AND_MANAGERS",
211
+ whoCanContactOwner: "ANYONE_CAN_CONTACT",
212
+ whoCanDeleteAnyPost: "OWNERS_AND_MANAGERS",
213
+ whoCanDeleteTopics: "OWNERS_AND_MANAGERS",
214
+ whoCanDiscoverGroup: "ALL_IN_DOMAIN_CAN_DISCOVER",
215
+ whoCanEnterFreeFormTags: "OWNERS_AND_MANAGERS",
216
+ whoCanHideAbuse: "OWNERS_AND_MANAGERS",
217
+ whoCanInvite: "ALL_MANAGERS_CAN_INVITE",
218
+ whoCanJoin: "INVITED_CAN_JOIN",
219
+ whoCanLeaveGroup: "ALL_MEMBERS_CAN_LEAVE",
220
+ whoCanLockTopics: "OWNERS_AND_MANAGERS",
221
+ whoCanMakeTopicsSticky: "OWNERS_AND_MANAGERS",
222
+ whoCanMarkDuplicate: "OWNERS_AND_MANAGERS",
223
+ whoCanMarkFavoriteReplyOnAnyTopic: "OWNERS_AND_MANAGERS",
224
+ whoCanMarkNoResponseNeeded: "OWNERS_AND_MANAGERS",
225
+ whoCanModerateContent: "OWNERS_AND_MANAGERS",
226
+ whoCanModerateMembers: "OWNERS_AND_MANAGERS",
227
+ whoCanModifyMembers: "OWNERS_AND_MANAGERS",
228
+ whoCanModifyTagsAndCategories: "OWNERS_AND_MANAGERS",
229
+ whoCanMoveTopicsIn: "OWNERS_AND_MANAGERS",
230
+ whoCanMoveTopicsOut: "OWNERS_AND_MANAGERS",
231
+ whoCanPostAnnouncements: "OWNERS_AND_MANAGERS",
232
+ whoCanPostMessage: "ALL_MEMBERS_CAN_POST",
233
+ whoCanTakeTopics: "OWNERS_AND_MANAGERS",
234
+ whoCanUnassignTopic: "OWNERS_AND_MANAGERS",
235
+ whoCanUnmarkFavoriteReplyOnAnyTopic: "OWNERS_AND_MANAGERS",
236
+ whoCanViewGroup: "ALL_MEMBERS_CAN_VIEW",
237
+ whoCanViewMembership: "ALL_MEMBERS_CAN_VIEW",
238
+ };
239
+ export const GROUP_SETTINGS_TEMPLATES = { announcement, crew, inbox, participants };
240
+ export const GROUP_SETTINGS_TEMPLATE_NAMES = Object.keys(GROUP_SETTINGS_TEMPLATES);
241
+ /** Looks up a template by name, e.g. what `google_groups.settings_template` stores. Throws on an
242
+ * unrecognized name rather than returning `null`, so a typo fails the settings pass for that group
243
+ * instead of leaving it silently unmanaged. */
244
+ export function resolveGroupSettingsTemplate(name) {
245
+ if (!Object.prototype.hasOwnProperty.call(GROUP_SETTINGS_TEMPLATES, name)) {
246
+ throw new Error(`Unknown Google Group settings template "${name}"; expected one of ${GROUP_SETTINGS_TEMPLATE_NAMES.join(", ")}`);
247
+ }
248
+ return GROUP_SETTINGS_TEMPLATES[name];
249
+ }
@@ -0,0 +1,5 @@
1
+ export * from "./common.js";
2
+ export * from "./calendar.js";
3
+ export * from "./spreadsheet.js";
4
+ export * from "./directory.js";
5
+ export * from "./group-settings-templates.js";
package/dist/index.js ADDED
@@ -0,0 +1,5 @@
1
+ export * from "./common.js";
2
+ export * from "./calendar.js";
3
+ export * from "./spreadsheet.js";
4
+ export * from "./directory.js";
5
+ export * from "./group-settings-templates.js";
@@ -0,0 +1,111 @@
1
+ import { GoogleSpreadsheet, GoogleSpreadsheetCellErrorValue, GoogleSpreadsheetWorksheet } from "google-spreadsheet";
2
+ import { Auth, sheets_v4 } from "googleapis";
3
+ type RowValueType = number | boolean | string | Date | undefined;
4
+ type CachedValue = number | boolean | string | Date | null | GoogleSpreadsheetCellErrorValue;
5
+ export type Row = Record<string, RowValueType>;
6
+ export type RowKeys<T extends Row> = Extract<keyof T, string>;
7
+ export type HeaderValues<T extends Row> = RowKeys<T>[];
8
+ interface AddOrUpdateResult {
9
+ readonly existing: boolean;
10
+ }
11
+ /**
12
+ * Represents a table in a Google Spreadsheet with cached cell access
13
+ */
14
+ export declare class Table<T extends Row> {
15
+ private readonly worksheet;
16
+ private readonly headerColumns;
17
+ private readonly addedRows;
18
+ private readonly valueCache;
19
+ constructor(worksheet: GoogleSpreadsheetWorksheet, headerColumns: Map<string, number>);
20
+ private cacheKey;
21
+ getCellValue(header: RowKeys<T>, rowIndex: number): CachedValue | undefined;
22
+ /**
23
+ * Finds all rows (by index) containing the values in "needle". This object may be a partial record to only
24
+ * match on key fields.
25
+ */
26
+ findRows(needle: Partial<T>): number[];
27
+ updateRow(rowIndex: number, values: Partial<T>): void;
28
+ addRow(values: Partial<T>): void;
29
+ updateRows(keys: HeaderValues<T>, values: Partial<T>): void;
30
+ /**
31
+ * Updates ALL rows where the key columns matched the supplied values, or if
32
+ * no such rows exist, adds a new one.
33
+ */
34
+ addOrUpdate(keys: HeaderValues<T>, values: Partial<T>): AddOrUpdateResult;
35
+ save(reload?: boolean): Promise<void>;
36
+ }
37
+ /**
38
+ * Represents a worksheet in a Google Spreadsheet
39
+ */
40
+ export declare class Worksheet<T extends Row> {
41
+ private readonly worksheet;
42
+ constructor(worksheet: GoogleSpreadsheetWorksheet);
43
+ /** The numeric sheet id, needed to target this worksheet in raw Sheets API requests. */
44
+ get sheetId(): number;
45
+ getRows(): Promise<import("google-spreadsheet").GoogleSpreadsheetRow<T>[]>;
46
+ getTable(): Promise<Table<T>>;
47
+ }
48
+ /**
49
+ * Extended GoogleSpreadsheet with helper methods
50
+ */
51
+ export declare class Spreadsheet extends GoogleSpreadsheet {
52
+ private createWorksheet;
53
+ getOrCreateWorksheet<T extends Row>(title: string, headerValues: HeaderValues<T>): Promise<Worksheet<T>>;
54
+ /**
55
+ * Adds a worksheet with the given headers, returning the typed wrapper. Unlike
56
+ * {@link getOrCreateWorksheet}, this always creates a new sheet (used when building a
57
+ * fresh spreadsheet where each tab is written once).
58
+ */
59
+ addWorksheet<T extends Row>(title: string, headerValues: HeaderValues<T>): Promise<Worksheet<T>>;
60
+ /** Deletes the worksheet with the given title, if it exists. */
61
+ deleteWorksheet(title: string): Promise<void>;
62
+ /**
63
+ * Clears every existing worksheet so the spreadsheet can be rebuilt from scratch,
64
+ * leaving a single empty placeholder sheet (a spreadsheet must always have ≥1 sheet).
65
+ * The placeholder is created first so it survives while the originals are deleted, and
66
+ * its title is returned so the caller can remove it after adding the real sheets.
67
+ */
68
+ resetSheets(): Promise<string>;
69
+ }
70
+ /**
71
+ * Client for loading Google Spreadsheets
72
+ */
73
+ export declare class SpreadsheetClient {
74
+ private readonly auth;
75
+ constructor(auth: Auth.GoogleAuth);
76
+ /**
77
+ * Creates a new, empty Google Spreadsheet inside the given Drive folder and returns it
78
+ * loaded and ready to write.
79
+ *
80
+ * The Drive API is used (rather than google-spreadsheet's createNewSpreadsheetDocument,
81
+ * which only lands the file in "My Drive") so the file can be parented directly in a
82
+ * folder. `supportsAllDrives` is required because our target folders live in shared
83
+ * drives. Requires the `drive` OAuth scope.
84
+ */
85
+ createSpreadsheet(title: string, folderId: string): Promise<Spreadsheet>;
86
+ /**
87
+ * Finds the id of a non-trashed spreadsheet with the exact given name inside the folder,
88
+ * or undefined if none exists. `supportsAllDrives` / `includeItemsFromAllDrives` are set
89
+ * because our folders live in shared drives.
90
+ */
91
+ findSpreadsheetInFolder(title: string, folderId: string): Promise<string | undefined>;
92
+ /**
93
+ * Returns a spreadsheet named `title` in the folder, ready to be rebuilt: if one already
94
+ * exists it is reused (and its sheets cleared) so the file id / URL stays stable across
95
+ * runs; otherwise a new one is created. The returned `placeholderTitle` is a throwaway
96
+ * sheet the caller should delete after adding the real worksheets.
97
+ */
98
+ getOrCreateSpreadsheet(title: string, folderId: string): Promise<{
99
+ spreadsheet: Spreadsheet;
100
+ placeholderTitle: string;
101
+ reused: boolean;
102
+ }>;
103
+ /**
104
+ * Applies raw Sheets API requests (formatting, banding, borders, etc.) that the
105
+ * google-spreadsheet abstraction doesn't expose. Requests are sent as a single atomic
106
+ * batchUpdate.
107
+ */
108
+ batchUpdate(spreadsheetId: string, requests: sheets_v4.Schema$Request[]): Promise<void>;
109
+ loadSpreadsheet(spreadsheetUrlOrId: string): Promise<Spreadsheet>;
110
+ }
111
+ export {};