@nopaque/sdk 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1702,6 +1702,275 @@ declare class SchedulerResource extends Resource {
     resume(scheduleId: string, requestOptions?: RequestOptions): Promise<Schedule>;
 }
 
+/**
+ * How the respondent behaves once the survey is under way. A closed set: each
+ * value maps to wording nopaque maintains, so an unknown one is a 400.
+ */
+type SurveyScenario = 'happy-path' | 'out-of-range' | 'changes-mind' | 'abandons' | 'asks-question-back';
+/** Observed when the survey arrives; absent until then. */
+type SurveyChannel = 'sms_chat' | 'phone_call';
+type SurveyRunState = 'waiting' | 'in_progress' | 'complete' | 'timed_out';
+/**
+ * What HAPPENED, not whether the survey passed. `completed` means every
+ * expected question was asked and answered, and nothing more.
+ */
+type SurveyOutcome = 'completed' | 'partial' | 'ended' | 'no_survey_arrived' | 'stopped' | 'start_failed';
+type SurveyEndReason = 'survey_over' | 'window_lapsed' | 'stopped' | 'start_failed';
+/**
+ * `provisional` may still grow; `final` will not change; `failed` means the
+ * conversation could not be retrieved, with `error` saying why.
+ */
+type SurveyCaptureStatus = 'pending' | 'provisional' | 'final' | 'failed';
+/**
+ * Arguments to `surveys.start()`. `sender` is the number your survey platform
+ * sends FROM; it goes on the wire as `endUserE164`.
+ */
+interface StartSurveyTestParams {
+    configId: string;
+    /** E.164. Must not be a number inside this nopaque account - that is a 400. */
+    sender: string;
+    /** 60-43200. Server default 300. The window holds one of your numbers, so keep it short. */
+    windowSecs?: number;
+    /**
+     * 1-50. Overrides the config's question count for this test. The only limit
+     * that is actually enforced.
+     */
+    expectedTurns?: number;
+    /** 1-200. Server default 40. A loop-safety cap in the respondent's instructions, not enforced. */
+    maxMessages?: number;
+}
+/** Body for `POST /testing/survey-runs`, as sent. */
+interface StartSurveyTestRequest {
+    configId: string;
+    endUserE164: string;
+    windowSecs?: number;
+    expectedTurns?: number;
+    maxMessages?: number;
+}
+interface StartSurveyTestResponse {
+    runId: string;
+    configId: string;
+    /** Point the survey at this number. Nothing can reach the test until it is aimed here. */
+    agentE164: string;
+    endUserE164: string;
+    state: 'waiting';
+    startedAt: string;
+    /** Epoch SECONDS. */
+    expiresAt: number;
+    maxMessages: number;
+}
+/** A survey test while it holds a number. */
+interface SurveyRun {
+    runId: string;
+    configId: string;
+    agentE164: string;
+    endUserE164: string;
+    state: SurveyRunState;
+    startedAt: string;
+    engagedAt?: string;
+    channel?: SurveyChannel;
+    /** Epoch SECONDS. Expiry sweeps are lazy - judge liveness by `live`. */
+    expiresAt: number;
+    live: boolean;
+    expectedTurns?: number;
+    answersGiven?: number;
+    /** `false` means no question count is set, so the respondent answers until stopped. */
+    enforcementActive?: boolean;
+}
+/** Concurrency, made visible. Check `free` before starting another test. */
+interface SurveyNumbers {
+    total: number;
+    busy: number;
+    free: number;
+}
+interface ListSurveyRunsResponse {
+    runs: SurveyRun[];
+    numbers: SurveyNumbers;
+}
+interface SurveyCapture {
+    status: SurveyCaptureStatus;
+    capturedAt?: string;
+    error?: string;
+}
+/** What happened in one survey test, kept after the test has ended however it ended. */
+interface SurveyResultSummary {
+    runId: string;
+    configId: string;
+    /** The respondent's name when the test started. */
+    configName?: string;
+    scenario?: SurveyScenario;
+    profileName?: string;
+    agentE164: string;
+    endUserE164: string;
+    channel?: SurveyChannel;
+    startedAt: string;
+    /** Epoch SECONDS - the close of the test window. */
+    expiresAt: number;
+    expectedTurns?: number;
+    answersGiven: number;
+    engagedAt?: string;
+    endedAt?: string;
+    state: 'live' | 'ended';
+    /** Set when the test ends. */
+    outcome?: SurveyOutcome;
+    endReason?: SurveyEndReason;
+    /** More than 500 messages were exchanged; only the first 500 are kept. */
+    turnsTruncated: boolean;
+    capture: SurveyCapture;
+}
+/** One message. `survey` is your platform; `respondent` is nopaque answering it. */
+interface SurveyTurn {
+    at: string;
+    from: 'survey' | 'respondent';
+    text: string;
+}
+interface SurveyResult extends SurveyResultSummary {
+    /**
+     * Oldest first. An empty list never means "could not be retrieved" - that is
+     * `capture.status === 'failed'`.
+     */
+    turns: SurveyTurn[];
+}
+interface SurveyResultListParams {
+    /** 1-100. Server default 50. */
+    limit?: number;
+    cursor?: string;
+    nextToken?: string | null;
+}
+/**
+ * One page of results, newest first. `nextCursor` is OMITTED (not null) on
+ * the last page.
+ */
+interface ListSurveyResultsResponse {
+    results: SurveyResultSummary[];
+    nextCursor?: string;
+}
+/** A saved survey respondent. Carries no phone number - the customer's platform originates. */
+interface SurveyTestConfig {
+    id: string;
+    workspaceId: string;
+    name: string;
+    description?: string;
+    sector: string;
+    mission: string;
+    acceptance: string;
+    profileId?: string;
+    expectedTurns?: number;
+    scenario: SurveyScenario;
+    tags?: string[];
+    /** Voice surveys only; ignored on an SMS conversation. */
+    voiceId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Slim list projection: `mission` and `acceptance` are omitted. */
+type SurveyTestConfigListItem = Omit<SurveyTestConfig, 'mission' | 'acceptance'>;
+interface ListSurveyTestConfigsResponse {
+    configs: SurveyTestConfigListItem[];
+}
+/** `required: [name, sector, mission, acceptance, scenario]`. Unknown properties are a 400. */
+interface CreateSurveyTestConfigRequest {
+    name: string;
+    description?: string;
+    sector: string;
+    mission: string;
+    acceptance: string;
+    profileId?: string;
+    /** 1-50. Without it nothing is enforced. */
+    expectedTurns?: number;
+    scenario: SurveyScenario;
+    tags?: string[];
+    voiceId?: string;
+}
+/**
+ * Partial update. At least one field is required - an empty body is a 400.
+ * `null` clears `description`, `tags` or `voiceId`.
+ */
+interface UpdateSurveyTestConfigRequest {
+    name?: string;
+    description?: string | null;
+    sector?: string;
+    mission?: string;
+    acceptance?: string;
+    profileId?: string;
+    expectedTurns?: number;
+    scenario?: SurveyScenario;
+    tags?: string[] | null;
+    voiceId?: string | null;
+}
+
+/** All durations in ms, like every other wait helper in this SDK. */
+interface SurveysWaitForResultOptions {
+    /**
+     * Overall deadline. Defaults to the test's `expiresAt` plus 10 minutes, read
+     * from the first successful fetch.
+     */
+    timeout?: number;
+    pollInterval?: number;
+    intervalCap?: number;
+    /** How long a 404 counts as "not written yet". Defaults to 60 s. */
+    notFoundGrace?: number;
+    onUpdate?: (result: SurveyResult) => void;
+    requestOptions?: RequestOptions;
+}
+/** Results of survey tests, kept after a test ends however it ended. */
+declare class SurveyResultsResource extends Resource {
+    /** Paginated list of result summaries, newest first. Transcripts are omitted. */
+    list(params?: SurveyResultListParams, requestOptions?: RequestOptions): Paginator<SurveyResultSummary>;
+    /** One page of result summaries. */
+    listPage(params?: SurveyResultListParams, requestOptions?: RequestOptions): Promise<Page<SurveyResultSummary>>;
+    /**
+     * One result with its conversation. While the test is live the capture may be
+     * `provisional` and still grow.
+     */
+    get(runId: string, requestOptions?: RequestOptions): Promise<SurveyResult>;
+}
+/** Saved survey respondents. */
+declare class SurveyConfigsResource extends Resource {
+    create(body: CreateSurveyTestConfigRequest, requestOptions?: RequestOptions): Promise<SurveyTestConfig>;
+    /** Every config in the workspace. Not paginated; `mission` and `acceptance` are omitted. */
+    list(requestOptions?: RequestOptions): Promise<SurveyTestConfigListItem[]>;
+    get(configId: string, requestOptions?: RequestOptions): Promise<SurveyTestConfig>;
+    /** PATCH - only the fields passed are sent. `null` clears `description`, `tags` or `voiceId`. */
+    update(configId: string, body: UpdateSurveyTestConfigRequest, requestOptions?: RequestOptions): Promise<SurveyTestConfig>;
+    /** Tests already started from the config are unaffected. */
+    delete(configId: string, requestOptions?: RequestOptions): Promise<void>;
+}
+/**
+ * Survey tests. The direction is REVERSED from every other test: your platform
+ * sends the survey and nopaque answers as the respondent.
+ */
+declare class SurveysResource extends Resource {
+    readonly results: SurveyResultsResource;
+    readonly configs: SurveyConfigsResource;
+    constructor(transport: 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.
+     */
+    start(params: StartSurveyTestParams, requestOptions?: RequestOptions): Promise<StartSurveyTestResponse>;
+    /** Stop a test before its window closes, freeing its number. */
+    stop(runId: string, requestOptions?: RequestOptions): Promise<void>;
+    /** Every survey test holding a number, plus how many numbers are free. Not paginated. */
+    list(requestOptions?: RequestOptions): Promise<ListSurveyRunsResponse>;
+    /**
+     * 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.
+     */
+    waitForResult(runId: string, opts?: SurveysWaitForResultOptions): Promise<SurveyResult>;
+}
+
 type SweepStatus = 'created' | 'running' | 'completed' | 'failed' | 'cancelled';
 interface Sweep {
     id: string;
@@ -1842,6 +2111,40 @@ interface TestRun {
     failedSteps?: number;
     [key: string]: unknown;
 }
+/**
+ * A single scripted step's result. Named `TestStepResult`, not `StepResult` —
+ * the latter is already exported for mapping and is an unrelated shape.
+ */
+interface TestStepResult {
+    id: string;
+    runId: string;
+    stepIndex: number;
+    stepId: string;
+    stepName: string;
+    outcome: 'PASS' | 'FAIL' | 'TIMEOUT' | 'ERROR';
+    expectedTranscript: string;
+    actualTranscript?: string;
+    similarity?: number;
+    threshold: number;
+    actionType?: string;
+    actionValue?: string;
+    duration?: number;
+    errorMessage?: string;
+    matcherScores?: Record<string, number>;
+    turnTelemetry?: Record<string, unknown>;
+    createdAt: string;
+}
+/**
+ * What `testing.runs.get()` returns: the run row enriched with its step
+ * results, the joined transcript, and a snapshot of the parent config.
+ * Mission and compliance runs have no scripted steps, so `stepResults` is
+ * empty and `config` is absent for those.
+ */
+interface TestRunDetails extends TestRun {
+    stepResults?: TestStepResult[];
+    fullTranscript?: string;
+    config?: TestConfig;
+}
 /**
  * Body for POST /testing/runs. Exactly one of jobId or testConfigId
  * must be provided:
@@ -2012,8 +2315,8 @@ declare class TestingRunsResource extends Resource {
     listPage(params?: TestRunListParams, requestOptions?: RequestOptions): Promise<Page<TestRunListItem>>;
     /** GET /testing/runs/aggregate — grouped counts over test runs. */
     aggregate(params: TestRunAggregateParams, requestOptions?: RequestOptions): Promise<TestRunAggregateResponse>;
-    get(runId: string, requestOptions?: RequestOptions): Promise<TestRun>;
-    waitForRun(runId: string, opts?: TestingWaitForOptions): Promise<TestRun>;
+    get(runId: string, requestOptions?: RequestOptions): Promise<TestRunDetails>;
+    waitForRun(runId: string, opts?: TestingWaitForOptions): Promise<TestRunDetails>;
 }
 declare class TestingResource extends Resource {
     readonly configs: TestingConfigsResource;
@@ -2047,6 +2350,7 @@ declare class Nopaque {
     readonly digitalTesting: DigitalTestingResource;
     readonly digitalTestConfigs: DigitalTestConfigsResource;
     readonly digitalCompliance: DigitalComplianceResource;
+    readonly surveys: SurveysResource;
     private readonly transport;
     constructor(options?: NopaqueOptions);
     close(): void;
@@ -2054,4 +2358,4 @@ declare class Nopaque {
 
 declare const VERSION: string;
 
-export { APIConnectionError, APITimeoutError, type AddProfileItemRequest, type AggregateGroup, type AggregateGroupBy, type AggregateTimeBucket, type AudioCategory, type AudioDownloadURL, type AudioFile, type AudioListParams, type AudioUploadURL, AuthenticationError, type Batch, type BatchRun, type BatchRunStatus, type BatchStatus, type BatchesListParams, type CallTelemetry, type ChatMatcher, type ChatStep, type ChatStepBase, type ComplianceCatalogue, type ComplianceCatalogueResponse, type ComplianceRegulation, type ComplianceRegulationSection, type ComplianceReport, type ComplianceReportListItem, type ComplianceReportListParams, type ComplianceReportSummary, type ComplianceTest, type ComplianceTestEvidence, type ComplianceTestVerdict, ConflictError, type ConnectChatTarget, type CreateBatchRequest, type CreateComplianceBatchRequest, type CreateComplianceBatchResponse, type CreateDatasetRequest, type CreateDigitalTestConfigRequest, type CreateDigitalTestRunRequest, type CreateDigitalTestRunResponse, type CreateLoadTestRequest, type CreateMappingJobRequest, type CreateMissionTestConfigRequest, type CreateMissionTestRequest, type CreateProfileRequest, type CreateScheduleRequest, type CreateSweepRequest, type CreateTestConfigRequest, type CreateTestJobRequest, type CreateTestRunRequest, type CreateUploadUrlRequest, type CurrentRun, type DTMFOption, type Dataset, type DatasetsListParams, type DigitalComplianceAuditSummary, type DigitalComplianceReportParams, type DigitalEvidence, type DigitalOutcome, type DigitalProfile, type DigitalProfileItem, type DigitalRunStatus, type DigitalSample, type DigitalStepResult, type DigitalTarget, type DigitalTestConfig, type DigitalTestConfigBase, type DigitalTestConfigListParams, type DigitalTestKind, type DigitalTestRun, type DigitalTestRunListParams, type DigitalTranscriptTurn, type DownloadOptions, type EndChatStep, type EnrichRequest, type EnrichResponse, type Enrichment, type EnrichmentConfig, type EnrichmentDimensions, type EnrichmentStatus, type ExpectChatStep, type FlatTreeNode, type GeneratePdfRequest, type GeneratePdfResponse, type HttpJsonTarget, type JobStatus, type LaunchDigitalTestConfigRequest, type ListDigitalComplianceAuditsResponse, type ListDigitalTestConfigsResponse, type ListDigitalTestRunsResponse, type ListVoicesResponse, type LoadTest, type LoadTestEstimate, type LoadTestEstimateRequest, type LoadTestProgress, type LoadTestRun, type LoadTestStatus, type LoadTestStatusResponse, type LoadTestingListParams, type MappingJob, type MappingJobConfig, type MappingJobListItem, type MappingJobStats, type MappingListParams, type MappingMode, type MappingPath, type MappingRun, type MappingRunStatus, type MappingStep, type MappingTree, type MappingTreeEmptyState, type MissionTestConfig, type MissionTestConfigListItem, type MissionTestConfigListParams, type MissionTestDefaults, type MissionTestKind, type MissionTestListParams, type MissionTestProfile, type MissionTestRun, type MissionTestRunResponse, type MissionTestStatus, Nopaque, NopaqueAPIError, NopaqueConfigError, NopaqueError, type NopaqueOptions, NopaqueTimeoutError, NotFoundError, Page, Paginator, PermissionError, type ProbeResult, type Profile, type ProfileDataItem, type ProfileItem, type ProfileParametersResponse, type ProfileVoiceItem, type ProfileVoiceItemBase, type ProfilesByParametersParams, type ProfilesByParametersResponse, type ProfilesListParams, type QualityScoringResults, RateLimitError, type RepeatBehavior, type RepeatConfig, type RequestOptions, type ResolvedDataset, type ResolvedDatasetEntry, type RetryConfig, type Schedule, type ScheduleListParams, type ScheduleTargetType, type ScheduleType, type SendChatStep, ServerError, type StepResult, type StepStatus, type Sweep, type SweepRun, type SweepRunStatus, type SweepStatus, type SweepVariationResult, type SweepsListParams, type TestConfig, type TestJob, type TestJobStatus, type TestRun, type TestRunAggregateParams, type TestRunAggregateResponse, type TestRunListItem, type TestRunListParams, type TestRunOutcome, type TestRunStatus, type TestRunType, type TestStep, type TestingListParams, type TokenUsageDetails, type TokenUsageResponse, type TreeFormat, type TreeInputRequired, type TreeNode, type TreeNodeEnrichment, type TurnTelemetry, type UpdateBatchRequest, type UpdateDatasetRequest, type UpdateDigitalTestConfigRequest, type UpdateLoadTestRequest, type UpdateMappingJobRequest, type UpdateMissionTestConfigRequest, type UpdateProfileItemRequest, type UpdateProfileRequest, type UpdateScheduleRequest, type UpdateSweepRequest, type UpdateTestConfigRequest, type UploadInput, VERSION, ValidationError, type Vertical, type Voice, type WaitChatStep, type WebWidgetTarget };
+export { APIConnectionError, APITimeoutError, type AddProfileItemRequest, type AggregateGroup, type AggregateGroupBy, type AggregateTimeBucket, type AudioCategory, type AudioDownloadURL, type AudioFile, type AudioListParams, type AudioUploadURL, AuthenticationError, type Batch, type BatchRun, type BatchRunStatus, type BatchStatus, type BatchesListParams, type CallTelemetry, type ChatMatcher, type ChatStep, type ChatStepBase, type ComplianceCatalogue, type ComplianceCatalogueResponse, type ComplianceRegulation, type ComplianceRegulationSection, type ComplianceReport, type ComplianceReportListItem, type ComplianceReportListParams, type ComplianceReportSummary, type ComplianceTest, type ComplianceTestEvidence, type ComplianceTestVerdict, ConflictError, type ConnectChatTarget, type CreateBatchRequest, type CreateComplianceBatchRequest, type CreateComplianceBatchResponse, type CreateDatasetRequest, type CreateDigitalTestConfigRequest, type CreateDigitalTestRunRequest, type CreateDigitalTestRunResponse, type CreateLoadTestRequest, type CreateMappingJobRequest, type CreateMissionTestConfigRequest, type CreateMissionTestRequest, type CreateProfileRequest, type CreateScheduleRequest, type CreateSurveyTestConfigRequest, type CreateSweepRequest, type CreateTestConfigRequest, type CreateTestJobRequest, type CreateTestRunRequest, type CreateUploadUrlRequest, type CurrentRun, type DTMFOption, type Dataset, type DatasetsListParams, type DigitalComplianceAuditSummary, type DigitalComplianceReportParams, type DigitalEvidence, type DigitalOutcome, type DigitalProfile, type DigitalProfileItem, type DigitalRunStatus, type DigitalSample, type DigitalStepResult, type DigitalTarget, type DigitalTestConfig, type DigitalTestConfigBase, type DigitalTestConfigListParams, type DigitalTestKind, type DigitalTestRun, type DigitalTestRunListParams, type DigitalTranscriptTurn, type DownloadOptions, type EndChatStep, type EnrichRequest, type EnrichResponse, type Enrichment, type EnrichmentConfig, type EnrichmentDimensions, type EnrichmentStatus, type ExpectChatStep, type FlatTreeNode, type GeneratePdfRequest, type GeneratePdfResponse, type HttpJsonTarget, type JobStatus, type LaunchDigitalTestConfigRequest, type ListDigitalComplianceAuditsResponse, type ListDigitalTestConfigsResponse, type ListDigitalTestRunsResponse, type ListSurveyResultsResponse, type ListSurveyRunsResponse, type ListSurveyTestConfigsResponse, type ListVoicesResponse, type LoadTest, type LoadTestEstimate, type LoadTestEstimateRequest, type LoadTestProgress, type LoadTestRun, type LoadTestStatus, type LoadTestStatusResponse, type LoadTestingListParams, type MappingJob, type MappingJobConfig, type MappingJobListItem, type MappingJobStats, type MappingListParams, type MappingMode, type MappingPath, type MappingRun, type MappingRunStatus, type MappingStep, type MappingTree, type MappingTreeEmptyState, type MissionTestConfig, type MissionTestConfigListItem, type MissionTestConfigListParams, type MissionTestDefaults, type MissionTestKind, type MissionTestListParams, type MissionTestProfile, type MissionTestRun, type MissionTestRunResponse, type MissionTestStatus, Nopaque, NopaqueAPIError, NopaqueConfigError, NopaqueError, type NopaqueOptions, NopaqueTimeoutError, NotFoundError, Page, Paginator, PermissionError, type ProbeResult, type Profile, type ProfileDataItem, type ProfileItem, type ProfileParametersResponse, type ProfileVoiceItem, type ProfileVoiceItemBase, type ProfilesByParametersParams, type ProfilesByParametersResponse, type ProfilesListParams, type QualityScoringResults, RateLimitError, type RepeatBehavior, type RepeatConfig, type RequestOptions, type ResolvedDataset, type ResolvedDatasetEntry, type RetryConfig, type Schedule, type ScheduleListParams, type ScheduleTargetType, type ScheduleType, type SendChatStep, ServerError, type StartSurveyTestParams, type StartSurveyTestRequest, type StartSurveyTestResponse, type StepResult, type StepStatus, type SurveyCapture, type SurveyCaptureStatus, type SurveyChannel, type SurveyEndReason, type SurveyNumbers, type SurveyOutcome, type SurveyResult, type SurveyResultListParams, type SurveyResultSummary, type SurveyRun, type SurveyRunState, type SurveyScenario, type SurveyTestConfig, type SurveyTestConfigListItem, type SurveyTurn, type SurveysWaitForResultOptions, type Sweep, type SweepRun, type SweepRunStatus, type SweepStatus, type SweepVariationResult, type SweepsListParams, type TestConfig, type TestJob, type TestJobStatus, type TestRun, type TestRunAggregateParams, type TestRunAggregateResponse, type TestRunDetails, type TestRunListItem, type TestRunListParams, type TestRunOutcome, type TestRunStatus, type TestRunType, type TestStep, type TestStepResult, type TestingListParams, type TokenUsageDetails, type TokenUsageResponse, type TreeFormat, type TreeInputRequired, type TreeNode, type TreeNodeEnrichment, type TurnTelemetry, type UpdateBatchRequest, type UpdateDatasetRequest, type UpdateDigitalTestConfigRequest, type UpdateLoadTestRequest, type UpdateMappingJobRequest, type UpdateMissionTestConfigRequest, type UpdateProfileItemRequest, type UpdateProfileRequest, type UpdateScheduleRequest, type UpdateSurveyTestConfigRequest, type UpdateSweepRequest, type UpdateTestConfigRequest, type UploadInput, VERSION, ValidationError, type Vertical, type Voice, type WaitChatStep, type WebWidgetTarget };