@tellescope/sdk 1.256.0 → 1.256.2

package/src/tests/api_tests/start_ai_conversation.test.ts

@@ -0,0 +1,256 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import { log_header, wait, async_test, assert } from "@tellescope/testing"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || "http://localhost:8080"
+
+const TEST_MARKER = '__TELLESCOPE_TEST_INCOMING_SMS_AUTOMATION__'
+const TEST_PHONE = '+15555555555' // send_sms short-circuits real sends for this number
+
+// SMS AI conversations (startAIConversation journey action).
+// Runtime flows (start/supersede/takeover/inbound absorption) require the organization to have an
+// SMS number configured — when it doesn't (typical dev org), those sections assert the
+// configuration error path and are otherwise skipped; config validation runs everywhere.
+export const start_ai_conversation_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Start AI Conversation (SMS Agent) Tests")
+
+  const users = await sdk.api.users.getSome({})
+  const senderId = users[0].id
+
+  const journey = await sdk.api.journeys.createOne({ title: 'SMS Agent Test Journey' })
+  const createdEnduserIds: string[] = []
+
+  try {
+    /*************** Config validation round-trip ***************/
+    const validInfo = {
+      channel: 'SMS' as const,
+      senderId,
+      initialMessage: 'Hello {{enduser.fname}}! Quick question for you.',
+      prompt: 'You are texting on behalf of Test Clinic. Answer briefly.',
+      outcomes: [{ value: 'resolved', description: 'The question was answered' }],
+    }
+
+    const step = await sdk.api.automation_steps.createOne({
+      journeyId: journey.id,
+      events: [{ type: 'onJourneyStart', info: {} }],
+      action: { type: 'startAIConversation', info: validInfo },
+    })
+    assert(
+      step.action.type === 'startAIConversation' && step.action.info.initialMessage === validInfo.initialMessage,
+      'startAIConversation step round-trip failed',
+      'startAIConversation step round-trips',
+    )
+
+    const outcomeChild = await sdk.api.automation_steps.createOne({
+      journeyId: journey.id,
+      events: [{ type: 'onAIConversationOutcome', info: { automationStepId: step.id, outcome: 'resolved' } }],
+      action: { type: 'addEnduserTags', info: { tags: ['sms-agent-resolved'] } },
+    })
+    assert(
+      outcomeChild.events[0].type === 'onAIConversationOutcome',
+      'onAIConversationOutcome event round-trip failed',
+      'onAIConversationOutcome event round-trips',
+    )
+
+    await async_test('startAIConversation without prompt is rejected',
+      () => sdk.api.automation_steps.createOne({
+        journeyId: journey.id,
+        events: [{ type: 'onJourneyStart', info: {} }],
+        action: { type: 'startAIConversation', info: { ...validInfo, prompt: undefined } as any },
+      }),
+      { shouldError: true, onError: () => true },
+    )
+    await async_test('startAIConversation without senderId is rejected',
+      () => sdk.api.automation_steps.createOne({
+        journeyId: journey.id,
+        events: [{ type: 'onJourneyStart', info: {} }],
+        action: { type: 'startAIConversation', info: { ...validInfo, senderId: undefined } as any },
+      }),
+      { shouldError: true, onError: () => true },
+    )
+    await async_test('startAIConversation without initialMessage is rejected',
+      () => sdk.api.automation_steps.createOne({
+        journeyId: journey.id,
+        events: [{ type: 'onJourneyStart', info: {} }],
+        action: { type: 'startAIConversation', info: { ...validInfo, initialMessage: undefined } as any },
+      }),
+      { shouldError: true, onError: () => true },
+    )
+    await async_test('startAIConversation with invalid tool is rejected',
+      () => sdk.api.automation_steps.createOne({
+        journeyId: journey.id,
+        events: [{ type: 'onJourneyStart', info: {} }],
+        action: { type: 'startAIConversation', info: { ...validInfo, tools: [{ type: 'Submit Form', info: { formId: 'not-an-id' } }] } as any },
+      }),
+      { shouldError: true, onError: () => true },
+    )
+
+    /*************** Runtime: the process endpoint ***************/
+    const processFor = async (enduserId: string) => {
+      const automatedAction = await sdk.api.automated_actions.createOne({
+        enduserId,
+        journeyId: journey.id,
+        automationStepId: step.id,
+        event: { type: 'onJourneyStart', info: {} },
+        action: { type: 'startAIConversation', info: validInfo },
+        status: 'active',
+        processAfter: Date.now(),
+      })
+      return sdk.api.automated_actions.process({ automatedActionId: automatedAction.id })
+    }
+
+    // no-phone error path works regardless of org SMS configuration
+    const phonelessEnduser = await sdk.api.endusers.createOne({ fname: 'sms-agent-nophone' })
+    createdEnduserIds.push(phonelessEnduser.id)
+    const noPhoneResult = await processFor(phonelessEnduser.id)
+    assert(
+      !noPhoneResult.success && !!noPhoneResult.error,
+      'phoneless start should fail with an error',
+      'start action errors for a contact without a phone',
+    )
+
+    // resolve the same organization the action does (last organizationId, else businessId) —
+    // getSome({})[0] is an arbitrary sub-organization and can be a different record entirely
+    const session = sdk.userInfo as { businessId?: string, organizationIds?: string[] }
+    const resolvedOrgId = [...(session.organizationIds ?? [])].pop() || session.businessId
+    const organization = (await sdk.api.organizations.getSome({})).find(o => o.id === resolvedOrgId)
+    const orgHasNumber = !!(organization as any)?.twilioNumber || !!((organization as any)?.twilioNumbers?.length)
+
+    if (!orgHasNumber) {
+      // still assert the wiring: the action processes and reports a configuration error rather than
+      // crashing. AI enablement is checked before the SMS number and short-circuits first, and
+      // bedrockAIAllowed/creditCount are super-admin-only (unreadable here), so accept either.
+      const enduser = await sdk.api.endusers.createOne({ fname: 'sms-agent-nonumber', phone: TEST_PHONE })
+      createdEnduserIds.push(enduser.id)
+      const result = await processFor(enduser.id)
+      assert(
+        !result.success && /no sms number configured|ai is not enabled/i.test(result.error || ''),
+        `expected a configuration error, got: ${result.error}`,
+        'start action reports a configuration error (org has no SMS number — runtime flows skipped)',
+      )
+      return
+    }
+
+    /*************** Runtime flows (org has an SMS number) ***************/
+    const enduser = await sdk.api.endusers.createOne({ fname: 'sms-agent-runtime', phone: TEST_PHONE })
+    createdEnduserIds.push(enduser.id)
+
+    const startResult = await processFor(enduser.id)
+    assert(startResult.success === true, `start failed: ${startResult.error}`, 'start action succeeds')
+    await wait(undefined, 1000)
+
+    let refreshed = await sdk.api.endusers.getOne(enduser.id)
+    const entry = (refreshed.aiConversations ?? []).find(c => c.active)
+    assert(!!entry, 'no active aiConversations entry on enduser', 'enduser has an active conversation entry')
+    assert(entry?.destination === TEST_PHONE, 'wrong destination on entry', 'conversation entry pairs the contact number')
+
+    const conversation = await sdk.api.ai_conversations.getOne(entry!.aiConversationId)
+    assert(conversation.type === 'sms_agent', 'wrong ai_conversations type', 'ai_conversations doc has type sms_agent')
+
+    const initialMessages = await sdk.api.sms_messages.getSome({ filter: { enduserId: enduser.id } })
+    const outbound = initialMessages.find(m => !m.inbound && m.automationStepId === step.id)
+    // exact equality on a merge-field-containing opener guards two regressions: templating must
+    // happen in send_sms (raw text on the record), and the agent-reply {{ escaping must NOT be
+    // applied to the org-authored initial message (preserveMergeFields)
+    assert(
+      !!outbound && outbound.message === validInfo.initialMessage,
+      'initial SMS record missing or not raw text',
+      'initial SMS logged with raw (untemplated) text + automationStepId',
+    )
+
+    // supersede: second start on the same pairing replaces the first
+    const secondStart = await processFor(enduser.id)
+    assert(secondStart.success === true, `second start failed: ${secondStart.error}`, 'duplicate start succeeds (replace)')
+    await wait(undefined, 1000)
+    refreshed = await sdk.api.endusers.getOne(enduser.id)
+    const activeEntries = (refreshed.aiConversations ?? []).filter(c => c.active)
+    assert(activeEntries.length === 1, 'expected exactly one active conversation', 'supersede leaves exactly one active conversation')
+    assert(
+      activeEntries[0].aiConversationId !== entry!.aiConversationId,
+      'active conversation was not replaced',
+      'supersede started a fresh conversation',
+    )
+
+    // inbound absorption via the testing hook: STOP ends the conversation
+    await sdk.api.sms_messages.createOne({
+      enduserId: enduser.id,
+      message: `stop${TEST_MARKER}`, // marker is stripped before the AI branch sees the text
+      inbound: true,
+      logOnly: true,
+      phoneNumber: activeEntries[0].source,
+      enduserPhoneNumber: TEST_PHONE,
+    } as any)
+    await wait(undefined, 2000)
+    refreshed = await sdk.api.endusers.getOne(enduser.id)
+    const stopped = (refreshed.aiConversations ?? []).find(c => c.aiConversationId === activeEntries[0].aiConversationId)
+    assert(
+      stopped?.active === false && stopped?.endedReason === 'unsubscribed',
+      `STOP did not end the conversation (${JSON.stringify(stopped)})`,
+      'STOP reply ends the conversation',
+    )
+
+    // staff takeover: start again, then a manual (user-session) SMS on the thread ends it
+    const takeoverStart = await processFor(enduser.id)
+    assert(takeoverStart.success === true, `takeover-start failed: ${takeoverStart.error}`, 'start (for takeover test) succeeds')
+    await wait(undefined, 1000)
+    await sdk.api.sms_messages.createOne({
+      enduserId: enduser.id,
+      message: 'Hi, this is a real person taking over.',
+      inbound: false,
+      phoneNumber: (await sdk.api.endusers.getOne(enduser.id)).aiConversations?.find(c => c.active)?.source,
+      enduserPhoneNumber: TEST_PHONE,
+    } as any)
+    await wait(undefined, 2000)
+    refreshed = await sdk.api.endusers.getOne(enduser.id)
+    const takenOver = (refreshed.aiConversations ?? []).find(c => c.endedReason === 'staff-takeover')
+    assert(!!takenOver, 'no staff-takeover ended entry found', 'manual staff SMS ends the conversation (takeover)')
+
+    // no-conversation baseline: marker inbound for a fresh enduser produces zero AI artifacts
+    const baselineEnduser = await sdk.api.endusers.createOne({ fname: 'sms-agent-baseline', phone: '+15555555554' })
+    createdEnduserIds.push(baselineEnduser.id)
+    await sdk.api.sms_messages.createOne({
+      enduserId: baselineEnduser.id,
+      message: `hello there${TEST_MARKER}`,
+      inbound: true,
+      logOnly: true,
+      phoneNumber: activeEntries[0].source,
+      enduserPhoneNumber: '+15555555554',
+    } as any)
+    await wait(undefined, 2000)
+    const baselineRefreshed = await sdk.api.endusers.getOne(baselineEnduser.id)
+    const baselineMessages = await sdk.api.sms_messages.getSome({ filter: { enduserId: baselineEnduser.id } })
+    assert(
+      !(baselineRefreshed.aiConversations ?? []).length && !baselineMessages.find(m => !m.inbound),
+      'AI artifacts appeared for an enduser with no conversation',
+      'no-conversation inbound produces zero AI artifacts (regression baseline)',
+    )
+  } finally {
+    await sdk.api.journeys.deleteOne(journey.id).catch(() => {})
+    for (const id of createdEnduserIds) {
+      await sdk.api.endusers.deleteOne(id).catch(() => {})
+    }
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await start_ai_conversation_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Start AI Conversation test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Start AI Conversation test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/tests.ts

@@ -38,6 +38,7 @@ import {
 import { Session, APIQuery, EnduserSession } from "../sdk"
 import { enduser_observations_acknowledge_tests } from "./api_tests/enduser_observations_acknowledge.test"
 import { translations_tests } from "./api_tests/translations.test"
+import { embeddables_auth_token_tests } from "./api_tests/embeddables_auth_token.test"
 import { user_portal_settings_tests } from "./api_tests/user_portal_settings.test"
 import { integrations_redacted_tests } from "./api_tests/integrations_redacted.test"
 import { healthie_multi_integration_tests } from "./api_tests/healthie_multi_integration.test"
@@ -97,6 +98,7 @@ import { outbound_chat_sent_trigger_tests } from "./api_tests/outbound_chat_sent
 import { time_tracks_tests, time_tracks_historical_tests, time_tracks_correction_tests, time_tracks_review_tests, time_tracks_lock_tests, time_tracks_edge_case_tests, time_tracks_resubmit_tests, time_tracks_appointment_duration_tests } from "./api_tests/time_tracks.test";
 import { monthly_availability_restrictions_tests } from "./api_tests/monthly_availability_restrictions.test";
 import { calendar_event_limits_tests } from "./api_tests/calendar_event_limits.test";
+import { appointment_link_expiration_tests } from "./api_tests/appointment_link_expiration.test";
 import { custom_aggregation_tests } from "./api_tests/custom_aggregation.test";
 import { chats_analytics_tests } from "./api_tests/chats_analytics.test";
 import { nutrition_tracking_tests } from "./api_tests/nutrition_tracking.test";
@@ -120,6 +122,8 @@ import { load_inbox_redaction_tests } from "./api_tests/security/F-0151-load-inb
 import { webhook_timeout_tests } from "./api_tests/security/F-0155-webhook-timeout.test";
 import { enduser_ai_summary_trust_gate_tests } from "./api_tests/security/enduser-ai-summary-trust-gate.test";
 import { allowed_paths_confinement_tests } from "./api_tests/security/F-0166-allowed-paths-wildcard-bypass.test";
+import { proxy_image_ssrf_tests } from "./api_tests/security/F-0025-proxy-image-unauth-ssrf.test";
+import { webhook_outbound_ssrf_tests } from "./api_tests/security/F-0015-webhook-outbound-ssrf.test";
 import { public_endpoint_auth_field_lock_tests } from "./api_tests/security/public_endpoint_auth_field_lock.test";
 import { formsort_webhook_auth_field_lock_tests } from "./api_tests/security/formsort_webhook_auth_field_lock.test";
 import { bulk_assignment_tests } from "./api_tests/bulk_assignment.test";
@@ -133,9 +137,11 @@ import { load_team_chat_tests } from "./api_tests/load_team_chat.test";
 import { form_started_trigger_tests } from "./api_tests/form_started_trigger.test";
 import { formsort_header_auth_tests } from "./api_tests/formsort_header_auth.test";
 import { form_submitted_trigger_tests } from "./api_tests/form_submitted_trigger.test";
+import { start_ai_conversation_tests } from "./api_tests/start_ai_conversation.test";
 import { dont_sync_to_elation_form_submission_tests } from "./api_tests/dont_sync_to_elation_form_submission.test";
 import { medication_added_trigger_tests } from "./api_tests/medication_added_trigger.test";
 import { conditional_logic_medication_unit_tests } from "./unit_tests/conditional_logic_medication.test";
+import { phone_validation_unit_tests } from "./unit_tests/phone_validation.test";
 import { elation_user_id_tests } from "./api_tests/elation_user_id.test";
 import { organization_settings_duplicates_tests } from "./api_tests/organization_settings_duplicates.test";
 import { calendar_events_bulk_update_tests } from "./api_tests/calendar_events_bulk_update.test";
@@ -144,6 +150,7 @@ import { openloop_webhooks_tests } from "./api_tests/openloop_webhooks.test";
 import { beluga_pharmacy_mappings_tests } from "./api_tests/beluga_pharmacy_mappings.test";
 import { mdi_case_offerings_tests } from "./api_tests/mdi_case_offerings.test";
 import { beluga_manual_sync_tests } from "./api_tests/beluga_manual_sync.test";
+import { beluga_trigger_refill_tests } from "./api_tests/beluga_trigger_refill.test";
 import { mdi_webhooks_tests } from "./api_tests/mdi_webhooks.test";
 import { account_switcher_tests } from "./api_tests/account_switcher.test";
 import { totp_mfa_tests } from "./api_tests/totp_mfa.test";
@@ -15270,10 +15277,14 @@ const ip_address_form_tests = async () => {
 
     await enduser_conditional_logic_tests()
     await conditional_logic_medication_unit_tests()
+    await phone_validation_unit_tests()
     await replace_enduser_template_values_tests()
     await replace_form_field_template_values_tests()
     await mfa_tests()
     await setup_tests(sdk, sdkNonAdmin)
+    await embeddables_auth_token_tests({ sdk, sdkNonAdmin })
+    await proxy_image_ssrf_tests({ sdk, sdkNonAdmin })
+    await webhook_outbound_ssrf_tests({ sdk, sdkNonAdmin })
     await allowed_paths_confinement_tests({ sdk, sdkNonAdmin })
     await phone_calls_conference_hold_tests({ sdk, sdkNonAdmin })
     await tickets_bulk_assign_care_team_tests({ sdk, sdkNonAdmin })
@@ -15282,6 +15293,7 @@ const ip_address_form_tests = async () => {
     await automation_trigger_tests()
     await resource_access_tags_tests({ sdk, sdkNonAdmin })
     await beluga_manual_sync_tests({ sdk, sdkNonAdmin })
+    await beluga_trigger_refill_tests({ sdk, sdkNonAdmin })
     await beluga_pharmacy_mappings_tests({ sdk, sdkNonAdmin })
     await mdi_case_offerings_tests({ sdk, sdkNonAdmin })
     await enduser_write_restrictions_tests({ sdk, sdkNonAdmin })
@@ -15320,6 +15332,7 @@ const ip_address_form_tests = async () => {
     await chats_analytics_tests({ sdk, sdkNonAdmin })
     await field_redaction_tests({ sdk, sdkNonAdmin })
     await form_submitted_trigger_tests({ sdk, sdkNonAdmin })
+    await start_ai_conversation_tests({ sdk, sdkNonAdmin })
     await dont_sync_to_elation_form_submission_tests({ sdk, sdkNonAdmin })
     await date_string_validation_tests({ sdk, sdkNonAdmin })
     await phone_tree_enduser_condition_tests({ sdk, sdkNonAdmin })
@@ -15338,6 +15351,7 @@ const ip_address_form_tests = async () => {
     await time_tracks_resubmit_tests({ sdk, sdkNonAdmin })
     await time_tracks_appointment_duration_tests({ sdk, sdkNonAdmin })
     await calendar_event_limits_tests({ sdk, sdkNonAdmin })
+    await appointment_link_expiration_tests({ sdk, sdkNonAdmin })
     await get_some_projection_tests({ sdk, sdkNonAdmin })
     await file_download_unicode_names_tests({ sdk, sdkNonAdmin })
     await elation_user_id_tests({ sdk, sdkNonAdmin })

package/src/tests/unit_tests/phone_validation.test.ts

@@ -0,0 +1,108 @@
+import {
+  parse_phone_number,
+  phoneValidator,
+  phoneValidatorOptional,
+} from "@tellescope/validation"
+import { to_human_readable_phone_number } from "@tellescope/utilities"
+
+let failures = 0
+let passed = 0
+
+const assert = (name: string, actual: unknown, expected: unknown) => {
+  if (actual === expected) {
+    passed++
+    console.log(`  ✓ ${name}`)
+  } else {
+    failures++
+    console.error(`  ✗ ${name} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`)
+  }
+}
+
+// validators throw on invalid input; THREW lets us assert rejection without try/catch per case
+const THREW = 'THREW'
+const attempt = (validate: (v: any) => string, value: string) => {
+  try { return validate(value) } catch (err) { return THREW }
+}
+
+// phoneValidator and phoneValidatorOptional carry identical parsing logic and differ only in
+// their build_validator options, so every parsing case runs against both.
+const run_validator_tests = () => {
+  console.log("\n[phoneValidator / phoneValidatorOptional]")
+
+  const cases: [string, string, string][] = [
+    // [input, expected, description]
+    ['+14155551234', '+14155551234', 'normalized E.164 passes through'],
+    ['4155551234', '+14155551234', 'bare 10 digits gets a US country code'],
+    ['(415) 555-1234', '+14155551234', 'formatted number is normalized'],
+    [' 415-555-1234 ', '+14155551234', 'whitespace and dashes are stripped'],
+    ['311', '311', 'N11 service code passes through (pre-existing behavior)'],
+
+    // Short codes: valid SMS endpoints, but not E.164 — no country code, no '+'
+    ['894546', '894546', '6-digit short code passes through unchanged'],
+    ['89454', '89454', '5-digit short code passes through unchanged'],
+    ['00000', '00000', 'leading zeroes are preserved, not normalized away'],
+
+    // The short-code allowance must not widen past bare 5-6 digits
+    ['+1894546', THREW, 'a leading + forces the strict E.164 path'],
+    ['1234', THREW, '4 digits still rejects'],
+    ['1234567', THREW, '7 digits still rejects'],
+    ['123456789', THREW, '9 digits still rejects'],
+    ['12', THREW, 'too-few digits still rejects'],
+    ['not a phone', THREW, 'junk still rejects'],
+  ]
+
+  for (const [input, expected, description] of cases) {
+    assert(`${description} (required)`, attempt(phoneValidator.validate(), input), expected)
+    assert(`${description} (optional)`, attempt(phoneValidatorOptional.validate(), input), expected)
+  }
+
+  assert(
+    'optional variant accepts empty string',
+    attempt(phoneValidatorOptional.validate(), ''),
+    '',
+  )
+}
+
+// parse_phone_number is the non-throwing wrapper used on integration payloads, where a junk
+// number must not fail the whole request. It inherits the short-code rule from phoneValidator.
+const run_parse_tests = () => {
+  console.log("\n[parse_phone_number]")
+
+  assert('E.164 passes through', parse_phone_number('+14155551234'), '+14155551234')
+  assert('bare 10 digits normalizes', parse_phone_number('4155551234'), '+14155551234')
+  assert('short code passes through', parse_phone_number('894546'), '894546')
+  assert('7 digits returns undefined', parse_phone_number('1234567'), undefined)
+  assert('junk returns undefined', parse_phone_number('not a phone'), undefined)
+  assert('empty string returns undefined', parse_phone_number(''), undefined)
+  assert('undefined returns undefined', parse_phone_number(undefined), undefined)
+  assert('null returns undefined', parse_phone_number(null), undefined)
+}
+
+// Guards the display formatter against the negative-slice bug: before the length check,
+// a 6-digit short code rendered as '+ (894) 546-'
+const run_display_tests = () => {
+  console.log("\n[to_human_readable_phone_number]")
+
+  assert('E.164 formats with country code', to_human_readable_phone_number('+15555555555'), '+1 (555) 555-5555')
+  assert('bare 10 digits formats', to_human_readable_phone_number('5555555555'), '(555) 555-5555')
+  assert('6-digit short code is returned as-is', to_human_readable_phone_number('894546'), '894546')
+  assert('5-digit short code is returned as-is', to_human_readable_phone_number('89454'), '89454')
+  assert('311 is returned as-is', to_human_readable_phone_number('311'), '311')
+  assert('empty string returns empty string', to_human_readable_phone_number(''), '')
+  assert('undefined returns empty string', to_human_readable_phone_number(undefined), '')
+}
+
+const run_all = () => {
+  console.log("Running phone_validation unit tests")
+  run_validator_tests()
+  run_parse_tests()
+  run_display_tests()
+  console.log(`\nResults: ${passed} passed, ${failures} failed`)
+  if (failures > 0) process.exit(1)
+}
+
+if (require.main === module) {
+  run_all()
+}
+
+export { run_all as phone_validation_unit_tests }