@api-client/core 0.19.0 → 0.19.2

package/tests/unit/modeling/ai/message_parser.spec.ts

@@ -0,0 +1,157 @@
+import { test } from '@japa/runner'
+import { parseAiChatMessage, detectReasoning } from '../../../../src/modeling/ai/message_parser.js'
+import type { AiUserMessageSchema, AiModelMessageSchema } from '../../../../src/models/AiMessage.js'
+import { AiMessageKind } from '../../../../src/models/kinds.js'
+import { AiModelMessageWithDelta } from '../../../../src/modeling/ai/types.js'
+
+test.group('Message Parser | parseAiChatMessage', () => {
+  test('returns user message as is', ({ assert }) => {
+    const userMsg: AiUserMessageSchema = {
+      kind: AiMessageKind,
+      key: 'msg1',
+      session: 'sess1',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      role: 'user',
+      state: 'complete',
+      text: 'Hello AI',
+    }
+
+    const result = parseAiChatMessage(userMsg)
+    assert.deepEqual(result, userMsg)
+  })
+
+  test('returns model message as is if state is not complete', ({ assert }) => {
+    const modelMsg: AiModelMessageSchema = {
+      kind: AiMessageKind,
+      key: 'msg2',
+      session: 'sess1',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      role: 'model',
+      state: 'loading',
+      text: '{"reasoning": "thinking...',
+    }
+
+    const result = parseAiChatMessage(modelMsg)
+    assert.deepEqual(result, modelMsg)
+  })
+
+  test('returns model message as is if JSON parsing fails', ({ assert }) => {
+    const modelMsg: AiModelMessageSchema = {
+      kind: AiMessageKind,
+      key: 'msg3',
+      session: 'sess1',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      role: 'model',
+      state: 'complete',
+      text: 'invalid json',
+    }
+
+    const result = parseAiChatMessage(modelMsg)
+    assert.deepEqual(result, modelMsg)
+  })
+
+  test('parses valid JSON text, sets delta and reasoning', ({ assert }) => {
+    const modelMsg: AiModelMessageSchema = {
+      kind: AiMessageKind,
+      key: 'msg4',
+      session: 'sess1',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      role: 'model',
+      state: 'complete',
+      text: JSON.stringify({
+        reasoning: 'I should add a new model',
+        delta: {
+          addedModels: [{ key: 'model1', name: 'Test Model' }],
+        },
+      }),
+    }
+
+    const result = parseAiChatMessage(modelMsg)
+    assert.equal(result.text, 'I should add a new model')
+    assert.isDefined((result as AiModelMessageWithDelta).delta)
+    assert.deepEqual((result as AiModelMessageWithDelta).delta!.addedModels, [{ key: 'model1', name: 'Test Model' }])
+  })
+
+  test('keeps original text if JSON has no reasoning', ({ assert }) => {
+    const originalJSON = JSON.stringify({
+      delta: {
+        addedModels: [{ key: 'model1', name: 'Test Model' }],
+      },
+    })
+    const modelMsg: AiModelMessageSchema = {
+      kind: AiMessageKind,
+      key: 'msg5',
+      session: 'sess1',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      role: 'model',
+      state: 'complete',
+      text: originalJSON,
+    }
+
+    const result = parseAiChatMessage(modelMsg)
+    assert.equal(result.text, originalJSON)
+    assert.isDefined((result as AiModelMessageWithDelta).delta)
+  })
+})
+
+test.group('Message Parser | detectReasoning', () => {
+  test('returns reasoning from valid JSON', ({ assert }) => {
+    const text = JSON.stringify({ reasoning: 'thinking process' })
+    const result = detectReasoning(text)
+    assert.equal(result, 'thinking process')
+  })
+
+  test('returns undefined from valid JSON without reasoning', ({ assert }) => {
+    const text = JSON.stringify({ other: 'data' })
+    const result = detectReasoning(text)
+    assert.isUndefined(result)
+  })
+
+  test('extracts reasoning from incomplete JSON string', ({ assert }) => {
+    const text = '{"reasoning": "this is some incomplete string'
+    const result = detectReasoning(text)
+    assert.equal(result, 'this is some incomplete string')
+  })
+
+  test('extracts reasoning with escaped characters in incomplete JSON', ({ assert }) => {
+    // Escaped newline and quotes within the incomplete JSON structure
+    const text = '{"reasoning": "line 1\\nline 2 with \\"quotes\\"'
+    const result = detectReasoning(text)
+    assert.equal(result, 'line 1\nline 2 with "quotes"')
+  })
+
+  test('extracts reasoning completely if it ends with quote in incomplete JSON', ({ assert }) => {
+    const text = '{"reasoning": "finished reasoning", "delta": '
+    const result = detectReasoning(text)
+    assert.equal(result, 'finished reasoning')
+  })
+
+  test('handles escaped trailing slashes gracefully', ({ assert }) => {
+    const text = '{"reasoning": "path\\\\to\\\\folder'
+    const result = detectReasoning(text)
+    assert.equal(result, 'path\\to\\folder')
+  })
+
+  test('returns undefined if "reasoning" key is missing in incomplete JSON', ({ assert }) => {
+    const text = '{"delta": {"added'
+    const result = detectReasoning(text)
+    assert.isUndefined(result)
+  })
+
+  test('returns undefined if colon is missing after "reasoning"', ({ assert }) => {
+    const text = '{"reasoning"'
+    const result = detectReasoning(text)
+    assert.isUndefined(result)
+  })
+
+  test('returns undefined if value quote is missing after "reasoning":', ({ assert }) => {
+    const text = '{"reasoning": '
+    const result = detectReasoning(text)
+    assert.isUndefined(result)
+  })
+})

