@unboundcx/sdk 4.13.75 → 4.13.80

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);
@@ -297,6 +301,7 @@ export { MessagingService } from './services/messaging.js';
 export { VideoService } from './services/video.js';
 export { VoiceService } from './services/voice.js';
 export { AIService } from './services/ai.js';
+export { PlaybooksService } from './services/ai/playbooks.js';
 export { LookupService } from './services/lookup.js';
 export { LayoutsService } from './services/layouts.js';
 export { SubscriptionsService } from './services/subscriptions.js';
@@ -339,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.75",
+  "version": "4.13.80",
   "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/ai/playbooks.js

@@ -186,6 +186,7 @@ export class PlaybooksService {
    * @param {string} [options.scoreType='boolean'] - Score type ('boolean' or 'scale')
    * @param {number} [options.weight=0] - Goal weight (0-100)
    * @param {boolean} [options.requiredForPass=false] - Whether required for pass
+   * @param {string} [options.visibility] - 'live' or 'reviewOnly'
    * @param {string} [options.recordTypeId] - Record type ID
    * @returns {Promise<Object>} Created goal with id
    *
@@ -211,6 +212,7 @@ export class PlaybooksService {
     signal,
     window,
     windowTurns,
+    visibility,
     recordTypeId,
   }) {
     this.sdk.validateParams(
@@ -240,6 +242,7 @@ export class PlaybooksService {
         signal: { type: 'string', required: false },
         window: { type: 'string', required: false },
         windowTurns: { type: 'number', required: false },
+        visibility: { type: 'string', required: false },
         recordTypeId: { type: 'string', required: false },
       },
     );
@@ -257,6 +260,7 @@ export class PlaybooksService {
         signal,
         window,
         windowTurns,
+        visibility,
         recordTypeId,
       },
     };
@@ -337,6 +341,7 @@ export class PlaybooksService {
    * @param {string} [options.scoreType] - Score type ('boolean' or 'scale')
    * @param {number} [options.weight] - Goal weight (0-100)
    * @param {boolean} [options.requiredForPass] - Whether required for pass
+   * @param {string} [options.visibility] - 'live' or 'reviewOnly'
    * @param {string} [options.recordTypeId] - Record type ID
    * @returns {Promise<Object>} Updated goal object
    *
@@ -360,6 +365,7 @@ export class PlaybooksService {
     signal,
     window,
     windowTurns,
+    visibility,
     recordTypeId,
   }) {
     this.sdk.validateParams(
@@ -389,6 +395,7 @@ export class PlaybooksService {
         signal: { type: 'string', required: false },
         window: { type: 'string', required: false },
         windowTurns: { type: 'number', required: false },
+        visibility: { type: 'string', required: false },
         recordTypeId: { type: 'string', required: false },
       },
     );
@@ -406,6 +413,7 @@ export class PlaybooksService {
         signal,
         window,
         windowTurns,
+        visibility,
         recordTypeId,
       },
     };
@@ -808,6 +816,7 @@ export class PlaybooksService {
    * @param {string} [options.taskId] - The task ID (used with workerId or userId)
    * @param {string} [options.workerId] - The worker ID (used with taskId)
    * @param {string} [options.userId] - The user ID (used with taskId)
+   * @param {boolean} [options.includeQa] - Include review-only goals and qaReview
    * @returns {Promise<Object>} Session object with playbookName and goals array
    *
    * @example
@@ -830,7 +839,7 @@ export class PlaybooksService {
    *   userId: 'user_789'
    * });
    */
