@tellescope/sdk 1.256.7 → 1.256.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.7",
+  "version": "1.256.9",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -32,14 +32,14 @@
   },
   "homepage": "https://github.com/tellescope-os/tellescope#readme",
   "dependencies": {
-    "@tellescope/constants": "1.256.7",
-    "@tellescope/schema": "1.256.7",
-    "@tellescope/testing": "1.256.7",
-    "@tellescope/types-client": "1.256.7",
-    "@tellescope/types-models": "1.256.7",
-    "@tellescope/types-utilities": "1.256.7",
-    "@tellescope/utilities": "1.256.7",
-    "@tellescope/validation": "1.256.7",
+    "@tellescope/constants": "1.256.9",
+    "@tellescope/schema": "1.256.9",
+    "@tellescope/testing": "1.256.9",
+    "@tellescope/types-client": "1.256.9",
+    "@tellescope/types-models": "1.256.9",
+    "@tellescope/types-utilities": "1.256.9",
+    "@tellescope/utilities": "1.256.9",
+    "@tellescope/validation": "1.256.9",
     "axios": "0.30.3",
     "dotenv": "14.3.2",
     "form-data": "4.0.4",
@@ -55,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "65726a9aff1e45ffbdd4a16d8b0fc3a21204fc6f"
+  "gitHead": "8952d9b32afa842c1488e4eab27fe1dadc859cdb"
 }

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

