@unboundcx/sdk 4.13.94 → 4.13.95

package/base.js

@@ -16,17 +16,6 @@
 const requestBySdk = new WeakMap();
 const SDK_REQUEST = Symbol.for('unbound.sdk.request');
 
-/**
- * Safely read a process.env var. `process` is an undeclared global in a
- * browser/Vite bundle -- `process?.env?.X` does NOT protect against that
- * (optional chaining only guards property access, not a bare identifier
- * reference), so a browser bundle throws `ReferenceError: process is not
- * defined` the moment `process` is referenced at all. Gate on
- * `typeof process !== 'undefined'` first.
- */
-export const env = (key) =>
-  typeof process !== 'undefined' && process.env ? process.env[key] : undefined;
-
 /**
  * Service-internal request. Not part of the public SDK surface.
  * Named SDK methods call this; app code must not. Optional transports
@@ -54,14 +43,14 @@ export class BaseSDK {
     // Support both object and legacy positional parameters for backwards compatibility
     if (typeof options === 'string') {
       // Legacy positional parameters: (namespace, callId, token, fwRequestId)
-      this.namespace = options || env('namespace');
+      this.namespace = options || process?.env?.namespace;
       this.callId = arguments[1];
       this.token = arguments[2];
       this.fwRequestId = arguments[3];
     } else {
       // New object-based parameters
       const { namespace, callId, token, fwRequestId, baseURL } = options;
-      this.namespace = namespace || env('namespace');
+      this.namespace = namespace || process?.env?.namespace;
       this.callId = callId;
       this.token = token;
       this.fwRequestId = fwRequestId;
@@ -89,7 +78,7 @@ export class BaseSDK {
       // Server-side (Node.js)
       this.environment = 'node';
       this.baseURL = this._constructorBaseURL || `https://${this.namespace ? this.namespace : 'login'}.${
-        env('API_BASE_URL') || defaultDomain
+        process.env?.API_BASE_URL || defaultDomain
       }`;
     } else {
       // Client-side (browser)
@@ -102,7 +91,7 @@ export class BaseSDK {
         this.baseUrl = url.hostname.replace(/^[^.]+\./, '');
       } else {
         this.baseUrl =
-          this.baseUrl || env('API_BASE_URL') || defaultDomain;
+          this.baseUrl || process?.env?.API_BASE_URL || defaultDomain;
         if (this.baseUrl && !this.baseUrl.startsWith('api.')) {
           this.baseUrl = `api.${this.baseUrl}`;
         }
@@ -122,23 +111,9 @@ export class BaseSDK {
     if (this.environment === 'node') {
       if (!this._constructorBaseURL) {
         this.baseURL = `https://${this.namespace ? this.namespace : 'login'}.${
-          env('API_BASE_URL') || defaultDomain
+          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}`;
     }
@@ -307,9 +282,9 @@ export class BaseSDK {
       }
     } else {
       // No transport available, fallback to HTTP
-      if (forceFetch && env('AUTH_V3_TOKEN_TYPE_OVERRIDE')) {
+      if (forceFetch && process.env.AUTH_V3_TOKEN_TYPE_OVERRIDE) {
         params.headers['x-token-type-override'] =
-          env('AUTH_V3_TOKEN_TYPE_OVERRIDE');
+          process.env.AUTH_V3_TOKEN_TYPE_OVERRIDE;
       }
       return this._httpRequest(
         endpoint,
@@ -383,7 +358,7 @@ export class BaseSDK {
     returnRawResponse = false,
     startTime = Date.now(),
   ) {
-    const { body, query, headers = {}, credentials } = params;
+    const { body, query, headers = {} } = params;
 
     const options = {
       method,
@@ -398,13 +373,9 @@ export class BaseSDK {
       },
     };
 
-    // Set credentials for browser environment. Public/unauthenticated
-    // endpoints called from third-party origins (forms, webchat loader) opt
-    // out via params.credentials = 'omit' — app1-api's CORS only sends
-    // access-control-allow-credentials for trusted app1 base domains, so a
-    // browser rejects the response for `include` requests from other origins.
+    // Set credentials for browser environment
     if (this.environment === 'browser') {
-      options.credentials = credentials === 'omit' ? 'omit' : 'include';
+      options.credentials = 'include';
     }
 
     let url;

package/index.js

@@ -26,7 +26,6 @@ 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';
@@ -126,7 +125,6 @@ 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);
@@ -328,9 +326,6 @@ 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 { FormsHealthService } from './services/forms/HealthService.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.94",
+  "version": "4.13.95",
   "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",
@@ -52,9 +52,6 @@
       "import": "./index.js",
       "require": "./index.cjs"
     },
-    "./base.js": {
-      "import": "./base.js"
-    },
     "./services/*": {
       "import": "./services/*.js"
     },

package/services/storage.js

@@ -1,4 +1,4 @@
-import { internalRequest, env } from '../base.js';
+import { internalRequest } from '../base.js';
 export class StorageService {
   constructor(sdk) {
     this.sdk = sdk;
@@ -314,12 +314,13 @@ export class StorageService {
       headers = result.headers;
     }
 
-    if (env('AUTH_V3_TOKEN_TYPE_OVERRIDE')) {
-      headers['x-token-type-override'] = env('AUTH_V3_TOKEN_TYPE_OVERRIDE');
+    if (process?.env?.AUTH_V3_TOKEN_TYPE_OVERRIDE) {
+      headers['x-token-type-override'] =
+        process.env.AUTH_V3_TOKEN_TYPE_OVERRIDE;
     }
 
-    if (skipClamscan && env('CLAMSCAN_OVERRIDE_KEY')) {
-      headers['x-clamscan-override-key'] = env('CLAMSCAN_OVERRIDE_KEY');
+    if (skipClamscan && process?.env?.CLAMSCAN_OVERRIDE_KEY) {
+      headers['x-clamscan-override-key'] = process.env.CLAMSCAN_OVERRIDE_KEY;
     }
 
     const params = {
@@ -407,16 +408,16 @@ export class StorageService {
       }
 
       // Add environment variable override headers
-      if (env('AUTH_V3_TOKEN_TYPE_OVERRIDE')) {
+      if (process?.env?.AUTH_V3_TOKEN_TYPE_OVERRIDE) {
         xhr.setRequestHeader(
           'x-token-type-override',
-          env('AUTH_V3_TOKEN_TYPE_OVERRIDE'),
+          process.env.AUTH_V3_TOKEN_TYPE_OVERRIDE,
         );
       }
-      if (skipClamscan && env('CLAMSCAN_OVERRIDE_KEY')) {
+      if (skipClamscan && process?.env?.CLAMSCAN_OVERRIDE_KEY) {
         xhr.setRequestHeader(
           'x-clamscan-override-key',
-          env('CLAMSCAN_OVERRIDE_KEY'),
+          process.env.CLAMSCAN_OVERRIDE_KEY,
         );
       }
 
@@ -655,8 +656,8 @@ Response:
       if (metadata) formData.append('metadata', JSON.stringify(metadata));
     }
 
-    if (_options?.skipScan && env('CLAMSCAN_OVERRIDE_KEY')) {
-      headers['x-clamscan-override-key'] = env('CLAMSCAN_OVERRIDE_KEY');
+    if (_options?.skipScan && process?.env?.CLAMSCAN_OVERRIDE_KEY) {
+      headers['x-clamscan-override-key'] = process.env.CLAMSCAN_OVERRIDE_KEY;
     }
 
     const params = {

package/services/taskRouter/ParticipantService.js

@@ -170,15 +170,23 @@ export class ParticipantService {
    * @example
    * await sdk.taskRouter.participants.update({ taskId: 'task_123', participantId: 'tp_456', held: true });
    */
