@homeflare/alchemy 0.29.0 → 0.30.0

package/src/google-workspace/domain-alias.ts

@@ -0,0 +1,116 @@
+/**
+ * `GoogleWorkspace.DomainAlias` — one secondary-domain alias on the Workspace account
+ * (`admin/directory/v1/customer/{customer}/domainaliases`).
+ *
+ * ⛔ NO `update` OPERATION EXISTS. The Directory API ships `get`/`insert`/`delete`/`list` for
+ *   domain aliases and nothing else — measured against `admin_directory_v1.ts`: there is no
+ *   `patchDomainAliases` or `updateDomainAliases`. `spec.update` is intentionally absent, so
+ *   `resource.ts`'s `diff` reports `replace` for any drift rather than an unsendable PATCH — the
+ *   same fallback NetBox's `netboxOperations` and Forgejo's `forgejoOperations` give a spec with
+ *   no `update`.
+ *
+ * ★ `domainAliasName` IS THE WHOLE IDENTITY. `parentDomainName` only matters at create time —
+ *   Google refuses reparenting an alias in place, so a declared `parentDomainName` that no longer
+ *   matches the live row is exactly the identity change `replace` exists for.
+ *
+ * ⚠️ THE HOUSE'S CLOUDFLARE ZONES (`homeflare.dev`, `aimto.app`, `schenanigans.com`, `taslabs.net`
+ *   — `site/live.site.json` in homeflare-landscape) are DNS zones, not Workspace domains by
+ *   themselves; a zone only becomes a valid `parentDomainName` once it is added and verified as a
+ *   primary or secondary domain in the Workspace admin console. This family does not verify a
+ *   domain — Google's verification is a TXT/CNAME challenge outside the Directory API's write
+ *   surface — so `create` will fail with `BadRequest` against an unverified domain, which is
+ *   correct: nothing here should silently paper over a step the account owner has to do by hand.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as directory from '@distilled.cloud/google-workspace/unstable/admin_directory_v1';
+import * as Effect from 'effect/Effect';
+import type { GoogleWorkspaceRequirements, GoogleWorkspaceSpec } from './resource.ts';
+import { googleWorkspaceHandlers } from './resource.ts';
+import { bool, ciEqual, text } from './values.ts';
+
+export interface DomainAliasProps {
+  /** The unique id for the Workspace account, or `my_customer` for the caller's own account. */
+  customer?: string;
+  /** The alias domain name — primary key for locate. */
+  domainAliasName: string;
+  /** The primary or secondary domain this alias resolves to. Immutable — a change replaces. */
+  parentDomainName: string;
+}
+
+export interface DomainAliasAttributes {
+  customer: string;
+  domainAliasName: string;
+  parentDomainName: string;
+  /** Read-only. */
+  verified: boolean;
+  /** Read-only, ISO-ish epoch-ms string as Google returns it. */
+  creationTime: string;
+}
+
+export interface GoogleWorkspaceDomainAlias extends Resource<
+  'GoogleWorkspace.DomainAlias',
+  DomainAliasProps,
+  DomainAliasAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceDomainAlias = Resource<GoogleWorkspaceDomainAlias>(
+  'GoogleWorkspace.DomainAlias',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+const customerOf = (props: DomainAliasProps): string => props.customer ?? 'my_customer';
+
+const attributesOf = (
+  live: directory.DomainAlias,
+  props: DomainAliasProps,
+): DomainAliasAttributes | undefined => {
+  if (live.domainAliasName === undefined || !ciEqual(live.domainAliasName, props.domainAliasName)) {
+    return undefined;
+  }
+  return {
+    creationTime: text(live.creationTime),
+    customer: customerOf(props),
+    domainAliasName: live.domainAliasName,
+    parentDomainName: text(live.parentDomainName),
+    verified: bool(live.verified),
+  };
+};
+
+/** ★ EXPORTED for direct testing — see domain-alias.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  DomainAliasProps,
+  directory.DomainAlias,
+  DomainAliasAttributes,
+  | directory.GetDomainAliasesError
+  | directory.InsertDomainAliasesError
+  | directory.DeleteDomainAliasesError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertDomainAliases({
+      body: { domainAliasName: props.domainAliasName, parentDomainName: props.parentDomainName },
+      customer: customerOf(props),
+    }),
+  describe: (props) => `customer/${customerOf(props)}/domainaliases/${props.domainAliasName}`,
+  destroy: (props, live) =>
+    directory.deleteDomainAliases({
+      customer: customerOf(props),
+      domainAliasName: text(live.domainAliasName) || props.domainAliasName,
+    }),
+  fetchLive: (props) =>
+    directory
+      .getDomainAliases({ customer: customerOf(props), domainAliasName: props.domainAliasName })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) => attributes.parentDomainName === props.parentDomainName,
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceDomainAliasProvider = () =>
+  Provider.effect(
+    GoogleWorkspaceDomainAlias,
+    Effect.succeed(GoogleWorkspaceDomainAlias.Provider.of(handlers)),
+  );

package/src/google-workspace/fake-google-workspace.ts

@@ -0,0 +1,54 @@
+/**
+ * A minimal in-memory Directory API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring
+ * `../netbox/fake-netbox.ts` and `../forgejo/fake-forgejo.ts`. Tests exercise distilled's REAL
+ * path assembly, JSON encode/decode and status→typed-error matching (`404` → `NotFound`, `403` →
+ * `Forbidden`, …) — nothing about that matching is re-implemented here, only the wire responses a
+ * scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. The token is a placeholder that is never a real bearer token, and
+ *   no request this fake answers ever leaves the process.
+ */
+import { type Credentials, fromAccessToken } from '@distilled.cloud/google-workspace/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_TOKEN = 'placeholder-google-workspace-token';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** Google's own `{ error: { code, message, status } }` failure envelope — matching protocol.ts. */
+export const fakeFailure = (status: number, message: string, googleStatus: string) =>
+  Response.json({ error: { code: status, message, status: googleStatus } }, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature. A test that expects no request at all asserts `seen` is empty.
+ */
+export const fakeGoogleWorkspace = (route: (method: string, url: URL) => Response) => {
+  const seen: Seen[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    return route(request.method, url);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen };
+};
+
+/**
+ * distilled Credentials + the real FetchHttpClient over the fake — `GoogleWorkspaceOpContext`,
+ * what every resource file's exported `spec.fetchLive` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers` (each resource file's `googleWorkspaceHandlers(spec)` export).
+ *   `handlers` bakes in `CredentialsFromEnv`, which resolves `GOOGLE_ACCESS_TOKEN` through
+ *   Effect's `Config` — whose default provider snapshots `process.env` once and never re-reads it
+ *   (measured in the forgejo migration, kit PR 180). So a test cannot point `handlers` at a fake
+ *   server; it calls `spec.fetchLive`/`spec.attributes` directly instead, with this explicit
+ *   layer, exercising exactly the same production code without that env seam.
+ */
+export const fakeGoogleWorkspaceLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = fromAccessToken({ accessToken: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/google-workspace/group-member.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `GoogleWorkspace.GroupMember`'s `spec` against a fake Directory API — unlike
+ * `Forgejo.TeamMember`, this membership has mutable fields (`role`, `deliverySettings`), so
+ * `matches` can see real drift, not just existence.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import {
+  fakeFailure,
+  fakeGoogleWorkspace,
+  fakeGoogleWorkspaceLayer,
+} from './fake-google-workspace.ts';
+import { spec } from './group-member.ts';
+
+// ⚠️ `@` is percent-encoded by the SDK's own path-token encoder — match the wire form (see the
+//   same note in group.test.ts).
+const MEMBER_PATH =
+  '/admin/directory/v1/groups/team%40schenanigans.com/members/tim%40schenanigans.com';
+const props = {
+  email: 'tim@schenanigans.com',
+  group: 'team@schenanigans.com',
+  role: 'OWNER' as const,
+};
+
+const readThrough = (fetchFn: typeof globalThis.fetch) =>
+  Effect.runPromise(
+    spec.fetchLive(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+      Effect.provide(fakeGoogleWorkspaceLayer(fetchFn)),
+    ),
+  );
+
+describe('GoogleWorkspace.GroupMember spec.fetchLive + spec.attributes', () => {
+  test('a live member decodes with its role and delivery settings', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === MEMBER_PATH
+        ? Response.json({
+            delivery_settings: 'ALL_MAIL',
+            email: 'tim@schenanigans.com',
+            id: 'member-1',
+            role: 'OWNER',
+            status: 'ACTIVE',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      deliverySettings: 'ALL_MAIL',
+      email: 'tim@schenanigans.com',
+      group: 'team@schenanigans.com',
+      memberId: 'member-1',
+      role: 'OWNER',
+      status: 'ACTIVE',
+    });
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(404, 'not found', 'NOT_FOUND'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});
+
+describe('GoogleWorkspace.GroupMember spec.matches — role and delivery drift', () => {
+  const live = {
+    deliverySettings: 'ALL_MAIL',
+    email: 'tim@schenanigans.com',
+    group: 'team@schenanigans.com',
+    memberId: 'member-1',
+    role: 'MEMBER',
+    status: 'ACTIVE',
+  };
+
+  test('a declared role different from live is drift', () => {
+    expect(spec.matches(live, props)).toBe(false);
+  });
+
+  test('the same role, and an undeclared deliverySettings converging to ALL_MAIL, is no drift', () => {
+    expect(spec.matches({ ...live, role: 'OWNER' }, props)).toBe(true);
+  });
+
+  test('a declared deliverySettings different from live is drift even with a matching role', () => {
+    expect(
+      spec.matches(
+        { ...live, deliverySettings: 'DIGEST', role: 'OWNER' },
+        {
+          ...props,
+          deliverySettings: 'NONE',
+        },
+      ),
+    ).toBe(false);
+  });
+});

package/src/google-workspace/group-member.ts

@@ -0,0 +1,126 @@
+/**
+ * `GoogleWorkspace.GroupMember` — one user or group's membership in one Directory group.
+ *
+ * ★ WHY THIS DOES NOT MODEL A `GoogleWorkspace.User`. `email` here identifies whoever the group
+ *   member is (a user's primary email, or another group's), the same way Forgejo's
+ *   `TeamMember.username` (team-member.ts) never creates the account it references. The Directory
+ *   API needs no user resource to exist in this family for a membership to be declared — see
+ *   group.ts's own note on why users are out of scope.
+ *
+ * ⚠️ UNLIKE `Forgejo.TeamMember`, A MEMBERSHIP HERE IS NOT EXISTENCE-ONLY. `role`
+ *   (`OWNER`/`MANAGER`/`MEMBER`) and `deliverySettings` (`ALL_MAIL`/`DIGEST`/`DAILY`/`NONE`/
+ *   `DISABLED`) are both mutable in place via `patchMembers` — so this spec declares `update`,
+ *   not `upsert`, the same shape `group.ts`/`domain-alias.ts` use.
+ *
+ * ⛔ GROUP CYCLES ARE THE VENDOR'S TO REFUSE, NOT THIS FAMILY'S. `insertMembers`/`patchMembers`
+ *   surface a cycle as `BadRequest`, which this spec's error union already carries un-narrowed —
+ *   nothing here guesses at "member is itself an ancestor group".
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as directory from '@distilled.cloud/google-workspace/unstable/admin_directory_v1';
+import * as Effect from 'effect/Effect';
+import type { GoogleWorkspaceRequirements, GoogleWorkspaceSpec } from './resource.ts';
+import { googleWorkspaceHandlers } from './resource.ts';
+import { ciEqual, text } from './values.ts';
+
+export type MemberRole = 'OWNER' | 'MANAGER' | 'MEMBER';
+export type DeliverySettings = 'ALL_MAIL' | 'DIGEST' | 'DAILY' | 'NONE' | 'DISABLED';
+
+export interface GroupMemberProps {
+  /** The group's email, alias or id — same key `Group.email` declares. */
+  group: string;
+  /** The member's email (a user or another group). Primary key alongside `group`. */
+  email: string;
+  /** @default 'MEMBER' */
+  role?: MemberRole;
+  /** @default 'ALL_MAIL' */
+  deliverySettings?: DeliverySettings;
+}
+
+export interface GroupMemberAttributes {
+  group: string;
+  email: string;
+  memberId: string;
+  role: string;
+  deliverySettings: string;
+  /** Read-only — `ACTIVE` for a normal member, `PENDING` while an invite is outstanding. */
+  status: string;
+}
+
+export interface GoogleWorkspaceGroupMember extends Resource<
+  'GoogleWorkspace.GroupMember',
+  GroupMemberProps,
+  GroupMemberAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceGroupMember = Resource<GoogleWorkspaceGroupMember>(
+  'GoogleWorkspace.GroupMember',
+);
+
+const defaultRole = (props: GroupMemberProps): MemberRole => props.role ?? 'MEMBER';
+const defaultDelivery = (props: GroupMemberProps): DeliverySettings =>
+  props.deliverySettings ?? 'ALL_MAIL';
+
+const attributesOf = (
+  live: directory.Member,
+  props: GroupMemberProps,
+): GroupMemberAttributes | undefined => {
+  if (live.email === undefined || !ciEqual(live.email, props.email)) return undefined;
+  return {
+    deliverySettings: text(live.delivery_settings),
+    email: live.email,
+    group: props.group,
+    memberId: text(live.id),
+    role: text(live.role),
+    status: text(live.status),
+  };
+};
+
+/** ★ EXPORTED for direct testing — see group-member.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  GroupMemberProps,
+  directory.Member,
+  GroupMemberAttributes,
+  | directory.GetMembersError
+  | directory.InsertMembersError
+  | directory.PatchMembersError
+  | directory.DeleteMembersError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertMembers({
+      body: {
+        delivery_settings: defaultDelivery(props),
+        email: props.email,
+        role: defaultRole(props),
+      },
+      groupKey: props.group,
+    }),
+  describe: (props) => `groups/${props.group}/members/${props.email}`,
+  destroy: (props, live) =>
+    directory.deleteMembers({ groupKey: props.group, memberKey: text(live.id) || props.email }),
+  fetchLive: (props) =>
+    directory
+      .getMembers({ groupKey: props.group, memberKey: props.email })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.role === defaultRole(props) &&
+    attributes.deliverySettings === defaultDelivery(props),
+  update: (props, live) =>
+    directory.patchMembers({
+      body: { delivery_settings: defaultDelivery(props), role: defaultRole(props) },
+      groupKey: props.group,
+      memberKey: text(live.id) || props.email,
+    }),
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceGroupMemberProvider = () =>
+  Provider.effect(
+    GoogleWorkspaceGroupMember,
+    Effect.succeed(GoogleWorkspaceGroupMember.Provider.of(handlers)),
+  );

package/src/google-workspace/group.test.ts

@@ -0,0 +1,93 @@
+/**
+ * `GoogleWorkspace.Group`'s `spec` against a fake Directory API — get-by-key, unlike NetBox's
+ * list-then-disambiguate (resource.ts's own note on why this family never needs `locateOne`).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import {
+  fakeFailure,
+  fakeGoogleWorkspace,
+  fakeGoogleWorkspaceLayer,
+} from './fake-google-workspace.ts';
+import { spec } from './group.ts';
+
+// ⚠️ `@` is percent-encoded by the SDK's own path-token encoder (`encodeURIComponent`), and
+//   `URL#pathname` does not decode an already-encoded sequence back — match the wire form.
+const GROUP_PATH = '/admin/directory/v1/groups/team%40schenanigans.com';
+const props = { email: 'team@schenanigans.com', name: 'Team', description: 'the team' };
+
+const readThrough = (fetchFn: typeof globalThis.fetch) =>
+  Effect.runPromise(
+    spec.fetchLive(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+      Effect.provide(fakeGoogleWorkspaceLayer(fetchFn)),
+    ),
+  );
+
+describe('GoogleWorkspace.Group spec.fetchLive + spec.attributes', () => {
+  test('a live group decodes into the full attribute set — adopt(true) exact-as-live', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({
+            adminCreated: true,
+            aliases: ['old-team@schenanigans.com'],
+            description: 'the team',
+            directMembersCount: '3',
+            email: 'team@schenanigans.com',
+            id: '01234567890',
+            name: 'Team',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      adminCreated: true,
+      aliases: ['old-team@schenanigans.com'],
+      description: 'the team',
+      directMembersCount: '3',
+      email: 'team@schenanigans.com',
+      groupId: '01234567890',
+      name: 'Team',
+      nonEditableAliases: [],
+    });
+  });
+
+  test('a 404 folds to undefined — the standard "not created yet" case', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(404, 'not found', 'NOT_FOUND'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+
+  test('a 403 propagates unfolded — never treated as absent', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(403, 'forbidden', 'PERMISSION_DENIED'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('GoogleWorkspace.Group spec.matches', () => {
+  const live = {
+    adminCreated: false,
+    aliases: [],
+    description: 'the team',
+    directMembersCount: '0',
+    email: 'team@schenanigans.com',
+    groupId: 'x',
+    name: 'Team',
+    nonEditableAliases: [],
+  };
+
+  test('declared description and name equal to live — no drift', () => {
+    expect(spec.matches(live, props)).toBe(true);
+  });
+
+  test('a changed description is drift', () => {
+    expect(spec.matches(live, { ...props, description: 'a different team' })).toBe(false);
+  });
+
+  test('an undeclared name converges to the email local-part deterministically', () => {
+    const { name: _name, ...withoutName } = props;
+    expect(spec.matches({ ...live, name: 'team' }, withoutName)).toBe(true);
+    expect(spec.matches(live, withoutName)).toBe(false);
+  });
+});

package/src/google-workspace/group.ts

@@ -0,0 +1,128 @@
+/**
+ * `GoogleWorkspace.Group` — one Admin SDK Directory group (`admin/directory/v1/groups`).
+ *
+ * ★ WHY A GROUP IS THE FIRST OBJECT CLASS, AND NOT A USER. The estate's own Cloudflare Access
+ *   policies already reference Workspace groups by name ("Schenanigans - Admin", "Schenanigans -
+ *   Google" — `docs/zero-trust-access-applications.md` in homeflare-landscape) as the Google IdP
+ *   groups an Access rule allows. A group is also the one Directory object with no foreign-key
+ *   prerequisite: `email` is the whole identity, the same reasoning `netbox/prefix.ts` gives for
+ *   starting with `Prefix` over `Device`.
+ *
+ * ⛔ USERS ARE OUT OF SCOPE FOR THIS FAMILY. `insertUsers`/`patchUsers`/`updateUsers` all accept a
+ *   `password` field on the wire `User` schema — modelling `GoogleWorkspace.User` here would put a
+ *   credential-shaped field one keystroke away from becoming a prop, and Alchemy persists props
+ *   unencrypted (S25). No stack in this estate declares a Workspace user today (measured
+ *   2026-09-24 — see docs/upstream-conformance.md), so there is no house need forcing the
+ *   question. `GroupMember` (group-member.ts) references a user by email without ever creating,
+ *   reading or storing one.
+ *
+ * ★ ADOPT-FRIENDLY BY CONSTRUCTION. `groupKey` accepts an email, alias or id; this family always
+ *   uses `email` so `fetchLive` binds the live group by the same key a human would type. An
+ *   instance that already has `admin@schenanigans.com`'s "Schenanigans - Admin" group is BOUND,
+ *   never duplicated, and `attributes` maps the full live row — the exact-as-live half of
+ *   `adopt(true)` (resource.ts's own note).
+ *
+ * ⛔ THIS RESOURCE DOES NOT DELETE BY DEFAULT. `defaultRemovalPolicy: 'retain'` — removing a group
+ *   an Access policy still names would break sign-in for everyone that rule allows. `delete` stays
+ *   fully implemented; a caller opts in with `.pipe(RemovalPolicy.destroy())`.
+ *
+ * ⛔ NO CREDENTIAL IS A PROP. `GOOGLE_ACCESS_TOKEN` is read from the environment at call time,
+ *   through `@distilled.cloud/google-workspace`'s `CredentialsFromEnv` (resource.ts) — see
+ *   credentials.ts for where that token comes from.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as directory from '@distilled.cloud/google-workspace/unstable/admin_directory_v1';
+import * as Effect from 'effect/Effect';
+import type { GoogleWorkspaceRequirements, GoogleWorkspaceSpec } from './resource.ts';
+import { googleWorkspaceHandlers } from './resource.ts';
+import { ciEqual, stringArray, text } from './values.ts';
+
+export interface GroupProps {
+  /** The group's email address — the primary key for locate, create and update alike. */
+  email: string;
+  /** Display name. @default the local part of `email` */
+  name?: string;
+  /** Free text, up to 4,096 characters per the Directory API. */
+  description?: string;
+}
+
+export interface GroupAttributes {
+  email: string;
+  name: string;
+  description: string;
+  groupId: string;
+  /** Read-only — direct members, as a decimal string on the wire (Directory's own choice). */
+  directMembersCount: string;
+  /** Read-only. Aliases outside the primary domain/subdomains; edited only via alias endpoints. */
+  nonEditableAliases: string[];
+  /** Read-only. Aliases within the account's domains; edited only via alias endpoints. */
+  aliases: string[];
+  adminCreated: boolean;
+}
+
+export interface GoogleWorkspaceGroup extends Resource<
+  'GoogleWorkspace.Group',
+  GroupProps,
+  GroupAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceGroup = Resource<GoogleWorkspaceGroup>('GoogleWorkspace.Group', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Un-declared `name` converges here — deterministic, so an undeclared field never drifts. */
+const defaultName = (props: GroupProps): string =>
+  props.name ?? props.email.split('@')[0] ?? props.email;
+
+const attributesOf = (live: directory.Group, props: GroupProps): GroupAttributes | undefined => {
+  if (live.email === undefined || !ciEqual(live.email, props.email)) return undefined;
+  return {
+    adminCreated: live.adminCreated === true,
+    aliases: stringArray(live.aliases),
+    description: text(live.description),
+    directMembersCount: text(live.directMembersCount),
+    email: live.email,
+    groupId: text(live.id),
+    name: text(live.name),
+    nonEditableAliases: stringArray(live.nonEditableAliases),
+  };
+};
+
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see group.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  GroupProps,
+  directory.Group,
+  GroupAttributes,
+  | directory.GetGroupsError
+  | directory.InsertGroupsError
+  | directory.PatchGroupsError
+  | directory.DeleteGroupsError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertGroups({
+      body: { description: props.description ?? '', email: props.email, name: defaultName(props) },
+    }),
+  describe: (props) => `groups/${props.email}`,
+  destroy: (_props, live) =>
+    directory.deleteGroups({ groupKey: text(live.id) || text(live.email) }),
+  fetchLive: (props) =>
+    directory
+      .getGroups({ groupKey: props.email })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.description === (props.description ?? '') && attributes.name === defaultName(props),
+  update: (props, live) =>
+    directory.patchGroups({
+      body: { description: props.description ?? '', name: defaultName(props) },
+      groupKey: text(live.id) || text(live.email),
+    }),
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceGroupProvider = () =>
+  Provider.effect(GoogleWorkspaceGroup, Effect.succeed(GoogleWorkspaceGroup.Provider.of(handlers)));

package/src/google-workspace/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Google Workspace providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. These are
+ *   the symbols a real stack consumes; the rest of the files are internals a provider needs but a
+ *   consumer should not depend on. An `export *` here would publish every helper as API and make
+ *   the next refactor a breaking change.
+ * ★ `credentials.ts`'s re-exports ARE published, because a stack needs `CredentialsFromEnv` (or
+ *   `fromAccessToken` in a test) to build a runtime layer, and `GoogleWorkspaceKeyRef` /
+ *   `describeKeyRef` are the documentation seam credential setup is meant to go through.
+ */
+export {
+  type GoogleWorkspaceConfig,
+  Credentials,
+  CredentialsFromEnv,
+  describeKeyRef,
+  fromAccessToken,
+  GOOGLE_ACCESS_TOKEN_ENV,
+  GOOGLE_PROJECT_ID_ENV,
+  type GoogleWorkspaceKeyRef,
+} from './credentials.ts';
+export {
+  GoogleWorkspaceDomainAlias,
+  GoogleWorkspaceDomainAliasProvider,
+  type DomainAliasAttributes,
+  type DomainAliasProps,
+} from './domain-alias.ts';
+export {
+  GoogleWorkspaceGroup,
+  GoogleWorkspaceGroupProvider,
+  type GroupAttributes,
+  type GroupProps,
+} from './group.ts';
+export {
+  GoogleWorkspaceGroupMember,
+  GoogleWorkspaceGroupMemberProvider,
+  type DeliverySettings,
+  type GroupMemberAttributes,
+  type GroupMemberProps,
+  type MemberRole,
+} from './group-member.ts';
+export {
+  GoogleWorkspaceOrgUnit,
+  GoogleWorkspaceOrgUnitProvider,
+  type OrgUnitAttributes,
+  type OrgUnitProps,
+} from './org-unit.ts';
+export { googleWorkspaceProviders } from './providers.ts';
+export {
+  googleWorkspaceHandlers,
+  googleWorkspaceOperations,
+  type GoogleWorkspaceRequirements,
+  type GoogleWorkspaceSpec,
+} from './resource.ts';