@nopaque/sdk 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to this project will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.8.0] - 2026-09-30
+
+### Fixed
+
+- An error body carrying `message` instead of `error` now surfaces its text.
+  API Gateway's own 401, 403 and 429 responses, and a few older handlers, send
+  `message`; the SDK read only `error`, so those errors showed as just
+  `HTTP 403` with no reason.
+- `pnpm test:integration` allows 30 s per test. The live-API schedule
+  round-trip makes three calls and could pass Vitest's 5 s default on cold
+  Lambdas.
+
+### Added
+
+- `surveys` resource for survey tests, where your platform sends the survey and
+  nopaque answers as the respondent.
+  - `surveys.start()`, `stop()` and `list()` over `/testing/survey-runs`.
+    `start()` takes `sender` — the number your survey platform sends from — and
+    sends it as `endUserE164`. `list()` returns the runs plus the workspace's
+    `numbers: { total, busy, free }`.
+  - `surveys.results.list()` / `listPage()` / `get()` over
+    `/testing/survey-results`. A result carries the conversation as `turns`.
+  - `surveys.configs.create()` / `list()` / `get()` / `update()` / `delete()`
+    over `/testing/survey-test-configs`. `configs.list()` is not paginated and
+    returns a plain array.
+  - `surveys.waitForResult(runId)` polls until `capture.status` is `final` or
+    `failed` and returns the result either way. A 404 counts as "not written
+    yet" for `notFoundGrace` (default 60 s). Without a `timeout`, the deadline
+    is the test's `expiresAt` plus 10 minutes. Throws `NopaqueTimeoutError` on
+    the deadline without stopping the test.
+
+## [0.7.0] - 2026-08-19
+
+### Fixed
+
+- `waitForRun()` could return before the run's verdict was written, giving
+  `outcome: undefined` and no step results on a run that had actually passed.
+  A re-fetch of the same id moments later returned the real verdict. The
+  container emits `run_status_changed{status:'completed'}` and
+  `run_completed{outcome}` as separate SQS messages with no ordering
+  guarantee, and the API skips undefined fields on write, so a status-only
+  message marks the run terminal with no outcome. Polling keyed on `status`
+  alone, so it returned that intermediate row. `completed` now also requires a
+  decided verdict; `failed` and `cancelled` still settle immediately, since
+  neither carries one.
+
+### Added
+
+- `TestStepResult` and `TestRunDetails`. `testing.runs.get()` and
+  `waitForRun()` return `TestRunDetails` — the run row plus `stepResults`,
+  `fullTranscript` and an inline `config` snapshot, all of which the API has
+  always sent and neither SDK declared.
+  - Named `TestStepResult`, not `StepResult`: the latter is already exported
+    for mapping and is an unrelated shape.
+
 ## [0.6.0] - 2026-08-19
 
 ### Fixed
