feature: more sdk/gateway improvements (#259)

- Do not talk about commits in sdk or public API, instead use versions.
- Replaced add-message endpoint with conversations/:uuid/chat endpoint.

apps/gateway/src/common/routes.ts

@@ -4,12 +4,12 @@ const ROUTES = {
     Base: '/api',
     V1: {
       Base: '/v1',
-      Chats: {
-        Base: '/chats',
-        AddMessage: '/add-message',
+      Conversations: {
+        Base: '/conversations',
+        Chat: '/:conversationUuid/chat',
       },
       Documents: {
-        Base: '/projects/:projectId/commits/:commitUuid/documents',
+        Base: '/projects/:projectId/versions/:versionUuid/documents',
         Get: '/:documentPath{.+}',
         Run: '/run',
       },

apps/gateway/src/routes/api/v1/chats/handlers/addMessage.test.ts → apps/gateway/src/routes/api/v1/conversations/:conversationUuid/handlers/chat.test.ts

@@ -74,12 +74,15 @@ let apiKey: ApiKey
 describe('POST /add-message', () => {
   describe('unauthorized', () => {
     it('fails', async () => {
-      const res = await app.request('/api/v1/chats/add-message', {
-        method: 'POST',
-        body: JSON.stringify({
-          path: '/path/to/document',
-        }),
-      })
+      const res = await app.request(
+        '/api/v1/conversations/fake-document-log-uuid/chat',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            path: '/path/to/document',
+          }),
+        },
+      )
 
       expect(res.status).toBe(401)
     })
@@ -98,10 +101,9 @@ describe('POST /add-message', () => {
       apiKey = key!
       token = apiKey.token
 
-      route = '/api/v1/chats/add-message'
+      route = '/api/v1/conversations/fake-document-log-uuid/chat'
       body = JSON.stringify({
         messages: [],
-        uuid: 'fake-document-log-uuid',
       })
       headers = {
         Authorization: `Bearer ${token}`,

apps/gateway/src/routes/api/v1/chats/handlers/addMessage.ts → apps/gateway/src/routes/api/v1/conversations/:conversationUuid/handlers/chat.ts

@@ -8,27 +8,27 @@ import { Factory } from 'hono/factory'
 import { streamSSE } from 'hono/streaming'
 import { z } from 'zod'
 
-import { chainEventPresenter } from '../../projects/:projectId/commits/:commitUuid/documents/handlers/_shared'
+import { chainEventPresenter } from '../../../projects/:projectId/versions/:versionUuid/documents/handlers/_shared'
 
 const factory = new Factory()
 
 const schema = z.object({
   messages: z.array(messageSchema),
-  uuid: z.string(),
 })
 
-export const addMessageHandler = factory.createHandlers(
+export const chatHandler = factory.createHandlers(
   zValidator('json', schema),
   async (c) => {
     return streamSSE(
       c,
       async (stream) => {
-        const { uuid, messages } = c.req.valid('json')
+        const { conversationUuid } = c.req.param()
+        const { messages } = c.req.valid('json')
         const workspace = c.get('workspace')
 
         const result = await addMessages({
           workspace,
-          documentLogUuid: uuid,
+          documentLogUuid: conversationUuid,
           messages,
           source: LogSources.API,
         }).then((r) => r.unwrap())

apps/gateway/src/routes/api/v1/conversations/:conversationUuid/index.ts

@@ -0,0 +1,8 @@
+import ROUTES from '$/common/routes'
+import { Hono } from 'hono'
+
+import { chatHandler } from './handlers/chat'
+
+export const chatsRouter = new Hono()
+
+chatsRouter.post(ROUTES.Api.V1.Conversations.Chat, ...chatHandler)

apps/gateway/src/routes/api/v1/projects/:projectId/commits/:commitUuid/documents/handlers/get.test.ts → apps/gateway/src/routes/api/v1/projects/:projectId/versions/:versionUuid/documents/handlers/get.test.ts

@@ -20,7 +20,7 @@ describe('GET documents', () => {
   describe('unauthorized', () => {
     it('fails', async () => {
       const res = await app.request(
-        '/api/v1/projects/1/commits/asldkfjhsadl/documents/path/to/document',
+        '/api/v1/projects/1/versions/asldkfjhsadl/documents/path/to/document',
       )
 
       expect(res.status).toBe(401)
@@ -54,7 +54,7 @@ describe('GET documents', () => {
         .getDocumentByPath({ commit, path })
         .then((r) => r.unwrap())
 
-      const route = `/api/v1/projects/${project!.id}/commits/${commit!.uuid}/documents/${document.documentVersion.path}`
+      const route = `/api/v1/projects/${project!.id}/versions/${commit!.uuid}/documents/${document.documentVersion.path}`
       const res = await app.request(route, {
         headers: {
           Authorization: `Bearer ${apikey!.token}`,

apps/gateway/src/routes/api/v1/projects/:projectId/commits/:commitUuid/documents/handlers/get.ts → apps/gateway/src/routes/api/v1/projects/:projectId/versions/:versionUuid/documents/handlers/get.ts

@@ -6,12 +6,12 @@ const factory = createFactory()
 
 export const getHandler = factory.createHandlers(async (c) => {
   const workspace = c.get('workspace')
-  const { projectId, commitUuid, documentPath } = c.req.param()
+  const { projectId, versionUuid, documentPath } = c.req.param()
 
   const { document } = await getData({
     workspace,
     projectId: Number(projectId!),
-    commitUuid: commitUuid!,
+    commitUuid: versionUuid!,
     documentPath: documentPath!,
   }).then((r) => r.unwrap())
 

apps/gateway/src/routes/api/v1/projects/:projectId/commits/:commitUuid/documents/handlers/run.test.ts → apps/gateway/src/routes/api/v1/projects/:projectId/versions/:versionUuid/documents/handlers/run.test.ts

@@ -61,7 +61,7 @@ describe('POST /run', () => {
   describe('unauthorized', () => {
     it('fails', async () => {
       const res = await app.request(
-        '/api/v1/projects/1/commits/asldkfjhsadl/documents/run',
+        '/api/v1/projects/1/versions/asldkfjhsadl/documents/run',
         {
           method: 'POST',
           body: JSON.stringify({
@@ -102,7 +102,7 @@ describe('POST /run', () => {
 
       commit = await mergeCommit(cmt).then((r) => r.unwrap())
 
-      route = `/api/v1/projects/${project!.id}/commits/${commit!.uuid}/documents/run`
+      route = `/api/v1/projects/${project!.id}/versions/${commit!.uuid}/documents/run`
       body = JSON.stringify({
         path: document.documentVersion.path,
         parameters: {},

apps/gateway/src/routes/api/v1/projects/:projectId/commits/:commitUuid/documents/handlers/run.ts → apps/gateway/src/routes/api/v1/projects/:projectId/versions/:versionUuid/documents/handlers/run.ts

@@ -22,13 +22,13 @@ export const runHandler = factory.createHandlers(
     return streamSSE(
       c,
       async (stream) => {
-        const { projectId, commitUuid } = c.req.param()
+        const { projectId, versionUuid } = c.req.param()
         const { path, parameters } = c.req.valid('json')
         const workspace = c.get('workspace')
         const { document, commit } = await getData({
           workspace,
           projectId: Number(projectId!),
-          commitUuid: commitUuid!,
+          commitUuid: versionUuid!,
           documentPath: path!,
         }).then((r) => r.unwrap())
         const result = await runDocumentAtCommit({

apps/gateway/src/routes/app.ts

@@ -5,8 +5,8 @@ import { Hono } from 'hono'
 import { logger } from 'hono/logger'
 import jetPaths from 'jet-paths'
 
-import { chatsRouter } from './api/v1/chats'
-import { documentsRouter } from './api/v1/projects/:projectId/commits/:commitUuid/documents'
+import { chatsRouter } from './api/v1/conversations/:conversationUuid'
+import { documentsRouter } from './api/v1/projects/:projectId/versions/:versionUuid/documents'
 
 const app = new Hono()
 
@@ -23,7 +23,7 @@ app.use(authMiddleware())
 
 // Routers
 app.route(jetPaths(ROUTES).Api.V1.Documents.Base, documentsRouter)
-app.route(jetPaths(ROUTES).Api.V1.Chats.Base, chatsRouter)
+app.route(jetPaths(ROUTES).Api.V1.Conversations.Base, chatsRouter)
 
 // Must be the last one!
 app.use(errorHandlerMiddleware())

apps/web/src/actions/sdk/runDocumentAction.ts

@@ -1,7 +1,7 @@
 'use server'
 
 import { StreamEventTypes } from '@latitude-data/core/browser'
-import { LatitudeSdk, type ChainEventDto } from '@latitude-data/sdk'
+import { Latitude, type ChainEventDto } from '@latitude-data/sdk'
 import { createSdk } from '$/app/(private)/_lib/createSdk'
 import { createStreamableValue, StreamableValue } from 'ai/rsc'
 
@@ -13,7 +13,7 @@ type RunDocumentActionProps = {
 }
 type RunDocumentResponse = Promise<{
   output: StreamableValue<{ event: StreamEventTypes; data: ChainEventDto }>
-  response: ReturnType<typeof LatitudeSdk.prototype.run>
+  response: ReturnType<typeof Latitude.prototype.run>
 }>
 export type RunDocumentActionFn = (
   _: RunDocumentActionProps,
@@ -30,9 +30,8 @@ export async function runDocumentAction({
     { event: StreamEventTypes; data: ChainEventDto },
     Error
   >()
-
   const response = sdk.run(documentPath, {
-    commitUuid,
+    versionUuid: commitUuid,
     parameters,
     onEvent: (event) => {
       stream.update(event)

apps/web/src/app/(private)/_lib/createSdk.ts

@@ -1,7 +1,7 @@
 import { compactObject } from '@latitude-data/core/lib/compactObject'
 import { Result } from '@latitude-data/core/lib/Result'
 import { LatitudeApiKeysRepository } from '@latitude-data/core/repositories'
-import { LatitudeSdk } from '@latitude-data/sdk'
+import { Latitude } from '@latitude-data/sdk'
 import env from '$/env'
 import { getCurrentUser } from '$/services/auth/getCurrentUser'
 
@@ -28,6 +28,6 @@ export async function createSdk(projectId?: number) {
     ssl: env.GATEWAY_SSL,
   }
   return Result.ok(
-    new LatitudeSdk(latitudeApiKey, compactObject({ gateway, projectId })),
+    new Latitude(latitudeApiKey, compactObject({ gateway, projectId })),
   )
 }

packages/sdks/typescript/package.json

@@ -6,8 +6,9 @@
   "license": "LGPL-3.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/latitude-dev/latitude-llm"
+    "url": "https://github.com/latitude-dev/latitude-llm/tree/main/packages/sdks/typescript"
   },
+  "homepage": "https://github.com/latitude-dev/latitude-llm/tree/main/packages/sdks/typescript#readme",
   "scripts": {
     "dev": "rollup -w -c ./rollup.config.mjs",
     "build": "NODE_ENV=production rollup -c ./rollup.config.mjs",

packages/sdks/typescript/src/addMessage.test.ts → packages/sdks/typescript/src/chat.test.ts

@@ -11,13 +11,13 @@ import {
   vi,
 } from 'vitest'
 
-import { LatitudeSdk } from './index'
+import { Latitude } from './index'
 import { parseSSE } from './utils/parseSSE'
 
 const encoder = new TextEncoder()
 let latitudeApiKey = 'fake-api-key'
 let projectId = 123
-const SDK = new LatitudeSdk(latitudeApiKey)
+const SDK = new Latitude(latitudeApiKey)
 
 const server = setupServer()
 
@@ -31,10 +31,13 @@ describe('message', () => {
     server.boundary(async () => {
       const mockFn = vi.fn()
       server.use(
-        http.post('http://localhost:8787/api/v1/chats/add-message', (info) => {
-          mockFn(info.request.headers.get('Authorization'))
-          return HttpResponse.json({})
-        }),
+        http.post(
+          'http://localhost:8787/api/v1/conversations/fake-document-log-uuid/chat',
+          (info) => {
+            mockFn(info.request.headers.get('Authorization'))
+            return HttpResponse.json({})
+          },
+        ),
       )
       await SDK.chat('fake-document-log-uuid', [])
       expect(mockFn).toHaveBeenCalledWith('Bearer fake-api-key')
@@ -47,7 +50,7 @@ describe('message', () => {
       const onMessageMock = vi.fn()
       server.use(
         http.post(
-          'http://localhost:8787/api/v1/chats/add-message',
+          'http://localhost:8787/api/v1/conversations/fake-document-log-uuid/chat',
           async () => {
             const stream = new ReadableStream({
               start(controller) {
@@ -89,7 +92,7 @@ describe('message', () => {
       const onFinishMock = vi.fn()
       server.use(
         http.post(
-          'http://localhost:8787/api/v1/projects/123/commits/live/documents/run',
+          'http://localhost:8787/api/v1/projects/123/versions/live/documents/run',
           async () => {
             const stream = new ReadableStream({
               start(controller) {
@@ -127,7 +130,7 @@ describe('message', () => {
       let body = {}
       server.use(
         http.post(
-          'http://localhost:8787/api/v1/chats/add-message',
+          'http://localhost:8787/api/v1/conversations/fake-document-log-uuid/chat',
           async (info) => {
             const reader = info.request.body!.getReader()
             while (true) {
@@ -147,7 +150,6 @@ describe('message', () => {
       expect(mockFn).toHaveBeenCalledWith({
         body: {
           messages: [],
-          uuid: 'fake-document-log-uuid',
         },
       })
     }),

packages/sdks/typescript/src/index.ts

@@ -24,7 +24,7 @@ type StreamResponseCallbacks = {
   onError?: (error: Error) => void
 }
 
-export class LatitudeSdk {
+export class Latitude {
   private projectId?: number
   private apiKey: string
   private routeResolver: RouteResolver
@@ -61,14 +61,14 @@ export class LatitudeSdk {
     path: string,
     {
       projectId,
-      commitUuid,
+      versionUuid,
       parameters,
       onEvent,
       onFinished,
       onError,
     }: {
       projectId?: number
-      commitUuid?: string
+      versionUuid?: string
       parameters?: Record<string, unknown>
     } & StreamResponseCallbacks,
   ) {
@@ -82,7 +82,7 @@ export class LatitudeSdk {
       const response = await this.request({
         method: 'POST',
         handler: HandlerType.RunDocument,
-        params: { projectId, commitUuid },
+        params: { projectId, versionUuid },
         body: { path, parameters },
       })
 
@@ -105,8 +105,9 @@ export class LatitudeSdk {
   ) {
     const response = await this.request({
       method: 'POST',
-      handler: HandlerType.AddMessageToDocumentLog,
-      body: { uuid, messages },
+      handler: HandlerType.Chat,
+      params: { conversationUuid: uuid },
+      body: { messages },
     })
     return this.handleStream({
       stream: response.body!,