@typeb-digital/nucleus-sdk 0.5.3 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,113 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the
 package is pre-`1.0.0`, **breaking changes may land in a minor version** (e.g. `0.0.x` → `0.1.0`).
 
+## [0.8.0] - 2026-09-08
+
+### Added
+
+- **Google Chat messaging — `chat.send`.** Nucleus can now message people on Google Chat
+  as the company's Chat app, giving apps a push channel that reaches a phone without
+  handling a Google identity or a bot token of their own. Address a message to
+  `{ employeeId }` and Nucleus opens the direct-message conversation with that person the
+  first time, caches it, and reuses it forever after; or address `{ space: 'spaces/…' }`
+  to post into a shared space the app belongs to. Send `text`, a small `card` (title,
+  body, one link button, expanded into Google's `cardsV2` for you), or raw `cardsV2`.
+  Needs the new `chat:send` scope, which is approval-gated.
+- **`requestId` makes a send idempotent.** Google returns the message already created
+  under that id rather than posting a second one, so a retried send cannot double-notify.
+  Key it on the event (`"leave-42-approved"`), not the attempt. Keys are scoped to your
+  app, so two apps cannot suppress each other's messages.
+- **`thread.key` groups related messages** into one Chat thread — every update about one
+  leave request in one place. Named spaces only: Google does not thread direct messages,
+  so it is ignored for an `employeeId` target rather than failing.
+
+### Notes
+
+- **This is a transport, not a notification system.** There are no templates, no audience
+  resolution, no retry policy and no per-person preferences. Your app decides who should
+  hear what; Nucleus puts one message in one place. A durable outbox on your side is the
+  intended pattern, which is what `requestId` exists for.
+- **A Chat message is more interruptive than an in-app badge.** It reaches a phone.
+  Choose the handful of notification kinds that genuinely warrant that, and give people a
+  way to turn them off — Nucleus deliberately holds no preferences of its own.
+- **Test tokens cannot reach a real person.** Under an `el_test_` token the message is
+  redirected to a configured sandbox space with a banner naming who it was meant for, and
+  no direct message with a real person is opened. `sandbox: true` and `redirectedFrom`
+  on the response tell you what happened. With no sandbox space configured the send is
+  refused (`SANDBOX_NOT_CONFIGURED`) rather than reaching someone real.
+- **`CHAT_NOT_AVAILABLE_FOR_EMPLOYEE` (422) is not retryable.** It means the Chat app's
+  visibility list does not cover that person, which only a Workspace administrator can
+  change. Drop the message rather than retrying it.
+
+## [0.7.0] - 2026-09-08
+
+### Added
+
+- **Google Calendar writes — `calendar.createEvent`, `calendar.updateEvent`,
+  `calendar.deleteEvent`.** The calendar capability was read-only; it can now put real
+  events on real calendars. Every write names the identity it acts as, so the organiser
+  is never ambiguous: `{ employeeId }` for an event that person organises on their own
+  calendar, or `{ organizer: 'company' }` for an org-wide event owned by the platform's
+  company mailbox. Attendees may be given as `{ employeeId }` or `{ email }` — employee
+  ids are resolved to Workspace emails server-side, so your app never needs a Google
+  identity. `createMeet: true` attaches a Google Meet conference and returns it as
+  `meetLink`. Needs the new `calendar:create` / `calendar:update` / `calendar:delete`
+  scopes, which are approval-gated: ask the platform team to grant them.
+- **`clientReference` makes a create idempotent.** Nucleus derives a stable Google event
+  id from it, so replaying a create — a queue retry, a redeploy mid-request — returns the
+  original event with `created: false` instead of double-booking. Give it a value that
+  identifies the _thing_ being scheduled (`"milestone:cycle-42"`), not the attempt. A
+  delete is likewise safe to repeat: an event Google reports as already cancelled counts
+  as deleted.
+- **`error.apiCode` on every failed result.** `error.code` stays the small union you
+  branch on; `apiCode` carries the server's specific reason —
+  `GOOGLE_DELEGATION_NOT_GRANTED`, `SANDBOX_NOT_CONFIGURED`, `ATTENDEE_NOT_RESOLVABLE`,
+  `EVENT_NOT_FOUND` — for logging and for telling two 4xx cases apart.
+- **`calendar.listEvents` accepts `calendarId`**, to read a calendar other than the
+  employee's `primary`. The returned event now also carries `eventType`, `meetLink`,
+  `iCalUID`, `updated` and `recurrence`.
+
+### Fixed
+
+- **`INVALID_SCOPE` now actually reaches you.** The transport read the API's error
+  _message_ where it meant to read the error _code_, so a missing-scope rejection always
+  arrived as the generic `FORBIDDEN`. Code that branches on `FORBIDDEN` keeps working;
+  code that wanted `INVALID_SCOPE` starts working.
+- **Failed results carry the API's message, not ofetch's.** `error.message` was
+  `"[POST] …: 400 Bad Request"`; it is now the reason the API gave, e.g.
+  `"start.timeZone: is required when dateTime has no UTC offset"`.
+
+### Notes
+
+- **`sendUpdates` defaults to `none`.** Creating or changing an event emails nobody
+  unless you pass `'all'` (or `'externalOnly'`). This is deliberate: an automation that
+  quietly mails a hundred people is worse than one that mails nobody. Pass it explicitly
+  for anything a human is expected to accept, such as a meeting invitation.
+- **Test tokens cannot reach a real calendar.** Under an `el_test_` token every write is
+  redirected to a dedicated sandbox calendar as the company mailbox, the summary is
+  stamped `[SANDBOX]`, attendees are stripped and returned in `suppressedAttendees`,
+  invitations are forced off, and out-of-office is downgraded to a plain event. The
+  response's `sandbox: true` tells you it happened. If the deployment has no sandbox
+  calendar configured, the write is refused (`SANDBOX_NOT_CONFIGURED`) rather than
+  landing somewhere real.
+- **`eventType` cannot be changed after creation** (Google's rule), so `updateEvent`
+  does not accept it. `updateEvent` is a patch — omitted fields are left alone — with one
+  exception: `attendees` replaces the whole list, and `[]` clears it.
+- **This release does not write the Nucleus company calendar.** `calendarEvents` (the
+  `calendar-events` resource) is unchanged and remains the date-only company calendar;
+  `calendar` is an employee's real Google Calendar. They are different things.
+
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- **`employeeCode` on the `employees:identity` bucket.** Nucleus now mirrors the
+  Google Workspace "Employee ID" (e.g. `"TB008"`) from the Directory API, so an app
+  can correlate an employee with payroll and HR systems that key on that code rather
+  than on the Nucleus UUID. It arrives with the fields you already read — no scope
+  change is needed if your token has `employees:identity` — and is `null` for anyone
+  whose directory entry has no employee ID set.
+
 ## [0.5.3] - 2026-09-04
 
 ### Fixed

package/README.md

@@ -259,6 +259,143 @@ Same pattern — `list(params?)` and `getById(id, options?)` on every resource a
 
 ---
 
+## Capabilities
+
+Most scopes are CRUD over a resource. A few are **actions the platform performs on your
+behalf** — sending mail, writing a calendar — and they work differently: they are granted
+per app at registration rather than declared in the client's typed `scopes` config, and
+the accessor is always present (the server rejects the call if the capability was not
+granted). Nucleus holds the Google credentials, so your app never handles a Google
+identity: you address people by Nucleus `employeeId`.
+
+### Email — needs `email:send`
+
+```typescript
+await nucleus.email.send({ to: 'ada@example.com', subject: 'Payslip ready', html });
+```
+
+The From address is platform-configured per app and cannot be set from the request body.
+
+### Google Calendar — needs `calendar:read`, and `calendar:create|update|delete` to write
+
+Reading an employee's calendar:
+
+```typescript
+const { data } = await nucleus.calendar.listEvents({
+  employeeId,
+  timeMin: '2026-09-01T00:00:00Z',
+  timeMax: '2026-09-30T23:59:59Z',
+});
+```
+
+Every write names the identity it acts as, so the organiser is never ambiguous — either
+the employee whose calendar it is, or the company mailbox for an org-wide event:
+
+```typescript
+// A 1:1, organised by the manager, with a Meet link and a real invitation.
+const { data } = await nucleus.calendar.createEvent(
+  { employeeId: managerId },
+  {
+    summary: 'Quarterly check-in',
+    start: { dateTime: '2026-09-10T09:00:00+05:30' },
+    end: { dateTime: '2026-09-10T09:30:00+05:30' },
+    attendees: [{ employeeId: reportId }],
+    createMeet: true,
+    sendUpdates: 'all',
+    clientReference: `milestone:${cycleId}`,
+  },
+);
+data.event.meetLink; // https://meet.google.com/…
+data.created; // false if this was a retry of a create that already succeeded
+
+// An all-hands, owned by the company mailbox rather than a person.
+await nucleus.calendar.createEvent(
+  { organizer: 'company' },
+  {
+    summary: 'Town hall',
+    start: { dateTime: '2026-10-01T15:00:00+05:30' },
+    end: { dateTime: '2026-10-01T16:00:00+05:30' },
+    attendees: [{ email: 'everyone@typeb.digital' }],
+    sendUpdates: 'all',
+  },
+);
+
+// Leave, as an out-of-office block on that person's own calendar.
+await nucleus.calendar.createEvent(
+  { employeeId },
+  {
+    summary: 'Annual leave',
+    eventType: 'outOfOffice',
+    outOfOffice: { autoDeclineMode: 'declineAllConflictingInvitations' },
+    start: { dateTime: '2026-09-14T00:00:00+05:30' },
+    end: { dateTime: '2026-09-19T00:00:00+05:30' },
+    clientReference: `leave:${leaveRequestId}`,
+  },
+);
+
+await nucleus.calendar.updateEvent({ employeeId: managerId }, eventId, { location: 'Room 2' });
+await nucleus.calendar.deleteEvent({ employeeId: managerId }, eventId, { sendUpdates: 'all' });
+```
+
+Four things worth knowing before you ship against this:
+
+- **Nothing is emailed unless you ask.** `sendUpdates` defaults to `none`. Pass `'all'`
+  for anything a human is expected to accept.
+- **Retries are safe if you pass `clientReference`.** Nucleus derives a stable Google
+  event id from it, so a replayed create returns the original event with
+  `created: false` instead of double-booking. Key it on the thing being scheduled, not on
+  the attempt. Deletes are idempotent already.
+- **`updateEvent` is a patch**, except `attendees`, which replaces the whole list (`[]`
+  clears it). `eventType` cannot be changed after creation, so it is not accepted.
+- **A test token cannot reach a real calendar.** Writes are redirected to a sandbox
+  calendar, stamped `[SANDBOX]`, with attendees stripped into `suppressedAttendees` and
+  invitations forced off. Check `sandbox` on the response.
+
+Nucleus's own **company calendar** is a different thing: that is `nucleus.calendarEvents`
+(the `calendar-events` CRUD resource, date-only), not `nucleus.calendar`.
+
+### Google Chat — needs `chat:send`
+
+Messages are posted as the company's Chat app. Address a person by `employeeId` and
+Nucleus opens their direct message with the app the first time, then reuses it:
+
+```typescript
+await nucleus.chat.send({
+  to: { employeeId },
+  card: {
+    title: 'Leave approved',
+    subtitle: '14–18 September',
+    body: 'Your request was approved by Grace.',
+    link: { text: 'Open OS', url: 'https://os.typeb.digital/hr/my-leave' },
+  },
+  requestId: `leave-${leaveRequestId}-approved`,
+});
+
+// Or into a shared space the app belongs to, threaded by a key you choose.
+await nucleus.chat.send({
+  to: { space: 'spaces/AAAA' },
+  text: 'Two expense claims are waiting for approval.',
+  thread: { key: `expenses-${weekOf}` },
+});
+```
+
+Worth knowing:
+
+- **This is a transport, not a notification system.** No templates, no audiences, no
+  preferences — your app decides who hears what. Drive it from a durable outbox and use
+  `requestId` so a retry cannot double-notify.
+- **A Chat message reaches a phone.** Reserve it for the few kinds that warrant an
+  interruption, and give people a way to opt out; Nucleus holds no preferences.
+- **Threads are for named spaces only.** Google does not thread direct messages, so
+  `thread` is ignored for an `employeeId` target.
+- **A test token cannot reach a real person.** Messages are redirected to a sandbox space
+  with a banner naming the intended recipient. Check `sandbox` and `redirectedFrom`.
+- **`CHAT_NOT_AVAILABLE_FOR_EMPLOYEE` (422) is final**, not transient: the Chat app's
+  visibility list does not cover that person. Read it from `error.apiCode` and drop the
+  message rather than retrying.
+
+---
+
 ## Result type
 
 Every method returns a result object — **never throws** by default:

package/dist/cjs/index.cjs

@@ -10,14 +10,23 @@ function statusToCode(status, apiCode) {
     if (status === 429) return 'RATE_LIMITED';
     return 'FORBIDDEN';
 }
-function makeErrorResult(code, message) {
+function makeErrorResult(code, message, apiCode) {
     return {
         error: {
             code,
-            message
+            message,
+            ...apiCode ? {
+                apiCode
+            } : {}
         }
     };
 }
+function stripUndefined(query) {
+    if (!query) return undefined;
+    return Object.fromEntries(Object.entries(query).filter((entry)=>{
+        return entry[1] !== undefined;
+    }));
+}
 class NucleusTransport {
     constructor(token, baseUrl){
         this.bodylessHeaders = {
@@ -29,117 +38,78 @@ class NucleusTransport {
         };
         this.baseUrl = (baseUrl ?? DEFAULT_BASE_URL$1).replace(/\/$/, '');
     }
-    async get(path, query) {
+    /**
+   * The one place a request is issued and a failure is interpreted. Every verb below
+   * funnels through here: when the error mapping lived in each verb, a fix to it had to
+   * be made five times, and one of them (reading the API's `code`) was wrong for years.
+   */ async request(method, path, opts, onSuccess) {
         try {
-            const params = query ? Object.fromEntries(Object.entries(query).filter(([, v])=>v !== undefined)) : undefined;
             const envelope = await ofetch.$fetch(`${this.baseUrl}${path}`, {
-                method: 'GET',
-                headers: this.bodylessHeaders,
-                params
+                method,
+                headers: opts.hasBody ? this.headers : this.bodylessHeaders,
+                ...opts.hasBody ? {
+                    body: JSON.stringify(opts.body)
+                } : {},
+                params: stripUndefined(opts.query)
             });
+            // A 2xx carrying `success: false` shouldn't happen, but the envelope allows it.
             if (!envelope.success) {
-                return makeErrorResult('FORBIDDEN', envelope.error);
+                return makeErrorResult(statusToCode(0, envelope.code), envelope.error, envelope.code);
             }
-            return {
-                data: envelope.data
-            };
+            return onSuccess(envelope);
         } catch (err) {
             if (err instanceof ofetch.FetchError) {
                 const body = err.data;
-                const code = statusToCode(err.status ?? 0, body?.error);
-                return makeErrorResult(code, err.message);
-            }
-            return makeErrorResult('NETWORK_ERROR', String(err));
-        }
-    }
-    async post(path, body) {
-        try {
-            const envelope = await ofetch.$fetch(`${this.baseUrl}${path}`, {
-                method: 'POST',
-                headers: this.headers,
-                body: JSON.stringify(body)
-            });
-            if (!envelope.success) return makeErrorResult('FORBIDDEN', envelope.error);
-            return {
-                data: envelope.data
-            };
-        } catch (err) {
-            if (err instanceof ofetch.FetchError) {
-                const errBody = err.data;
-                return makeErrorResult(statusToCode(err.status ?? 0, errBody?.error), err.message);
+                // Prefer the API's own message ("start.timeZone: is required") over ofetch's
+                // generic "[POST] …: 400 Bad Request", which says nothing actionable.
+                return makeErrorResult(statusToCode(err.status ?? 0, body?.code), body?.error ?? err.message, body?.code);
             }
             return makeErrorResult('NETWORK_ERROR', String(err));
         }
     }
-    async put(path, body) {
-        try {
-            const envelope = await ofetch.$fetch(`${this.baseUrl}${path}`, {
-                method: 'PUT',
-                headers: this.headers,
-                body: JSON.stringify(body)
-            });
-            if (!envelope.success) return makeErrorResult('FORBIDDEN', envelope.error);
-            return {
-                data: envelope.data
-            };
-        } catch (err) {
-            if (err instanceof ofetch.FetchError) {
-                const errBody = err.data;
-                return makeErrorResult(statusToCode(err.status ?? 0, errBody?.error), err.message);
-            }
-            return makeErrorResult('NETWORK_ERROR', String(err));
-        }
+    single(envelope) {
+        return {
+            data: envelope.data
+        };
     }
-    async patch(path, body) {
-        try {
-            const envelope = await ofetch.$fetch(`${this.baseUrl}${path}`, {
-                method: 'PATCH',
-                headers: this.headers,
-                body: JSON.stringify(body)
-            });
-            if (!envelope.success) return makeErrorResult('FORBIDDEN', envelope.error);
-            return {
-                data: envelope.data
-            };
-        } catch (err) {
-            if (err instanceof ofetch.FetchError) {
-                const errBody = err.data;
-                return makeErrorResult(statusToCode(err.status ?? 0, errBody?.error), err.message);
-            }
-            return makeErrorResult('NETWORK_ERROR', String(err));
-        }
+    async get(path, query) {
+        return this.request('GET', path, {
+            query,
+            hasBody: false
+        }, (e)=>this.single(e));
+    }
+    async post(path, body, query) {
+        return this.request('POST', path, {
+            body,
+            query,
+            hasBody: true
+        }, (e)=>this.single(e));
+    }
+    async put(path, body, query) {
+        return this.request('PUT', path, {
+            body,
+            query,
+            hasBody: true
+        }, (e)=>this.single(e));
+    }
+    async patch(path, body, query) {
+        return this.request('PATCH', path, {
+            body,
+            query,
+            hasBody: true
+        }, (e)=>this.single(e));
     }
     async del(path, query) {
-        try {
-            const params = query ? Object.fromEntries(Object.entries(query).filter(([, v])=>v !== undefined)) : undefined;
-            const envelope = await ofetch.$fetch(`${this.baseUrl}${path}`, {
-                method: 'DELETE',
-                headers: this.bodylessHeaders,
-                params
-            });
-            if (!envelope.success) return makeErrorResult('FORBIDDEN', envelope.error);
-            return {
-                data: envelope.data
-            };
-        } catch (err) {
-            if (err instanceof ofetch.FetchError) {
-                const errBody = err.data;
-                return makeErrorResult(statusToCode(err.status ?? 0, errBody?.error), err.message);
-            }
-            return makeErrorResult('NETWORK_ERROR', String(err));
-        }
+        return this.request('DELETE', path, {
+            query,
+            hasBody: false
+        }, (e)=>this.single(e));
     }
     async getList(path, query) {
-        try {
-            const params = query ? Object.fromEntries(Object.entries(query).filter(([, v])=>v !== undefined)) : undefined;
-            const envelope = await ofetch.$fetch(`${this.baseUrl}${path}`, {
-                method: 'GET',
-                headers: this.bodylessHeaders,
-                params
-            });
-            if (!envelope.success) {
-                return makeErrorResult('FORBIDDEN', envelope.error);
-            }
+        return this.request('GET', path, {
+            query,
+            hasBody: false
+        }, (envelope)=>{
             const { data, meta } = envelope;
             const listMeta = {
                 total: meta.total,
@@ -151,14 +121,7 @@ class NucleusTransport {
                 data,
                 meta: listMeta
             };
-        } catch (err) {
-            if (err instanceof ofetch.FetchError) {
-                const body = err.data;
-                const code = statusToCode(err.status ?? 0, body?.error);
-                return makeErrorResult(code, err.message);
-            }
-            return makeErrorResult('NETWORK_ERROR', String(err));
-        }
+        });
     }
 }
 
@@ -247,6 +210,7 @@ function transformEmployee(raw) {
     if ('job_title' in r) out['jobTitle'] = str(r['job_title']);
     if ('department' in r) out['department'] = str(r['department']);
     if ('employment_status' in r) out['employmentStatus'] = str(r['employment_status']);
+    if ('employee_code' in r) out['employeeCode'] = str(r['employee_code']);
     if ('employment_type' in r) out['employmentType'] = str(r['employment_type']);
     if ('is_external' in r) out['isExternal'] = bool(r['is_external']);
     // employment
@@ -1644,9 +1608,22 @@ class TimesheetsAccessor {
     }
 }
 
+function actorQuery(actor) {
+    return {
+        employeeId: actor.employeeId,
+        organizer: actor.organizer,
+        calendarId: actor.calendarId
+    };
+}
 /**
- * CalendarAccessor — read workspace users' Google Calendar events (WS3).
- * Requires the app's `calendar:read` scope. Not part of the bucket/CRUD scope system.
+ * CalendarAccessor — read and write workspace users' Google Calendar events (WS3).
+ * Requires the app's `calendar:read` scope to list, and `calendar:create` /
+ * `calendar:update` / `calendar:delete` to write. Not part of the bucket/CRUD scope
+ * system, so these are not declared in the client's typed `scopes` config.
+ *
+ * Writes are mode-aware: under a test token every event is redirected to a sandbox
+ * calendar with attendees stripped (reported in `suppressedAttendees`) and invitations
+ * forced off, so a sandbox caller can never touch a real calendar or email a real guest.
  */ class CalendarAccessor {
     constructor(transport){
         this.transport = transport;
@@ -1656,7 +1633,32 @@ class TimesheetsAccessor {
             employeeId: params.employeeId,
             timeMin: params.timeMin,
             timeMax: params.timeMax,
-            q: params.q
+            q: params.q,
+            calendarId: params.calendarId
+        });
+        if ('error' in result) return result;
+        return {
+            data: result.data
+        };
+    }
+    async createEvent(actor, input) {
+        const result = await this.transport.post('/api/v1/data/calendar/events', input, actorQuery(actor));
+        if ('error' in result) return result;
+        return {
+            data: result.data
+        };
+    }
+    async updateEvent(actor, eventId, input) {
+        const result = await this.transport.patch(`/api/v1/data/calendar/events/${encodeURIComponent(eventId)}`, input, actorQuery(actor));
+        if ('error' in result) return result;
+        return {
+            data: result.data
+        };
+    }
+    async deleteEvent(actor, eventId, opts) {
+        const result = await this.transport.del(`/api/v1/data/calendar/events/${encodeURIComponent(eventId)}`, {
+            ...actorQuery(actor),
+            sendUpdates: opts?.sendUpdates
         });
         if ('error' in result) return result;
         return {
@@ -1665,6 +1667,29 @@ class TimesheetsAccessor {
     }
 }
 
+/**
+ * ChatAccessor — send Google Chat messages as the company's Chat app. Requires the
+ * app's `chat:send` scope. Not part of the bucket/CRUD scope system.
+ *
+ * This is a transport, not a notification system: no templates, no audience resolution,
+ * no per-person preferences. Your app decides who should hear what.
+ *
+ * Mode-aware: under a test token the message is redirected to a sandbox space with a
+ * banner naming the intended recipient, and no direct message with a real person is ever
+ * opened.
+ */ class ChatAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    async send(input) {
+        const result = await this.transport.post('/api/v1/data/chat/messages', input);
+        if ('error' in result) return result;
+        return {
+            data: result.data
+        };
+    }
+}
+
 /**
  * EmailAccessor — send Nucleus-mediated email (WS5). Requires the app's `email:send` scope.
  * In test mode the message is marked `[SANDBOX]` and external recipients are suppressed.
@@ -2033,6 +2058,7 @@ class AuthAccessor {
         this.timesheets = new TimesheetsAccessor(transport);
         this.calendar = new CalendarAccessor(transport);
         this.email = new EmailAccessor(transport);
+        this.chat = new ChatAccessor(transport);
         this.employeeCompensation = new EmployeeCompensationAccessor(transport);
         this.employeeProfiles = new EmployeeProfilesAccessor(transport);
         this.employeeReviews = new EmployeeReviewsAccessor(transport);
@@ -2054,6 +2080,9 @@ function isError(result) {
     return 'error' in result;
 }
 
+exports.CalendarAccessor = CalendarAccessor;
+exports.ChatAccessor = ChatAccessor;
+exports.EmailAccessor = EmailAccessor;
 exports.FilesAccessor = FilesAccessor;
 exports.NucleusClient = NucleusClient;
 exports.isError = isError;