@unboundcx/sdk 4.13.82 → 4.13.85

package/base.js

@@ -114,6 +114,20 @@ export class BaseSDK {
           process.env?.API_BASE_URL || defaultDomain
         }`;
       }
+    } else if (this._constructorBaseURL && !this.namespace) {
+      // Forms v2 P3 fix: a browser-environment instance constructed with
+      // ONLY a literal baseURL (no namespace) -- e.g. sdk.forms.public /
+      // sdk.webchat.visitor on a page that resolves its tenant server-side
+      // from an opaque key, never a namespace subdomain -- must hit that
+      // exact baseURL. Before this fix, this branch unconditionally built
+      // `https://${namespace}.${baseUrl}` even when namespace was
+      // undefined, producing a literal "https://undefined.<host>" request
+      // URL (caught via forms-v2 marketing-site integration, P3). The
+      // Node branch above already had the equivalent guard
+      // (`if (!this._constructorBaseURL)`); this mirrors it for browser.
+      // A namespace passed ALONGSIDE baseURL still prefixes it (unchanged,
+      // existing behavior other callers rely on).
+      this.fullUrl = this._constructorBaseURL;
     } else {
       this.fullUrl = `https://${this.namespace}.${this.baseUrl}`;
     }

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.82",
+  "version": "4.13.85",
   "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);
+  }
+}