package/tests/unit/modeling/ai/tools/DataDomain.tools.spec.ts

@@ -0,0 +1,64 @@
+import { test } from '@japa/runner'
+import { explain_schema, get_entity_details } from '../../../../../src/modeling/ai/tools/DataDomain.tools.js'
+import { DataDomain } from '../../../../../src/index.js'
+import type { ToolConfig } from '../../../../../src/modeling/ai/tools/config.js'
+
+test.group('DataDomain.tools', () => {
+  test('explain_schema returns valid schemas', async ({ assert }) => {
+    const config = {} as ToolConfig
+    assert.isObject(await explain_schema(config, { dataType: 'string' }))
+    assert.isObject(await explain_schema(config, { dataType: 'number' }))
+    assert.isObject(await explain_schema(config, { dataType: 'boolean' }))
+    assert.isObject(await explain_schema(config, { dataType: 'date' }))
+    assert.isObject(await explain_schema(config, { dataType: 'datetime' }))
+    assert.isObject(await explain_schema(config, { dataType: 'time' }))
+    assert.isObject(await explain_schema(config, { dataType: 'binary' }))
+
+    try {
+      await explain_schema(config, { dataType: 'unsupported' })
+      assert.fail('Should throw error for unsupported type')
+    } catch (err: unknown) {
+      assert.equal((err as Error).message, 'Unsupported data type: unsupported')
+    }
+  })
+
+  test('get_entity_details handles errors', ({ assert }) => {
+    const config = {} as ToolConfig
+    assert.throws(() => get_entity_details(config, {}), 'No current domain provided.')
+
+    config.domain = new DataDomain()
+    assert.throws(() => get_entity_details(config, {}), 'Entity key is required.')
+
+    assert.throws(
+      () => get_entity_details(config, { entityKey: 'missing' }),
+      'Entity with key missing not found in the current domain.'
+    )
+  })
+
+  test('get_entity_details successfully returns details for a valid entity', ({ assert }) => {
+    const domain = new DataDomain()
+    const model = domain.addModel()
+    domain.addEntity(model.key, { key: 'valid-entity', info: { name: 'Valid' } })
+    const config = { domain } as ToolConfig
+
+    const details = get_entity_details(config, { entityKey: 'valid-entity' })
+    assert.equal(details.key, 'valid-entity')
+    assert.equal(details.name, 'Valid')
+    assert.equal(details.modelKey, model.key)
+  })
+
+  test('get_entity_details handles entity without a parent model', ({ assert }) => {
+    const domain = new DataDomain()
+    const model = domain.addModel()
+    const entity = domain.addEntity(model.key, { key: 'orphan-entity', info: { name: 'Orphan' } })
+
+    // Mock getParentInstance
+    entity.getParentInstance = () => undefined
+
+    const config = { domain } as ToolConfig
+    assert.throws(
+      () => get_entity_details(config, { entityKey: 'orphan-entity' }),
+      'Entity with key orphan-entity has no parent model.'
+    )
+  })
+})

