@cobbl-ai/sdk 0.1.0

package/src/__tests__/errors.test.ts

@@ -0,0 +1,100 @@
+import { CobblError } from '../errors'
+
+describe('CobblError', () => {
+  describe('constructor', () => {
+    it('should create an error with message and code', () => {
+      const error = new CobblError('Test error', 'INVALID_REQUEST')
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error).toBeInstanceOf(CobblError)
+      expect(error.message).toBe('Test error')
+      expect(error.code).toBe('INVALID_REQUEST')
+      expect(error.name).toBe('CobblError')
+      expect(error.details).toBeUndefined()
+    })
+
+    it('should create an error with details', () => {
+      const details = { field: 'apiKey', reason: 'missing' }
+      const error = new CobblError('Invalid config', 'INVALID_CONFIG', details)
+
+      expect(error.message).toBe('Invalid config')
+      expect(error.code).toBe('INVALID_CONFIG')
+      expect(error.details).toEqual(details)
+    })
+
+    it('should maintain proper stack trace', () => {
+      const error = new CobblError('Test error', 'API_ERROR')
+
+      expect(error.stack).toBeDefined()
+      expect(error.stack).toContain('CobblError')
+    })
+  })
+
+  describe('isCobblError', () => {
+    it('should return true for CobblError instances', () => {
+      const error = new CobblError('Test', 'NETWORK_ERROR')
+
+      expect(CobblError.isCobblError(error)).toBe(true)
+    })
+
+    it('should return false for standard Error instances', () => {
+      const error = new Error('Test')
+
+      expect(CobblError.isCobblError(error)).toBe(false)
+    })
+
+    it('should return false for non-error values', () => {
+      expect(CobblError.isCobblError(null)).toBe(false)
+      expect(CobblError.isCobblError(undefined)).toBe(false)
+      expect(CobblError.isCobblError('error')).toBe(false)
+      expect(CobblError.isCobblError({ message: 'error' })).toBe(false)
+    })
+  })
+
+  describe('toJSON', () => {
+    it('should serialize error to JSON', () => {
+      const error = new CobblError('Test error', 'SERVER_ERROR', {
+        status: 500,
+      })
+      const json = error.toJSON()
+
+      expect(json).toEqual({
+        name: 'CobblError',
+        message: 'Test error',
+        code: 'SERVER_ERROR',
+        details: { status: 500 },
+      })
+    })
+
+    it('should serialize error without details', () => {
+      const error = new CobblError('Test error', 'NOT_FOUND')
+      const json = error.toJSON()
+
+      expect(json).toEqual({
+        name: 'CobblError',
+        message: 'Test error',
+        code: 'NOT_FOUND',
+        details: undefined,
+      })
+    })
+  })
+
+  describe('error codes', () => {
+    const errorCodes = [
+      'INVALID_CONFIG',
+      'INVALID_REQUEST',
+      'UNAUTHORIZED',
+      'NOT_FOUND',
+      'RATE_LIMIT_EXCEEDED',
+      'SERVER_ERROR',
+      'NETWORK_ERROR',
+      'API_ERROR',
+    ] as const
+
+    it.each(errorCodes)('should support %s error code', (code) => {
+      const error = new CobblError('Test', code)
+
+      expect(error.code).toBe(code)
+    })
+  })
+})

package/src/__tests__/integration.test.ts