@@ -181,5 +238,6 @@ client.mapping.create({
 - Typed error class hierarchy.
 - Dual ESM + CJS output with TypeScript definitions.
 
-[Unreleased]: https://github.com/nopaque/node-sdk/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/nopaque/node-sdk/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/nopaque/node-sdk/releases/tag/v0.8.0
 [0.1.0]: https://github.com/nopaque/node-sdk/releases/tag/v0.1.0

package/README.md

@@ -55,6 +55,31 @@ const finished = await client.digitalTesting.waitForRun(run.id);
 console.log(finished.status, finished.outcome, finished.passRate);
 ```
 
+### Survey tests
+
+Survey testing reverses the direction: your platform sends the survey, and
+nopaque answers as the respondent. Start a test, point your survey at the
+number it returns, then wait for the conversation.
+
+```ts
+const test = await client.surveys.start({
+  configId: 'cfg_123',
+  sender: '+447700900123', // the number your survey platform sends FROM
+  windowSecs: 300,
+});
+
+// Trigger your survey from `sender` to this number before `expiresAt`.
+console.log('Send the survey to', test.agentE164);
+
+const result = await client.surveys.waitForResult(test.runId);
+// A failed capture is a RESULT, not an error: check `capture.error`.
+console.log(result.outcome, result.capture.status);
+for (const turn of result.turns) console.log(`${turn.from}: ${turn.text}`);
+```
+
+`start()` throws `ConflictError` when the workspace has no free survey number
+for that sender. `surveys.list()` shows how many are free.
+
 ## Features
 
 - Full coverage of the Nopaque REST API via API-key auth

package/dist/index.cjs

@@ -133,7 +133,7 @@ function resolveConfig(opts) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.6.0" : "0.0.0-dev";
+var VERSION = true ? "0.8.0" : "0.0.0-dev";
 
 // src/userAgent.ts
 function composeUserAgent() {
@@ -274,7 +274,7 @@ async function classifyResponse(response) {
     body = null;
   }
   const bodyObj = body && typeof body === "object" ? body : {};
-  const message = typeof bodyObj.error === "string" ? bodyObj.error : `HTTP ${response.status}`;
+  const message = typeof bodyObj.error === "string" ? bodyObj.error : typeof bodyObj.message === "string" ? bodyObj.message : `HTTP ${response.status}`;
   const code = typeof bodyObj.code === "string" ? bodyObj.code : null;
   const details = bodyObj.details ?? null;
   const requestId = response.headers.get("x-request-id");
@@ -1317,6 +1317,176 @@ var SchedulerResource = class extends Resource {
   }
 };
 
+// src/resources/surveys.ts
+var TERMINAL_CAPTURE = /* @__PURE__ */ new Set(["final", "failed"]);
+var DEFAULT_NOT_FOUND_GRACE = 6e4;
+var CAPTURE_GRACE = 6e5;
+var SurveyResultsResource = class extends Resource {
+  /** Paginated list of result summaries, newest first. Transcripts are omitted. */
+  list(params = {}, requestOptions) {
+    return new Paginator({
+      fetchPage: async (p) => {
+        const { nextToken, cursor, ...rest } = p;
+        const raw = await this.transport.request(
+          "GET",
+          "/testing/survey-results",
+          {
+            // `nextToken` first: the Paginator advances by writing it, and a
+            // caller-supplied `cursor` would otherwise pin every page to page one.
+            params: { ...rest, cursor: nextToken ?? cursor },
+            requestOptions
+          }
+        );
+        return {
+          items: raw.results ?? raw.items ?? [],
+          nextToken: raw.nextCursor ?? raw.nextToken ?? null
+        };
+      },
+      params: { ...params }
+    });
+  }
+  /** One page of result summaries. */
+  async listPage(params = {}, requestOptions) {
+    const { nextToken, cursor, ...rest } = params;
+    const raw = await this.transport.request("GET", "/testing/survey-results", {
+      params: { ...rest, cursor: nextToken ?? cursor },
+      requestOptions
+    });
+    return new Page(raw.results ?? raw.items ?? [], raw.nextCursor ?? raw.nextToken ?? null);
+  }
+  /**
+   * One result with its conversation. While the test is live the capture may be
+   * `provisional` and still grow.
+   */
+  async get(runId, requestOptions) {
+    return await this.transport.request("GET", `/testing/survey-results/${runId}`, {
+      requestOptions
+    });
+  }
+};
+var SurveyConfigsResource = class extends Resource {
+  async create(body, requestOptions) {
+    return await this.transport.request("POST", "/testing/survey-test-configs", {
+      body,
+      requestOptions
+    });
+  }
+  /** Every config in the workspace. Not paginated; `mission` and `acceptance` are omitted. */
+  async list(requestOptions) {
+    const raw = await this.transport.request(
+      "GET",
+      "/testing/survey-test-configs",
+      { requestOptions }
+    );
+    return raw.configs ?? [];
+  }
+  async get(configId, requestOptions) {
+    return await this.transport.request("GET", `/testing/survey-test-configs/${configId}`, {
+      requestOptions
+    });
+  }
+  /** PATCH - only the fields passed are sent. `null` clears `description`, `tags` or `voiceId`. */
+  async update(configId, body, requestOptions) {
+    return await this.transport.request("PATCH", `/testing/survey-test-configs/${configId}`, {
+      body,
+      requestOptions
+    });
+  }
+  /** Tests already started from the config are unaffected. */
+  async delete(configId, requestOptions) {
+    await this.transport.request("DELETE", `/testing/survey-test-configs/${configId}`, {
+      requestOptions
+    });
+  }
+};
+var SurveysResource = class extends Resource {
+  results;
+  configs;
+  constructor(transport) {
+    super(transport);
+    this.results = new SurveyResultsResource(transport);
+    this.configs = new SurveyConfigsResource(transport);
+  }
+  /**
+   * Start a survey test. Nothing runs yet: nopaque begins WAITING for a survey
+   * sent from `sender` to the returned `agentE164`, until `expiresAt`.
+   *
+   * Throws `ConflictError` (409) when the workspace has no live survey numbers,
+   * or when every one of them is already running a test against this sender -
+   * the message tells the two apart. `NotFoundError` (404) for an unknown
+   * config. A 503 means the number could not be put into service and nothing
+   * was reserved; it is safe to try again, but this method does not.
+   */
+  async start(params, requestOptions) {
+    const { configId, sender, windowSecs, expectedTurns, maxMessages } = params;
+    const body = {
+      configId,
+      endUserE164: sender,
+      ...windowSecs !== void 0 && { windowSecs },
+      ...expectedTurns !== void 0 && { expectedTurns },
+      ...maxMessages !== void 0 && { maxMessages }
+    };
+    return await this.transport.request("POST", "/testing/survey-runs", { body, requestOptions });
+  }
+  /** Stop a test before its window closes, freeing its number. */
+  async stop(runId, requestOptions) {
+    await this.transport.request("DELETE", `/testing/survey-runs/${runId}`, { requestOptions });
+  }
+  /** Every survey test holding a number, plus how many numbers are free. Not paginated. */
+  async list(requestOptions) {
+    return await this.transport.request("GET", "/testing/survey-runs", { requestOptions });
+  }
+  /**
+   * Poll `results.get(runId)` until the capture is `final` or `failed`, and
+   * return the result either way. A `failed` capture is a RESULT, not an error -
+   * inspect `capture.error`.
+   *
+   * The result row is written asynchronously after `start()`, so a 404 is
+   * treated as "not yet" for `notFoundGrace` and rethrown after that. Throws
+   * `NopaqueTimeoutError` on the deadline; the test itself is NOT stopped.
+   */
+  async waitForResult(runId, opts = {}) {
+    const notFoundGrace = opts.notFoundGrace ?? DEFAULT_NOT_FOUND_GRACE;
+    const started = Date.now();
+    let deadline = started + (opts.timeout ?? notFoundGrace);
+    let deadlineDerived = opts.timeout !== void 0;
+    let step = 0;
+    while (true) {
+      let result;
+      try {
+        result = await this.results.get(runId, opts.requestOptions);
+      } catch (err) {
+        if (!(err instanceof NotFoundError) || Date.now() - started >= notFoundGrace) throw err;
+      }
+      if (result) {
+        if (opts.onUpdate) {
+          try {
+            opts.onUpdate(result);
+          } catch {
+          }
+        }
+        if (TERMINAL_CAPTURE.has(result.capture?.status)) return result;
+        if (!deadlineDerived) {
+          deadline = result.expiresAt * 1e3 + CAPTURE_GRACE;
+          deadlineDerived = true;
+        }
+      }
+      const now = Date.now();
+      if (now >= deadline) {
+        throw new NopaqueTimeoutError(
+          `waitForResult timed out after ${now - started}ms waiting for survey result ${runId}`
+        );
+      }
+      const interval = Math.min(
+        pollIntervalCurve(step, { base: opts.pollInterval, cap: opts.intervalCap }),
+        Math.max(0, deadline - now)
+      );
+      await new Promise((r) => setTimeout(r, interval));
+      step++;
+    }
+  }
+};
+
 // src/resources/sweeps.ts
 var RUN_TERMINAL_STATUSES2 = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var SweepsResource = class extends Resource {
@@ -1388,6 +1558,11 @@ var SweepsResource = class extends Resource {
 
 // src/resources/testing.ts
 var RUN_TERMINAL_STATUSES3 = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+function isRunSettled(run) {
+  if (run.status === void 0 || !RUN_TERMINAL_STATUSES3.has(run.status)) return false;
+  if (run.status !== "completed") return true;
+  return run.outcome != null && run.outcome !== "pending";
+}
 var TestingConfigsResource = class extends Resource {
   async create(body, requestOptions) {
     return await this.transport.request("POST", "/testing/configs", { body, requestOptions });
@@ -1488,7 +1663,7 @@ var TestingRunsResource = class extends Resource {
   async waitForRun(runId, opts = {}) {
     return await waitFor({
       fetch: () => this.get(runId, opts.requestOptions),
-      isTerminal: (run) => run.status !== void 0 && RUN_TERMINAL_STATUSES3.has(run.status),
+      isTerminal: isRunSettled,
       timeout: opts.timeout,
       initialInterval: opts.pollInterval,
       intervalCap: opts.intervalCap,
@@ -1544,6 +1719,7 @@ var Nopaque = class {
   digitalTesting;
   digitalTestConfigs;
   digitalCompliance;
+  surveys;
   transport;
   constructor(options = {}) {
     const config = resolveConfig(options);
@@ -1564,6 +1740,7 @@ var Nopaque = class {
     this.digitalTesting = new DigitalTestingResource(this.transport);
     this.digitalTestConfigs = new DigitalTestConfigsResource(this.transport);
     this.digitalCompliance = new DigitalComplianceResource(this.transport);
+    this.surveys = new SurveysResource(this.transport);
   }
   close() {
   }