package/tests/unit/modeling/ai/tools/Semantic.tools.spec.ts

@@ -0,0 +1,55 @@
+import { test } from '@japa/runner'
+import { list_semantics, get_semantic_details } from '../../../../../src/modeling/ai/tools/Semantic.tools.js'
+import { SemanticType, DataSemantics } from '../../../../../src/modeling/Semantics.js'
+import { AiSemanticsConfig } from '../../../../../src/modeling/ai/Semantics.js'
+import type { ToolConfig } from '../../../../../src/modeling/ai/tools/config.js'
+
+test.group('Semantic.tools', () => {
+  const dummyConfig = {
+    logger: {
+      silly: () => {},
+    },
+  } as unknown as ToolConfig
+
+  test('list_semantics returns all available data semantics', ({ assert }) => {
+    const result = list_semantics(dummyConfig)
+    assert.isArray(result)
+    assert.lengthOf(result, Object.keys(DataSemantics).length)
+
+    // Check first item structure
+    const firstItem = result[0]
+    assert.property(firstItem, 'id')
+    assert.property(firstItem, 'displayName')
+    assert.property(firstItem, 'description')
+    assert.property(firstItem, 'scope')
+    assert.property(firstItem, 'category')
+    assert.property(firstItem, 'hasConfig')
+    // It should map from DataSemantics correctly
+    const firstKey = Object.keys(DataSemantics)[0] as SemanticType
+    assert.equal(firstItem.id, DataSemantics[firstKey].id)
+    assert.equal(firstItem.displayName, DataSemantics[firstKey].displayName)
+  })
+
+  test('get_semantic_details returns details', async ({ assert }) => {
+    const semanticId = SemanticType.Calculated
+    const result = await get_semantic_details(dummyConfig, { semanticId })
+
+    assert.equal(result.id, semanticId)
+    assert.equal(result.displayName, DataSemantics[semanticId].displayName)
+
+    const cnf = AiSemanticsConfig[semanticId] as { configSchema?: unknown }
+    assert.equal(result.configSchema, cnf.configSchema)
+  })
+
+  test('get_semantic_details throws if semanticId is missing', async ({ assert }) => {
+    await assert.rejects(async () => {
+      await get_semantic_details(dummyConfig, {})
+    }, 'Semantic ID is required.')
+  })
+
+  test('get_semantic_details throws if semanticId is invalid', async ({ assert }) => {
+    await assert.rejects(async () => {
+      await get_semantic_details(dummyConfig, { semanticId: 'invalid-id' })
+    }, 'Semantic with ID invalid-id not found')
+  })
+})

package/tests/unit/models/AiMessage.spec.ts