@@ -0,0 +1,346 @@
+import { CobblClient, CobblError } from '../index'
+
+// Mock fetch globally
+const mockFetch = jest.fn()
+global.fetch = mockFetch as any
+
+describe('CobblClient Integration Tests', () => {
+  beforeEach(() => {
+    mockFetch.mockClear()
+    delete process.env.COBBL_API_URL
+  })
+
+  describe('complete workflow', () => {
+    it('should run prompt and submit feedback successfully', async () => {
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      // Mock runPrompt response
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          runId: 'run-123',
+          output: 'AI generated summary of Q4 results in a friendly tone.',
+          tokenUsage: {
+            promptTokens: 50,
+            completionTokens: 100,
+            totalTokens: 150,
+          },
+          renderedPrompt:
+            'Summarize Q4 Results in a friendly tone for investors',
+          promptVersion: {
+            id: 'version-1',
+            promptId: 'sales-summary',
+            version: 1,
+            provider: 'openai',
+            model: 'gpt-4',
+            template: 'Summarize {{topic}} in a {{tone}} tone for {{audience}}',
+            variables: ['topic', 'tone', 'audience'],
+            isActive: true,
+            createdAt: new Date('2024-01-01'),
+            metadata: {},
+          },
+        }),
+      })
+
+      const runResult = await client.runPrompt('sales_summary', {
+        topic: 'Q4 Results',
+        tone: 'friendly',
+        audience: 'investors',
+      })
+
+      expect(runResult.runId).toBe('run-123')
+      expect(runResult.output).toContain('Q4 results')
+      expect(runResult.tokenUsage.totalTokens).toBe(150)
+
+      // Mock submitFeedback response
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          feedbackId: 'feedback-123',
+          message: 'Feedback submitted successfully',
+        }),
+      })
+
+      const feedbackResult = await client.submitFeedback({
+        runId: runResult.runId,
+        helpful: 'helpful',
+        userFeedback: 'Great summary! Very clear and concise.',
+      })
+
+      expect(feedbackResult.feedbackId).toBe('feedback-123')
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+
+    it('should handle error in runPrompt and not proceed to feedback', async () => {
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        json: async () => ({ error: 'Prompt not found' }),
+      })
+
+      await expect(client.runPrompt('nonexistent-prompt', {})).rejects.toThrow(
+        CobblError
+      )
+
+      // Should not call submitFeedback after error
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('error handling scenarios', () => {
+    it('should handle multiple API errors gracefully', async () => {
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      // First call fails with 429
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        json: async () => ({
+          error: 'Rate limit exceeded. Please try again later.',
+        }),
+      })
+
+      try {
+        await client.runPrompt('test', {})
+        fail('Should have thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(CobblError)
+        expect((error as CobblError).code).toBe('RATE_LIMIT_EXCEEDED')
+      }
+
+      // Second call fails with 500
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+        json: async () => ({ error: 'Internal server error' }),
+      })
+
+      try {
+        await client.runPrompt('test', {})
+        fail('Should have thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(CobblError)
+        expect((error as CobblError).code).toBe('SERVER_ERROR')
+      }
+
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+
+    it('should maintain state across multiple successful calls', async () => {
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      for (let i = 0; i < 3; i++) {
+        mockFetch.mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({
+            runId: `run-${i}`,
+            output: `Output ${i}`,
+            tokenUsage: {
+              promptTokens: 10,
+              completionTokens: 20,
+              totalTokens: 30,
+            },
+            renderedPrompt: 'test',
+            promptVersion: {
+              id: 'v1',
+              promptId: 'p1',
+              version: 1,
+              provider: 'openai',
+              model: 'gpt-4',
+              template: 'test',
+              variables: [],
+              isActive: true,
+              createdAt: new Date(),
+              metadata: {},
+            },
+          }),
+        })
+
+        const result = await client.runPrompt('test', {})
+        expect(result.runId).toBe(`run-${i}`)
+      }
+
+      expect(mockFetch).toHaveBeenCalledTimes(3)
+    })
+  })
+
+  describe('exports', () => {
+    it('should export CobblClient', () => {
+      expect(CobblClient).toBeDefined()
+      expect(typeof CobblClient).toBe('function')
+    })
+
+    it('should export CobblError', () => {
+      expect(CobblError).toBeDefined()
+      expect(typeof CobblError).toBe('function')
+    })
+
+    it('should be able to create instances of exported classes', () => {
+      const client = new CobblClient({ apiKey: 'test' })
+      const error = new CobblError('test', 'API_ERROR')
+
+      expect(client).toBeInstanceOf(CobblClient)
+      expect(error).toBeInstanceOf(CobblError)
+      expect(error).toBeInstanceOf(Error)
+    })
+  })
+
+  describe('API URL configuration', () => {
+    it('should use default URL when not configured', async () => {
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          runId: 'run-123',
+          output: 'test',
+          tokenUsage: {
+            promptTokens: 10,
+            completionTokens: 20,
+            totalTokens: 30,
+          },
+          renderedPrompt: 'test',
+          promptVersion: {
+            id: 'v1',
+            promptId: 'p1',
+            version: 1,
+            provider: 'openai',
+            model: 'gpt-4',
+            template: 'test',
+            variables: [],
+            isActive: true,
+            createdAt: new Date(),
+            metadata: {},
+          },
+        }),
+      })
+
+      await client.runPrompt('test', {})
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.cobbl.ai/prompt/run',
+        expect.any(Object)
+      )
+    })
+
+    it('should use custom URL from environment', async () => {
+      process.env.COBBL_API_URL = 'https://staging.cobbl.ai'
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          runId: 'run-123',
+          output: 'test',
+          tokenUsage: {
+            promptTokens: 10,
+            completionTokens: 20,
+            totalTokens: 30,
+          },
+          renderedPrompt: 'test',
+          promptVersion: {
+            id: 'v1',
+            promptId: 'p1',
+            version: 1,
+            provider: 'openai',
+            model: 'gpt-4',
+            template: 'test',
+            variables: [],
+            isActive: true,
+            createdAt: new Date(),
+            metadata: {},
+          },
+        }),
+      })
+
+      await client.runPrompt('test', {})
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://staging.cobbl.ai/prompt/run',
+        expect.any(Object)
+      )
+    })
+  })
+
+  describe('type safety', () => {
+    it('should enforce correct types for runPrompt input', async () => {
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          runId: 'run-123',
+          output: 'test',
+          tokenUsage: {
+            promptTokens: 10,
+            completionTokens: 20,
+            totalTokens: 30,
+          },
+          renderedPrompt: 'test',
+          promptVersion: {
+            id: 'v1',
+            promptId: 'p1',
+            version: 1,
+            provider: 'openai',
+            model: 'gpt-4',
+            template: 'test',
+            variables: [],
+            isActive: true,
+            createdAt: new Date(),
+            metadata: {},
+          },
+        }),
+      })
+
+      // Should accept various input types
+      await client.runPrompt('test', {
+        string: 'value',
+        number: 123,
+        boolean: true,
+        nested: { key: 'value' },
+      })
+
+      expect(mockFetch).toHaveBeenCalled()
+    })
+
+    it('should enforce correct types for feedback submission', async () => {
+      const client = new CobblClient({ apiKey: 'test-key' })
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          feedbackId: 'fb-123',
+          message: 'Success',
+        }),
+      })
+
+      // Should accept 'helpful' or 'not_helpful'
+      await client.submitFeedback({
+        runId: 'run-123',
+        helpful: 'helpful',
+        userFeedback: 'Great!',
+      })
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          feedbackId: 'fb-124',
+          message: 'Success',
+        }),
+      })
+
+      await client.submitFeedback({
+        runId: 'run-124',
+        helpful: 'not_helpful',
+        userFeedback: 'Needs improvement',
+      })
+
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+  })
+})