-  async update({ taskId, participantId, held, muted, bridgeRole } = {}) {
+  async update({
+    taskId,
+    participantId,
+    held,
+    muted,
+    bridgeRole,
+    joinAudio,
+  } = {}) {
     this.sdk.validateParams(
-      { taskId, participantId, held, muted, bridgeRole },
+      { taskId, participantId, held, muted, bridgeRole, joinAudio },
       {
         taskId: { type: 'string', required: true },
         participantId: { type: 'string', required: true },
         held: { type: 'boolean', required: false },
         muted: { type: 'boolean', required: false },
         bridgeRole: { type: 'string', required: false },
+        joinAudio: { type: 'boolean', required: false },
       },
     );
 
@@ -186,6 +194,7 @@ export class ParticipantService {
     if (held !== undefined) params.body.held = held;
     if (muted !== undefined) params.body.muted = muted;
     if (bridgeRole !== undefined) params.body.bridgeRole = bridgeRole;
+    if (joinAudio !== undefined) params.body.joinAudio = joinAudio;
 
     return await internalRequest(
       this.sdk,

package/services/webchat/VisitorService.js

@@ -14,16 +14,6 @@ import { internalRequest } from '../../base.js';
 // method forces HTTP (esign.public precedent, base.js `forceFetch`) since
 // these are one-shot fetches from a customer page or a custom UI, never
 // NATS-transport traffic.
-//
-// Every call also passes `credentials: 'omit'` (base.js `_httpRequest`
-// opt-in), matching app1-webchat-embed's own webchatApi.js fetch wrapper
-// (which already sets `credentials:'omit'` for the same reason). This
-// surface is meant for a custom UI on a third-party origin calling the API
-// directly (see `grant()` below), not just the embed iframe -- and
-// app1-api's CORS only sends `access-control-allow-credentials` for
-// trusted app1 base domains, so a browser rejects the response for a
-// `credentials:'include'` request from any other origin even though auth
-// here is Authorization-header/body-token based, not cookie based.
 function authHeaders(token) {
   return token ? { headers: { Authorization: `Bearer ${token}` } } : {};
 }
@@ -74,7 +64,6 @@ class WebchatVisitorSessionService {
           trackingId,
           initialMessage,
         },
-        credentials: 'omit',
       },
       true,
     );
@@ -100,7 +89,7 @@ class WebchatVisitorSessionService {
       this.sdk,
       `/webchat/${widgetId}/visitor-profile`,
       'POST',
-      { body: { embedGrant, trackingId }, credentials: 'omit' },
+      { body: { embedGrant, trackingId } },
       true,
     );
   }
@@ -126,7 +115,7 @@ class WebchatVisitorSessionService {
       this.sdk,
       `/webchat/${widgetId}/session`,
       'POST',
-      { body: { resumeToken }, credentials: 'omit' },
+      { body: { resumeToken } },
       true,
     );
   }