@@ -0,0 +1,216 @@
+import { test } from '@japa/runner'
+import { AiUserMessage, AiModelMessage, AiMessageFactory } from '../../../src/models/AiMessage.js'
+import { AiMessageKind } from '../../../src/models/kinds.js'
+
+test.group('AiMessage | AiUserMessage', () => {
+  test('constants and static properties', ({ assert }) => {
+    assert.equal(AiUserMessage.Kind, AiMessageKind)
+  })
+
+  test('createSchema validates required session', ({ assert }) => {
+    assert.throws(() => AiUserMessage.createSchema({}), 'Session is required to create an AiMessage.')
+  })
+
+  test('createSchema builds valid user schema', ({ assert }) => {
+    const schema = AiUserMessage.createSchema({ session: 'session1', text: 'Hello' })
+    assert.isString(schema.key)
+    assert.isNotEmpty(schema.key)
+    assert.equal(schema.kind, AiMessageKind)
+    assert.equal(schema.session, 'session1')
+    assert.equal(schema.text, 'Hello')
+    assert.equal(schema.role, 'user')
+    assert.equal(schema.state, 'complete')
+    assert.equal(schema.createdAt, 0)
+    assert.equal(schema.updatedAt, 0)
+    assert.isUndefined(schema.deleted)
+    assert.isUndefined(schema.deletedInfo)
+  })
+
+  test('constructor builds AiUserMessage instance', ({ assert }) => {
+    const msg = new AiUserMessage({
+      key: 'msg1',
+      session: 'sess1',
+      text: 'User utterance',
+      createdAt: 10,
+      updatedAt: 20,
+    })
+
+    assert.equal(msg.key, 'msg1')
+    assert.equal(msg.session, 'sess1')
+    assert.equal(msg.role, 'user')
+    assert.equal(msg.state, 'complete')
+    assert.equal(msg.text, 'User utterance')
+    assert.equal(msg.createdAt, 10)
+    assert.equal(msg.updatedAt, 20)
+    assert.isFalse(msg.deleted)
+  })
+
+  test('toJSON correctly serializes an AiUserMessage', ({ assert }) => {
+    const msg = new AiUserMessage({
+      key: 'msg1',
+      session: 'sess1',
+      text: 'Message Data',
+      createdAt: 50,
+      updatedAt: 60,
+      deleted: true,
+      deletedInfo: { time: 100, byMe: true, user: 'user1' },
+    })
+
+    const json = msg.toJSON()
+    assert.deepEqual(json, {
+      kind: AiMessageKind,
+      key: 'msg1',
+      role: 'user',
+      session: 'sess1',
+      state: 'complete',
+      text: 'Message Data',
+      createdAt: 50,
+      updatedAt: 60,
+      deleted: true,
+      deletedInfo: { time: 100, byMe: true, user: 'user1' },
+    })
+  })
+})
+
+test.group('AiMessage | AiModelMessage', () => {
+  test('createSchema validates required session', ({ assert }) => {
+    assert.throws(() => AiModelMessage.createSchema({}), 'Session is required to create an AiMessage.')
+  })
+
+  test('createSchema builds valid model schema', ({ assert }) => {
+    const schema = AiModelMessage.createSchema({ session: 'session1', text: 'Response' })
+    assert.isString(schema.key)
+    assert.isNotEmpty(schema.key)
+    assert.equal(schema.kind, AiMessageKind)
+    assert.equal(schema.session, 'session1')
+    assert.equal(schema.text, 'Response')
+    assert.equal(schema.role, 'model')
+    assert.equal(schema.state, 'loading') // default
+    assert.equal(schema.thoughts, '')
+    assert.isUndefined(schema.applied)
+    assert.isUndefined(schema.deleted)
+    assert.isUndefined(schema.deletedInfo)
+  })
+
+  test('constructor builds AiModelMessage instance', ({ assert }) => {
+    const msg = new AiModelMessage({
+      key: 'msg1',
+      session: 'sess1',
+      text: 'Model utterance',
+      state: 'complete',
+      applied: true,
+      thoughts: 'Initial Thoughts',
+      createdAt: 10,
+      updatedAt: 20,
+    })
+
+    assert.equal(msg.key, 'msg1')
+    assert.equal(msg.session, 'sess1')
+    assert.equal(msg.role, 'model')
+    assert.equal(msg.state, 'complete')
+    assert.equal(msg.text, 'Model utterance')
+    assert.equal(msg.thoughts, 'Initial Thoughts')
+    assert.isTrue(msg.applied)
+    assert.equal(msg.createdAt, 10)
+    assert.equal(msg.updatedAt, 20)
+    assert.isFalse(msg.deleted)
+  })
+
+  test('toJSON correctly serializes an AiModelMessage', ({ assert }) => {
+    const msg = new AiModelMessage({
+      key: 'msg1',
+      session: 'sess1',
+      text: 'Message Data',
+      state: 'complete',
+      thoughts: 'Inner Monologue',
+      applied: false,
+      createdAt: 50,
+      updatedAt: 60,
+      deleted: true,
+      deletedInfo: { time: 100, byMe: true, user: 'user1' },
+    })
+
+    const json = msg.toJSON()
+    assert.deepEqual(json, {
+      kind: AiMessageKind,
+      key: 'msg1',
+      role: 'model',
+      session: 'sess1',
+      state: 'complete',
+      text: 'Message Data',
+      thoughts: 'Inner Monologue',
+      applied: false,
+      createdAt: 50,
+      updatedAt: 60,
+      deleted: true,
+      deletedInfo: { time: 100, byMe: true, user: 'user1' },
+    })
+  })
+
+  test('addThought safely appends thoughts', ({ assert }) => {
+    const msg = new AiModelMessage({ session: 's1' })
+    msg.addThought('Hello ')
+    msg.addThought('World!')
+    msg.addThought()
+    assert.equal(msg.thoughts, 'Hello World!')
+  })
+
+  test('addText safely appends text', ({ assert }) => {
+    const msg = new AiModelMessage({ session: 's1' })
+    msg.addText('Hello ')
+    msg.addText('World!')
+    msg.addText()
+    assert.equal(msg.text, 'Hello World!')
+  })
+
+  test('processMessage throws on invalid JSON', ({ assert }) => {
+    const msg = new AiModelMessage({ session: 's1', text: 'NOT JSON' })
+    assert.throws(() => msg.processMessage(), SyntaxError)
+  })
+
+  test('processMessage parses delta and reasoning', ({ assert }) => {
+    const msg = new AiModelMessage({
+      session: 's1',
+      text: JSON.stringify({
+        reasoning: 'I need to make models',
+        delta: { addedModels: [{ key: 'model1' }] },
+      }),
+    })
+    msg.processMessage()
+    assert.equal(msg.reasoning, 'I need to make models')
+    assert.isDefined(msg.delta)
+    assert.deepEqual(msg.delta!.addedModels, [{ key: 'model1' }])
+  })
+
+  test('processMessageSafe swallows errors', ({ assert }) => {
+    const msg = new AiModelMessage({ session: 's1', text: 'NOT JSON' })
+    msg.processMessageSafe() // should not throw
+    assert.isUndefined(msg.delta)
+    assert.isUndefined(msg.reasoning)
+  })
+
+  test('createEmpty generates loading stub', ({ assert }) => {
+    const msg = AiModelMessage.createEmpty('sess1')
+    assert.equal(msg.session, 'sess1')
+    assert.equal(msg.state, 'loading')
+    assert.equal(msg.role, 'model')
+  })
+})
+
+test.group('AiMessage | AiMessageFactory', () => {
+  test('fromSchema generates AiUserMessage when role=user', ({ assert }) => {
+    const schema = AiUserMessage.createSchema({ session: 'sess', text: 'Hello User' })
+    const msg = AiMessageFactory.fromSchema(schema)
+    assert.instanceOf(msg, AiUserMessage)
+    assert.equal(msg.role, 'user')
+    assert.equal(msg.text, 'Hello User')
+  })
+
+  test('fromSchema generates AiModelMessage when role=model', ({ assert }) => {
+    const schema = AiModelMessage.createSchema({ session: 'sess', text: 'Hello Model' })
+    const msg = AiMessageFactory.fromSchema(schema)
+    assert.instanceOf(msg, AiModelMessage)
+    assert.equal(msg.role, 'model')
+    assert.equal(msg.text, 'Hello Model')
+  })
+})

