@typeb-digital/nucleus-sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ 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.1.1] - 2026-06-22
+
+### Changed
+
+- **Employees are read-only.** Nucleus owns employee writes (sourced via Google/HRIS
+  sync), so the scope system no longer accepts `create` / `update` / `delete` grants
+  for `employees`:
+  - `ScopeDeclaration` types `employees` as read-only — declaring a write action on it
+    is now a compile-time error.
+  - Removed `employees.update()` / `employees.delete()` from the SDK.
+
+  (The platform also rejects employee write grants at app-registration / group-permission
+  time, and the dashboard scope matrix shows `employees` as read-only.)
+
 ## [0.1.0] - 2026-06-22
 
 Action-typed scopes and write support. **This is a breaking release** — every consumer's

package/dist/cjs/index.cjs

@@ -415,6 +415,30 @@ function transformJurisdiction(raw) {
     if ('country' in r) out['country'] = str(r['country']);
     return out;
 }
+function transformJobLevel(raw) {
+    if (!raw || typeof raw !== 'object') return {};
+    const r = raw;
+    const out = {};
+    if ('id' in r) out['id'] = r['id'];
+    if ('name' in r) out['name'] = str(r['name']);
+    if ('code' in r) out['code'] = str(r['code']);
+    if ('department_id' in r) out['departmentId'] = str(r['department_id']);
+    if ('sort_order' in r) out['sortOrder'] = num(r['sort_order']) ?? 0;
+    return out;
+}
+function transformSalaryBand(raw) {
+    if (!raw || typeof raw !== 'object') return {};
+    const r = raw;
+    const out = {};
+    if ('id' in r) out['id'] = r['id'];
+    if ('job_level_id' in r) out['jobLevelId'] = str(r['job_level_id']);
+    if ('jurisdiction_id' in r) out['jurisdictionId'] = str(r['jurisdiction_id']);
+    if ('currency_code' in r) out['currencyCode'] = str(r['currency_code']);
+    if ('min_salary' in r) out['minSalary'] = num(r['min_salary']);
+    if ('max_salary' in r) out['maxSalary'] = num(r['max_salary']);
+    if ('target_salary' in r) out['targetSalary'] = num(r['target_salary']);
+    return out;
+}
 function transformLeaveType(raw) {
     if (!raw || typeof raw !== 'object') return {};
     const r = raw;
@@ -566,6 +590,7 @@ class EmployeesAccessor {
         if (params?.employmentStatus) query['employmentStatus'] = params.employmentStatus;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/employees', query);
         if ('error' in result) return result;
@@ -583,23 +608,16 @@ class EmployeesAccessor {
             data: transformEmployee(result.data)
         };
     }
-    // No create: the platform exposes no POST route for employees.
-    /** Update an employee (managerId / timezone overrides). Requires `employees.update` scope. */ async update(id, data) {
-        const result = await this.transport.patch(`/api/v1/data/employees/${id}`, toSnakeBody(data));
-        if ('error' in result) return result;
-        return {
-            data: transformEmployee(result.data)
-        };
-    }
-    /** Soft-delete an employee. Requires `employees.delete` scope. */ async delete(id) {
-        const result = await this.transport.del(`/api/v1/data/employees/${id}`);
-        if ('error' in result) return result;
-        return {
-            data: null
-        };
-    }
 }
 
