@typeb-digital/nucleus-sdk 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,114 @@ 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.3.1] - 2026-07-07
+
+Calendar-event jurisdiction support. Additive and non-breaking.
+
+### Added
+
+- **`calendarEvents` expose jurisdiction.** `CalendarEventCore` now includes
+  `jurisdictionId: string | null` (which jurisdiction a holiday applies to; null for
+  non-holiday events) and `national: boolean` (national vs region-specific holiday).
+- **Expandable `jurisdiction`.** `calendarEvents.list(...)` and `calendarEvents.getById(...)`
+  accept `expand: ['jurisdiction']` to hydrate the full jurisdiction inline
+  (`event.jurisdiction` → the resolved jurisdiction, or `null`). Requires a `jurisdictions`
+  read scope on the token (the platform enforces scope on expanded resources). Example:
+
+  ```ts
+  const { data } = await nucleus.calendarEvents.list({
+    type: 'holiday',
+    expand: ['jurisdiction'],
+  });
+  data[0].jurisdiction?.name; // typed only when expanded
+  ```
+
+## [0.3.0] - 2026-07-01
+
+Leveling model v2 and app-writable employee data. **This is a breaking release** — the
+`employees` and `jobLevels` scope shapes changed (see _Migration_ below).
+
+### Changed
+
+- **BREAKING — `jobLevels` is now many-to-many with departments.** A level applies to any
+  number of departments (empty = company-wide), replacing the single-department field:
+
+  ```diff
+  - jobLevels.core.departmentId: string | null
+  + jobLevels.core.departmentIds: string[]
+  ```
+
+  The create/update input follows suit (`departmentId?` → `departmentIds?: string[]`), and
+  `jobLevels.list({ departmentId })` filters to levels that include that department.
+
+- **BREAKING — `employees` is now update-only, not read-only.** The scope moved from
+  `{ read }` to `{ read, update }`, and the readable fields were re-bucketed. A new writable
+  **`placement`** bucket holds `managerId`, `partnerId`, `departmentId`, `jurisdictionId`,
+  `jobLevelId`, `employmentType`, `isExternal`, and `timezone`; identity/contact/sensitive/
+  employment remain read-only (Google/HRIS-owned). Create and delete are still rejected
+  (onboarding requires Google Workspace provisioning).
+
+### Added
+
+- **`employees.update(id, data)`** — patch the `placement` bucket, gated at compile time by a
+  declared `employees.update` scope and per-bucket-authorized at runtime. Writing any
+  read-only field (identity/contact/etc.) is rejected with `400` / `INVALID_SCOPE`.
+- **`employeeProfiles` accessor** — work-arrangement records: `get(employeeId)` and
+  `upsert(employeeId, data)` (daily hours, probation months, overtime enabled).
+- **`employeeReviews` accessor** — `list` / `create` / `update` / `delete`. The `feedback`
+  bucket (rating + written feedback) is confidential and approval-gated, separate from the
+  `core` review metadata.
+- **`salaryBands.departmentId`** — bands can now be scoped to a department (null = company-wide
+  fallback); added to reads, create/update input, and the `list({ departmentId })` filter.
+- **`genericRates.jobLevelId`** — an optional link from a generic rate to a job level; added to
+  reads, create input, and the `list({ jobLevelId })` filter.
+
+### Migration
+
+1. `jobLevels`: replace any `departmentId` read/write with `departmentIds` (a `string[]`; use
+   `[]` for a company-wide level).
+2. `employees`: change the scope from a bucket array / read-only form to
+   `{ read: [...], update: ['placement'] }` if the app writes placement fields; call
+   `nucleus.employees.update(id, { ... })` for those writes. No create/delete.
+3. New optional fields (`salaryBands.departmentId`, `genericRates.jobLevelId`) are additive —
+   no action needed unless you want to set or filter by them.
+
+## [0.2.1] - 2026-06-30
+
+### Changed
+
+- **Removed `Department.titles`.** The unused `titles: string[]` field was dropped from the
+  `Department` type.
+
+### Fixed
+
+- **Inlined resource path literals.** Internal accessors (employee-compensation, project
+  members) previously built request paths through private helper methods; these are now inline
+  string literals. No behavioural change — this keeps the paths discoverable by the OpenAPI
+  sync check.
+- **`AddProjectMemberInput` is now a `type` alias** (was an `interface`), fixing a
+  snake-case body-cast type error. Field shape is unchanged.
+
+## [0.2.0] - 2026-06-29
+
+Reference data, compensation writes, and communication surfaces.
+
+### Added
+
+- **`jobLevels` accessor** — read the career-ladder levels (code, name, per-department scope).
+- **`salaryBands` accessor** — read per-`(level, jurisdiction)` pay ranges (financial figures
+  are sensitivity-gated).
+- **`employeeCompensation` accessor** — `list(employeeId)`, `current(employeeId)`,
+  `create(...)`, and `delete(employeeId, id)` for an employee's compensation history.
+- **`calendar.listEvents(params)`** — query Google Calendar events for a workspace user.
+- **`email.send(input)`** — send mode-aware email (live sends via Gmail; test mode is
+  sandboxed).
+- **`timesheets.bulkCreate(...)`** — create many timesheet entries in one request.
+- **Project team membership** — `projects.listMembers`, `addMember`, and `removeMember`.
+- **Incremental sync** — list accessors accept `updatedSince` (ISO-8601) to return only records
+  changed at or after that time.
+- **`projects.list({ stage })`** — filter projects by pipeline stage.
+
 ## [0.1.1] - 2026-06-22
 
 ### Changed