package/src/client.ts

@@ -0,0 +1,257 @@
+/**
+ * CobblClient - SDK for the Cobbl platform
+ *
+ * Provides methods to run prompts and submit feedback to the Cobbl API.
+ */
+
+import type { PromptInput, PromptVersionClient } from '@prompti/shared'
+import type {
+  RunPromptResponse,
+  SubmitFeedbackResponse,
+  CobblConfig,
+  TokenUsage,
+  FeedbackSubmission,
+} from './types'
+import { CobblError } from './errors'
+
+const REQUEST_TIMEOUT_MS = 30_000
+
+export class CobblClient {
+  private readonly apiKey: string
+
+  /**
+   * Initialize the Cobbl SDK client
+   *
+   * @param config - Configuration object
+   * @param config.apiKey - Your Cobbl API key
+   *
+   * @example
+   * ```typescript
+   * const client = new CobblClient({
+   *   apiKey: process.env.COBBL_API_KEY
+   * })
+   * ```
+   */
+  constructor(config: CobblConfig) {
+    if (!config.apiKey || config.apiKey.trim().length === 0) {
+      throw new CobblError('API key is required', 'INVALID_CONFIG')
+    }
+
+    this.apiKey = config.apiKey
+  }
+
+  /**
+   * Execute a prompt with the given input variables
+   *
+   * @param promptSlug - The unique slug identifier for the prompt
+   * @param input - Input variables to populate the prompt template
+   * @returns Promise containing the prompt execution results
+   *
+   * @throws {CobblError} When the request fails or API returns an error
+   *
+   * @example
+   * ```typescript
+   * const result = await client.runPrompt('sales_summary', {
+   *   topic: 'Q4 Results',
+   *   tone: 'friendly',
+   *   audience: 'investors'
+   * })
+   *
+   * console.log(result.output) // AI-generated response
+   * console.log(result.runId) // Save this to link feedback later
+   * ```
+   */
+  async runPrompt(
+    promptSlug: string,
+    input: PromptInput
+  ): Promise<RunPromptResponse> {
+    if (!promptSlug || promptSlug.trim().length === 0) {
+      throw new CobblError('promptSlug is required', 'INVALID_REQUEST')
+    }
+
+    try {
+      const response = await this.makeRequest('/prompt/run', {
+        method: 'POST',
+        body: JSON.stringify({
+          promptSlug: promptSlug.trim(),
+          input,
+        }),
+      })
+
+      if (!response.ok) {
+        await this.handleErrorResponse(response)
+      }
+
+      const data = (await response.json()) as {
+        runId: string
+        output: string
+        tokenUsage: TokenUsage
+        renderedPrompt: string
+        promptVersion: PromptVersionClient
+      }
+
+      return {
+        runId: data.runId,
+        output: data.output,
+        tokenUsage: data.tokenUsage,
+        renderedPrompt: data.renderedPrompt,
+        promptVersion: data.promptVersion,
+      }
+    } catch (error) {
+      if (error instanceof CobblError) {
+        throw error
+      }
+      throw new CobblError(
+        `Failed to run prompt: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'NETWORK_ERROR'
+      )
+    }
+  }
+
+  /**
+   * Submit user feedback for a prompt run
+   *
+   * @param feedback - Feedback submission data
+   * @param feedback.runId - The run ID from a previous runPrompt call
+   * @param feedback.helpful - Whether the output was helpful ('helpful' or 'not_helpful')
+   * @param feedback.userFeedback - Detailed feedback message from the user
+   * @returns Promise containing the created feedback ID
+   *
+   * @throws {CobblError} When the request fails or API returns an error
+   *
+   * @example
+   * ```typescript
+   * await client.submitFeedback({
+   *   runId: result.runId,
+   *   helpful: 'not_helpful',
+   *   userFeedback: 'The response was too formal and lengthy'
+   * })
+   * ```
+   */
+  async submitFeedback(
+    feedback: FeedbackSubmission
+  ): Promise<SubmitFeedbackResponse> {
+    if (!feedback.runId || feedback.runId.trim().length === 0) {
+      throw new CobblError('runId is required', 'INVALID_REQUEST')
+    }
+
+    if (!feedback.userFeedback || feedback.userFeedback.trim().length === 0) {
+      throw new CobblError('userFeedback is required', 'INVALID_REQUEST')
+    }
+
+    if (
+      !feedback.helpful ||
+      !['helpful', 'not_helpful'].includes(feedback.helpful)
+    ) {
+      throw new CobblError(
+        'helpful must be either "helpful" or "not_helpful"',
+        'INVALID_REQUEST'
+      )
+    }
+
+    try {
+      const response = await this.makeRequest('/feedback', {
+        method: 'POST',
+        body: JSON.stringify({
+          runId: feedback.runId.trim(),
+          helpful: feedback.helpful,
+          userFeedback: feedback.userFeedback.trim(),
+        }),
+      })
+
+      if (!response.ok) {
+        await this.handleErrorResponse(response)
+      }
+
+      const data = (await response.json()) as {
+        feedbackId: string
+        message: string
+      }
+
+      return {
+        feedbackId: data.feedbackId,
+        message: data.message,
+      }
+    } catch (error) {
+      if (error instanceof CobblError) {
+        throw error
+      }
+      throw new CobblError(
+        `Failed to submit feedback: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'NETWORK_ERROR'
+      )
+    }
+  }
+
+  /**
+   * Make an HTTP request to the Cobbl API
+   * @private
+   */
+  private async makeRequest(
+    path: string,
+    options: RequestInit
+  ): Promise<Response> {
+    const baseUrl = process.env.COBBL_API_URL || 'https://api.cobbl.ai'
+    const url = `${baseUrl}${path}`
+
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.apiKey}`,
+          ...options.headers,
+        },
+        signal: controller.signal,
+      })
+
+      return response
+    } finally {
+      clearTimeout(timeoutId)
+    }
+  }
+
+  /**
+   * Handle error responses from the API
+   * @private
+   */
+  private async handleErrorResponse(response: Response): Promise<never> {
+    let errorData: any
+    try {
+      errorData = await response.json()
+    } catch {
+      throw new CobblError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        'API_ERROR',
+        { status: response.status }
+      )
+    }
+
+    const message = errorData.error || errorData.message || 'Unknown error'
+    const details = errorData.details
+
+    switch (response.status) {
+      case 400:
+        throw new CobblError(message, 'INVALID_REQUEST', details)
+      case 401:
+        throw new CobblError(message, 'UNAUTHORIZED', details)
+      case 404:
+        throw new CobblError(message, 'NOT_FOUND', details)
+      case 429:
+        throw new CobblError(message, 'RATE_LIMIT_EXCEEDED', details)
+      case 500:
+      case 502:
+      case 503:
+      case 504:
+        throw new CobblError(message, 'SERVER_ERROR', details)
+      default:
+        throw new CobblError(message, 'API_ERROR', {
+          status: response.status,
+          ...details,
+        })
+    }
+  }
+}