@@ -151,7 +140,7 @@ class WebchatVisitorSessionService {
       this.sdk,
       `/webchat/${widgetId}/session/end`,
       'POST',
-      { ...authHeaders(token), credentials: 'omit' },
+      { ...authHeaders(token) },
       true,
     );
   }
@@ -190,7 +179,6 @@ class WebchatVisitorMessagesService {
           ...(limit !== undefined && limit !== null ? { limit } : {}),
         },
         ...authHeaders(token),
-        credentials: 'omit',
       },
       true,
     );
@@ -217,7 +205,7 @@ class WebchatVisitorMessagesService {
       this.sdk,
       `/webchat/${widgetId}/messages`,
       'POST',
-      { body: { message, media }, ...authHeaders(token), credentials: 'omit' },
+      { body: { message, media }, ...authHeaders(token) },
       true,
     );
   }
@@ -260,7 +248,7 @@ class WebchatVisitorFilesService {
       this.sdk,
       `/webchat/${widgetId}/files`,
       'POST',
-      { body, ...authHeaders(token), credentials: 'omit' },
+      { body, ...authHeaders(token) },
       true,
     );
   }
@@ -309,13 +297,7 @@ export class WebchatVisitorService {
       { widgetId },
       { widgetId: { type: 'string', required: true } },
     );