+function transformMember(raw) {
+    return {
+        id: raw['id'],
+        projectId: raw['project_id'],
+        employeeId: raw['employee_id'],
+        role: raw['role'] ?? null
+    };
+}
 class ProjectsAccessor {
     constructor(transport){
         this.transport = transport;
@@ -608,9 +626,11 @@ class ProjectsAccessor {
         const query = {};
         if (params?.search) query['search'] = params.search;
         if (params?.status) query['status'] = params.status;
+        if (params?.stage) query['stage'] = params.stage;
         if (params?.clientId) query['clientId'] = params.clientId;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/projects', query);
         if ('error' in result) return result;
@@ -649,6 +669,33 @@ class ProjectsAccessor {
             data: null
         };
     }
+    // ─── Team membership (the projects `team` bucket) ──────────────────────────
+    // Membership is the project↔employee join. Reads need `projects` read on `team`;
+    // add/remove need `projects` update on `team` (re-adding restores a soft-deleted row).
+    membersBase(projectId) {
+        return `/api/v1/data/project-memberships/projects/${projectId}/members`;
+    }
+    /** List a project's team members. Requires `projects` read on the `team` bucket. */ async listMembers(projectId) {
+        const result = await this.transport.get(this.membersBase(projectId));
+        if ('error' in result) return result;
+        return {
+            data: (result.data ?? []).map((r)=>transformMember(r))
+        };
+    }
+    /** Add a team member. Requires `projects` update on the `team` bucket. */ async addMember(projectId, data) {
+        const result = await this.transport.post(this.membersBase(projectId), toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transformMember(result.data)
+        };
+    }
+    /** Remove a team member. Requires `projects` update on the `team` bucket. */ async removeMember(projectId, employeeId) {
+        const result = await this.transport.del(`${this.membersBase(projectId)}/${employeeId}`);
+        if ('error' in result) return result;
+        return {
+            data: null
+        };
+    }
 }
 
 class ClientsAccessor {
@@ -662,6 +709,7 @@ class ClientsAccessor {
         if (params?.country) query['country'] = params.country;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/clients', query);
         if ('error' in result) return result;
@@ -711,6 +759,7 @@ class PartnersAccessor {
         if (params?.search) query['search'] = params.search;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/partners', query);
         if ('error' in result) return result;
@@ -760,6 +809,7 @@ class DepartmentsAccessor {
         if (params?.search) query['search'] = params.search;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/departments', query);
         if ('error' in result) return result;
         return {
@@ -805,6 +855,7 @@ class ProjectTypesAccessor {
         const query = {};
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/project-types', query);
         if ('error' in result) return result;
         return {
@@ -850,6 +901,7 @@ class CurrenciesAccessor {
         const query = {};
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/currencies', query);
         if ('error' in result) return result;
         return {
@@ -899,6 +951,7 @@ class GenericRatesAccessor {
         if (params?.department) query['department'] = params.department;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/generic-rates', query);
         if ('error' in result) return result;
         return {
@@ -945,6 +998,7 @@ class JurisdictionsAccessor {
         if (params?.search) query['search'] = params.search;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/jurisdictions', query);
         if ('error' in result) return result;
         return {
@@ -982,6 +1036,105 @@ class JurisdictionsAccessor {
     }
 }
 
+/** JobLevelsAccessor — the company's career-ladder rungs (WS7). */ class JobLevelsAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    async list(params) {
+        const query = {};
+        if (params?.search) query['search'] = params.search;
+        if (params?.departmentId) query['departmentId'] = params.departmentId;
+        if (params?.page) query['page'] = params.page;
+        if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
+        const result = await this.transport.getList('/api/v1/data/job-levels', query);
+        if ('error' in result) return result;
+        return {
+            data: result.data.map((r)=>transformJobLevel(r)),
+            meta: result.meta
+        };
+    }
+    async getById(id) {
+        const result = await this.transport.get(`/api/v1/data/job-levels/${id}`);
+        if ('error' in result) return result;
+        return {
+            data: transformJobLevel(result.data)
+        };
+    }
+    /** Create a job level. Requires `job-levels.create` scope. */ async create(data) {
+        const result = await this.transport.post('/api/v1/data/job-levels', toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transformJobLevel(result.data)
+        };
+    }
+    /** Update a job level. Requires `job-levels.update` scope. */ async update(id, data) {
+        const result = await this.transport.put(`/api/v1/data/job-levels/${id}`, toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transformJobLevel(result.data)
+        };
+    }
+    /** Soft-delete a job level. Requires `job-levels.delete` scope. */ async delete(id) {
+        const result = await this.transport.del(`/api/v1/data/job-levels/${id}`);
+        if ('error' in result) return result;
+        return {
+            data: null
+        };
+    }
+}
+
+/**
+ * SalaryBandsAccessor — per-jurisdiction pay ranges for a job level (WS7).
+ * The `financials` bucket (min/max/target) is flagged sensitive server-side.
+ */ class SalaryBandsAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    async list(params) {
+        const query = {};
+        if (params?.jobLevelId) query['jobLevelId'] = params.jobLevelId;
+        if (params?.jurisdictionId) query['jurisdictionId'] = params.jurisdictionId;
+        if (params?.page) query['page'] = params.page;
+        if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
+        const result = await this.transport.getList('/api/v1/data/salary-bands', query);
+        if ('error' in result) return result;
+        return {
+            data: result.data.map((r)=>transformSalaryBand(r)),
+            meta: result.meta
+        };
+    }
+    async getById(id) {
+        const result = await this.transport.get(`/api/v1/data/salary-bands/${id}`);
+        if ('error' in result) return result;
+        return {
+            data: transformSalaryBand(result.data)
+        };
+    }
+    /** Create a salary band. Requires `salary-bands.create` scope. */ async create(data) {
+        const result = await this.transport.post('/api/v1/data/salary-bands', toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transformSalaryBand(result.data)
+        };
+    }
+    /** Update a salary band. Requires `salary-bands.update` scope. */ async update(id, data) {
+        const result = await this.transport.put(`/api/v1/data/salary-bands/${id}`, toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transformSalaryBand(result.data)
+        };
+    }
+    /** Soft-delete a salary band. Requires `salary-bands.delete` scope. */ async delete(id) {
+        const result = await this.transport.del(`/api/v1/data/salary-bands/${id}`);
+        if ('error' in result) return result;
+        return {
+            data: null
+        };
+    }
+}
+
 class LeaveTypesAccessor {
     constructor(transport){
         this.transport = transport;
@@ -991,6 +1144,7 @@ class LeaveTypesAccessor {
         if (params?.search) query['search'] = params.search;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/leave-types', query);
         if ('error' in result) return result;
         return {
@@ -1039,6 +1193,7 @@ class LeavesAccessor {
         if (params?.status) query['status'] = params.status;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/leaves', query);
         if ('error' in result) return result;
@@ -1090,6 +1245,7 @@ class LeaveBalancesAccessor {
         if (params?.year) query['year'] = params.year;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/leave-balances', query);
         if ('error' in result) return result;
@@ -1140,6 +1296,7 @@ class PoliciesAccessor {
         if (params?.category) query['category'] = params.category;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/policies', query);
         if ('error' in result) return result;
         return {
@@ -1187,6 +1344,7 @@ class PolicyAcknowledgementsAccessor {
         if (params?.employeeId) query['employeeId'] = params.employeeId;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/policy-acknowledgements', query);
         if ('error' in result) return result;
@@ -1235,8 +1393,10 @@ class CalendarEventsAccessor {
         const query = {};
         if (params?.search) query['search'] = params.search;
         if (params?.type) query['type'] = params.type;
+        if (params?.jurisdictionId) query['jurisdictionId'] = params.jurisdictionId;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         const result = await this.transport.getList('/api/v1/data/calendar-events', query);
         if ('error' in result) return result;
         return {
@@ -1284,6 +1444,7 @@ class TimesheetsAccessor {
         if (params?.projectId) query['projectId'] = params.projectId;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
+        if (params?.updatedSince) query['updatedSince'] = params.updatedSince;
         if (params?.expand?.length) query['expand'] = params.expand.join(',');
         const result = await this.transport.getList('/api/v1/data/timesheets', query);
         if ('error' in result) return result;
@@ -1308,6 +1469,23 @@ class TimesheetsAccessor {
             data: transformTimesheet(result.data)
         };
     }
+    /**
+   * Bulk-create timesheet entries (partial accept). Requires `timesheets.create` scope.
+   * Returns `{ created, rejected }` — every valid item is inserted; invalid items come back
+   * with their input index + reason.
+   */ async bulkCreate(items) {
+        const result = await this.transport.post('/api/v1/data/timesheets/bulk', {
+            items: items.map((i)=>toSnakeBody(i))
+        });
+        if ('error' in result) return result;
+        const data = result.data;
+        return {
+            data: {
+                created: data.created.map((r)=>transformTimesheet(r)),
+                rejected: data.rejected
+            }
+        };
+    }
     /** Update a timesheet entry. Requires `timesheets.update` scope. */ async update(id, data) {
         const result = await this.transport.put(`/api/v1/data/timesheets/${id}`, toSnakeBody(data));
         if ('error' in result) return result;
@@ -1324,6 +1502,98 @@ class TimesheetsAccessor {
     }
 }
 
+/**
+ * CalendarAccessor — read workspace users' Google Calendar events (WS3).
+ * Requires the app's `calendar:read` scope. Not part of the bucket/CRUD scope system.
+ */ class CalendarAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    async listEvents(params) {
+        const result = await this.transport.get('/api/v1/data/calendar/events', {
+            employeeId: params.employeeId,
+            timeMin: params.timeMin,
+            timeMax: params.timeMax,
+            q: params.q
+        });
+        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.
+ */ class EmailAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    async send(input) {
+        const result = await this.transport.post('/api/v1/data/comms/send', input);
+        if ('error' in result) return result;
+        return {
+            data: result.data
+        };
+    }
+}
+
+function transform(raw) {
+    return {
+        id: raw['id'],
+        employeeId: raw['employee_id'],
+        hourlyCostRate: raw['hourly_cost_rate'] ?? null,
+        monthlyCostRate: raw['monthly_cost_rate'] ?? null,
+        hourlyBillableRate: raw['hourly_billable_rate'] ?? null,
+        monthlyBillableRate: raw['monthly_billable_rate'] ?? null,
+        salary: raw['salary'] ?? null,
+        currencyCode: raw['currency_code'],
+        effectiveFrom: raw['effective_from'],
+        effectiveTo: raw['effective_to'] ?? null
+    };
+}
+/**
+ * EmployeeCompensationAccessor — read/write an employee's effective-dated compensation (WS6).
+ * Gated server-side by the `employee-compensation` scope (buckets: `core`, `rates`, `salary`).
+ * `create` closes the prior open record and opens a new one (Nucleus = single comp authority).
+ */ class EmployeeCompensationAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    base(employeeId) {
+        return `/api/v1/data/employee-compensation/employees/${employeeId}/compensation`;
+    }
+    /** Full history, newest first. */ async list(employeeId) {
+        const result = await this.transport.get(this.base(employeeId));
+        if ('error' in result) return result;
+        return {
+            data: (result.data ?? []).map((r)=>transform(r))
+        };
+    }
+    /** The current (open) record, or null. */ async current(employeeId) {
+        const result = await this.transport.get(`${this.base(employeeId)}/current`);
+        if ('error' in result) return result;
+        return {
+            data: result.data ? transform(result.data) : null
+        };
+    }
+    /** Add a new effective-dated record (closes the prior open one). */ async create(employeeId, data) {
+        const result = await this.transport.post(this.base(employeeId), toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transform(result.data)
+        };
+    }
+    /** Soft-delete a compensation record. */ async delete(employeeId, id) {
+        const result = await this.transport.del(`${this.base(employeeId)}/${id}`);
+        if ('error' in result) return result;
+        return {
+            data: null
+        };
+    }
+}
+
 /**
  * AppsAccessor — wraps the self-service app info endpoint (§3.8, §6).
  * Calls GET /api/v1/platform/apps/me with the app token.
@@ -1478,6 +1748,8 @@ class AuthAccessor {
         this.currencies = new CurrenciesAccessor(transport);
         this.genericRates = new GenericRatesAccessor(transport);
         this.jurisdictions = new JurisdictionsAccessor(transport);
+        this.jobLevels = new JobLevelsAccessor(transport);
+        this.salaryBands = new SalaryBandsAccessor(transport);
         this.leaveTypes = new LeaveTypesAccessor(transport);
         this.leaves = new LeavesAccessor(transport);
         this.leaveBalances = new LeaveBalancesAccessor(transport);
@@ -1485,6 +1757,9 @@ class AuthAccessor {
         this.policyAcknowledgements = new PolicyAcknowledgementsAccessor(transport);
         this.calendarEvents = new CalendarEventsAccessor(transport);
         this.timesheets = new TimesheetsAccessor(transport);
+        this.calendar = new CalendarAccessor(transport);
+        this.email = new EmailAccessor(transport);
+        this.employeeCompensation = new EmployeeCompensationAccessor(transport);
         this.apps = new AppsAccessor(transport);
         this.files = new FilesAccessor(transport);
         this.auth = new AuthAccessor(config.baseUrl);
@@ -1494,7 +1769,7 @@ class AuthAccessor {
 /**
  * Nucleus SDK — Type System
  *
- * Bucket types are transcribed from docs/NUCLEUS_PIVOT.md §7 (Bucket Definitions).
+ * Bucket types are transcribed from docs/ARCHITECTURE.md §7 (Bucket Definitions).
  * Each bucket type contains only that bucket's fields.
  * The scope-to-type inference intersects selected bucket types at compile time.
  */ // ─── Utility types ────────────────────────────────────────────────────────────