@cobbl-ai/sdk 0.1.0 → 0.1.2

package/README.md

@@ -13,6 +13,7 @@ The official TypeScript/JavaScript SDK for [Cobbl](https://cobbl.ai) - a feedbac
 - 📦 **Zero config** - Works out of the box with sensible defaults
 - 🌐 **Cross-platform** - Supports both CommonJS and ES modules
 - ⚡ **Optimized** - Minimal bundle size, tree-shakeable exports
+- 🎯 **Namespaced exports** - Separate admin and public clients for different use cases
 
 ## Installation
 
@@ -27,18 +28,39 @@ yarn add @cobbl-ai/sdk
 pnpm add @cobbl-ai/sdk
 ```
 
+### CDN / Script Tag
+
+For use without a bundler, load the SDK via a `<script>` tag. This exposes `CobblPublicClient` on `window.Cobbl`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@cobbl-ai/sdk"></script>
+
+<script>
+  const client = new Cobbl.CobblPublicClient()
+
+  client.createFeedback({
+    runId: 'your-run-id',
+    helpful: 'helpful',
+  }).then(({ id }) => {
+    console.log('Feedback created:', id)
+  })
+</script>
+```
+
+> **Note:** Only `CobblPublicClient` is available via the CDN bundle. The `CobblAdminClient` requires an API key and should only be used server-side.
+
 ## Quick Start
 
 ```typescript
-import { CobblClient } from '@cobbl-ai/sdk'
+// Admin operations (server-side)
+import { CobblAdminClient } from '@cobbl-ai/sdk/admin'
 
-// Initialize the client
-const client = new CobblClient({
-  apiKey: process.env.PROMPTI_API_KEY,
+const adminClient = new CobblAdminClient({
+  apiKey: process.env.COBBL_API_KEY,
 })
 
 // Run a prompt
-const result = await client.runPrompt('sales_summary', {
+const result = await adminClient.runPrompt('sales_summary', {
   topic: 'Q4 Results',
   tone: 'friendly',
   audience: 'investors',
@@ -47,46 +69,98 @@ const result = await client.runPrompt('sales_summary', {
 console.log(result.output) // AI-generated response
 console.log(result.runId) // Save this to link feedback later
 
-// Submit user feedback
-await client.submitFeedback({
+// Public operations (client-facing, no auth required)
+import { CobblPublicClient } from '@cobbl-ai/sdk/public'
+
+const publicClient = new CobblPublicClient()
+
+// Create user feedback
+await publicClient.createFeedback({
   runId: result.runId,
   helpful: 'not_helpful',
   userFeedback: 'The response was too formal and lengthy',
 })
 ```
 
+## Namespaced Imports
+
+The SDK provides separate entry points for admin and public operations:
+
+```typescript
+// Admin client - for server-side operations
+import { CobblAdminClient } from '@cobbl-ai/sdk/admin'
+
+// Public client - for client-facing feedback operations
+import { CobblPublicClient } from '@cobbl-ai/sdk/public'
+
+// Or import both from main entry
+import { CobblAdminClient, CobblPublicClient } from '@cobbl-ai/sdk'
+```
+
 ## Configuration
 
-### Initializing the Client
+### Initializing the Clients
 
 ```typescript
-import { CobblClient } from '@cobbl-ai/sdk'
+import { CobblAdminClient } from '@cobbl-ai/sdk/admin'
+import { CobblPublicClient } from '@cobbl-ai/sdk/public'
+
+// Production (uses default URL: https://api.cobbl.ai)
+const adminClient = new CobblAdminClient({
+  apiKey: 'your-api-key',
+})
+
+// Public client (no auth required)
+const publicClient = new CobblPublicClient()
 
-const client = new CobblClient({
-  apiKey: 'your-api-key', // Your Cobbl API key
+// Custom URL (e.g., local development)
+const devAdminClient = new CobblAdminClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'http://localhost:5001/your-project-id/us-central1/externalApi',
+})
+
+const devPublicClient = new CobblPublicClient({
+  baseUrl: 'http://localhost:5001/your-project-id/us-central1/externalApi',
 })
 ```
 
+### Configuration Options
+
+**CobblAdminClient:**
+
+| Option    | Type   | Required | Default                | Description          |
+| --------- | ------ | -------- | ---------------------- | -------------------- |
+| `apiKey`  | string | Yes      | -                      | Your Cobbl API key   |
+| `baseUrl` | string | No       | `https://api.cobbl.ai` | Base URL for the API |
+
+**CobblPublicClient:**
+
+| Option    | Type   | Required | Default                | Description                                       |
+| --------- | ------ | -------- | ---------------------- | ------------------------------------------------- |
+| `baseUrl` | string | No       | `https://api.cobbl.ai` | Base URL for the API (no authentication required) |
+
 ### Environment Variables
 
 We recommend storing your API key in environment variables:
 
 ```bash
 # .env
-PROMPTI_API_KEY=your_api_key_here
+COBBL_API_KEY=your_api_key_here
 ```
 
 Then load it in your application:
 
 ```typescript
-const client = new CobblClient({
-  apiKey: process.env.PROMPTI_API_KEY,
+const adminClient = new CobblAdminClient({
+  apiKey: process.env.COBBL_API_KEY,
 })
 ```
 
 ## API Reference
 
-### `runPrompt(promptSlug, input)`
+### CobblAdminClient
+
+#### `runPrompt(promptSlug, input)`
 
 Execute a prompt with the given input variables.
 
@@ -129,7 +203,7 @@ Execute a prompt with the given input variables.
 **Example:**
 
 ```typescript
-const result = await client.runPrompt('customer_email', {
+const result = await adminClient.runPrompt('customer_email', {
   customerName: 'John Doe',
   issue: 'login_problem',
   urgency: 'high',
@@ -139,24 +213,30 @@ console.log(result.output)
 // => "Dear John Doe, We understand you're experiencing login issues..."
 ```
 
-### `submitFeedback(feedback)`
+### CobblPublicClient
+
+The public client is designed for end-user feedback submission and **does not require authentication**. This makes it safe to use in client-side applications like React, Vue, or vanilla JavaScript.
 
-Submit user feedback for a prompt run.
+#### `createFeedback(feedback)`
+
+Create user feedback for a prompt run.
 
 **Parameters:**
 
-- `feedback` (FeedbackSubmission):
+- `feedback` (CreateFeedbackRequest):
   - `runId` (string): The run ID from a previous `runPrompt` call
-  - `helpful` ('helpful' | 'not_helpful'): Whether the output was helpful
-  - `userFeedback` (string): Detailed feedback message
+  - `helpful` ('helpful' | 'not_helpful'): Whether the output was helpful (optional)
+  - `userFeedback` (string): Detailed feedback message (optional)
+
+At least one of `helpful` or `userFeedback` is required.
 
-**Returns:** `Promise<SubmitFeedbackResponse>`
+**Returns:** `Promise<CreateFeedbackResponse>`
 
 **Response:**
 
 ```typescript
 {
-  feedbackId: string // Unique ID for the feedback item
+  id: string // Unique ID for the feedback item
   message: string // Success message
 }
 ```
@@ -164,13 +244,41 @@ Submit user feedback for a prompt run.
 **Example:**
 
 ```typescript
-await client.submitFeedback({
+await publicClient.createFeedback({
   runId: result.runId,
   helpful: 'not_helpful',
   userFeedback: 'The tone was too casual for a professional email',
 })
 ```
 
+#### `updateFeedback(id, update)`
+
+Update existing feedback with additional data.
+
+**Parameters:**
+
+- `id` (string): The feedback ID from `createFeedback`
+- `update` (UpdateFeedbackRequest):
+  - `helpful` ('helpful' | 'not_helpful'): Whether the output was helpful (optional)
+  - `userFeedback` (string): Detailed feedback message (optional)
+
+**Returns:** `Promise<UpdateFeedbackResponse>`
+
+**Example:**
+
+```typescript
+// First create feedback with just a rating
+const { id } = await publicClient.createFeedback({
+  runId: result.runId,
+  helpful: 'not_helpful',
+})
+
+// Later update with detailed feedback
+await publicClient.updateFeedback(id, {
+  userFeedback: 'The response was too verbose and missed key points.',
+})
+```
+
 ## Advanced Usage
 
 ### Error Handling
@@ -178,10 +286,10 @@ await client.submitFeedback({
 The SDK throws `CobblError` for all error cases. You can catch and handle these errors:
 
 ```typescript
-import { CobblClient, CobblError } from '@cobbl-ai/sdk'
+import { CobblAdminClient, CobblError } from '@cobbl-ai/sdk/admin'
 
 try {
-  const result = await client.runPrompt('my-prompt', { topic: 'test' })
+  const result = await adminClient.runPrompt('my-prompt', { topic: 'test' })
 } catch (error) {
   if (error instanceof CobblError) {
     console.error(`Error [${error.code}]: ${error.message}`)
@@ -191,9 +299,15 @@ try {
       case 'UNAUTHORIZED':
         console.error('Invalid API key')
         break
+      case 'FORBIDDEN':
+        console.error('Prompt is disabled or forbidden')
+        break
       case 'NOT_FOUND':
         console.error('Prompt not found')
         break
+      case 'ARCHIVED':
+        console.error('Prompt has been archived')
+        break
       case 'INVALID_REQUEST':
         console.error('Invalid request:', error.details)
         break
@@ -214,7 +328,9 @@ try {
 - `INVALID_CONFIG` - Invalid SDK configuration
 - `INVALID_REQUEST` - Malformed request (e.g., missing required fields)
 - `UNAUTHORIZED` - Invalid or missing API key
+- `FORBIDDEN` - Prompt is disabled or access is forbidden
 - `NOT_FOUND` - Resource not found (e.g., prompt doesn't exist)
+- `ARCHIVED` - Prompt has been archived and is no longer available
 - `RATE_LIMIT_EXCEEDED` - Too many requests
 - `SERVER_ERROR` - Server-side error
 - `NETWORK_ERROR` - Network connectivity issue
@@ -228,7 +344,7 @@ The SDK is written in TypeScript and includes full type definitions:
 import type {
   PromptInput,
   RunPromptResponse,
-  FeedbackSubmission,
+  CreateFeedbackRequest,
   TokenUsage,
 } from '@cobbl-ai/sdk'
 
@@ -239,7 +355,10 @@ const input: PromptInput = {
 }
 
 // Type-safe response handling
-const result: RunPromptResponse = await client.runPrompt('blog_post', input)
+const result: RunPromptResponse = await adminClient.runPrompt(
+  'blog_post',
+  input
+)
 
 // Access token usage
 const tokens: TokenUsage = result.tokenUsage
@@ -252,16 +371,20 @@ console.log(`Used ${tokens.totalTokens} tokens`)
 
 ```typescript
 import express from 'express'
-import { CobblClient } from '@cobbl-ai/sdk'
+import { CobblAdminClient } from '@cobbl-ai/sdk/admin'
+import { CobblPublicClient } from '@cobbl-ai/sdk/public'
 
 const app = express()
-const cobbl = new CobblClient({
-  apiKey: process.env.PROMPTI_API_KEY,
+const adminClient = new CobblAdminClient({
+  apiKey: process.env.COBBL_API_KEY,
+})
+const publicClient = new CobblPublicClient({
+  apiKey: process.env.COBBL_API_KEY,
 })
 
 app.post('/api/generate', async (req, res) => {
   try {
-    const result = await cobbl.runPrompt('content_generator', req.body)
+    const result = await adminClient.runPrompt('content_generator', req.body)
     res.json({
       output: result.output,
       runId: result.runId,
@@ -273,10 +396,10 @@ app.post('/api/generate', async (req, res) => {
 
 app.post('/api/feedback', async (req, res) => {
   try {
-    await cobbl.submitFeedback(req.body)
+    await publicClient.createFeedback(req.body)
     res.json({ success: true })
   } catch (error) {
-    res.status(500).json({ error: 'Failed to submit feedback' })
+    res.status(500).json({ error: 'Failed to create feedback' })
   }
 })
 ```
@@ -285,18 +408,18 @@ app.post('/api/feedback', async (req, res) => {
 
 ```typescript
 // app/api/generate/route.ts
-import { CobblClient } from '@cobbl-ai/sdk'
+import { CobblAdminClient } from '@cobbl-ai/sdk/admin'
 import { NextResponse } from 'next/server'
 
-const cobbl = new CobblClient({
-  apiKey: process.env.PROMPTI_API_KEY!,
+const adminClient = new CobblAdminClient({
+  apiKey: process.env.COBBL_API_KEY!,
 })
 
 export async function POST(request: Request) {
   const body = await request.json()
 
   try {
-    const result = await cobbl.runPrompt('summarizer', {
+    const result = await adminClient.runPrompt('summarizer', {
       text: body.text,
       length: 'short',
     })
@@ -311,7 +434,7 @@ export async function POST(request: Request) {
 }
 ```
 
-#### React Component (Client-Side via API)
+#### React (Client-Side via API)
 
 ```typescript
 'use client'
@@ -382,7 +505,7 @@ Always save the `runId` returned from `runPrompt()` so users can provide feedbac
 
 ```typescript
 // Store in database with your application data
-const result = await client.runPrompt('recommendation', { userId: '123' })
+const result = await adminClient.runPrompt('recommendation', { userId: '123' })
 
 await db.recommendations.create({
   userId: '123',
@@ -397,7 +520,7 @@ Always wrap SDK calls in try-catch blocks and provide fallback behavior:
 
 ```typescript
 try {
-  const result = await client.runPrompt('greeting', { name: userName })
+  const result = await adminClient.runPrompt('greeting', { name: userName })
   return result.output
 } catch (error) {
   // Log for debugging
@@ -413,8 +536,8 @@ try {
 Use different API keys for development, staging, and production:
 
 ```typescript
-const client = new CobblClient({
-  apiKey: process.env.PROMPTI_API_KEY,
+const adminClient = new CobblAdminClient({
+  apiKey: process.env.COBBL_API_KEY,
 })
 ```
 
@@ -456,18 +579,21 @@ pnpm clean
 ```
 sdk/
 ├── src/
-│   ├── client.ts       # Main SDK client
+│   ├── admin.ts        # Admin API client
+│   ├── public.ts       # Public API client
+│   ├── browser.ts      # Browser entry point (CDN/script tag)
 │   ├── errors.ts       # Error classes
 │   ├── types.ts        # Type definitions
-│   ├── shared-types.ts # Inlined types from shared package
 │   └── index.ts        # Public exports
 ├── dist/               # Compiled output (created by build)
-│   ├── index.js        # CommonJS bundle
-│   ├── index.mjs       # ES modules bundle
-│   ├── index.d.ts      # TypeScript declarations (CJS)
-│   ├── index.d.mts     # TypeScript declarations (ESM)
-│   └── *.map           # Source maps
-├── examples/           # Usage examples
+│   ├── index.js        # CommonJS bundle (main)
+│   ├── index.mjs       # ES modules bundle (main)
+│   ├── admin.js        # CommonJS bundle (admin)
+│   ├── admin.mjs       # ES modules bundle (admin)
+│   ├── public.js       # CommonJS bundle (public)
+│   ├── public.mjs      # ES modules bundle (public)
+│   ├── cobbl-sdk.global.js  # IIFE bundle for CDN/script tag
+│   └── *.d.ts          # TypeScript declarations
 ├── tsup.config.ts      # Build configuration
 ├── package.json
 └── README.md
@@ -494,8 +620,7 @@ Before publishing, make sure to:
 ```bash
 # Test the package locally
 pnpm pack
-# This creates cobbl-ai
--sdk-0.1.0.tgz that you can test
+# This creates @cobbl-ai-sdk-0.1.0.tgz that you can test
 
 # Publish to npm (requires npm login)
 pnpm publish --access public
@@ -507,9 +632,8 @@ pnpm publish --tag beta --access public
 ## Support
 
 - 📧 Email: support@cobbl.ai
-- 🐛 Issues: [GitHub Issues](https://github.com/your-org/cobbl-ai/issues)
+- 🐛 Issues: [GitHub Issues](https://github.com/cobbl-ai/sdk/issues)
 - 📚 Documentation: [docs.cobbl.ai](https://docs.cobbl.ai)
-- 💬 Discord: [Join our community](https://discord.gg/cobbl)
 
 ## License
 

package/dist/admin.d.mts

@@ -0,0 +1,90 @@
+import { b as CobblConfig, P as PromptInput, c as RunPromptResponse } from './errors-BaYZ2rGo.mjs';
+export { C as CobblError, a as CobblErrorCode, g as PromptVersionClient, h as Provider, R as RunPromptRequest, T as TokenUsage, V as VariableConfig } from './errors-BaYZ2rGo.mjs';
+
+/**
+ * Cobbl SDK - Admin API Client
+ *
+ * A client for admin/server-side operations like running prompts.
+ * Use this in server-side contexts where you need to execute prompts.
+ *
+ * @example
+ * ```typescript
+ * import { CobblAdminClient } from '@cobbl-ai/sdk/admin'
+ *
+ * const client = new CobblAdminClient({
+ *   apiKey: process.env.COBBL_API_KEY
+ * })
+ *
+ * // Run a prompt
+ * const result = await client.runPrompt('sales_summary', {
+ *   topic: 'Q4 Results',
+ *   tone: 'friendly'
+ * })
+ *
+ * console.log(result.output)
+ * console.log(result.runId) // Use this to link feedback later
+ * ```
+ */
+
+/**
+ * Admin API Client for Cobbl
+ *
+ * Provides methods to run prompts via the admin API.
+ * This client is suitable for use in server-side contexts.
+ */
+declare class CobblAdminClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /**
+     * Initialize the Cobbl Admin SDK client
+     *
+     * @param config - Configuration object
+     * @param config.apiKey - Your Cobbl API key
+     * @param config.baseUrl - Optional base URL for the API (defaults to 'https://api.cobbl.ai')
+     *
+     * @example Production (uses default URL)
+     * ```typescript
+     * const client = new CobblAdminClient({
+     *   apiKey: process.env.COBBL_API_KEY
+     * })
+     * ```
+     *
+     * @example Local development with Firebase emulators
+     * ```typescript
+     * const client = new CobblAdminClient({
+     *   apiKey: process.env.COBBL_API_KEY,
+     *   baseUrl: 'http://localhost:5001/your-project-id/us-central1/externalApi'
+     * })
+     * ```
+     */
+    constructor(config: CobblConfig);
+    /**
+     * 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
+     * ```
+     */
+    runPrompt(promptSlug: string, input: PromptInput): Promise<RunPromptResponse>;
+    /**
+     * Make an HTTP request to the Cobbl API
+     * @private
+     */
+    private makeRequest;
+}
+
+export { CobblAdminClient, CobblConfig, PromptInput, RunPromptResponse };

package/dist/admin.d.ts

@@ -0,0 +1,90 @@
+import { b as CobblConfig, P as PromptInput, c as RunPromptResponse } from './errors-BaYZ2rGo.js';
+export { C as CobblError, a as CobblErrorCode, g as PromptVersionClient, h as Provider, R as RunPromptRequest, T as TokenUsage, V as VariableConfig } from './errors-BaYZ2rGo.js';
+
+/**
+ * Cobbl SDK - Admin API Client
+ *
+ * A client for admin/server-side operations like running prompts.
+ * Use this in server-side contexts where you need to execute prompts.
+ *
+ * @example
+ * ```typescript
+ * import { CobblAdminClient } from '@cobbl-ai/sdk/admin'
+ *
+ * const client = new CobblAdminClient({
+ *   apiKey: process.env.COBBL_API_KEY
+ * })
+ *
+ * // Run a prompt
+ * const result = await client.runPrompt('sales_summary', {
+ *   topic: 'Q4 Results',
+ *   tone: 'friendly'
+ * })
+ *
+ * console.log(result.output)
+ * console.log(result.runId) // Use this to link feedback later
+ * ```
+ */
+
+/**
+ * Admin API Client for Cobbl
+ *
+ * Provides methods to run prompts via the admin API.
+ * This client is suitable for use in server-side contexts.
+ */
+declare class CobblAdminClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /**
+     * Initialize the Cobbl Admin SDK client
+     *
+     * @param config - Configuration object
+     * @param config.apiKey - Your Cobbl API key
+     * @param config.baseUrl - Optional base URL for the API (defaults to 'https://api.cobbl.ai')
+     *
+     * @example Production (uses default URL)
+     * ```typescript
+     * const client = new CobblAdminClient({
+     *   apiKey: process.env.COBBL_API_KEY
+     * })
+     * ```
+     *
+     * @example Local development with Firebase emulators
+     * ```typescript
+     * const client = new CobblAdminClient({
+     *   apiKey: process.env.COBBL_API_KEY,
+     *   baseUrl: 'http://localhost:5001/your-project-id/us-central1/externalApi'
+     * })
+     * ```
+     */
+    constructor(config: CobblConfig);
+    /**
+     * 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
+     * ```
+     */
+    runPrompt(promptSlug: string, input: PromptInput): Promise<RunPromptResponse>;
+    /**
+     * Make an HTTP request to the Cobbl API
+     * @private
+     */
+    private makeRequest;
+}
+
+export { CobblAdminClient, CobblConfig, PromptInput, RunPromptResponse };