-    return internalRequest(
-      this.sdk,
-      `/webchat/${widgetId}/grant`,
-      'GET',
-      { credentials: 'omit' },
-      true,
-    );
+    return internalRequest(this.sdk, `/webchat/${widgetId}/grant`, 'GET', {}, true);
   }
 
   /**
@@ -328,13 +310,7 @@ export class WebchatVisitorService {
       { widgetId },
       { widgetId: { type: 'string', required: true } },
     );
-    return internalRequest(
-      this.sdk,
-      `/webchat/${widgetId}/status`,
-      'GET',
-      { credentials: 'omit' },
-      true,
-    );
+    return internalRequest(this.sdk, `/webchat/${widgetId}/status`, 'GET', {}, true);
   }
 
   /**
@@ -360,7 +336,7 @@ export class WebchatVisitorService {
       this.sdk,
       `/webchat/${widgetId}/transcript`,
       'POST',
-      { body: { optIn, email }, ...authHeaders(token), credentials: 'omit' },
+      { body: { optIn, email }, ...authHeaders(token) },
       true,
     );
   }
@@ -396,7 +372,7 @@ export class WebchatVisitorService {
       this.sdk,
       `/webchat/${widgetId}/identify`,
       'POST',
-      { body: { ...fields, hash }, ...authHeaders(token), credentials: 'omit' },
+      { body: { ...fields, hash }, ...authHeaders(token) },
       true,
     );
   }

package/services/forms/HealthService.js

@@ -1,35 +0,0 @@
-import { internalRequest } from '../../base.js';
-
-// Forms v2 P8 (plans/forms-v2-plan.md D13, forms-v2-precheck.md §9) --
-// agent-authenticated Health tab data (`sdk.forms.health`): submissions
-// tiles, a 30-day submissions-per-day sparkline, per-field fill rate, and
-// drift alerts (a field with 0 non-blank values in the last 7 days after
-// previously being filled >=50% of the time). Backed by the nightly
-// `formFieldStats` rollup -- server route:
-// `app1-api/src/services/forms/controllers/getFormHealth.js`.
-export class FormsHealthService {
-  constructor(sdk) {
-    this.sdk = sdk;
-  }
-
-  /**
-   * @param {string} formId
-   * @returns {Promise<{
-   *   tiles: {submissions:number, submissionsChangePct:number|null,
-   *     spamCount:number, spamRatePct:number, companyLinkedPct:number,
-   *     companyCreated:number, actionsFailed:number},
-   *   sparkline: {day:string, submitted:number}[],
-   *   fields: {fieldKey:string, label:string, fillRate:number|null,
-   *     priorFillRate:number|null, isDrifting:boolean}[],
-   *   driftAlerts: object[],
-   *   windowDays: number,
-   * }>}
-   */
-  async get(formId) {
-    return internalRequest(
-      this.sdk,
-      `/forms/${encodeURIComponent(formId)}/health`,
-      'GET',
-    );
-  }
-}

package/services/forms/PublicService.js

@@ -1,110 +0,0 @@
-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.
-//
-// Every call passes `credentials: 'omit'` (base.js `_httpRequest` opt-in) --
-// this surface is hit from third-party origins (a marketing site embedding
-// a form, not an app1 base domain), and app1-api's CORS
-// (`src/index.js` allowlist) only sends `access-control-allow-credentials`
-// for trusted app1 base domains. A browser rejects the whole response for
-// a `credentials:'include'` request when that header is missing, even
-// though these endpoints don't use cookies for auth -- so third-party
-// callers must opt out explicitly.
-//
-// 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, e.g. `_idempotencyKey`/`_captchaToken` below --
-// formSubmitPublicKey.js splits on that same convention. `context` is NOT a
-// control field: app1-api's captureContext.js builds the submission's
-// context column by scanning the body's TOP-LEVEL keys against an
-// allowlist (utm_*, gclid, fbclid, referrer, landingUrl, pageUrl,
-// userAgent) and explicitly skips any `_`-prefixed key as a control
-// field -- so `context` values are spread onto the top level alongside
-// `fields`, never nested, or the server drops them silently.
-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 -- publicKey + origin/
-   * domainAllowlist is the only auth for a public form submit).
-   * @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 -- spread onto the top-level body (never nested);
-   *   the server's captureContext.js allowlist only reads top-level keys.
-   *   A key here that collides with a `fields` key loses to `fields`.
-   * @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 = { ...(context || {}), ...(fields || {}) };
-    if (idempotencyKey) body._idempotencyKey = idempotencyKey;
-    if (captchaToken) body._captchaToken = captchaToken;
-
-    return internalRequest(
-      this.sdk,
-      `/f/${publicKey}`,
-      'POST',
-      { body, credentials: 'omit' },
-      true,
-    );
-  }
-
-  /**
-   * Upload a file for a `file` inputType field (D21), ahead of the real
-   * `submit()` call. Mirrors `webchat.visitor.files.upload()`'s shape:
-   * browser-only (needs `FormData`), no progress event. The returned
-   * `token` must be echoed back inside `submit()`'s `fields[fieldKey]` as
-   * `JSON.stringify({fileId, token})` -- the server (formFileAttach.js)
-   * verifies it names this exact (formId, fieldKey, fileId) triple before
-   * attaching the file to the submission.
-   * @param {string} publicKey
-   * @param {string} fieldKey - Must match a `file` inputType field on the form.
-   * @param {File|Blob} file
-   * @returns {Promise<{fileId:string, token:string, fileName:string, fileType:string, fileSize:number}>}
-   */
-  async upload(publicKey, fieldKey, file) {
-    this.sdk.validateParams(
-      { publicKey, fieldKey },
-      {
-        publicKey: { type: 'string', required: true },
-        fieldKey: { type: 'string', required: true },
-      },
-    );
-    if (typeof FormData === 'undefined' || !file) {
-      throw new Error(
-        'forms.public.upload :: a browser File/Blob and FormData support are required',
-      );
-    }
-    const body = new FormData();
-    body.append('fieldKey', fieldKey);
-    body.append('file', file);
-    return internalRequest(
-      this.sdk,
-      `/f/${publicKey}/upload`,
-      'POST',
-      { body, credentials: 'omit' },
-      true,
-    );
-  }
-}

