@typeb-digital/nucleus-sdk 0.1.0 → 0.2.0

package/dist/es/index.js

@@ -413,6 +413,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;
@@ -564,6 +588,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;
@@ -581,23 +606,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;
@@ -606,9 +624,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;
@@ -647,6 +667,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 {
@@ -660,6 +707,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;
@@ -709,6 +757,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;
@@ -758,6 +807,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 {
@@ -803,6 +853,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 {
@@ -848,6 +899,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 {
@@ -897,6 +949,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 {
@@ -943,6 +996,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 {
@@ -980,6 +1034,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;
@@ -989,6 +1142,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 {
@@ -1037,6 +1191,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;
@@ -1088,6 +1243,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;
@@ -1138,6 +1294,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 {
@@ -1185,6 +1342,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;
@@ -1233,8 +1391,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 {
@@ -1282,6 +1442,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;
@@ -1306,6 +1467,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;
@@ -1322,6 +1500,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.
@@ -1476,6 +1746,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);
@@ -1483,6 +1755,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);
@@ -1492,7 +1767,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 ────────────────────────────────────────────────────────────

package/package.json

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