@@ -24,12 +24,17 @@ const decode_jwt_payload = (token: string) => {
 // The API returns a /r/<token> shortlink, not the destination — follow one hop and pull the
 // `token` query param out of the URL the patient actually lands on.
 const resolve_redirect_token = async (link: string) => {
-  const { status, headers } = await axios.get(link, {
+  // The server stamps the shortlink's host from its own config (organization.customPortalURL || API_URL),
+  // which is independent of the API port under test. Follow the /r/<token> path on our test `host` so this
+  // stays port-flexible like the rest of the suite (the redirect route is served by the same API server).
+  const { pathname, search } = new URL(link)
+  const followURL = `${host}${pathname}${search}`
+  const { status, headers } = await axios.get(followURL, {
     maxRedirects: 0,
     validateStatus: () => true,
   })
   const location = headers['location']
-  if (!location) throw new Error(`Expected a redirect from ${link}, got status ${status}`)
+  if (!location) throw new Error(`Expected a redirect from ${followURL}, got status ${status}`)
 
   const token = new URL(location).searchParams.get('token')
   if (!token) throw new Error(`No token query param in redirect destination: ${location}`)

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

@@ -0,0 +1,168 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import { CreateNoteAutomationAction } from "@tellescope/types-models"
+import { log_header, async_test, assert } from "@tellescope/testing"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || "http://localhost:8080"
+
+// createNote journey action: creates a note on the enduser timeline with deterministic
+// (merge-field) text, or AI-generated text when aiSummaryConfiguration.enabled is set.
+// The deterministic path is fully covered here; the AI path asserts config round-trip and,
+// when the org lacks Bedrock enablement/credits (typical dev org), the error path instead.
+export const create_note_action_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Create Note Action Tests")
+
+  const journey = await sdk.api.journeys.createOne({ title: 'Create Note Test Journey' })
+  const createdEnduserIds: string[] = []
+
+  try {
+    /*************** Config validation round-trip ***************/
+    const validInfo = {
+      title: 'Note for {{enduser.fname}}',
+      text: 'Hi {{enduser.fname}}, this is a journey note.',
+      tags: ['auto-note'],
+    }
+
+    const step = await sdk.api.automation_steps.createOne({
+      journeyId: journey.id,
+      events: [{ type: 'onJourneyStart', info: {} }],
+      action: { type: 'createNote', info: validInfo },
+    })
+    assert(
+      step.action.type === 'createNote' && step.action.info.title === validInfo.title && step.action.info.text === validInfo.text,
+      'createNote step round-trip failed',
+      'createNote step round-trips',
+    )
+
+    await async_test('createNote without title is rejected',
+      () => sdk.api.automation_steps.createOne({
+        journeyId: journey.id,
+        events: [{ type: 'onJourneyStart', info: {} }],
+        action: { type: 'createNote', info: { ...validInfo, title: undefined } as any },
+      }),
+      { shouldError: true, onError: () => true },
+    )
+    await async_test('createNote with over-length title is rejected',
+      () => sdk.api.automation_steps.createOne({
+        journeyId: journey.id,
+        events: [{ type: 'onJourneyStart', info: {} }],
+        action: { type: 'createNote', info: { ...validInfo, title: 'x'.repeat(251) } },
+      }),
+      { shouldError: true, onError: () => true },
+    )
+
+    /*************** Runtime: the process endpoint ***************/
+    const processFor = async (enduserId: string, info: CreateNoteAutomationAction['info']) => {
+      const automatedAction = await sdk.api.automated_actions.createOne({
+        enduserId,
+        journeyId: journey.id,
+        automationStepId: step.id,
+        event: { type: 'onJourneyStart', info: {} },
+        action: { type: 'createNote', info },
+        status: 'active',
+        processAfter: Date.now(),
+      })
+      return sdk.api.automated_actions.process({ automatedActionId: automatedAction.id })
+    }
+
+    // deterministic path: merge fields resolve, tags + source set
+    const enduser = await sdk.api.endusers.createOne({ fname: 'NoteTest' })
+    createdEnduserIds.push(enduser.id)
+
+    const result = await processFor(enduser.id, validInfo)
+    assert(result.success === true, `deterministic createNote failed: ${result.error}`, 'deterministic createNote succeeds')
+
+    const notes = await sdk.api.notes.getSome({ filter: { enduserId: enduser.id } })
+    assert(notes.length === 1, `expected 1 note, got ${notes.length}`, 'exactly one note created')
+    assert(notes[0].title === 'Note for NoteTest', `title not templated: ${notes[0].title}`, 'title merge fields resolve')
+    assert(notes[0].text === 'Hi NoteTest, this is a journey note.', `text not templated: ${notes[0].text}`, 'text merge fields resolve')
+    assert(!!notes[0].tags?.includes('auto-note'), 'tags missing on note', 'tags set on note')
+    assert(notes[0].source === 'Journey', `wrong source: ${notes[0].source}`, 'note source is Journey')
+    assert(!notes[0].hiddenFromTimeline, 'note unexpectedly hidden', 'note visible on timeline by default')
+    assert(!notes[0].aiGenerated, 'deterministic note incorrectly flagged aiGenerated', 'deterministic note not flagged as AI-generated')
+
+    // hiddenFromTimeline + no text variant
+    const hiddenResult = await processFor(enduser.id, { title: 'Hidden note', hiddenFromTimeline: true })
+    assert(hiddenResult.success === true, `hidden createNote failed: ${hiddenResult.error}`, 'hidden createNote succeeds')
+    const allNotes = await sdk.api.notes.getSome({ filter: { enduserId: enduser.id } })
+    const hiddenNote = allNotes.find(n => n.title === 'Hidden note')
+    assert(
+      !!hiddenNote && hiddenNote.hiddenFromTimeline === true && !hiddenNote.text,
+      'hidden/textless note not created correctly',
+      'hiddenFromTimeline note created without text',
+    )
+
+    /*************** AI path ***************/
+    const aiInfo = {
+      title: 'AI note for {{enduser.fname}}',
+      aiSummaryConfiguration: {
+        enabled: true,
+        prompt: 'Write a one-sentence note stating this is a test patient.',
+      },
+    }
+    const aiStep = await sdk.api.automation_steps.createOne({
+      journeyId: journey.id,
+      events: [{ type: 'onJourneyStart', info: {} }],
+      action: { type: 'createNote', info: aiInfo },
+    })
+    assert(
+      aiStep.action.type === 'createNote' && aiStep.action.info.aiSummaryConfiguration?.enabled === true,
+      'AI createNote config round-trip failed',
+      'AI createNote config round-trips',
+    )
+
+    const aiEnduser = await sdk.api.endusers.createOne({ fname: 'AINoteTest' })
+    createdEnduserIds.push(aiEnduser.id)
+    const aiResult = await processFor(aiEnduser.id, aiInfo)
+    if (!aiResult.success) {
+      // bedrockAIAllowed/credits are org-level and unreadable here — accept the configuration error path
+      assert(
+        /bedrock|credit|enabled|ai/i.test(aiResult.error || ''),
+        `unexpected AI createNote error: ${aiResult.error}`,
+        'AI createNote reports a configuration error (Bedrock unavailable — runtime generation skipped)',
+      )
+    } else {
+      const aiNotes = await sdk.api.notes.getSome({ filter: { enduserId: aiEnduser.id } })
+      assert(
+        aiNotes.length === 1 && !!aiNotes[0].text && aiNotes[0].title === 'AI note for AINoteTest',
+        'AI-generated note missing or malformed',
+        'AI-generated note created with non-empty text',
+      )
+      assert(aiNotes[0].aiGenerated === true, 'AI note missing aiGenerated flag', 'AI note flagged as AI-generated')
+      const conversations = await sdk.api.ai_conversations.getSome({ filter: { enduserId: aiEnduser.id } })
+      assert(
+        conversations.some(c => c.type === 'AI Note'),
+        'no AI Note ai_conversations record',
+        'AI generation logged to ai_conversations with type AI Note',
+      )
+    }
+  } 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 create_note_action_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Create Note Action test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Create Note Action test suite failed:", error)
+      process.exit(1)
+    })
+}

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

@@ -0,0 +1,161 @@
+require('source-map-support').install();
+
+import { Session, EnduserSession } from "../../sdk"
+import { async_test, handleAnyError, passOnAnyResult, log_header } from "@tellescope/testing"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+// An enduser attendee can PATCH a calendar_event (needed to self-cancel out of a group event), and
+// attendeeStatuses / cancelledGroupAttendees are attendee-keyed arrays that drive per-attendee
+// automation triggers (handle_attendee_status_change_triggers + event-wide completion). The
+// calendar_events relationship constraint must let an enduser touch ONLY their own id's entry, so a
+// patient cannot fire or suppress a co-attendee's Appointment triggers by patching the shared event.
+export const group_event_attendee_self_update_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Group Event Attendee Self-Update Constraint")
+
+  const createdEnduserIds: string[] = []
+  const createdEventIds: string[] = []
+
+  const createEnduser = async (label: string) => {
+    const e = await sdk.api.endusers.createOne({ email: `attendee_self_update_${label}_${Date.now()}@test.tellescope.com` })
+    createdEnduserIds.push(e.id)
+    return e
+  }
+  const enduserSession = async (id: string) => {
+    const { authToken, enduser } = await sdk.api.endusers.generate_auth_token({ id })
+    return new EnduserSession({ host, authToken, enduser, businessId: sdk.userInfo.businessId })
+  }
+  const createGroupEvent = async (attendeeIds: string[]) => {
+    const event = await sdk.api.calendar_events.createOne({
+      title: 'Attendee Self-Update Test',
+      durationInMinutes: 30,
+      startTimeInMS: Date.now() + Math.floor(Math.random() * 100000),
+      attendees: attendeeIds.map(id => ({ type: 'enduser' as const, id })),
+    })
+    createdEventIds.push(event.id)
+    return event
+  }
+
+  try {
+    const attacker = await createEnduser('self')
+    const victim = await createEnduser('other')
+    const attackerSDK = await enduserSession(attacker.id)
+
+    // ---- ALLOWED: self-cancel out of a fresh group event (the portal self-cancel path) ----
+    const e1 = await createGroupEvent([attacker.id, victim.id])
+    await async_test(
+      "enduser may add their OWN cancelledGroupAttendees entry (self-cancel)",
+      () => attackerSDK.api.calendar_events.updateOne(e1.id, {
+        cancelledGroupAttendees: [{ id: attacker.id, at: new Date() }],
+      }, { replaceObjectFields: true }),
+      passOnAnyResult,
+    )
+
+    // ---- ALLOWED: set own attendeeStatuses entry ----
+    const e2 = await createGroupEvent([attacker.id, victim.id])
+    await async_test(
+      "enduser may set their OWN attendeeStatuses entry",
+      () => attackerSDK.api.calendar_events.updateOne(e2.id, {
+        attendeeStatuses: [{ id: attacker.id, at: new Date(), status: 'Cancelled' }],
+      }, { replaceObjectFields: true }),
+      passOnAnyResult,
+    )
+
+    // ---- REJECTED: set a co-attendee's attendeeStatuses (would fire that patient's triggers) ----
+    const e3 = await createGroupEvent([attacker.id, victim.id])
+    await async_test(
+      "enduser may NOT set a co-attendee's attendeeStatuses entry",
+      () => attackerSDK.api.calendar_events.updateOne(e3.id, {
+        attendeeStatuses: [{ id: victim.id, at: new Date(), status: 'No-showed' }],
+      }, { replaceObjectFields: true }),
+      handleAnyError,
+    )
+
+    // ---- REJECTED: set a co-attendee's cancelledGroupAttendees entry ----
+    const e4 = await createGroupEvent([attacker.id, victim.id])
+    await async_test(
+      "enduser may NOT set a co-attendee's cancelledGroupAttendees entry",
+      () => attackerSDK.api.calendar_events.updateOne(e4.id, {
+        cancelledGroupAttendees: [{ id: victim.id, at: new Date() }],
+      }, { replaceObjectFields: true }),
+      handleAnyError,
+    )
+
+    // ---- REJECTED: drop a co-attendee's existing entry (would suppress their completion trigger) ----
+    const e5 = await createGroupEvent([attacker.id, victim.id])
+    await sdk.api.calendar_events.updateOne(e5.id, {
+      attendeeStatuses: [{ id: victim.id, at: new Date(), status: 'Completed' }],
+    }, { replaceObjectFields: true })
+    await async_test(
+      "enduser may NOT remove a co-attendee's existing attendeeStatuses entry",
+      () => attackerSDK.api.calendar_events.updateOne(e5.id, {
+        attendeeStatuses: [{ id: attacker.id, at: new Date(), status: 'Cancelled' }], // silently drops victim's entry
+      }, { replaceObjectFields: true }),
+      handleAnyError,
+    )
+
+    // ---- REJECTED: modify a co-attendee's existing entry ----
+    const e6 = await createGroupEvent([attacker.id, victim.id])
+    await sdk.api.calendar_events.updateOne(e6.id, {
+      attendeeStatuses: [{ id: victim.id, at: new Date(), status: 'Completed' }],
+    }, { replaceObjectFields: true })
+    await async_test(
+      "enduser may NOT modify a co-attendee's existing attendeeStatuses entry",
+      () => attackerSDK.api.calendar_events.updateOne(e6.id, {
+        attendeeStatuses: [{ id: victim.id, at: new Date(), status: 'No-showed' }],
+      }, { replaceObjectFields: true }),
+      handleAnyError,
+    )
+
+    // ---- ALLOWED: self-cancel while PRESERVING a co-attendee's existing entry (realistic group self-cancel) ----
+    const e7 = await createGroupEvent([attacker.id, victim.id])
+    await sdk.api.calendar_events.updateOne(e7.id, {
+      cancelledGroupAttendees: [{ id: victim.id, at: new Date() }],
+    }, { replaceObjectFields: true })
+    const e7ForAttacker = await attackerSDK.api.calendar_events.getOne(e7.id)
+    await async_test(
+      "enduser may self-cancel while preserving a co-attendee's existing entry",
+      () => attackerSDK.api.calendar_events.updateOne(e7.id, {
+        cancelledGroupAttendees: [...(e7ForAttacker.cancelledGroupAttendees || []), { id: attacker.id, at: new Date() }],
+      }, { replaceObjectFields: true }),
+      passOnAnyResult,
+    )
+
+    // ---- ALLOWED (baseline): staff may set any attendee's status (constraint is enduser-only) ----
+    const e8 = await createGroupEvent([attacker.id, victim.id])
+    await async_test(
+      "staff may set any attendee's status",
+      () => sdk.api.calendar_events.updateOne(e8.id, {
+        attendeeStatuses: [{ id: victim.id, at: new Date(), status: 'No-showed' }],
+      }, { replaceObjectFields: true }),
+      passOnAnyResult,
+    )
+
+  } finally {
+    for (const id of createdEventIds) { try { await sdk.api.calendar_events.deleteOne(id) } catch (_) {} }
+    for (const id of createdEnduserIds) { try { await sdk.api.endusers.deleteOne(id) } catch (_) {} }
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await group_event_attendee_self_update_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Group event attendee self-update constraint tests completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Group event attendee self-update constraint tests failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0006-develop-health-benefit-verification-rbac.test.ts

@@ -88,20 +88,80 @@ export const develop_health_benefit_verification_rbac_tests = async ({ sdk, sdkN
       {
         shouldError: true,
         onError: (e: any) => {
-          // Accept any 4xx access-denial response — handler uses 403 (recommended).
-          // Explicitly reject the pre-fix "Integration not found" / "Enduser is required" /
-          // similar validation messages, which would indicate the access check never fired.
+          // Match the gate's exact message. The SDK error surfaces { message, info } (no top-level
+          // status/code), so we key on the message rather than the HTTP status. This is deliberately
+          // specific: a lapsed subscription ("Your subscription has expired") or an expired token
+          // ("Unauthenticated") also errors BEFORE the handler runs, but neither contains this string,
+          // so the test can't false-pass without the gate executing. Also reject the pre-fix
+          // downstream messages, which would indicate the access check never fired.
           const msg = (e?.message ?? '').toLowerCase()
-          const status = e?.status ?? e?.code
           if (msg.includes('integration not found') || msg.includes('enduser is required')
             || msg.includes('organization') || msg.includes('provider')) {
             return false // reached past the access gate — regression
           }
-          return status === 403 || status === 401
-            || msg.includes('access') || msg.includes('permission') || msg.includes('forbidden')
+          return msg.includes('access to this resource')
         },
       },
     )
+
+    // 4. POSITIVE case: a provider role WITH enduser access must PASS the gate and reach the
+    //    integration stage (this test org has no Develop Health integration, so it 400s with
+    //    "Integration not found"). This guards against the gate over-blocking legitimate users —
+    //    the failure mode a future tightening (e.g. gating on 'All') would introduce.
+    const providerRoleName = `f0006-develop-health-provider-${Date.now()}`
+    let providerRbapId: string | undefined
+    try {
+      const providerRbap = await sdk.api.role_based_access_permissions.createOne({
+        role: providerRoleName,
+        permissions: { ...PROVIDER_PERMISSIONS }, // endusers read/create non-null, eligibility create non-null
+      })
+      providerRbapId = providerRbap.id
+
+      await sdk.api.users.updateOne(sdkNonAdmin.userInfo.id, { roles: [providerRoleName] }, { replaceObjectFields: true })
+      await wait(undefined, 1500)
+      await sdkNonAdmin.authenticate(nonAdminEmail!, nonAdminPassword!)
+
+      await async_test(
+        "F-0006: a provider role with enduser access passes the gate (reaches 'Integration not found', not 403)",
+        () => sdkNonAdmin.api.enduser_eligibility_results.develop_health_run_benefit_verification({
+          enduserId: new ObjectId().toHexString(),
+          providerUserId: new ObjectId().toHexString(),
+          insuranceType: 'primary',
+          diagnoses: [],
+          drugs: [{ name: 'Test Drug', dosage: '10mg', quantity: 1 }],
+          drug_history: { currently_taking_drugs: [], previously_taken_drugs: [] },
+        } as any),
+        {
+          shouldError: true,
+          onError: (e: any) => {
+            const msg = (e?.message ?? '').toLowerCase()
+            // Must NOT be the access-denial message (that would mean the gate wrongly blocked a
+            // provider). Reaching "Integration not found" (or org/provider validation) proves the
+            // gate passed and the read-scoped enduser load did not over-restrict a legitimate role.
+            if (msg.includes('access to this resource')) return false
+            return msg.includes('integration not found') || msg.includes('organization') || msg.includes('provider')
+          },
+        },
+      )
+    } finally {
+      if (providerRbapId) {
+        try {
+          await sdk.api.users.updateOne(sdkNonAdmin.userInfo.id, { roles: originalRoles ?? [] }, { replaceObjectFields: true })
+        } catch {}
+        try { await sdk.api.role_based_access_permissions.deleteOne(providerRbapId) } catch {}
+        await wait(undefined, 1500)
+        try { await sdkNonAdmin.authenticate(nonAdminEmail!, nonAdminPassword!) } catch {}
+      }
+    }
+
+    // NOTE — the create>read bypass (endusers.create broader than endusers.read) that the 2026-08-19
+    // read-scoping closes is NOT live-testable here: this org has no Develop Health integration, so
+    // the handler throws "Integration not found" BEFORE reaching the (now read-scoped) enduser load,
+    // and the enduser load is what the create>read fix governs. Exercising it would need either a real
+    // Develop Health integration or reordering the handler purely for the test. It is covered by code
+    // review + F-0166 (systemic follow-up). If a Develop Health sandbox integration is ever available
+    // in the test org, add: role { endusers: create 'All', read 'Assigned' } → call with a real
+    // enduser NOT assigned to the caller → expect the enduser-not-found path, not a successful forward.
   } finally {
     // Cleanup: restore original roles, delete the test role.
     try {

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

@@ -0,0 +1,152 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import {
+  async_test,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+// Unreachable webhook target — the request will fail quickly but the API still writes
+// the resolved payload to webhook_logs, which is what we're verifying.
+const WEBHOOK_TARGET_URL = 'http://127.0.0.1:9'
+
+const find_log_for_url = async (sdk: Session, url: string) => {
+  const start = Date.now()
+  while (Date.now() - start < 10_000) {
+    const logs = await sdk.api.webhook_logs.getSome({ limit: 50, sort: 'newFirst' as any }) as Array<any>
+    const match = logs.find(l => l.url === url)
+    if (match) return match
+    await wait(undefined, 500)
+  }
+  return null
+}
+
+// Main test function that can be called independently
+export const webhook_raw_json_number_tests = async (
+  { sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }
+) => {
+  log_header("Webhook Raw JSON Body Numeric Placeholder Tests")
+
+  const enduser = await sdk.api.endusers.createOne({ fname: 'RawJSON', lname: 'Number' })
+  const purchase = await sdk.api.purchases.createOne({
+    enduserId: enduser.id,
+    title: 'Raw JSON Number Test Purchase',
+    cost: { amount: 129.99, currency: 'USD' },
+    processor: 'Stripe',
+  })
+
+  // create an automation step to satisfy schema validation (automationStepId is required)
+  const journey = await sdk.api.journeys.createOne({
+    title: 'Webhook Raw JSON Number Tests',
+    defaultState: 'State 1',
+  })
+  const step = await sdk.api.automation_steps.createOne({
+    journeyId: journey.id,
+    events: [{ type: 'onJourneyStart', info: {} }],
+    action: {
+      type: 'sendWebhook',
+      info: {
+        message: 'placeholder',
+        url: WEBHOOK_TARGET_URL,
+      },
+    },
+  })
+
+  try {
+    await async_test(
+      'Send Webhook rawJSONBody sends unquoted {{purchase.cost.amount}} as a number and quoted as a string',
+      async () => {
+        const url = `${WEBHOOK_TARGET_URL}/raw-json-number/${purchase.id}`
+        await sdk.api.webhooks.send_automation_webhook({
+          message: 'placeholder',
+          enduserId: enduser.id,
+          automationStepId: step.id,
+          action: {
+            type: 'sendWebhook',
+            info: {
+              message: 'placeholder',
+              url,
+              rawJSONBody: '{"amount": {{purchase.cost.amount}}, "asString": "{{purchase.cost.amount}}"}',
+            },
+          },
+          context: { purchaseId: purchase.id },
+        }).catch(() => {}) // the unreachable URL is expected to error after logging
+
+        const log = await find_log_for_url(sdk, url)
+        if (!log) return false
+        const payload = log.payload as any
+        return (
+          typeof payload?.amount === 'number' && payload.amount === 129.99
+          && typeof payload?.asString === 'string' && payload.asString === '129.99'
+        )
+      },
+      { onResult: r => r === true }
+    )
+
+    await async_test(
+      'Send Webhook rawJSONBody with a MISSING unquoted placeholder degrades to null instead of dropping the whole body',
+      async () => {
+        const url = `${WEBHOOK_TARGET_URL}/raw-json-missing/${purchase.id}`
+        await sdk.api.webhooks.send_automation_webhook({
+          message: 'placeholder',
+          enduserId: enduser.id,
+          automationStepId: step.id,
+          action: {
+            type: 'sendWebhook',
+            info: {
+              message: 'placeholder',
+              url,
+              // enduser has no 'NoSuchNumber' field: the unquoted placeholder would otherwise leave a
+              // literal {{...}} in a value slot, invalidating the JSON and dropping the entire payload.
+              rawJSONBody: '{"missing": {{enduser.NoSuchNumber}}, "patient": "{{enduser.fname}}"}',
+            },
+          },
+          context: { purchaseId: purchase.id },
+        }).catch(() => {})
+
+        const log = await find_log_for_url(sdk, url)
+        if (!log) return false
+        const payload = log.payload as any
+        // body must still be sent (not null/empty), the missing value coerced to JSON null,
+        // and the resolvable placeholder still substituted
+        return (
+          payload && typeof payload === 'object'
+          && payload.missing === null
+          && payload.patient === 'RawJSON'
+        )
+      },
+      { onResult: r => r === true }
+    )
+  } finally {
+    try { await sdk.api.purchases.deleteOne(purchase.id) } catch {}
+    try { await sdk.api.automation_steps.deleteOne(step.id) } catch {}
+    try { await sdk.api.journeys.deleteOne(journey.id) } catch {}
+    try { await sdk.api.endusers.deleteOne(enduser.id) } catch {}
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await webhook_raw_json_number_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Webhook raw JSON number test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Webhook raw JSON number test suite failed:", error)
+      process.exit(1)
+    })
+}