package/services/forms/README.md

@@ -1,160 +0,0 @@
-# Forms v2 SDK module (`sdk.forms`)
-
-Internal reference for `services/forms.js` + `services/forms/*.js` as they exist in code
-today on branch `f-forms-v2` (sdk version `4.13.92`). Not the plan — every claim below is
-cited to a source line. See `/workspace/code/app1/plans/forms-v2-plan.md` /
-`forms-v2-progress.md` / `forms-v2-precheck.md` for design history; §"Deviations from
-plan" at the bottom lists where progress-doc claims and code disagree.
-
-## Files
-
-| File | Exports |
-|---|---|
-| `services/forms.js` | `FormsService` (registers as `sdk.forms`) |
-| `services/forms/PublicService.js` | `FormsPublicService` → `sdk.forms.public` |
-| `services/forms/SubmissionsService.js` | `FormsSubmissionsService` → `sdk.forms.submissions` |
-| `services/forms/SettingsService.js` | `FormsSettingsService` → `sdk.forms.settings` |
-| `services/forms/HealthService.js` | `FormsHealthService` → `sdk.forms.health` |
-
-Registered in `index.js:29` (import), `index.js:129` (`this.forms = new FormsService(this)`),
-exported at `index.js:331-333`.
-
-## Methods
-
-| Method | Signature | Returns | Purpose |
-|---|---|---|---|
-| `sdk.forms.public.submit` | `submit(publicKey: string, fields: Object, { context, captchaToken, idempotencyKey }: Object = {})` | `Promise<{ok: boolean, message?: string}>` | Submit a public form by `publicKey`; `POST /f/:publicKey` |
-| `sdk.forms.public.upload` | `upload(publicKey: string, fieldKey: string, file: File\|Blob)` | `Promise<{fileId, token, fileName, fileType, fileSize}>` | Browser-only file upload ahead of `submit()`, for a `file`-type field; `POST /f/:publicKey/upload` |
-| `sdk.forms.submissions.reprocess` | `reprocess(id: string)` | `Promise<Object>` | Re-run the pipeline for a stored submission; `POST /object/formSubmissions/:id/reprocess` |
-| `sdk.forms.submissions.markNotSpam` | `markNotSpam(id: string)` | `Promise<Object>` | Clear a submission's spam status; `POST /object/formSubmissions/:id/mark-not-spam` |
-| `sdk.forms.submissions.resolveReview` | `resolveReview(id: string, choice: string)` | `Promise<Object>` | Resolve an `identityConflict`/`review`-flagged submission; `POST /object/formSubmissions/:id/resolve-review`, body `{choice}` |
-| `sdk.forms.settings.get` | `get()` | `Promise<{defaultRegion?, turnstileSiteKey?, turnstileSecretRef?}>` | Read the account-level `formsAccountSettings` singleton; `GET /forms/settings` |
-| `sdk.forms.settings.set` | `set(patch: {defaultRegion?, turnstileSiteKey?, turnstileSecret?})` | `Promise<Object>` | Merge-patch the singleton; `turnstileSecret` is plaintext in, never echoed back; `PUT /forms/settings` |
-| `sdk.forms.settings.setForm` | `setForm(formId: string, patch: {captchaProvider?, turnstileSiteKey?, turnstileSecret?})` | `Promise<Object>` | Per-form Turnstile override; `PUT /forms/:formId/settings` |
-| `sdk.forms.health.get` | `get(formId: string)` | `Promise<{tiles, sparkline, fields, driftAlerts, windowDays}>` | Health tab data (tiles, 30-day sparkline, per-field fill rate, drift alerts); `GET /forms/:formId/health` |
-| `sdk.forms.regeneratePublicKey` | `regeneratePublicKey(formId: string)` | `Promise<{publicKey: string}>` | Mint a new `publicKey`, invalidating every embed using the old one (destructive); `POST /forms/:formId/regenerate-key` |
-| `sdk.forms.previewToken` | `previewToken(formId: string)` | `Promise<{token: string, expiresIn: number}>` | Mint a signed 15-min draft-preview token; `POST /forms/:formId/preview-token` |
-
-Sources: `PublicService.js:46-100`, `SubmissionsService.js:28-79`, `SettingsService.js:28-72`,
-`HealthService.js:28-34`, `forms.js:20-63`.
-
-## Auth model
-
-| Group | Methods | Session/JWT required? | Mechanism |
-|---|---|---|---|
-| Public | `public.submit`, `public.upload` | No | `internalRequest(..., forceFetch=true)` — `PublicService.js:46-62,77-100` explicitly pass `true` as the 5th arg. No `sdk.token` involved; auth is `publicKey` + server-side origin/domainAllowlist check, not a session (comment `PublicService.js:1-8`, mirrors `WebchatVisitorService`/`VisitorService` pattern). |
-| Agent-authenticated | `submissions.*`, `settings.*`, `health.get`, `regeneratePublicKey`, `previewToken` | Yes | `internalRequest(sdk, endpoint, method, {...})` with no `forceFetch`/`httpOnly` flag — routed through the SDK's normal transport (socket/HTTP) using `sdk.token`, same as any other authenticated service call (e.g. `WebchatWidgetsService.get()`). |
-
-`internalRequest`'s `forceFetch` param (`base.js:22-38`) skips optional transports and goes
-HTTP-only — used for the two public methods because they're one-shot calls from a visitor
-page with no socket session, same convention as file upload/download elsewhere in the SDK.
-
-Both `public.submit` and `public.upload` also pass `credentials: 'omit'` in the request
-params (`PublicService.js:46-62,77-100`; consumed by `base.js` `_httpRequest`, which
-otherwise defaults browser fetches to `credentials:'include'`). This surface is called
-from third-party origins (a marketing site, not an app1 base domain), and app1-api's CORS
-only sends `access-control-allow-credentials` for trusted app1 base domains — a browser
-rejects the entire response for a `credentials:'include'` fetch when that header is
-missing, even though these endpoints don't use cookies for auth. `sdk.webchat.visitor.*`
-(`services/webchat/VisitorService.js`) has the same third-party-origin exposure and sets
-the same option for the same reason.
-
-**Known SDK-surface gap (not a code bug, documented in-file):** `submissions.*` and
-`settings.get/set` call server routes that, per their own doc comments, were not yet built
-as of P2 (`SubmissionsService.js:7-16`, `SettingsService.js:7-17` — "GAP (forms-v2 P2) ...
-the server-side routes these call do NOT exist yet"). `forms-v2-progress.md` marks P5 done
-and lists "forms account settings API" and "reprocess/mark-not-spam/review actions" as
-shipped, so these comments are likely stale relative to the API side — the SDK client code
-itself was not re-verified against `app1-api` route files in this pass (out of scope: this
-README covers the SDK repo only). Flagged in Deviations below.
-
-## Example — browser handler mode (public form submission)
-
-Realistic embed-adjacent usage: a page with its own HTML/`<form>` calling the SDK directly
-(the `forms.public` surface backs both the generated embed script and any hand-rolled
-integration like this).
-
-```js
-import { BaseSDK, internalRequest } from '@unboundcx/sdk/base.js';
-import { FormsPublicService } from '@unboundcx/sdk/services/forms/PublicService.js';
-
-// Minimal public-only instance — namespace or a custom baseURL, NEVER sdk.token.
-// Importing only base.js + PublicService.js avoids pulling in the full SDK's
-// service tree (some of which have bundler-unfriendly static imports that broke
-// marketing_unbound_cx's browser build — see CHANGELOG 4.13.90).
-const sdk = new BaseSDK({ namespace: 'masterc' });
-const forms = new FormsPublicService(sdk);
-
-document.querySelector('#lead-form').addEventListener('submit', async (e) => {
-  e.preventDefault();
-  const data = new FormData(e.target);
-
-  await forms.submit(
-    'PUBLIC_KEY_HERE',
-    {
-      email: data.get('email'),
-      name: data.get('name'),
-      interests: data.getAll('interests'), // arrays kept as arrays
-    },
-    {
-      context: {
-        utm_source: new URLSearchParams(location.search).get('utm_source'),
-        referrer: document.referrer,
-        landingUrl: location.href,
-      },
-      idempotencyKey: crypto.randomUUID(),
-    },
-  );
-});
-```
-
-`context` is spread onto the top level of the request body alongside `fields` (not nested
-under a `_context` key — that was a bug fixed in 4.13.89, `PublicService.js:10-21` +
-CHANGELOG). Control fields (`_idempotencyKey`, `_captchaToken`) are sent with a leading
-underscore so the server can distinguish them from real form values (`PublicService.js:51-53`).
-
-## Example — server-side submit (Node)
-
-```js
-import UnboundSDK from '@unboundcx/sdk';
-
-// GOTCHA: in Node, UnboundSDK's constructor does NOT use a literal `baseURL` you pass
-// unless you pass it explicitly as `options.baseURL` — and even then only via the
-// object-form constructor. If you only pass `namespace` (the common case), Node builds
-// the URL as `https://<namespace||'login'>.${process.env.API_BASE_URL || 'api.unbound.cx'}`
-// (base.js:79-82). So:
-//   - No API_BASE_URL env var set  -> requests go to https://masterc.api.unbound.cx (WRONG
-//     for dev — hits the real production-shaped host, not dev-d01).
-//   - API_BASE_URL is treated as a DOMAIN SUFFIX appended after the namespace, not a full
-//     URL override — set it to e.g. `dev-d01.app1svc.com`, not `https://api.dev-d01...`.
-process.env.API_BASE_URL = 'dev-d01.app1svc.com';
-
-const sdk = new UnboundSDK({ namespace: 'masterc', token: process.env.AGENT_JWT });
-
-const health = await sdk.forms.health.get('formIdHere');
-console.log(health.tiles);
-
-// Public submit also works from Node (no browser needed) since forms.public.submit()
-// only requires FormData for upload(), not submit():
-await sdk.forms.public.submit('PUBLIC_KEY_HERE', { email: 'test@example.com' });
-```
-
-Verified against `base.js:56-82` (`_initializeEnvironment`, Node branch) and
-`base.js:107-134` (`setNamespace`, Node branch uses the same `!this._constructorBaseURL`
-guard) — this gotcha is still true for this SDK's client construction as of `4.13.92`.
-Matches the repo memory note "SDK Node baseURL gotcha."
-
-## Deviations from plan / progress docs
-
-1. **Health service exists but isn't in the precheck's SDK contract.** `forms-v2-precheck.md`
-   §5 only specifies `public`, `submissions`, `settings` on `FormsService`; `health` (P8,
-   `HealthService.js`) and the two gap-closure methods `regeneratePublicKey`/`previewToken`
-   (added directly on `FormsService`, not a sub-service) were added later and aren't in the
-   precheck's code sample — expected drift for a precheck doc frozen at P0, not a bug.
-2. **`submissions.*` / `settings.get`/`settings.set` carry "route may not exist yet" comments
-   still in the source** (`SubmissionsService.js:7-16`, `SettingsService.js:7-17`), even
-   though `forms-v2-progress.md` marks P5 ("Captcha gate ... forms account settings API,
-   submission reprocess/mark-not-spam/review actions") as done. This README does not resolve
-   the discrepancy — it was not in scope to audit `app1-api`'s route files — but flags it as
-   a live contradiction between the sdk source comments and the progress ledger. Reported
-   back to Cameron per task instructions.

package/services/forms/SettingsService.js

@@ -1,66 +0,0 @@
-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`).
-//
-// Methods call:
-// - get() → GET /forms/settings (services/forms/routes.js)
-// - set() → PUT /forms/settings (services/forms/routes.js)
-// - setForm() → PUT /forms/:id/settings (services/forms/routes.js)
-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 || {}) },
-    });
-  }
-
-  /**
-   * Review fix -- per-form Turnstile override (Settings tab's "Secret key
-   * (override)" field). Mirrors `set()`: the raw secret goes under
-   * `turnstileSecret`, never the stored `turnstileSecretRef` column name.
-   * Server route: `PUT /forms/:id/settings`
-   * (app1-api/src/services/forms/controllers/putFormSettings.js).
-   * @param {string} formId
-   * @param {Object} patch
-   * @param {string|null} [patch.captchaProvider]
-   * @param {string|null} [patch.turnstileSiteKey]
-   * @param {string} [patch.turnstileSecret] - Plaintext; omit (or send '')
-   *   to leave the currently stored secret untouched.
-   * @returns {Promise<Object>}
-   */
-  async setForm(formId, patch) {
-    this.sdk.validateParams(
-      { formId },
-      { formId: { type: "string", required: true } },
-    );
-    return internalRequest(
-      this.sdk,
-      `/forms/${encodeURIComponent(formId)}/settings`,
-      "PUT",
-      { body: { ...(patch || {}) } },
-    );
-  }
-}

