@tellescope/sdk 2.0.0-beta.1 → 2.0.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.3",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -35,17 +35,18 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@tellescope/constants": "2.0.0-beta.1",
-    "@tellescope/schema": "2.0.0-beta.1",
-    "@tellescope/testing": "2.0.0-beta.1",
-    "@tellescope/types-client": "2.0.0-beta.1",
-    "@tellescope/types-models": "2.0.0-beta.1",
-    "@tellescope/types-utilities": "2.0.0-beta.1",
-    "@tellescope/utilities": "2.0.0-beta.1",
-    "@tellescope/validation": "2.0.0-beta.1",
-    "axios": "0.33.0",
+    "@tellescope/constants": "2.0.0-beta.3",
+    "@tellescope/schema": "2.0.0-beta.3",
+    "@tellescope/testing": "2.0.0-beta.3",
+    "@tellescope/types-client": "2.0.0-beta.3",
+    "@tellescope/types-models": "2.0.0-beta.3",
+    "@tellescope/types-utilities": "2.0.0-beta.3",
+    "@tellescope/utilities": "2.0.0-beta.3",
+    "@tellescope/validation": "2.0.0-beta.3",
+    "axios": "0.34.0",
     "dotenv": "14.3.2",
     "form-data": "4.0.6",
+    "mongodb": "5.7.0",
     "source-map-support": "0.5.21"
   },
   "devDependencies": {
@@ -58,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "20732ce4e382a7d81dde795ce9c7194c2aca1ce6"
+  "gitHead": "3aca7d6ab38a40816760c9e0f9145558a7a794d9"
 }

package/src/sdk.ts

