@unboundcx/sdk 4.13.76 → 4.13.81

package/index.js

@@ -38,6 +38,7 @@ import { FaxService } from './services/fax.js';
 import { DocumentsService } from './services/documents.js';
 import { EsignService } from './services/esign.js';
 import { PermissionsService } from './services/permissions.js';
+import { UsersService } from './services/users.js';
 import { TriggersService } from './services/triggers.js';
 import { RecentsService } from './services/recents.js';
 import { SearchService } from './services/search.js';
@@ -45,6 +46,7 @@ import { DirectoryService } from './services/directory.js';
 import { ChatService } from './services/chat.js';
 import { DeveloperApisService } from './services/developerApis.js';
 import { TextService } from './services/text.js';
+import { ReportingService } from './services/reporting.js';
 import {
   DataImportService,
   DataExportService,
@@ -136,6 +138,8 @@ class UnboundSDK extends BaseSDK {
     this.documents = new DocumentsService(this);
     this.esign = new EsignService(this);
     this.permissions = new PermissionsService(this);
+    this.users = new UsersService(this);
+    this.reporting = new ReportingService(this);
     this.triggers = new TriggersService(this);
     this.recents = new RecentsService(this);
     this.search = new SearchService(this);
@@ -340,6 +344,8 @@ export { KnowledgeBaseService } from './services/knowledgeBase.js';
 export { FaxService } from './services/fax.js';
 export { EsignService, EsignPublicService } from './services/esign.js';
 export { PermissionsService } from './services/permissions.js';
+export { UsersService } from './services/users.js';
+export { ReportingService } from './services/reporting.js';
 export { RecentsService } from './services/recents.js';
 export { SearchService } from './services/search.js';
 export { DirectoryService } from './services/directory.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.13.76",
+  "version": "4.13.81",
   "description": "Official JavaScript SDK for the Unbound API - A comprehensive toolkit for integrating with Unbound's communication, AI, and data management services",
   "main": "index.js",
   "type": "module",

package/services/permissions.js

@@ -5,7 +5,12 @@ export class PermissionsService {
   }
 
   /**
-   * List permission groups
+   * List permission groups. Server-filtered to what the caller can see
+   * (group access model): account admin / admin:group:manage /
+   * admin:group:view see every group; a group manager or member sees only
+   * their own group(s). Each row carries `members: [{id, role}]`,
+   * `canManage` (name/description/members), and `canManagePermissionSets`
+   * (account admin / admin:group:manage only).
    * @returns {Promise<Object>} Object with results: Array of permission groups
    * @example
    * const { results } = await sdk.permissions.listGroups();
@@ -20,24 +25,32 @@ export class PermissionsService {
    * @param {Object} group - Group configuration
    * @param {string} group.name - Group name (required)
    * @param {string} group.description - Group description
+   * @param {string} [group.type] - 'access' (default) or 'team'
+   * @param {string} [group.managerUserId] - Manager user id, for `team` groups
    * @returns {Promise<Object>} Created group
    * @example
    * await sdk.permissions.createGroup({
    *   name: 'Support Leads',
    *   description: 'Escalation-tier support agents',
+   *   type: 'team',
+   *   managerUserId: 'user-456',
    * });
    */
-  async createGroup({ name, description }) {
+  async createGroup({ name, description, type, managerUserId }) {
     this.sdk.validateParams(
-      { name, description },
+      { name, description, type, managerUserId },
       {
         name: { type: 'string', required: true },
         description: { type: 'string', required: false },
+        type: { type: 'string', required: false },
+        managerUserId: { type: 'string', required: false },
       },
     );
 
     const groupData = { name };
     if (description !== undefined) groupData.description = description;
+    if (type !== undefined) groupData.type = type;
+    if (managerUserId !== undefined) groupData.managerUserId = managerUserId;
 
     const params = {
       body: groupData,
@@ -50,10 +63,11 @@ export class PermissionsService {
   /**
    * Update an existing permission group
    * @param {string} groupId - Group ID to update
-   * @param {Object} data - Fields to update (e.g. name, description)
+   * @param {Object} data - Fields to update (name, description, type,
+   *   managerUserId)
    * @returns {Promise<Object>} Updated group
    * @example
-   * await sdk.permissions.updateGroup('group-123', { description: 'Updated' });
+   * await sdk.permissions.updateGroup('group-123', { type: 'team', managerUserId: 'user-456' });
    */
   async updateGroup(groupId, data) {
     groupId = String(groupId);
@@ -103,11 +117,13 @@ export class PermissionsService {
    * Add a user to a permission group
    * @param {string} groupId - Group ID
    * @param {string} userId - User ID to add
+   * @param {string} [role] - 'member' (default) or 'manager'
    * @returns {Promise<Object>} Membership confirmation
    * @example
    * await sdk.permissions.addGroupMember('group-123', 'user-456');
+   * await sdk.permissions.addGroupMember('group-123', 'user-456', 'manager');
    */
-  async addGroupMember(groupId, userId) {
+  async addGroupMember(groupId, userId, role) {
     groupId = String(groupId);
     userId = String(userId);
     this.sdk.validateParams(
@@ -118,11 +134,14 @@ export class PermissionsService {
       },
     );
 
+    const body = { userId };
+    if (role !== undefined) body.role = role;
+
     const params = {
-      body: { userId },
+      body,
     };
 
-    const result = await internalRequest(this.sdk, 
+    const result = await internalRequest(this.sdk,
       `/permissions/groups/${groupId}/members`,
       'POST',
       params,
@@ -130,6 +149,41 @@ export class PermissionsService {
     return result;
   }
 
+  /**
+   * Change a group member's role (Member / Manager) — group-manager-safe:
+   * account admin, admin:group:manage, or a manager of this group can call
+   * it; plain members cannot.
+   * @param {string} groupId - Group ID
+   * @param {string} userId - User ID
+   * @param {string} role - 'member' or 'manager'
+   * @returns {Promise<Object>} { groupId, userId, role }
+   * @example
+   * await sdk.permissions.updateGroupMemberRole('group-123', 'user-456', 'manager');
+   */
+  async updateGroupMemberRole(groupId, userId, role) {
+    groupId = String(groupId);
+    userId = String(userId);
+    this.sdk.validateParams(
+      { groupId, userId, role },
+      {
+        groupId: { type: 'string', required: true },
+        userId: { type: 'string', required: true },
+        role: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { role },
+    };
+
+    const result = await internalRequest(this.sdk,
+      `/permissions/groups/${groupId}/members/${userId}`,
+      'PUT',
+      params,
+    );
+    return result;
+  }
+
   /**
    * Remove a user from a permission group
    * @param {string} groupId - Group ID

package/services/reporting.js

@@ -0,0 +1,329 @@
+import { internalRequest } from '../base.js';
+import { ReportingAgentsService } from './reportingAgents.js';
+
+// Q2: same queryString helper as reportingAgents.js (kept local -- no
+// shared util module between the two files today).
+function queryString(params = {}) {
+  const parts = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') continue;
+    const v = Array.isArray(value) ? value.join(',') : value;
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
+  }
+  return parts.length ? `?${parts.join('&')}` : '';
+}
+
+// F7 (cc-reporting-foundation-plan.md §8) -- reporting API surface.
+export class ReportingService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.views = {
+      list: (...args) => this.listViews(...args),
+      create: (...args) => this.createView(...args),
+      update: (...args) => this.updateView(...args),
+      remove: (...args) => this.removeView(...args),
+    };
+    this.schedules = {
+      create: (...args) => this.createSchedule(...args),
+      list: (...args) => this.listSchedules(...args),
+      update: (...args) => this.updateSchedule(...args),
+      remove: (...args) => this.removeSchedule(...args),
+      runs: (...args) => this.listScheduleRuns(...args),
+      runNow: (...args) => this.runScheduleNow(...args),
+    };
+    // P3 (agent-reporting-plan.md §7 + §8.1): thin presets over the same
+    // registry above -- /reporting/agents/*. Split into its own file/class
+    // (house 400-line limit) since this file was already at 215 lines.
+    this.agents = new ReportingAgentsService(sdk);
+  }
+
+  /**
+   * Metrics + dimensions catalogue.
+   * @returns {Promise<Object>} { metrics: [...], dimensions: [...] }
+   * @example
+   * const { metrics } = await sdk.reporting.definitions();
+   */
+  async definitions() {
+    return internalRequest(this.sdk, '/reporting/definitions', 'GET');
+  }
+
+  /**
+   * Run a report over the reporting rollups (+ today stitch).
+   * @param {Object} body - { metrics, dimensions, filters, from, to, grain, tz, continuous }
+   * @returns {Promise<Object>} { columns, rows, definitions, meta }
+   * @example
+   * await sdk.reporting.query({ metrics: ['handled','slPct'], dimensions: ['queue','time'], from, to, grain: 'day' });
+   */
+  async query(body) {
+    this.sdk.validateParams(
+      { metrics: body?.metrics, from: body?.from, to: body?.to },
+      {
+        metrics: { type: 'array', required: true },
+        from: { type: 'string', required: true },
+        to: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(this.sdk, '/reporting/query', 'POST', { body });
+  }
+
+  /**
+   * Same as query(), but streams a CSV (forces HTTP transport).
+   * @param {Object} body
+   * @returns {Promise<Object>} raw CSV response (transport-dependent)
+   * @example
+   * await sdk.reporting.csv({ metrics: ['handled'], dimensions: ['queue'], from, to });
+   */
+  async csv(body) {
+    return internalRequest(this.sdk, '/reporting/query?format=csv', 'POST', { body, httpOnly: true });
+  }
+
+  /**
+   * Drilldown: the raw records underlying one metric cell.
+   * @param {Object} body - { metric, cell: { dimensions, bucketFrom, bucketTo }, cursor, limit }
+   * @returns {Promise<Object>} { rows, cursor, hasMore }
+   * @example
+   * await sdk.reporting.detail({ metric: 'handled', cell: { dimensions: { queueId }, bucketFrom, bucketTo } });
+   */
+  async detail(body) {
+    this.sdk.validateParams(
+      { metric: body?.metric },
+      { metric: { type: 'string', required: true } },
+    );
+    return internalRequest(this.sdk, '/reporting/detail', 'POST', { body });
+  }
+
+  /**
+   * Q2 preset: disposition matrix (code x queue|agent|code), incl. a
+   * noDisposition count for groupBy=queue|code.
+   * @param {Object} params - { from, to, queueIds, userIds, groupBy: 'queue'|'agent'|'code' }
+   * @returns {Promise<Object>} { groupBy, columns, rows, noDisposition, meta }
+   * @example
+   * await sdk.reporting.dispositions({ from, to, groupBy: 'queue' });
+   */
+  async dispositions({ from, to, queueIds, userIds, groupBy } = {}) {
+    this.sdk.validateParams(
+      { from, to },
+      { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/dispositions${queryString({ from, to, queueIds, userIds, groupBy })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Q2 preset: exec summary (originating-tasks-only KPI tiles + channel mix
+   * + trend), with a server-computed delta vs the previous period.
+   * @param {Object} params - { from, to, compareTo: 'previous' }
+   * @returns {Promise<Object>} { kpis, channelMix, trend, fcr, previousPeriod }
+   * @example
+   * await sdk.reporting.execSummary({ from, to, compareTo: 'previous' });
+   */
+  async execSummary({ from, to, compareTo } = {}) {
+    this.sdk.validateParams(
+      { from, to },
+      { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/execSummary${queryString({ from, to, compareTo })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Q2 preset: first-contact-resolution / repeat-contact count over
+   * accounts.fcrWindowHours.
+   * @param {Object} params - { from, to, queueIds }
+   * @returns {Promise<Object>} { windowHours, repeatContacts, originatingHandled, fcrPct }
+   * @example
+   * await sdk.reporting.fcr({ from, to });
+   */
+  async fcr({ from, to, queueIds } = {}) {
+    this.sdk.validateParams(
+      { from, to },
+      { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/fcr${queryString({ from, to, queueIds })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Rollup health: last computed bucket, lag, missing buckets.
+   * @returns {Promise<Object>}
+   * @example
+   * const { lagSeconds } = await sdk.reporting.health();
+   */
+  async health() {
+    return internalRequest(this.sdk, '/reporting/health', 'GET');
+  }
+
+  /**
+   * @returns {Promise<Object>} { results: [...] }
+   * @example
+   * const { results } = await sdk.reporting.views.list();
+   */
+  async listViews() {
+    return internalRequest(this.sdk, '/reporting/views', 'GET');
+  }
+
+  /**
+   * @param {Object} view - { name, query, isShared }
+   * @returns {Promise<Object>} created view
+   * @example
+   * await sdk.reporting.views.create({ name: 'Daily SL', query: {...} });
+   */
+  async createView({ name, query, isShared } = {}) {
+    this.sdk.validateParams(
+      { name, query },
+      { name: { type: 'string', required: true }, query: { type: 'object', required: true } },
+    );
+    const body = { name, query };
+    if (isShared !== undefined) body.isShared = isShared;
+    return internalRequest(this.sdk, '/reporting/views', 'POST', { body });
+  }
+
+  /**
+   * @param {string} id
+   * @param {Object} data - { name, query, isShared }
+   * @returns {Promise<Object>} updated view
+   * @example
+   * await sdk.reporting.views.update('263...', { isShared: true });
+   */
+  async updateView(id, data) {
+    id = String(id);
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    return internalRequest(this.sdk, `/reporting/views/${id}`, 'PUT', { body: data });
+  }
+
+  /**
+   * @param {string} id
+   * @returns {Promise<Object>} { id, deleted: true }
+   * @example
+   * await sdk.reporting.views.remove('263...');
+   */
+  async removeView(id) {
+    id = String(id);
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    return internalRequest(this.sdk, `/reporting/views/${id}`, 'DELETE');
+  }
+
+  /**
+   * @param {string} viewId
+   * @param {Object} schedule - { cron, timezone, recipients, format, runAs, isEnabled }
+   * @returns {Promise<Object>} created schedule
+   * @example
+   * await sdk.reporting.schedules.create('263...', { cron: '0 8 * * MON', timezone: 'America/Denver', recipients: ['a@b.com'] });
+   */
+  async createSchedule(viewId, { cron, timezone, recipients, format, runAs, isEnabled } = {}) {
+    viewId = String(viewId);
+    this.sdk.validateParams(
+      { viewId, cron, timezone, recipients },
+      {
+        viewId: { type: 'string', required: true },
+        cron: { type: 'string', required: true },
+        timezone: { type: 'string', required: true },
+        recipients: { type: 'array', required: true },
+      },
+    );
+    const body = { cron, timezone, recipients };
+    if (format !== undefined) body.format = format;
+    if (runAs !== undefined) body.runAs = runAs;
+    if (isEnabled !== undefined) body.isEnabled = isEnabled;
+    return internalRequest(this.sdk, `/reporting/views/${viewId}/schedule`, 'POST', { body });
+  }
+
+  /**
+   * @param {string} viewId
+   * @returns {Promise<Object>} { results: [...] }
+   * @example
+   * await sdk.reporting.schedules.list('263...');
+   */
+  async listSchedules(viewId) {
+    viewId = String(viewId);
+    this.sdk.validateParams({ viewId }, { viewId: { type: 'string', required: true } });
+    return internalRequest(this.sdk, `/reporting/views/${viewId}/schedule`, 'GET');
+  }
+
+  /**
+   * @param {string} viewId
+   * @param {string} scheduleId
+   * @param {Object} data - partial { cron, timezone, recipients, format, isEnabled }
+   * @returns {Promise<Object>} updated schedule
+   * @example
+   * await sdk.reporting.schedules.update('263...', '264...', { isEnabled: false });
+   */
+  async updateSchedule(viewId, scheduleId, data = {}) {
+    viewId = String(viewId);
+    scheduleId = String(scheduleId);
+    this.sdk.validateParams(
+      { viewId, scheduleId },
+      { viewId: { type: 'string', required: true }, scheduleId: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/views/${viewId}/schedule/${scheduleId}`,
+      'PUT',
+      { body: data },
+    );
+  }
+
+  /**
+   * @param {string} viewId
+   * @param {string} scheduleId
+   * @returns {Promise<Object>} { id, deleted: true }
+   * @example
+   * await sdk.reporting.schedules.remove('263...', '264...');
+   */
+  async removeSchedule(viewId, scheduleId) {
+    viewId = String(viewId);
+    scheduleId = String(scheduleId);
+    this.sdk.validateParams(
+      { viewId, scheduleId },
+      { viewId: { type: 'string', required: true }, scheduleId: { type: 'string', required: true } },
+    );
+    return internalRequest(this.sdk, `/reporting/views/${viewId}/schedule/${scheduleId}`, 'DELETE');
+  }
+
+  /**
+   * @returns {Promise<Array>} schedule runs (status, startedAt, finishedAt, error, attempt)
+   * @example
+   * await sdk.reporting.schedules.runs('263...', '264...');
+   */
+  async listScheduleRuns(viewId, scheduleId) {
+    viewId = String(viewId);
+    scheduleId = String(scheduleId);
+    this.sdk.validateParams(
+      { viewId, scheduleId },
+      { viewId: { type: 'string', required: true }, scheduleId: { type: 'string', required: true } },
+    );
+    return internalRequest(this.sdk, `/reporting/views/${viewId}/schedule/${scheduleId}/runs`, 'GET');
+  }
+
+  /**
+   * Manual trigger -- runs the same delivery path as the cron tick, awaits
+   * sent/failed instead of just queuing.
+   * @param {string} viewId
+   * @param {string} scheduleId
+   * @returns {Promise<Object>} { id, status, attempt, error? }
+   * @example
+   * await sdk.reporting.schedules.runNow('263...', '264...');
+   */
+  async runScheduleNow(viewId, scheduleId) {
+    viewId = String(viewId);
+    scheduleId = String(scheduleId);
+    this.sdk.validateParams(
+      { viewId, scheduleId },
+      { viewId: { type: 'string', required: true }, scheduleId: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/views/${viewId}/schedule/${scheduleId}/run-now`,
+      'POST',
+    );
+  }
+}

package/services/reportingAgents.js

@@ -0,0 +1,184 @@
+import { internalRequest } from '../base.js';
+
+function queryString(params = {}) {
+  const parts = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') continue;
+    const v = Array.isArray(value) ? value.join(',') : value;
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
+  }
+  return parts.length ? `?${parts.join('&')}` : '';
+}
+
+// P3 (agent-reporting-plan.md §7 + §8.1) -- /reporting/agents/* thin
+// presets over the Foundation registry. sdk.reporting.agents.*
+export class ReportingAgentsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Agent summary rows (§6 metrics), grouped by agent, queue, or team.
+   * @param {Object} params - { from, to, userIds, queueIds, teamIds, groupBy }
+   * @returns {Promise<Object>} { columns, rows, definitions, meta }
+   * @example
+   * await sdk.reporting.agents.summary({ from, to, groupBy: 'team' });
+   */
+  async summary({ from, to, userIds, queueIds, teamIds, groupBy } = {}) {
+    this.sdk.validateParams(
+      { from, to },
+      { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/agents/summary${queryString({ from, to, userIds, queueIds, teamIds, groupBy })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Collapsed presence timeline for one agent. userId 'me' resolves to the
+   * caller.
+   * @param {string} userId
+   * @param {Object} params - { from, to }
+   * @returns {Promise<Object>} { rows }
+   * @example
+   * await sdk.reporting.agents.states('me', { from, to });
+   */
+  async states(userId, { from, to } = {}) {
+    userId = String(userId);
+    this.sdk.validateParams(
+      { userId, from, to },
+      {
+        userId: { type: 'string', required: true },
+        from: { type: 'string', required: true },
+        to: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/agents/${userId}/states${queryString({ from, to })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Per-task interaction rows for one agent, paginated.
+   * @param {string} userId
+   * @param {Object} params - { from, to, cursor, limit }
+   * @returns {Promise<Object>} { rows, cursor, hasMore }
+   * @example
+   * await sdk.reporting.agents.interactions('me', { from, to });
+   */
+  async interactions(userId, { from, to, cursor, limit } = {}) {
+    userId = String(userId);
+    this.sdk.validateParams(
+      { userId, from, to },
+      {
+        userId: { type: 'string', required: true },
+        from: { type: 'string', required: true },
+        to: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/agents/${userId}/interactions${queryString({ from, to, cursor, limit })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * Per-agent per-local-day timesheet rows (net paid hours).
+   * @param {Object} params - { from, to, userIds, teamIds }
+   * @returns {Promise<Object>} { columns, rows }
+   * @example
+   * await sdk.reporting.agents.timesheet({ from, to, userIds: ['u1'] });
+   */
+  async timesheet({ from, to, userIds, teamIds } = {}) {
+    this.sdk.validateParams(
+      { from, to },
+      { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/agents/timesheet${queryString({ from, to, userIds, teamIds })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * CSV export of any of the four views above.
+   * @param {Object} params - { view: 'summary'|'states'|'interactions'|'timesheet', from, to, userId, userIds, queueIds, teamIds, groupBy }
+   * @returns {Promise<Object>} raw CSV response (transport-dependent)
+   * @example
+   * await sdk.reporting.agents.export({ view: 'timesheet', from, to });
+   */
+  async export({ view, from, to, userId, userIds, queueIds, teamIds, groupBy } = {}) {
+    this.sdk.validateParams(
+      { from, to },
+      { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
+    );
+    const qs = queryString({
+      view,
+      from,
+      to,
+      userId,
+      userIds,
+      queueIds,
+      teamIds,
+      groupBy,
+      format: 'csv',
+    });
+    return internalRequest(this.sdk, `/reporting/agents/export${qs}`, 'GET', { httpOnly: true });
+  }
+
+  /**
+   * §8.1 quality trend: aiScoreAvg/humanScoreAvg + n/N counts, per day.
+   * @param {string} userId
+   * @param {Object} params - { from, to, grain }
+   * @returns {Promise<Object>} { columns, rows, definitions, meta }
+   * @example
+   * await sdk.reporting.agents.qualityTrend('me', { from, to, grain: 'day' });
+   */
+  async qualityTrend(userId, { from, to, grain } = {}) {
+    userId = String(userId);
+    this.sdk.validateParams(
+      { userId, from, to },
+      {
+        userId: { type: 'string', required: true },
+        from: { type: 'string', required: true },
+        to: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/agents/${userId}/qualityTrend${queryString({ from, to, grain })}`,
+      'GET',
+    );
+  }
+
+  /**
+   * §8.1 best/lowest playbook-scored tasks for one agent.
+   * @param {string} userId
+   * @param {Object} params - { from, to, order: 'best'|'lowest', limit }
+   * @returns {Promise<Object>} { rows }
+   * @example
+   * await sdk.reporting.agents.topTasks('me', { from, to, order: 'lowest', limit: 10 });
+   */
+  async topTasks(userId, { from, to, order, limit } = {}) {
+    userId = String(userId);
+    this.sdk.validateParams(
+      { userId, from, to },
+      {
+        userId: { type: 'string', required: true },
+        from: { type: 'string', required: true },
+        to: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/reporting/agents/${userId}/topTasks${queryString({ from, to, order, limit })}`,
+      'GET',
+    );
+  }
+}

package/services/users.js

@@ -0,0 +1,134 @@
+import { internalRequest } from '../base.js';
+
+// agent-reporting-plan.md P0 — status reasons (§5.1) + a typed wrapper over
+// the existing status-set path (objects.updateById on the `users` object;
+// see app1-api src/services/objects/functions/customHandlers/update/users.js).
+// No existing "users" service in the SDK to extend — this is a new one.
+export class UsersService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.statusReasons = {
+      list: (...args) => this.listStatusReasons(...args),
+      create: (...args) => this.createStatusReason(...args),
+      update: (...args) => this.updateStatusReason(...args),
+      remove: (...args) => this.removeStatusReason(...args),
+    };
+    this.status = {
+      set: (...args) => this.setStatus(...args),
+    };
+  }
+
+  /**
+   * List agent status reasons (includes system rows).
+   * @returns {Promise<Object>} Object with results: Array of status reasons
+   * @example
+   * const { results } = await sdk.users.statusReasons.list();
+   */
+  async listStatusReasons() {
+    return internalRequest(this.sdk, '/userStatusReasons', 'GET');
+  }
+
+  /**
+   * Create an admin-defined status reason.
+   * @param {Object} reason
+   * @param {string} reason.code - Unique code (required)
+   * @param {string} reason.label - Display label (required)
+   * @param {string} reason.state - 'Away' | 'Busy' | 'Offline' (required)
+   * @param {string} [reason.emoji]
+   * @param {number} [reason.maxSeconds]
+   * @param {boolean} [reason.isPaid]
+   * @param {number} [reason.order]
+   * @returns {Promise<Object>} Created status reason
+   * @example
+   * await sdk.users.statusReasons.create({ code: 'standup', label: 'Standup', state: 'Away' });
+   */
+  async createStatusReason({ code, label, state, emoji, maxSeconds, isPaid, order }) {
+    this.sdk.validateParams(
+      { code, label, state },
+      {
+        code: { type: 'string', required: true },
+        label: { type: 'string', required: true },
+        state: { type: 'string', required: true },
+      },
+    );
+
+    const body = { code, label, state };
+    if (emoji !== undefined) body.emoji = emoji;
+    if (maxSeconds !== undefined) body.maxSeconds = maxSeconds;
+    if (isPaid !== undefined) body.isPaid = isPaid;
+    if (order !== undefined) body.order = order;
+
+    return internalRequest(this.sdk, '/userStatusReasons', 'POST', { body });
+  }
+
+  /**
+   * Update a status reason (label/emoji/maxSeconds/isPaid/order only —
+   * code/state are immutable for every row).
+   * @param {string} id
+   * @param {Object} data
+   * @returns {Promise<Object>} Updated status reason
+   * @example
+   * await sdk.users.statusReasons.update('usr_break', { maxSeconds: 600 });
+   */
+  async updateStatusReason(id, data) {
+    id = String(id);
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+
+    return internalRequest(this.sdk, `/userStatusReasons/${id}`, 'PUT', {
+      body: data,
+    });
+  }
+
+  /**
+   * Delete (soft) an admin-defined status reason. System reasons cannot be
+   * deleted.
+   * @param {string} id
+   * @returns {Promise<Object>} Deletion confirmation
+   * @example
+   * await sdk.users.statusReasons.remove('usr_standup');
+   */
+  async removeStatusReason(id) {
+    id = String(id);
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+
+    return internalRequest(this.sdk, `/userStatusReasons/${id}`, 'DELETE');
+  }
+
+  /**
+   * Set the current user's (or another user's, with permission) presence
+   * status. Thin typed wrapper over
+   * `sdk.objects.updateById({ object: 'users', ... })` — the underlying
+   * write path is unchanged, this just gives status-set a discoverable,
+   * typed entry point that also carries `reasonId`.
+   * @param {string} userId
+   * @param {Object} status
+   * @param {string} status.state - e.g. 'Available' | 'Away' | 'Busy' | 'Offline'
+   * @param {string} [status.reasonId] - id from statusReasons.list()
+   * @param {string} [status.label] - custom label, when no reasonId applies
+   * @param {string} [status.emoji] - custom emoji, when no reasonId applies
+   * @returns {Promise<Object>} Updated user
+   * @example
+   * await sdk.users.status.set('user-123', { state: 'Away', reasonId: 'usr_break' });
+   */
+  async setStatus(userId, { state, reasonId, label, emoji } = {}) {
+    userId = String(userId);
+    this.sdk.validateParams(
+      { userId, state },
+      {
+        userId: { type: 'string', required: true },
+        state: { type: 'string', required: true },
+      },
+    );
+
+    const status = { state };
+    if (reasonId !== undefined) status.reasonId = reasonId;
+    if (label !== undefined) status.label = label;
+    if (emoji !== undefined) status.emoji = emoji;
+
+    return this.sdk.objects.updateById({
+      object: 'users',
+      id: userId,
+      update: { status },
+    });
+  }
+}