package/services/forms/SubmissionsService.js

@@ -1,68 +0,0 @@
-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()).
-//
-// Methods call:
-// - reprocess() → POST /object/formSubmissions/:id/reprocess (api objects/routes.js)
-// - markNotSpam() → POST /object/formSubmissions/:id/mark-not-spam (api objects/routes.js)
-// - resolveReview() → POST /object/formSubmissions/:id/resolve-review (api objects/routes.js)
-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

@@ -1,64 +0,0 @@
-import { internalRequest } from '../base.js';
-import { FormsPublicService } from './forms/PublicService.js';
-import { FormsSubmissionsService } from './forms/SubmissionsService.js';
-import { FormsSettingsService } from './forms/SettingsService.js';
-import { FormsHealthService } from './forms/HealthService.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`/`health` 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);
-    this.health = new FormsHealthService(sdk);
-  }
-
-  /**
-   * Gap closure (task item 2, D1/D20). Mints a brand new `forms.publicKey`
-   * and overwrites the old one -- every embed snippet/HTML still carrying
-   * the old key stops resolving immediately (see the server route's doc
-   * comment). A destructive action; callers should confirm with the user
-   * before invoking (FormIdentitySettingsCard.svelte's "Regenerate" flow).
-   * Server route: `POST /forms/:id/regenerate-key`
-   * (app1-api/src/services/forms/controllers/regenerateFormPublicKey.js).
-   * @param {string} formId
-   * @returns {Promise<{publicKey:string}>}
-   */
-  async regeneratePublicKey(formId) {
-    this.sdk.validateParams(
-      { formId },
-      { formId: { type: 'string', required: true } },
-    );
-    return internalRequest(
-      this.sdk,
-      `/forms/${encodeURIComponent(formId)}/regenerate-key`,
-      'POST',
-    );
-  }
-
-  /**
-   * Gap closure (task item 3, D19). Mints a signed, 15-min-TTL token
-   * scoped to this exact formId so a `draft`/non-`active` form's real
-   * embed script can be requested via
-   * `GET /f/:publicKey.js?preview=<token>` without making the form
-   * publicly live. Server route: `POST /forms/:id/preview-token`
-   * (app1-api/src/services/forms/controllers/mintFormPreviewToken.js);
-   * verify side has been live since P2 (formEmbedPublicKey.js).
-   * @param {string} formId
-   * @returns {Promise<{token:string, expiresIn:number}>}
-   */
-  async previewToken(formId) {
-    this.sdk.validateParams(
-      { formId },
-      { formId: { type: 'string', required: true } },
-    );
-    return internalRequest(
-      this.sdk,
-      `/forms/${encodeURIComponent(formId)}/preview-token`,
-      'POST',
-    );
-  }
-}