package/tests/unit/models/AiSession.spec.ts

@@ -0,0 +1,147 @@
+import { test } from '@japa/runner'
+import { AiSession } from '../../../src/models/AiSession.js'
+import { AiSessionKind, AiMessageKind } from '../../../src/models/kinds.js'
+import type { AiModelMessage } from '../../../src/models/AiMessage.js'
+
+test.group('AiSession', () => {
+  test('constants and static properties', ({ assert }) => {
+    assert.equal(AiSession.Kind, AiSessionKind)
+
+    const session = new AiSession({ app: 'general' })
+    assert.equal(session.kind, AiSessionKind)
+  })
+
+  test('isSessionApp check valid and invalid apps', ({ assert }) => {
+    assert.isTrue(AiSession.isSessionApp('domain'))
+    assert.isTrue(AiSession.isSessionApp('api'))
+    assert.isTrue(AiSession.isSessionApp('general'))
+    assert.isFalse(AiSession.isSessionApp('unknown'))
+    assert.isFalse(AiSession.isSessionApp(null))
+    assert.isFalse(AiSession.isSessionApp(undefined))
+  })
+
+  test('createSchema validates required arguments', ({ assert }) => {
+    assert.throws(() => AiSession.createSchema({}), 'App is required to create an AiSession schema.')
+    // @ts-expect-error for testing invalid app
+    assert.throws(() => AiSession.createSchema({ app: 'invalid' }), 'Invalid app: invalid')
+  })
+
+  test('createSchema generates schema with defaults', ({ assert }) => {
+    const schema = AiSession.createSchema({ app: 'domain' })
+    assert.isString(schema.key)
+    assert.isNotEmpty(schema.key)
+    assert.equal(schema.kind, AiSessionKind)
+    assert.equal(schema.app, 'domain')
+    assert.equal(schema.title, '')
+    assert.isFalse(schema.pinned)
+    assert.isFalse(schema.userRenamed)
+    assert.equal(schema.createdAt, 0)
+    assert.equal(schema.updatedAt, 0)
+    assert.isUndefined(schema.deleted)
+    assert.isUndefined(schema.deletedInfo)
+  })
+
+  test('constructor builds AiSession instance', ({ assert }) => {
+    const session = new AiSession({
+      key: 'test-key',
+      app: 'api',
+      title: 'API Session',
+      pinned: true,
+      userRenamed: true,
+      createdAt: 100,
+      updatedAt: 200,
+    })
+
+    assert.equal(session.key, 'test-key')
+    assert.equal(session.app, 'api')
+    assert.equal(session.title, 'API Session')
+    assert.isTrue(session.pinned)
+    assert.isTrue(session.userRenamed)
+    assert.equal(session.createdAt, 100)
+    assert.equal(session.updatedAt, 200)
+    assert.isFalse(session.deleted)
+    assert.isUndefined(session.deletedInfo)
+  })
+
+  test('toJSON correctly serializes an AiSession', ({ assert }) => {
+    const session = new AiSession({
+      key: 'test-key',
+      app: 'general',
+      createdAt: 50,
+      updatedAt: 50,
+      deleted: true,
+      deletedInfo: {
+        time: 100,
+        byMe: true,
+        user: 'user1',
+      },
+    })
+    session.title = 'Test Title'
+
+    const json = session.toJSON()
+    assert.deepEqual(json, {
+      kind: AiSessionKind,
+      key: 'test-key',
+      app: 'general',
+      title: 'Test Title',
+      pinned: false,
+      userRenamed: false,
+      createdAt: 50,
+      updatedAt: 50,
+      deleted: true,
+      deletedInfo: {
+        time: 100,
+        byMe: true,
+        user: 'user1',
+      },
+    })
+  })
+
+  test('extractSessionTitle extracts sessionTitle when valid', ({ assert }) => {
+    const msg: AiModelMessage = {
+      kind: AiMessageKind,
+      key: 'msg1',
+      session: 'sess1',
+      role: 'model',
+      state: 'complete',
+      createdAt: 1,
+      updatedAt: 1,
+      text: JSON.stringify({ sessionTitle: 'New Generated Title' }),
+    } as unknown as AiModelMessage
+
+    const title = AiSession.extractSessionTitle(msg)
+    assert.equal(title, 'New Generated Title')
+  })
+
+  test('extractSessionTitle returns null for non-json response text', ({ assert }) => {
+    const msg: AiModelMessage = {
+      kind: AiMessageKind,
+      key: 'msg1',
+      session: 'sess1',
+      role: 'model',
+      state: 'complete',
+      createdAt: 1,
+      updatedAt: 1,
+      text: 'I am not JSON',
+    } as unknown as AiModelMessage
+
+    const title = AiSession.extractSessionTitle(msg)
+    assert.isNull(title)
+  })
+
+  test('extractSessionTitle returns null for JSON without sessionTitle', ({ assert }) => {
+    const msg: AiModelMessage = {
+      kind: AiMessageKind,
+      key: 'msg1',
+      session: 'sess1',
+      role: 'model',
+      state: 'complete',
+      createdAt: 1,
+      updatedAt: 1,
+      text: JSON.stringify({ otherField: 'value' }),
+    } as unknown as AiModelMessage
+
+    const title = AiSession.extractSessionTitle(msg)
+    assert.isNull(title)
+  })
+})