@unboundcx/sdk 4.13.81 → 4.13.84

package/index.js

@@ -26,6 +26,7 @@ import { CobrowseService } from './services/cobrowse.js';
 import { MessageTemplatesService } from './services/messageTemplates.js';
 import { ExternalOAuthService } from './services/externalOAuth.js';
 import { GoogleCalendarService } from './services/googleCalendar.js';
+import { FormsService } from './services/forms.js';
 import { DriveService } from './services/drive.js';
 import { EnrollService } from './services/enroll.js';
 import { PhoneNumbersService } from './services/phoneNumbers.js';
@@ -125,6 +126,7 @@ class UnboundSDK extends BaseSDK {
     this.messageTemplates = new MessageTemplatesService(this);
     this.externalOAuth = new ExternalOAuthService(this);
     this.googleCalendar = new GoogleCalendarService(this);
+    this.forms = new FormsService(this);
     this.drive = new DriveService(this);
     this.enroll = new EnrollService(this);
     this.phoneNumbers = new PhoneNumbersService(this);
@@ -326,6 +328,8 @@ export { MessageTemplatesService } from './services/messageTemplates.js';
 export { WebchatVisitorService } from './services/webchat/VisitorService.js';
 export { ExternalOAuthService } from './services/externalOAuth.js';
 export { GoogleCalendarService } from './services/googleCalendar.js';
+export { FormsService } from './services/forms.js';
+export { FormsPublicService } from './services/forms/PublicService.js';
 export { DriveService } from './services/drive.js';
 export { EnrollService } from './services/enroll.js';
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.13.81",
+  "version": "4.13.84",
   "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/forms/PublicService.js

@@ -0,0 +1,57 @@
+import { internalRequest } from '../../base.js';
+
+// Public, unauthenticated forms surface -- `sdk.forms.public`. Mirrors
+// WebchatVisitorService.js: the sdk instance backing this only needs
+// `namespace` (or a custom `baseURL`) set at construction, never
+// `sdk.token`. POSTs `forceFetch` (HTTP-only, no NATS transport) since
+// these are one-shot fetches from a customer page / marketing site, same
+// as every other visitor-facing call.
+//
+// Wire shape matches `POST /f/:publicKey` (app1-api webhooks service,
+// forms-v2-precheck.md §4.1): plain form fields go at the top level of the
+// body (fieldKey -> value, arrays allowed), and everything the server
+// treats as a *control* field (not a form value) is sent with a leading
+// underscore -- the same convention formSubmit.js/formSubmitPublicKey.js
+// already split on for the legacy `_token` field.
+export class FormsPublicService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Submit a public form by its publicKey (D1 -- every form has its own
+   * publicKey; no tracking-code/_token needed for this path). Legacy
+   * hosted-fields forms keep using the `/webhooks/form/:formId` +
+   * `_token` path (unchanged, not exposed here).
+   * @param {string} publicKey
+   * @param {Object} fields - fieldKey -> value (arrays kept as arrays).
+   * @param {Object} [options]
+   * @param {Object} [options.context] - Client-observed context (utm/referrer/
+   *   landingUrl/etc, D12) to merge with what the server infers from the
+   *   request itself -- sent as the `_context` control field.
+   * @param {string} [options.captchaToken] - Turnstile/etc response token
+   *   (D10); sent as `_captchaToken`. Ignored server-side until a captcha
+   *   provider is configured for the form/account.
+   * @param {string} [options.idempotencyKey] - Per-render dedupe token
+   *   (D10); sent as `_idempotencyKey`.
+   * @returns {Promise<{ok:boolean, message?:string}>}
+   */
+  async submit(publicKey, fields, { context, captchaToken, idempotencyKey } = {}) {
+    this.sdk.validateParams(
+      { publicKey },
+      { publicKey: { type: 'string', required: true } },
+    );
+    const body = { ...(fields || {}) };
+    if (idempotencyKey) body._idempotencyKey = idempotencyKey;
+    if (captchaToken) body._captchaToken = captchaToken;
+    if (context) body._context = context;
+
+    return internalRequest(
+      this.sdk,
+      `/f/${publicKey}`,
+      'POST',
+      { body },
+      true,
+    );
+  }
+}

