@cobbl-ai/sdk 0.1.0 → 0.1.2

package/src/public.ts

@@ -0,0 +1,270 @@
+/**
+ * Cobbl SDK - Public API Client
+ *
+ * A lightweight client for public-facing feedback operations.
+ * Use this in client-side or user-facing contexts.
+ * No authentication required - designed for end-user feedback submission.
+ *
+ * @example
+ * ```typescript
+ * import { CobblPublicClient } from '@cobbl-ai/sdk/public'
+ *
+ * const client = new CobblPublicClient({
+ *   baseUrl: 'https://api.cobbl.ai' // Optional, defaults to production
+ * })
+ *
+ * // Submit feedback
+ * const { id } = await client.createFeedback({
+ *   runId: 'run_abc123',
+ *   helpful: 'not_helpful'
+ * })
+ *
+ * // Update feedback with details later
+ * await client.updateFeedback(id, {
+ *   userFeedback: 'Too formal'
+ * })
+ * ```
+ */
+
+import type {
+  CreateFeedbackRequest,
+  CreateFeedbackResponse,
+  UpdateFeedbackRequest,
+  UpdateFeedbackResponse,
+} from './types'
+import { CobblError, handleErrorResponse } from './errors'
+import { validateCreateFeedback, validateUpdateFeedback } from './validation'
+
+/**
+ * Configuration options for CobblPublicClient
+ */
+export interface CobblPublicConfig {
+  /**
+   * Base URL for the API
+   * @optional
+   * @default 'https://api.cobbl.ai'
+   * @internal
+   * @example 'http://localhost:5001/your-project/us-central1/externalApi' // For local development
+   */
+  baseUrl?: string
+}
+
+const REQUEST_TIMEOUT_MS = 30_000
+
+/**
+ * Public API Client for Cobbl
+ *
+ * Provides methods to submit and update feedback via the public API.
+ * This client is suitable for use in client-side or user-facing contexts.
+ * No authentication required - designed for end-user feedback submission.
+ */
+export class CobblPublicClient {
+  private readonly baseUrl: string
+
+  /**
+   * Initialize the Cobbl Public SDK client
+   *
+   * @param config - Configuration object
+   * @param config.baseUrl - Optional base URL for the API (defaults to 'https://api.cobbl.ai')
+   */
+  constructor(config: CobblPublicConfig = {}) {
+    this.baseUrl = config.baseUrl?.trim() || 'https://api.cobbl.ai'
+  }
+
+  /**
+   * Create user feedback for a prompt run
+   * Supports segmented feedback - you can provide just helpful, just userFeedback, or both
+   * Use updateFeedback to add additional data later
+   *
+   * @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') - optional
+   * @param feedback.userFeedback - Detailed feedback message from the user - optional
+   * @returns Promise containing the created feedback ID
+   *
+   * @throws {CobblError} When the request fails or API returns an error
+   *
+   * @example Submit just thumbs down first
+   * ```typescript
+   * const { id } = await client.createFeedback({
+   *   runId: result.runId,
+   *   helpful: 'not_helpful'
+   * })
+   * // Later, add details
+   * await client.updateFeedback(id, {
+   *   userFeedback: 'The response was too formal and lengthy'
+   * })
+   * ```
+   *
+   * @example Submit both at once
+   * ```typescript
+   * await client.createFeedback({
+   *   runId: result.runId,
+   *   helpful: 'not_helpful',
+   *   userFeedback: 'The response was too formal and lengthy'
+   * })
+   * ```
+   */
+  async createFeedback(
+    feedback: CreateFeedbackRequest
+  ): Promise<CreateFeedbackResponse> {
+    const validationError = validateCreateFeedback(feedback)
+    if (validationError) {
+      throw new CobblError(validationError, 'INVALID_REQUEST')
+    }
+
+    try {
+      // Build request body with only provided fields
+      const body: CreateFeedbackRequest = {
+        runId: feedback.runId.trim(),
+        helpful: feedback.helpful,
+        userFeedback: feedback.userFeedback?.trim(),
+      }
+
+      const response = await this.makeRequest('/public/v1/feedback', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      })
+
+      if (!response.ok) {
+        await handleErrorResponse(response)
+      }
+
+      const data = (await response.json()) as {
+        id: string
+        message: string
+      }
+
+      return {
+        id: data.id,
+        message: data.message,
+      }
+    } catch (error) {
+      if (error instanceof CobblError) {
+        throw error
+      }
+      throw new CobblError(
+        `Failed to create feedback: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'NETWORK_ERROR'
+      )
+    }
+  }
+
+  /**
+   * Update existing feedback with additional data
+   * Use this to add helpful sentiment or detailed feedback after initial submission
+   *
+   * @param id - The ID returned from createFeedback
+   * @param update - The data to update
+   * @param update.helpful - Whether the output was helpful ('helpful' or 'not_helpful') - optional
+   * @param update.userFeedback - Detailed feedback message from the user - optional
+   * @returns Promise containing the updated feedback ID
+   *
+   * @throws {CobblError} When the request fails or API returns an error
+   *
+   * @example Add details after initial thumbs down
+   * ```typescript
+   * // First, submit just the rating
+   * const { id } = await client.createFeedback({
+   *   runId: result.runId,
+   *   helpful: 'not_helpful'
+   * })
+   *
+   * // Later, add detailed feedback
+   * await client.updateFeedback(id, {
+   *   userFeedback: 'The response was too formal and lengthy'
+   * })
+   * ```
+   */
+  async updateFeedback(
+    id: string,
+    update: UpdateFeedbackRequest
+  ): Promise<UpdateFeedbackResponse> {
+    if (!id || id.trim().length === 0) {
+      throw new CobblError('id is required', 'INVALID_REQUEST')
+    }
+
+    const validationError = validateUpdateFeedback(update)
+    if (validationError) {
+      throw new CobblError(validationError, 'INVALID_REQUEST')
+    }
+
+    try {
+      // Build request body with only provided fields
+      const body: UpdateFeedbackRequest = {
+        helpful: update.helpful,
+        userFeedback: update.userFeedback?.trim(),
+      }
+
+      const response = await this.makeRequest(
+        `/public/v1/feedback/${id.trim()}`,
+        {
+          method: 'PATCH',
+          body: JSON.stringify(body),
+        }
+      )
+
+      if (!response.ok) {
+        await handleErrorResponse(response)
+      }
+
+      const data = (await response.json()) as {
+        id: string
+        message: string
+      }
+
+      return {
+        id: data.id,
+        message: data.message,
+      }
+    } catch (error) {
+      if (error instanceof CobblError) {
+        throw error
+      }
+      throw new CobblError(
+        `Failed to update 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 url = `${this.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',
+          ...options.headers,
+        },
+        signal: controller.signal,
+      })
+
+      return response
+    } finally {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+// Export the client
+export { CobblError } from './errors'
+export type { CobblErrorCode } from './errors'
+export type {
+  CreateFeedbackRequest,
+  CreateFeedbackResponse,
+  UpdateFeedbackRequest,
+  UpdateFeedbackResponse,
+  Helpful,
+} from './types'

package/src/types.ts

@@ -1,8 +1,12 @@
 /**
  * Type definitions for the Cobbl SDK
+ *
+ * All types are defined locally to keep the SDK self-contained.
+ * These match the API contract and are used as type hints for SDK consumers.
  */
 
-import type { PromptVersionClient, TokenUsage, Helpful } from '@prompti/shared'
+
+// ─── SDK Config ──────────────────────────────────────────────
 
 /**
  * Configuration options for the CobblClient
@@ -13,82 +17,184 @@ export interface CobblConfig {
    * @required
    */
   apiKey: string
+
+  /**
+   * Base URL for the API
+   * @optional
+   * @default 'https://api.cobbl.ai'
+   * @internal
+   * @example 'http://localhost:5001/your-project/us-central1/externalApi' // For local development
+   */
+  baseUrl?: string
 }
 
+// ─── Feedback Types ──────────────────────────────────────────
+
 /**
- * Response from running a prompt
+ * Whether the AI output was helpful
  */
-export interface RunPromptResponse {
-  /**
-   * Unique ID for this prompt run - use this to link feedback
-   */
+export type Helpful = 'helpful' | 'not_helpful'
+
+/**
+ * Request payload for creating feedback
+ * Supports segmented feedback submission - at least one of helpful or userFeedback required
+ */
+export interface CreateFeedbackRequest {
   runId: string
+  helpful?: Helpful
+  userFeedback?: string
+}
 
-  /**
-   * The AI-generated output
-   */
-  output: string
+/**
+ * Response from creating feedback
+ */
+export interface CreateFeedbackResponse {
+  id: string
+  message: string
+}
 
-  /**
-   * Token usage statistics
-   */
-  tokenUsage: TokenUsage
+/**
+ * Request payload for updating feedback
+ * At least one of helpful or userFeedback required
+ */
+export interface UpdateFeedbackRequest {
+  helpful?: Helpful
+  userFeedback?: string
+}
 
-  /**
-   * The rendered prompt that was sent to the LLM (with variables substituted)
-   */
-  renderedPrompt: string
+/**
+ * Response from updating feedback
+ */
+export interface UpdateFeedbackResponse {
+  id: string
+  message: string
+}
 
-  /**
-   * Information about the prompt version that was used
-   */
-  promptVersion: PromptVersionClient
+// ─── Prompt Types ────────────────────────────────────────────
+
+/**
+ * Supported LLM providers
+ */
+export type Provider = 'openai' | 'anthropic' | 'google'
+
+/**
+ * Configuration for a variable in the prompt
+ */
+export interface VariableConfig {
+  key: string
+  type: 'string' | 'number' | 'boolean' | 'list' | 'object'
+  required: boolean
+  description?: string
 }
 
 /**
- * Feedback submission data
+ * Input values provided when executing a prompt
  */
-export interface FeedbackSubmission {
-  /**
-   * The run ID from a previous runPrompt call
-   * @required
-   */
-  runId: string
+export type PromptInput = Record<
+  string,
+  string | number | boolean | unknown[] | Record<string, unknown>
+>
 
-  /**
-   * Whether the output was helpful
-   * @required
-   */
-  helpful: Helpful
+// ─── Token Usage ─────────────────────────────────────────────
 
-  /**
-   * Detailed feedback message from the user
-   * @required
-   */
-  userFeedback: string
+/**
+ * Token usage breakdown for a completed prompt run
+ */
+export interface TokenUsage {
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
 }
 
+// ─── Analytics ───────────────────────────────────────────────
+
 /**
- * Response from submitting feedback
+ * Aggregated analytics for a prompt or prompt version
  */
-export interface SubmitFeedbackResponse {
-  /**
-   * Unique ID for the created feedback item
-   */
-  feedbackId: string
+export interface PromptAggregatedAnalytics {
+  runs: {
+    totalCount: number
+    successCount: number
+    errorCount: number
+    totalProviderMs: number
+    totalRequestMs: number
+    successRate: number
+    errorRate: number
+    avgProviderMs: number
+    avgRequestMs: number
+  }
+  feedback: {
+    totalCount: number
+    helpfulCount: number
+    notHelpfulCount: number
+    helpfulRate: number
+  }
+}
 
-  /**
-   * Success message
-   */
-  message: string
+// ─── Prompt Version ──────────────────────────────────────────
+
+/**
+ * Base fields shared across all prompt version sources
+ */
+interface PromptVersionBase {
+  id: string
+  schemaVersion: number
+  createdAt: Date
+  updatedAt: Date
+  tenantId: string
+  environmentId: string
+  promptId: string
+  versionNumber: number
+  template: string
+  variables: VariableConfig[]
+  provider: Provider
+  model: string
+  status: 'draft' | 'active' | 'inactive'
+  parentVersionId: string | null
+  analytics: PromptAggregatedAnalytics
+  publishedAt: Date | null
+}
+
+/**
+ * Manually created prompt version (by a user or from feedback edits)
+ */
+interface PromptVersionManual extends PromptVersionBase {
+  source: 'manual'
+  authorId: string
+  authorName: string | null
+}
+
+/**
+ * AI-generated prompt version suggestion from feedback issue assessment
+ */
+interface PromptVersionIssueLlmSuggestion extends PromptVersionBase {
+  source: 'issue_llm_suggestion'
+}
+
+/**
+ * Prompt version - discriminated union by source
+ */
+export type PromptVersionClient =
+  | PromptVersionManual
+  | PromptVersionIssueLlmSuggestion
+
+// ─── API Request/Response Types ──────────────────────────────
+
+/**
+ * Request payload for running a prompt
+ */
+export interface RunPromptRequest {
+  promptSlug: string
+  input: PromptInput
 }
 
-// Re-export commonly used types from shared
-export type {
-  PromptInput,
-  PromptVersionClient,
-  Provider,
-  VariableConfig,
-  TokenUsage,
-  Helpful,
-} from '@prompti/shared'
+/**
+ * Response from running a prompt
+ */
+export interface RunPromptResponse {
+  runId: string
+  output: string
+  tokenUsage: TokenUsage
+  renderedPrompt: string
+  promptVersion: PromptVersionClient
+}

package/src/validation.ts

@@ -0,0 +1,52 @@
+import type {
+  CreateFeedbackRequest,
+  UpdateFeedbackRequest,
+  Helpful,
+} from './types'
+
+const VALID_HELPFUL_VALUES: Helpful[] = ['helpful', 'not_helpful']
+
+export function validateCreateFeedback(
+  feedback: CreateFeedbackRequest
+): string | null {
+  if (!feedback.runId || feedback.runId.trim().length === 0) {
+    return 'runId is required'
+  }
+  if (
+    feedback.helpful !== undefined &&
+    !VALID_HELPFUL_VALUES.includes(feedback.helpful)
+  ) {
+    return 'helpful must be "helpful" or "not_helpful"'
+  }
+  if (
+    feedback.userFeedback !== undefined &&
+    feedback.userFeedback.trim().length === 0
+  ) {
+    return 'userFeedback cannot be empty'
+  }
+  if (feedback.helpful === undefined && feedback.userFeedback === undefined) {
+    return 'At least one of helpful or userFeedback is required'
+  }
+  return null
+}
+
+export function validateUpdateFeedback(
+  update: UpdateFeedbackRequest
+): string | null {
+  if (
+    update.helpful !== undefined &&
+    !VALID_HELPFUL_VALUES.includes(update.helpful)
+  ) {
+    return 'helpful must be "helpful" or "not_helpful"'
+  }
+  if (
+    update.userFeedback !== undefined &&
+    update.userFeedback.trim().length === 0
+  ) {
+    return 'userFeedback cannot be empty'
+  }
+  if (update.helpful === undefined && update.userFeedback === undefined) {
+    return 'At least one of helpful or userFeedback is required'
+  }
+  return null
+}