package/dist/cjs/index.cjs

@@ -399,6 +399,7 @@ function transformGenericRate(raw) {
     if ('id' in r) out['id'] = r['id'];
     if ('title' in r) out['title'] = str(r['title']);
     if ('department' in r) out['department'] = str(r['department']);
+    if ('job_level_id' in r) out['jobLevelId'] = str(r['job_level_id']);
     if ('currency_code' in r) out['currencyCode'] = str(r['currency_code']);
     if ('cost_rate' in r) out['costRate'] = num(r['cost_rate']);
     if ('billable_rate' in r) out['billableRate'] = num(r['billable_rate']);
@@ -421,7 +422,10 @@ function transformJobLevel(raw) {
     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']);
+    // The API returns the join rows under `departments`; flatten to a string[] of ids.
+    if ('departments' in r && Array.isArray(r['departments'])) {
+        out['departmentIds'] = r['departments'].map((d)=>d?.['department_id']).filter((v)=>typeof v === 'string');
+    }
     if ('sort_order' in r) out['sortOrder'] = num(r['sort_order']) ?? 0;
     return out;
 }
@@ -431,6 +435,7 @@ function transformSalaryBand(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 ('department_id' in r) out['departmentId'] = str(r['department_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']);
@@ -547,6 +552,12 @@ function transformCalendarEvent(raw) {
     if ('location' in r) out['location'] = str(r['location']);
     if ('color' in r) out['color'] = str(r['color']);
     if ('is_published' in r) out['isPublished'] = bool(r['is_published']);
+    if ('jurisdiction_id' in r) out['jurisdictionId'] = str(r['jurisdiction_id']);
+    if ('national' in r) out['national'] = bool(r['national']);
+    // Expand: jurisdiction (recursively transformed)
+    if ('jurisdiction' in r) {
+        out['jurisdiction'] = r['jurisdiction'] ? transformJurisdiction(r['jurisdiction']) : null;
+    }
     return out;
 }
 function transformTimesheet(raw) {
@@ -607,6 +618,18 @@ class EmployeesAccessor {
             data: transformEmployee(result.data)
         };
     }
+    /**
+   * Update an employee's placement (manager, partner, department, jurisdiction, job
+   * level, employment type, external flag, timezone). Requires `employees` update on the
+   * `placement` bucket. Identity/contact/sensitive fields are Google-owned and read-only;
+   * employees cannot be created or deleted via the SDK.
+   */ 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)
+        };
+    }
 }
 
 function transformMember(raw) {
@@ -671,25 +694,22 @@ class ProjectsAccessor {
     // ─── 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));
+        const result = await this.transport.get(`/api/v1/data/project-memberships/projects/${projectId}/members`);
         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));