package/services/forms/SettingsService.js

@@ -0,0 +1,46 @@
+import { internalRequest } from '../../base.js';
+
+// Agent-authenticated `formsAccountSettings` singleton -- `sdk.forms.settings`
+// (defaultRegion, turnstileSiteKey, turnstileSecretRef; plan §6.5's
+// account-settings page, `/app/setup/forms/account-settings`).
+//
+// GAP (forms-v2 P2, see plans/forms-v2-progress/P2.md): same as
+// SubmissionsService.js -- the server-side singleton get/set controller +
+// route are not built yet (no phase in forms-v2-precheck.md §9 owns this
+// file explicitly). `/forms/settings` is P2's proposed path, chosen to
+// mirror the client route name (`forms/account-settings`) rather than the
+// generic `/object/:objectName` shape, since `formsAccountSettings` is a
+// fixed-id singleton with no `id` the client ever knows (same shape as
+// `chatAccountSettings`/`aiAccountSettings`) -- not a normal CRUD object.
+// Whichever phase builds the backend (P5, alongside the account-settings
+// page per §9) should implement exactly this path/method pair, or bump
+// the SDK with a corrected one.
+export class FormsSettingsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * @returns {Promise<{defaultRegion?:string, turnstileSiteKey?:string, turnstileSecretRef?:string}>}
+   *   `turnstileSecretRef` is a reference/handle only -- the raw secret
+   *   never round-trips to the client.
+   */
+  async get() {
+    return internalRequest(this.sdk, '/forms/settings', 'GET');
+  }
+
+  /**
+   * Merge-patch the singleton row.
+   * @param {Object} patch
+   * @param {string} [patch.defaultRegion]
+   * @param {string} [patch.turnstileSiteKey]
+   * @param {string} [patch.turnstileSecret] - Plaintext; server stores only
+   *   `turnstileSecretRef` and never echoes the raw value back.
+   * @returns {Promise<Object>}
+   */
+  async set(patch) {
+    return internalRequest(this.sdk, '/forms/settings', 'PUT', {
+      body: { ...(patch || {}) },
+    });
+  }
+}

package/services/forms/SubmissionsService.js