-  async getSession({ sessionId, taskId, workerId, userId }) {
+  async getSession({ sessionId, taskId, workerId, userId, includeQa }) {
     this.sdk.validateParams(
       { sessionId, taskId, workerId, userId },
       {
@@ -838,13 +847,17 @@ export class PlaybooksService {
         taskId: { type: 'string', required: false },
         workerId: { type: 'string', required: false },
         userId: { type: 'string', required: false },
+        includeQa: { type: 'boolean', required: false },
       },
     );
 
     if (sessionId) {
+      const query = {};
+      if (includeQa) query.includeQa = 1;
       const result = await internalRequest(this.sdk, 
         `/ai/playbooks/sessions/${sessionId}`,
         'GET',
+        { query },
       );
       return result;
     }
@@ -853,6 +866,7 @@ export class PlaybooksService {
     if (taskId) query.taskId = taskId;
     if (workerId) query.workerId = workerId;
     if (userId) query.userId = userId;
+    if (includeQa) query.includeQa = 1;
 
     const result = await internalRequest(this.sdk, 
       `/ai/playbooks/sessions`,
@@ -1044,4 +1058,167 @@ export class PlaybooksService {
     );
     return result;
   }
+
+  /**
+   * Submit a human QA review for an AI playbook session (replace-semantics).
+   *
+   * @param {Object} options
+   * @param {string} options.sessionId
+   * @param {Array} options.goals
+   * @returns {Promise<Object>} QA review
+   */
+  async submitQaReview({ sessionId, goals }) {
+    this.sdk.validateParams(
+      { sessionId, goals },
+      {
+        sessionId: { type: 'string', required: true },
+        goals: { type: 'array', required: true },
+      },
+    );
+
+    const result = await internalRequest(
+      this.sdk,
+      `/ai/playbooks/sessions/${sessionId}/qa`,
+      'PUT',
+      { body: { goals } },
+    );
+    return result;
+  }
+
+  /**
+   * Get the primary QA review for an AI playbook session.
+   *
+   * @param {Object} options
+   * @param {string} options.sessionId
+   * @returns {Promise<Object>} QA review
+   */
+  async getQaReview({ sessionId }) {
+    this.sdk.validateParams(
+      { sessionId },
+      {
+        sessionId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await internalRequest(
+      this.sdk,
+      `/ai/playbooks/sessions/${sessionId}/qa`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * List QA disagreements for a playbook goal (keyset on reviewedAt, id).
+   *
+   * @param {Object} options
+   * @param {string} options.playbookGoalId
+   * @param {number} [options.limit]
+   * @param {string} [options.beforeReviewedAt]
+   * @param {string} [options.beforeId]
+   * @returns {Promise<Object>} { results, agreeRate, reviewedCount, disagreeCount, next }
+   */
+  async listQaDisagreements({
+    playbookGoalId,
+    limit,
+    beforeReviewedAt,
+    beforeId,
+  }) {
+    this.sdk.validateParams(
+      { playbookGoalId },
+      {
+        playbookGoalId: { type: 'string', required: true },
+        limit: { type: 'number', required: false },
+        beforeReviewedAt: { type: 'string', required: false },
+        beforeId: { type: 'string', required: false },
+      },
+    );
+
+    const query = {};
+    if (limit != null) query.limit = limit;
+    if (beforeReviewedAt) query.beforeReviewedAt = beforeReviewedAt;
+    if (beforeId) query.beforeId = beforeId;
+
+    const result = await internalRequest(
+      this.sdk,
+      `/ai/playbooks/goals/${playbookGoalId}/disagreements`,
+      'GET',
+      { query },
+    );
+    return result;
+  }
+
+  /**
+   * Playbook-level QA agree-rate (exact integer match).
+   *
+   * @param {Object} options
+   * @param {string} options.playbookId
+   * @returns {Promise<Object>} agree-rate payload
+   */
+  async getQaAgreeRate({ playbookId }) {
+    this.sdk.validateParams(
+      { playbookId },
+      {
+        playbookId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await internalRequest(
+      this.sdk,
+      `/ai/playbooks/${playbookId}/qa/agree-rate`,
+      'GET',
+    );
+    return result;
+  }
+
+  /**
+   * Suggest a criteria/window rewrite from QA disagreements. Never auto-applies.
+   *
+   * @param {Object} options
+   * @param {string} options.playbookGoalId
+   * @returns {Promise<Object>} { suggestionId, status, current, proposed, rationale }
+   */
+  async suggestGoalDefinition({ playbookGoalId }) {
+    this.sdk.validateParams(
+      { playbookGoalId },
+      {
+        playbookGoalId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await internalRequest(
+      this.sdk,
+      `/ai/playbooks/goals/${playbookGoalId}/suggest`,
+      'POST',
+      { body: {} },
+    );
+    return result;
+  }
+
+  /**
+   * Accept, edit, or reject a pending goal-definition suggestion.
+   *
+   * @param {Object} options
+   * @param {string} options.suggestionId
+   * @param {string} options.action - accept | reject | edit
+   * @param {Object} [options.proposed]
+   * @returns {Promise<Object>}
+   */
+  async resolveGoalSuggestion({ suggestionId, action, proposed }) {
+    this.sdk.validateParams(
+      { suggestionId, action },
+      {
+        suggestionId: { type: 'string', required: true },
+        action: { type: 'string', required: true },
+      },
+    );
+
+    const result = await internalRequest(
+      this.sdk,
+      `/ai/playbooks/suggestions/${suggestionId}/resolve`,
+      'POST',
+      { body: { action, proposed } },
+    );
+    return result;
+  }
 }

package/services/permissions.js

@@ -20,24 +20,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 +58,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);

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 },
+    });
+  }
+}