@typeb-digital/nucleus-sdk 0.5.3 → 0.8.0

package/dist/es/index.js

@@ -8,14 +8,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 = {
@@ -27,117 +36,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 $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 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 $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 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 $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 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 $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 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 $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 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 $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,
@@ -149,14 +119,7 @@ class NucleusTransport {
                 data,
                 meta: listMeta
             };
-        } catch (err) {
-            if (err instanceof FetchError) {
-                const body = err.data;
-                const code = statusToCode(err.status ?? 0, body?.error);
-                return makeErrorResult(code, err.message);
-            }
-            return makeErrorResult('NETWORK_ERROR', String(err));
-        }
+        });
     }
 }
 
@@ -245,6 +208,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
@@ -1642,9 +1606,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;
@@ -1654,7 +1631,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 {
@@ -1663,6 +1665,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.
@@ -2031,6 +2056,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);
@@ -2052,4 +2078,4 @@ function isError(result) {
     return 'error' in result;
 }
 
-export { FilesAccessor, NucleusClient, isError };
+export { CalendarAccessor, ChatAccessor, EmailAccessor, FilesAccessor, NucleusClient, isError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeb-digital/nucleus-sdk",
-  "version": "0.5.3",
+  "version": "0.8.0",
   "description": "Server-side TypeScript SDK for the Nucleus data platform",
   "type": "module",
   "engines": {