@@ -0,0 +1,80 @@
+import { internalRequest } from '../../base.js';
+
+// Agent-authenticated formSubmissions actions -- `sdk.forms.submissions`.
+// Normal agent-token path (no forceFetch, no authHeaders), same as any
+// other authenticated service method (e.g. WebchatWidgetsService.get()).
+//
+// GAP (forms-v2 P2, see plans/forms-v2-progress/P2.md): the server-side
+// routes these call do NOT exist yet. forms-v2-precheck.md §9 gates the
+// Quarantine/reprocess UI behind P5, but never assigns an owner file for
+// the *backend* controllers -- adding them here to app1-api's
+// `objects/routes.js` (the `/:objectName/merge`-style precedent for a
+// custom per-object action route) is outside P2's file-ownership map, so
+// P2 only forward-declares the wire contract below. Whichever phase wires
+// the server (P5 for reprocess/markNotSpam per plan §8, or earlier if
+// needed) must implement these exact paths/methods, or bump the SDK with
+// a corrected path.
+export class FormsSubmissionsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Re-run the pipeline for an existing submission from its stored
+   * rawFields (marks the new submission's `reprocessedFromId`).
+   * @param {string} id - formSubmissions id.
+   * @returns {Promise<Object>}
+   */
+  async reprocess(id) {
+    this.sdk.validateParams(
+      { id },
+      { id: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/object/formSubmissions/${id}/reprocess`,
+      'POST',
+    );
+  }
+
+  /**
+   * Clear a submission's spam status (Quarantine "Not spam" action, D10).
+   * @param {string} id - formSubmissions id.
+   * @returns {Promise<Object>}
+   */
+  async markNotSpam(id) {
+    this.sdk.validateParams(
+      { id },
+      { id: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/object/formSubmissions/${id}/mark-not-spam`,
+      'POST',
+    );
+  }
+
+  /**
+   * Resolve a submission flagged `identityConflict`/`review` (D16).
+   * @param {string} id - formSubmissions id.
+   * @param {string} choice - Which candidate record to keep/link; shape is
+   *   whatever the Review queue UI (P4) settles on -- documented here as a
+   *   passthrough until that's built.
+   * @returns {Promise<Object>}
+   */
+  async resolveReview(id, choice) {
+    this.sdk.validateParams(
+      { id, choice },
+      {
+        id: { type: 'string', required: true },
+        choice: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/object/formSubmissions/${id}/resolve-review`,
+      'POST',
+      { body: { choice } },
+    );
+  }
+}

package/services/forms.js

@@ -0,0 +1,15 @@
+import { FormsPublicService } from './forms/PublicService.js';
+import { FormsSubmissionsService } from './forms/SubmissionsService.js';
+import { FormsSettingsService } from './forms/SettingsService.js';
+
+// Forms v2 (forms-v2-plan.md §7 / forms-v2-precheck.md §5) -- `sdk.forms`.
+// `public` needs no agent auth (VisitorService pattern, publicKey-scoped);
+// `submissions`/`settings` are normal agent-token calls.
+export class FormsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.public = new FormsPublicService(sdk);
+    this.submissions = new FormsSubmissionsService(sdk);
+    this.settings = new FormsSettingsService(sdk);
+  }
+}

package/services/reportingAgents.js

@@ -88,9 +88,10 @@ export class ReportingAgentsService {
   }
 
   /**
-   * Per-agent per-local-day timesheet rows (net paid hours).
+   * Per-agent per-local-day timesheet rows (net paid hours), plus one
+   * additive-sum row per agent (`agents`) for grouped totals.
    * @param {Object} params - { from, to, userIds, teamIds }
-   * @returns {Promise<Object>} { columns, rows }
+   * @returns {Promise<Object>} { columns, rows, agents }
    * @example
    * await sdk.reporting.agents.timesheet({ from, to, userIds: ['u1'] });
    */
@@ -107,13 +108,26 @@ export class ReportingAgentsService {
   }
 
   /**
-   * CSV export of any of the four views above.
-   * @param {Object} params - { view: 'summary'|'states'|'interactions'|'timesheet', from, to, userId, userIds, queueIds, teamIds, groupBy }
+   * CSV export of any of the four views above. For view: 'timesheet', pass
+   * `totals: true` to get one additive-sum row per agent instead of the
+   * flat per-agent-per-day rows.
+   * @param {Object} params - { view: 'summary'|'states'|'interactions'|'timesheet', from, to, userId, userIds, queueIds, teamIds, groupBy, totals }
    * @returns {Promise<Object>} raw CSV response (transport-dependent)
    * @example
    * await sdk.reporting.agents.export({ view: 'timesheet', from, to });
+   * await sdk.reporting.agents.export({ view: 'timesheet', from, to, totals: true });
    */
-  async export({ view, from, to, userId, userIds, queueIds, teamIds, groupBy } = {}) {
+  async export({
+    view,
+    from,
+    to,
+    userId,
+    userIds,
+    queueIds,
+    teamIds,
+    groupBy,
+    totals,
+  } = {}) {
     this.sdk.validateParams(
       { from, to },
       { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
@@ -127,6 +141,7 @@ export class ReportingAgentsService {
       queueIds,
       teamIds,
       groupBy,
+      totals: totals ? '1' : undefined,
       format: 'csv',
     });
     return internalRequest(this.sdk, `/reporting/agents/export${qs}`, 'GET', { httpOnly: true });