@@ -3,6 +3,7 @@ import {
   schema,
   extractFields,
   PublicActions,
+  MDBFilter,
 } from "@tellescope/schema"
 
 import {
@@ -79,7 +80,7 @@ export interface LoadFunctionArguments <T> {
   search?: SearchOptions,
   ids?: string[],
   returnCount?: boolean,
-  mdbFilter?: any,
+  mdbFilter?: MDBFilter<T>,
   mdbSort?: any,
   projection?: { [K in keyof T]?: 1 },
 }
@@ -95,7 +96,7 @@ export interface APIQuery<
 {
   createOne: (t: CREATE & { sharedWithOrganizations?: string[][], _overrideUnique?: boolean }) => Promise<T>;
   createSome: (ts: CREATE[], o?: { _overrideUnique?: boolean }) => Promise<{ created: T[], errors: object[] }>;
-  getOne: (argument: string | ReadFilter<T>, mdbFilter?: any) => Promise<T>;
+  getOne: (argument: string | ReadFilter<T>, mdbFilter?: MDBFilter<T>) => Promise<T>;
   getSome: LoadFunction<T>;
   getByIds: ({ ids } : { ids: string[] }) => Promise<{ matches: T[] }>;
   updateOne: (id: string, updates: UPDATE, options?: CustomUpdateOptions, _overrideUnique?: boolean) => Promise<T>;
@@ -275,6 +276,9 @@ type Queries = { [K in keyof ClientModelForName]: APIQuery<K> } & {
     get_organization_api_keys: (args?: extractFields<CustomActions['api_keys']['get_organization_api_keys']['parameters']>) => (
       Promise<extractFields<CustomActions['api_keys']['get_organization_api_keys']['returns']>>
     ),
+    update_organization_api_key: (args: extractFields<CustomActions['api_keys']['update_organization_api_key']['parameters']>) => (
+      Promise<extractFields<CustomActions['api_keys']['update_organization_api_key']['returns']>>
+    ),
     delete_organization_api_key: (args: extractFields<CustomActions['api_keys']['delete_organization_api_key']['parameters']>) => (
       Promise<extractFields<CustomActions['api_keys']['delete_organization_api_key']['returns']>>
     ),
@@ -946,6 +950,12 @@ type Queries = { [K in keyof ClientModelForName]: APIQuery<K> } & {
     generate_ai_decision: (args: extractFields<CustomActions['ai_conversations']['generate_ai_decision']['parameters']>) => (
       Promise<extractFields<CustomActions['ai_conversations']['generate_ai_decision']['returns']>>
     ),
+    // Buffered JSON only. Set `stream: true` and the server answers text/event-stream, which this
+    // Promise-returning client cannot surface — a streaming caller should use fetch/EventSource
+    // against POST /v1/ai-conversations/agent-message directly.
+    agent_message: (args: extractFields<CustomActions['ai_conversations']['agent_message']['parameters']>) => (
+      Promise<extractFields<CustomActions['ai_conversations']['agent_message']['returns']>>
+    ),
   },
   automated_actions: {
     process: (args: extractFields<CustomActions['automated_actions']['process']['parameters']>) => (
@@ -999,6 +1009,7 @@ export class Session extends SessionManager {
     queries.journeys.get_journey_statistics = a => this._GET(`/v1${schema.journeys.customActions.get_journey_statistics.path}`, a)
 
     queries.api_keys.get_organization_api_keys = () => this._GET(`/v1${schema.api_keys.customActions.get_organization_api_keys.path}`)
+    queries.api_keys.update_organization_api_key = ({ id, description }) => this._PATCH(`/v1/organization-api-key/${id}`, { description })
     queries.api_keys.delete_organization_api_key = ({ id }) => this._DELETE(`/v1/organization-api-key/${id}`)
 
     queries.user_logs.restore_deleted = a => this._POST(`/v1${schema.user_logs.customActions.restore_deleted.path}`, a)
@@ -1261,6 +1272,7 @@ export class Session extends SessionManager {
 
     queries.ai_conversations.send_message = args => this._POST(`/v1${schema.ai_conversations.customActions.send_message.path}`, args)
     queries.ai_conversations.generate_ai_decision = args => this._POST(`/v1${schema.ai_conversations.customActions.generate_ai_decision.path}`, args)
+    queries.ai_conversations.agent_message = args => this._POST(`/v1${schema.ai_conversations.customActions.agent_message.path}`, args)
 
     queries.automated_actions.process = args => this._POST(`/v1${schema.automated_actions.customActions.process.path}`, args)
 

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

@@ -1,157 +1,189 @@
 require('source-map-support').install();
 
-import { Session } from "../../sdk"
 import {
-  async_test,
-  handleAnyError,
-  log_header,
-} from "@tellescope/testing"
-import { setup_tests } from "../setup"
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
-// Main test function that can be called independently or as part of the main test suite
-export const ai_conversations_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("AI Conversations Tests")
-
-  // Use unique identifiers per test run to avoid collisions (since delete is not enabled)
-  const testRunId = Date.now().toString()
-  const testOrchestrationId = `test-orchestration-${testRunId}`
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/** Prefers the error's message, falling back to the raw value — JSON.stringify('') is '""' (truthy),
+ *  so a `|| fallback` on the stringified value would make the fallback unreachable. */
+const error_detail = (e: any) => (
+  typeof e?.message === 'string' && e.message !== ''
+    ? e.message
+    : (e === undefined || e === null ? String(e) : JSON.stringify(e))
+)
+
+/**
+ * CRUD coverage for ai_conversations: create, read, the append-only `messages` update, the
+ * replaceObjectFields: true block, and querying by orchestrationId.
+ *
+ * Runs on its own provisioned tenant. `delete` is not enabled for this model, so on the shared
+ * fixture every run left two conversations behind permanently; tearing the whole tenant down is the
+ * only cleanup available to it.
+ */
+export const ai_conversations_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `AIConversations ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    // Unique identifiers per test run (delete is not enabled for this model)
+    const testRunId = Date.now().toString()
+    const testOrchestrationId = `test-orchestration-${testRunId}`
+
+    // Test 1: Create an AIConversation
+    const testMessage = {
+      role: 'user' as const,
+      text: 'Hello, this is a test message',
+      timestamp: new Date(),
+      tokens: 10,
+    }
 
-  // Test 1: Create an AIConversation
-  const testMessage = {
-    role: 'user' as const,
-    text: 'Hello, this is a test message',
-    timestamp: new Date(),
-    tokens: 10,
-  }
+    const conversation = await sdk.api.ai_conversations.createOne({
+      type: 'test-conversation',
+      modelName: 'test-model',
+      messages: [testMessage],
+    })
 
-  const conversation = await sdk.api.ai_conversations.createOne({
-    type: 'test-conversation',
-    modelName: 'test-model',
-    messages: [testMessage],
-  })
-
-  await async_test(
-    "AIConversation created successfully",
-    async () => conversation,
-    { onResult: c => (
-         c.id !== undefined
-      && c.type === 'test-conversation'
-      && c.modelName === 'test-model'
-      && c.messages.length === 1
-      && c.messages[0].text === testMessage.text
-    ) }
-  )
-
-  // Test 2: Read the created AIConversation
-  await async_test(
-    "AIConversation can be read",
-    () => sdk.api.ai_conversations.getOne(conversation.id),
-    { onResult: c => (
-         c.id === conversation.id
-      && c.type === 'test-conversation'
-      && c.messages.length === 1
-    ) }
-  )
-
-  // Test 3: Update by appending messages (without replaceObjectFields)
-  const appendedMessage = {
-    role: 'assistant' as const,
-    text: 'This is an appended response',
-    timestamp: new Date(),
-    tokens: 15,
-  }
+    record(
+      "AIConversation created successfully",
+      conversation.id !== undefined
+      && conversation.type === 'test-conversation'
+      && conversation.modelName === 'test-model'
+      && conversation.messages.length === 1
+      && conversation.messages[0].text === testMessage.text,
+      `created=${JSON.stringify({
+        id: conversation.id, type: conversation.type, modelName: conversation.modelName,
+        messages: conversation.messages.map(m => m.text),
+      })}`,
+    )
+
+    // Test 2: Read the created AIConversation
+    const read = await sdk.api.ai_conversations.getOne(conversation.id)
+    record(
+      "AIConversation can be read",
+      read.id === conversation.id
+      && read.type === 'test-conversation'
+      && read.messages.length === 1,
+      `read=${JSON.stringify({ id: read.id, type: read.type, messages: read.messages.length })}`,
+    )
+
+    // Test 3: Update by appending messages (without replaceObjectFields)
+    const appendedMessage = {
+      role: 'assistant' as const,
+      text: 'This is an appended response',
+      timestamp: new Date(),
+      tokens: 15,
+    }
 
-  await async_test(
-    "AIConversation update appends messages (without replaceObjectFields)",
-    async () => {
-      await sdk.api.ai_conversations.updateOne(conversation.id, {
-        messages: [appendedMessage],
-      })
-      return sdk.api.ai_conversations.getOne(conversation.id)
-    },
-    { onResult: c => (
-         c.messages.length === 2
-      && c.messages[0].text === testMessage.text
-      && c.messages[1].text === appendedMessage.text
-    ) }
-  )
-
-  // Test 4: Verify replaceObjectFields: true is blocked
-  await async_test(
-    "AIConversation update with replaceObjectFields: true is blocked",
-    () => sdk.api.ai_conversations.updateOne(
-      conversation.id,
-      { messages: [appendedMessage] },
-      { replaceObjectFields: true }
-    ),
-    {
-      shouldError: true,
-      onError: (e: any) => (
-        e.message?.includes('replaceObjectFields: true are not allowed')
-        || e.message?.includes('replaceObjectFields')
+    await sdk.api.ai_conversations.updateOne(conversation.id, { messages: [appendedMessage] })
+    const appended = await sdk.api.ai_conversations.getOne(conversation.id)
+    record(
+      "AIConversation update appends messages (without replaceObjectFields)",
+      appended.messages.length === 2
+      && appended.messages[0].text === testMessage.text
+      && appended.messages[1].text === appendedMessage.text,
+      `messages=${JSON.stringify(appended.messages.map(m => m.text))}`,
+    )
+
+    // Test 4: Verify replaceObjectFields: true is blocked
+    try {
+      const unexpected = await sdk.api.ai_conversations.updateOne(
+        conversation.id,
+        { messages: [appendedMessage] },
+        { replaceObjectFields: true },
+      )
+      record(
+        "AIConversation update with replaceObjectFields: true is blocked",
+        false,
+        `the update succeeded (result=${unexpected === undefined ? '(none)' : JSON.stringify(unexpected)});`
+        + ` it must be rejected`,
+      )
+    } catch (e: any) {
+      record(
+        "AIConversation update with replaceObjectFields: true is blocked",
+        !!(
+          e?.message?.includes('replaceObjectFields: true are not allowed')
+          || e?.message?.includes('replaceObjectFields')
+        ),
+        `rejected with ${error_detail(e)}`,
       )
     }
-  )
-
-  // Test 5: Verify messages are still intact after blocked update attempt
-  await async_test(
-    "AIConversation messages preserved after blocked replaceObjectFields attempt",
-    () => sdk.api.ai_conversations.getOne(conversation.id),
-    { onResult: c => (
-         c.messages.length === 2
-      && c.messages[0].text === testMessage.text
-      && c.messages[1].text === appendedMessage.text
-    ) }
-  )
-
-  // Test 6: Can set orchestrationId via update
-  await async_test(
-    "AIConversation orchestrationId can be set via update",
-    async () => {
-      await sdk.api.ai_conversations.updateOne(conversation.id, {
-        orchestrationId: testOrchestrationId,
-      })
-      return sdk.api.ai_conversations.getOne(conversation.id)
-    },
-    { onResult: c => c.orchestrationId === testOrchestrationId }
-  )
-
-  // Test 7: Multiple conversations with same orchestrationId can be queried
-  const conversation2 = await sdk.api.ai_conversations.createOne({
-    type: 'test-conversation-2',
-    modelName: 'test-model',
-    messages: [testMessage],
-    orchestrationId: testOrchestrationId,
-  })
-
-  await async_test(
-    "AIConversations can be queried by orchestrationId",
-    () => sdk.api.ai_conversations.getSome({ filter: { orchestrationId: testOrchestrationId } }),
-    { onResult: conversations => (
-         conversations.length === 2
-      && conversations.some(c => c.id === conversation.id)
-      && conversations.some(c => c.id === conversation2.id)
-    ) }
-  )
-
-  // Note: delete is not enabled for ai_conversations, so no cleanup is performed
-  // Test data will persist but is identifiable by 'test-' prefixes
+
+    // Test 5: Verify messages are still intact after blocked update attempt
+    const preserved = await sdk.api.ai_conversations.getOne(conversation.id)
+    record(
+      "AIConversation messages preserved after blocked replaceObjectFields attempt",
+      preserved.messages.length === 2
+      && preserved.messages[0].text === testMessage.text
+      && preserved.messages[1].text === appendedMessage.text,
+      `messages=${JSON.stringify(preserved.messages.map(m => m.text))}`,
+    )
+
+    // Test 6: Can set orchestrationId via update
+    await sdk.api.ai_conversations.updateOne(conversation.id, { orchestrationId: testOrchestrationId })
+    const withOrchestration = await sdk.api.ai_conversations.getOne(conversation.id)
+    record(
+      "AIConversation orchestrationId can be set via update",
+      withOrchestration.orchestrationId === testOrchestrationId,
+      `orchestrationId=${JSON.stringify(withOrchestration.orchestrationId ?? null)}`
+      + ` (want ${JSON.stringify(testOrchestrationId)})`,
+    )
+
+    // Test 7: Multiple conversations with same orchestrationId can be queried
+    const conversation2 = await sdk.api.ai_conversations.createOne({
+      type: 'test-conversation-2',
+      modelName: 'test-model',
+      messages: [testMessage],
+      orchestrationId: testOrchestrationId,
+    })
+
+    const byOrchestration = await sdk.api.ai_conversations.getSome({
+      filter: { orchestrationId: testOrchestrationId },
+    })
+    record(
+      "AIConversations can be queried by orchestrationId",
+      byOrchestration.length === 2
+      && byOrchestration.some(c => c.id === conversation.id)
+      && byOrchestration.some(c => c.id === conversation2.id),
+      `ids=${JSON.stringify(byOrchestration.map(c => c.id))}`
+      + ` (want both ${conversation.id} and ${conversation2.id})`,
+    )
+  } finally {
+    // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+    // It is also the only cleanup available: ai_conversations has no delete.
+    if (tenant) { try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) } }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs. */
+export const ai_conversations_tests = async () => {
+  assert_checks('AI conversations', await ai_conversations_checks())
 }
 
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'AI conversations', run: ai_conversations_checks }
+
 // 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 ai_conversations_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  ai_conversations_tests()
     .then(() => {
       console.log("✅ AI Conversations test suite completed successfully")
       process.exit(0)