+        const result = await this.transport.post(`/api/v1/data/project-memberships/projects/${projectId}/members`, 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}`);
+        const result = await this.transport.del(`/api/v1/data/project-memberships/projects/${projectId}/members/${employeeId}`);
         if ('error' in result) return result;
         return {
             data: null
@@ -1093,6 +1113,7 @@ class JurisdictionsAccessor {
     async list(params) {
         const query = {};
         if (params?.jobLevelId) query['jobLevelId'] = params.jobLevelId;
+        if (params?.departmentId) query['departmentId'] = params.departmentId;
         if (params?.jurisdictionId) query['jurisdictionId'] = params.jurisdictionId;
         if (params?.page) query['page'] = params.page;
         if (params?.pageSize) query['pageSize'] = params.pageSize;
@@ -1396,6 +1417,7 @@ class CalendarEventsAccessor {
         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/calendar-events', query);
         if ('error' in result) return result;
         return {
@@ -1403,8 +1425,10 @@ class CalendarEventsAccessor {
             meta: result.meta
         };
     }
-    async getById(id) {
-        const result = await this.transport.get(`/api/v1/data/calendar-events/${id}`);
+    async getById(id, options) {
+        const query = {};
+        if (options?.expand?.length) query['expand'] = options.expand.join(',');
+        const result = await this.transport.get(`/api/v1/data/calendar-events/${id}`, query);
         if ('error' in result) return result;
         return {
             data: transformCalendarEvent(result.data)
@@ -1538,7 +1562,7 @@ class TimesheetsAccessor {
     }
 }
 
-function transform(raw) {
+function transform$2(raw) {
     return {
         id: raw['id'],
         employeeId: raw['employee_id'],
@@ -1560,32 +1584,111 @@ function transform(raw) {
     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));
+        const result = await this.transport.get(`/api/v1/data/employee-compensation/employees/${employeeId}/compensation`);
         if ('error' in result) return result;
         return {
-            data: (result.data ?? []).map((r)=>transform(r))
+            data: (result.data ?? []).map((r)=>transform$2(r))
         };
     }
     /** The current (open) record, or null. */ async current(employeeId) {
-        const result = await this.transport.get(`${this.base(employeeId)}/current`);
+        const result = await this.transport.get(`/api/v1/data/employee-compensation/employees/${employeeId}/compensation/current`);
         if ('error' in result) return result;
         return {
-            data: result.data ? transform(result.data) : null
+            data: result.data ? transform$2(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));
+        const result = await this.transport.post(`/api/v1/data/employee-compensation/employees/${employeeId}/compensation`, toSnakeBody(data));
         if ('error' in result) return result;
         return {
-            data: transform(result.data)
+            data: transform$2(result.data)
         };
     }
     /** Soft-delete a compensation record. */ async delete(employeeId, id) {
-        const result = await this.transport.del(`${this.base(employeeId)}/${id}`);
+        const result = await this.transport.del(`/api/v1/data/employee-compensation/employees/${employeeId}/compensation/${id}`);
+        if ('error' in result) return result;
+        return {
+            data: null
+        };
+    }
+}
+
+function transform$1(raw) {
+    return {
+        id: raw['id'],
+        employeeId: raw['employee_id'],
+        dailyHours: raw['daily_hours'] ?? 8,
+        probationMonths: raw['probation_months'] ?? null,
+        isOvertimeEnabled: raw['is_overtime_enabled'] ?? false
+    };
+}
+/**
+ * EmployeeProfilesAccessor — an employee's work-arrangement profile (Iteration 4).
+ * Gated server-side by the `employee-profiles` scope.
+ */ class EmployeeProfilesAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    async get(employeeId) {
+        const result = await this.transport.get(`/api/v1/data/employee-profiles/employees/${employeeId}/profile`);
+        if ('error' in result) return result;
+        return {
+            data: result.data ? transform$1(result.data) : null
+        };
+    }
+    /** Create-or-update the profile. Requires `employee-profiles` update scope. */ async upsert(employeeId, data) {
+        const result = await this.transport.put(`/api/v1/data/employee-profiles/employees/${employeeId}/profile`, toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transform$1(result.data)
+        };
+    }
+}
+
+function transform(raw) {
+    return {
+        id: raw['id'],
+        employeeId: raw['employee_id'],
+        reviewType: raw['review_type'],
+        dueDate: raw['due_date'] ?? null,
+        completedDate: raw['completed_date'] ?? null,
+        status: raw['status'],
+        rating: raw['rating'] ?? null,
+        feedback: raw['feedback'] ?? null,
+        reviewerId: raw['reviewer_id'] ?? null
+    };
+}
+/**
+ * EmployeeReviewsAccessor — performance reviews (Iteration 4). Gated server-side by the
+ * `employee-reviews` scope; the `feedback` bucket (rating + feedback) is approval-gated.
+ */ class EmployeeReviewsAccessor {
+    constructor(transport){
+        this.transport = transport;
+    }
+    async list(employeeId) {
+        const result = await this.transport.get(`/api/v1/data/employee-reviews/employees/${employeeId}/reviews`);
+        if ('error' in result) return result;
+        return {
+            data: (result.data ?? []).map((r)=>transform(r))
+        };
+    }
+    async create(employeeId, data) {
+        const result = await this.transport.post(`/api/v1/data/employee-reviews/employees/${employeeId}/reviews`, toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transform(result.data)
+        };
+    }
+    async update(employeeId, id, data) {
+        const result = await this.transport.patch(`/api/v1/data/employee-reviews/employees/${employeeId}/reviews/${id}`, toSnakeBody(data));
+        if ('error' in result) return result;
+        return {
+            data: transform(result.data)
+        };
+    }
+    async delete(employeeId, id) {
+        const result = await this.transport.del(`/api/v1/data/employee-reviews/employees/${employeeId}/reviews/${id}`);
         if ('error' in result) return result;
         return {
             data: null
@@ -1759,6 +1862,8 @@ class AuthAccessor {
         this.calendar = new CalendarAccessor(transport);
         this.email = new EmailAccessor(transport);
         this.employeeCompensation = new EmployeeCompensationAccessor(transport);
+        this.employeeProfiles = new EmployeeProfilesAccessor(transport);
+        this.employeeReviews = new EmployeeReviewsAccessor(transport);
         this.apps = new AppsAccessor(transport);
         this.files = new FilesAccessor(transport);
         this.auth = new AuthAccessor(config.baseUrl);

package/dist/cjs/index.d.cts

@@ -49,8 +49,6 @@ type EmployeeIdentity = {
     jobTitle: string | null;
     department: string | null;
     employmentStatus: string;
-    employmentType: string | null;
-    isExternal: boolean;
 };
 type EmployeeContact = {
     profile: {
@@ -62,13 +60,21 @@ type EmployeeContact = {
 type EmployeeEmployment = {
     startDate: string | null;
     weeklyCapacity: number | null;
+    profile: {
+        biography?: string | null;
+    };
+};
+/** HR-managed org placement — the only app-writable employee bucket (update-only). */
+type EmployeePlacement = {
     managerId: string | null;
     partnerId: string | null;
+    departmentId: string | null;
+    jurisdictionId: string | null;
+    jobLevelId: string | null;
+    employmentType: string | null;
+    isExternal: boolean;
     /** IANA timezone string, e.g. "Asia/Colombo". Null when not yet set. */
     timezone: string | null;
-    profile: {
-        biography?: string | null;
-    };
 };
 type EmployeeSensitive = {
     birthday: string | null;
@@ -107,10 +113,22 @@ type EmployeeBucketMap = {
     identity: EmployeeIdentity;
     contact: EmployeeContact;
     employment: EmployeeEmployment;
+    placement: EmployeePlacement;
     sensitive: EmployeeSensitive;
     compensation: EmployeeCompensation;
     compensation_history: EmployeeCompensationHistory;
 };
+/** Body for `employees.update` — the writable `placement` fields only. */
+type EmployeePlacementUpdateInput = {
+    managerId?: string | null;
+    partnerId?: string | null;
+    departmentId?: string | null;
+    jurisdictionId?: string | null;
+    jobLevelId?: string | null;
+    employmentType?: string | null;
+    isExternal?: boolean;
+    timezone?: string | null;
+};
 type ProjectMembership = {
     employeeId: string;
     role: string | null;
@@ -226,6 +244,7 @@ type GenericRateCore = {
     id: string;
     title: string;
     department: string;
+    jobLevelId: string | null;
     currencyCode: string;
 };
 type GenericRateFinancials = {
@@ -249,7 +268,8 @@ type JobLevelCore = {
     id: string;
     name: string;
     code: string | null;
-    departmentId: string | null;
+    /** Departments this level applies to. Empty = company-wide. */
+    departmentIds: string[];
     sortOrder: number;
 };
 type JobLevelBucketMap = {
@@ -258,6 +278,7 @@ type JobLevelBucketMap = {
 type SalaryBandCore = {
     id: string;
     jobLevelId: string;
+    departmentId: string | null;
     jurisdictionId: string | null;
     currencyCode: string;
 };
@@ -346,6 +367,10 @@ type CalendarEventCore = {
     location: string | null;
     color: string | null;
     isPublished: boolean;
+    /** Jurisdiction this event applies to (holidays); null for non-holiday events. */
+    jurisdictionId: string | null;
+    /** For holidays: national (country-level) vs region-specific. */
+    national: boolean;
 };
 type CalendarEventBucketMap = {
     core: CalendarEventCore;
@@ -387,12 +412,13 @@ type ResourceScope<M> = {
     update?: readonly (keyof M)[];
     delete?: boolean;
 };
-/** A resource Nucleus owns the writes for — only `read` may be declared. */
-type ReadOnlyResourceScope<M> = {
+/** A resource that may be read or updated, but never created/deleted (e.g. employees). */
+type UpdateOnlyResourceScope<M> = {
     read?: readonly (keyof M)[];
+    update?: readonly (keyof M)[];
 };
 type ScopeDeclaration = {
-    employees?: ReadOnlyResourceScope<EmployeeBucketMap>;
+    employees?: UpdateOnlyResourceScope<EmployeeBucketMap>;
     projects?: ResourceScope<ProjectBucketMap>;
     clients?: ResourceScope<ClientBucketMap>;
     partners?: ResourceScope<PartnerBucketMap>;
@@ -505,6 +531,10 @@ type WithTimesheetExpand<T, E extends readonly TimesheetExpandPath[], S extends
 } : unknown) & ('project' extends E[number] ? {
     project: ResolveProject<S> | null;
 } : unknown);
+type CalendarEventExpandPath = 'jurisdiction';
+type WithCalendarEventExpand<T, E extends readonly CalendarEventExpandPath[], S extends ScopeDeclaration> = T & ('jurisdiction' extends E[number] ? {
+    jurisdiction: ResolveJurisdiction<S> | null;
+} : unknown);
 type LeaveCreateInput = {
     employeeId: string;
     leaveTypeId: string;
@@ -577,6 +607,7 @@ type CurrencyUpdateInput = Partial<Omit<CurrencyCreateInput, 'code'>>;
 type GenericRateCreateInput = {
     title: string;
     department: string;
+    jobLevelId?: string | null;
     costRate: number;
     billableRate: number;
     currencyCode?: string;
@@ -595,13 +626,15 @@ type JurisdictionUpdateInput = Partial<JurisdictionCreateInput>;
 type JobLevelCreateInput = {
     name: string;
     code?: string | null;
-    /** Owning department; null = company-wide rung. */
-    departmentId?: string | null;
+    /** Departments this level applies to. Empty/omitted = company-wide rung. */
+    departmentIds?: string[];
     sortOrder?: number;
 };
 type JobLevelUpdateInput = Partial<JobLevelCreateInput>;
 type SalaryBandCreateInput = {
     jobLevelId: string;
+    /** Null = applies to all departments. */
+    departmentId?: string | null;
     /** Null = applies to all jurisdictions (org-wide band). */
     jurisdictionId?: string | null;
     currencyCode?: string;
@@ -748,6 +781,13 @@ declare class EmployeesAccessor<S extends ScopeDeclaration> {
     getById<E extends readonly EmployeeExpandPath[] = never[]>(id: string, options?: {
         expand?: E;
     }): Promise<SingleResult<WithEmployeeExpand<ResolveEmployee<S>, E, S>>>;
+    /**
+     * Update an employee's placement (manager, partner, department, jurisdiction, job
+     * level, employment type, external flag, timezone). Requires `employees` update on the
+     * `placement` bucket. Identity/contact/sensitive fields are Google-owned and read-only;
+     * employees cannot be created or deleted via the SDK.
+     */
+    update(id: string, data: IfUpdate<S['employees'], EmployeePlacementUpdateInput>): Promise<SingleResult<ResolveEmployee<S>>>;
 }
 
 type ProjectListParams = {
@@ -769,10 +809,10 @@ interface ProjectMember {
     employeeId: string;
     role: string | null;
 }
-interface AddProjectMemberInput {
+type AddProjectMemberInput = {
     employeeId: string;
     role?: string | null;
-}
+};
 declare class ProjectsAccessor<S extends ScopeDeclaration> {
     private readonly transport;
     constructor(transport: NucleusTransport);
@@ -788,7 +828,6 @@ declare class ProjectsAccessor<S extends ScopeDeclaration> {
     update(id: string, data: IfUpdate<S['projects'], ProjectUpdateInput>): Promise<SingleResult<ResolveProject<S>>>;
     /** Soft-delete a project. Requires `projects.delete` scope. */
     delete(id: IfDelete<S['projects'], string>): Promise<SingleResult<null>>;
-    private membersBase;
     /** List a project's team members. Requires `projects` read on the `team` bucket. */
     listMembers(projectId: string): Promise<SingleResult<ProjectMember[]>>;
     /** Add a team member. Requires `projects` update on the `team` bucket. */
@@ -912,6 +951,7 @@ declare class CurrenciesAccessor<S extends ScopeDeclaration> {
 
 type GenericRateListParams = {
     department?: string;
+    jobLevelId?: string;
     page?: number;
     pageSize?: number;
     /** ISO-8601 — return only records changed (created/updated/deleted) at or after this time (incremental sync). */
@@ -974,6 +1014,7 @@ declare class JobLevelsAccessor<S extends ScopeDeclaration> {
 
 type SalaryBandListParams = {
     jobLevelId?: string;
+    departmentId?: string;
     jurisdictionId?: string;
     page?: number;
     pageSize?: number;
@@ -1127,12 +1168,18 @@ type CalendarEventListParams = {
     pageSize?: number;
     /** ISO-8601 — return only records changed (created/updated/deleted) at or after this time (incremental sync). */
     updatedSince?: string;
+    /** Hydrate related resources inline (e.g. the event's jurisdiction). */
+    expand?: readonly CalendarEventExpandPath[];
 };
 declare class CalendarEventsAccessor<S extends ScopeDeclaration> {
     private readonly transport;
     constructor(transport: NucleusTransport);
-    list(params?: CalendarEventListParams): Promise<PaginatedResult<ResolveCalendarEvent<S>>>;
-    getById(id: string): Promise<SingleResult<ResolveCalendarEvent<S>>>;
+    list<E extends readonly CalendarEventExpandPath[] = never[]>(params?: CalendarEventListParams & {
+        expand?: E;
+    }): Promise<PaginatedResult<WithCalendarEventExpand<ResolveCalendarEvent<S>, E, S>>>;
+    getById<E extends readonly CalendarEventExpandPath[] = never[]>(id: string, options?: {
+        expand?: E;
+    }): Promise<SingleResult<WithCalendarEventExpand<ResolveCalendarEvent<S>, E, S>>>;
     /** Create a calendar event. Requires `calendarEvents.create` scope. */
     create(data: IfCreate<S['calendarEvents'], CalendarEventCreateInput>): Promise<SingleResult<ResolveCalendarEvent<S>>>;
     /** Update a calendar event. Requires `calendarEvents.update` scope. */
@@ -1266,7 +1313,6 @@ interface EmployeeCompensationInput {
 declare class EmployeeCompensationAccessor {
     private readonly transport;
     constructor(transport: NucleusTransport);
-    private base;
     /** Full history, newest first. */
     list(employeeId: string): Promise<SingleResult<EmployeeCompensationRecord[]>>;
     /** The current (open) record, or null. */
@@ -1277,6 +1323,67 @@ declare class EmployeeCompensationAccessor {
     delete(employeeId: string, id: string): Promise<SingleResult<null>>;
 }
 
+/** Per-employee work-arrangement settings. */
+interface EmployeeProfile {
+    id: string;
+    employeeId: string;
+    dailyHours: number;
+    probationMonths: number | null;
+    isOvertimeEnabled: boolean;
+}
+type EmployeeProfileInput = {
+    dailyHours?: number;
+    probationMonths?: number | null;
+    isOvertimeEnabled?: boolean;
+};
+/**
+ * EmployeeProfilesAccessor — an employee's work-arrangement profile (Iteration 4).
+ * Gated server-side by the `employee-profiles` scope.
+ */
+declare class EmployeeProfilesAccessor {
+    private readonly transport;
+    constructor(transport: NucleusTransport);
+    get(employeeId: string): Promise<SingleResult<EmployeeProfile | null>>;
+    /** Create-or-update the profile. Requires `employee-profiles` update scope. */
+    upsert(employeeId: string, data: EmployeeProfileInput): Promise<SingleResult<EmployeeProfile>>;
+}
+
+/** A performance review. `rating`/`feedback` are in the approval-gated `feedback` bucket. */
+interface EmployeeReview {
+    id: string;
+    employeeId: string;
+    reviewType: string;
+    dueDate: string | null;
+    completedDate: string | null;
+    status: string;
+    rating: string | null;
+    feedback: string | null;
+    reviewerId: string | null;
+}
+type EmployeeReviewCreateInput = {
+    reviewType: string;
+    dueDate?: string | null;
+    status?: string;
+    rating?: string | null;
+    feedback?: string | null;
+    reviewerId?: string | null;
+};
+type EmployeeReviewUpdateInput = Partial<EmployeeReviewCreateInput> & {
+    completedDate?: string | null;
+};
+/**
+ * EmployeeReviewsAccessor — performance reviews (Iteration 4). Gated server-side by the
+ * `employee-reviews` scope; the `feedback` bucket (rating + feedback) is approval-gated.
+ */
+declare class EmployeeReviewsAccessor {
+    private readonly transport;
+    constructor(transport: NucleusTransport);
+    list(employeeId: string): Promise<SingleResult<EmployeeReview[]>>;
+    create(employeeId: string, data: EmployeeReviewCreateInput): Promise<SingleResult<EmployeeReview>>;
+    update(employeeId: string, id: string, data: EmployeeReviewUpdateInput): Promise<SingleResult<EmployeeReview>>;
+    delete(employeeId: string, id: string): Promise<SingleResult<null>>;
+}
+
 /**
  * AppsAccessor — wraps the self-service app info endpoint (§3.8, §6).
  * Calls GET /api/v1/platform/apps/me with the app token.
@@ -1442,6 +1549,8 @@ declare class NucleusClient<const S extends ScopeDeclaration> {
     readonly email: EmailAccessor;
     /** Read/write an employee's compensation history (requires `employee-compensation` scope). */
     readonly employeeCompensation: EmployeeCompensationAccessor;
+    readonly employeeProfiles: EmployeeProfilesAccessor;
+    readonly employeeReviews: EmployeeReviewsAccessor;
     readonly apps: AppsAccessor;
     readonly files: FilesAccessor;
     readonly auth: AuthAccessor;