@kookee/sdk 0.0.30 → 0.0.31

package/README.md

@@ -4,7 +4,7 @@ Official TypeScript SDK for [Kookee](https://kookee.dev) - the headless CMS for
 
 ## Features
 
-- **Lightweight** - Only ~1.5 KB minified (ESM), no bloat
+- **Lightweight** - Only ~6.41 KB KB minified (ESM), no bloat
 - **Zero dependencies** - Uses native `fetch`, nothing else
 - **TypeScript-first** - Full type definitions out of the box
 - **Tree-shakeable** - Import only what you need
@@ -36,6 +36,14 @@ const posts = await kookee.blog.list({ limit: 10 });
 const post = await kookee.blog.getBySlug('hello-world');
 ```
 
+## Configuration
+
+```typescript
+const kookee = new Kookee({
+  apiKey: 'your-api-key',
+});
+```
+
 ## Blog
 
 ```typescript
@@ -61,7 +69,8 @@ const tags = await kookee.blog.getTags();
 await kookee.blog.react('post-id', { reactionType: 'heart', action: 'add' });
 
 // Get translations
-const translations = await kookee.blog.getTranslationsBySlug('my-post');
+const translationsBySlug = await kookee.blog.getTranslationsBySlug('my-post');
+const translationsById = await kookee.blog.getTranslationsById('post-uuid');
 ```
 
 ## Help Center
@@ -84,21 +93,31 @@ const article = await kookee.help.getBySlug('getting-started');
 const articleById = await kookee.help.getById('article-uuid');
 
 // Get article translations
-const translations = await kookee.help.getTranslationsBySlug('getting-started');
+const translationsBySlug = await kookee.help.getTranslationsBySlug('getting-started');
+const translationsById = await kookee.help.getTranslationsById('article-uuid');
 
 // AI-powered chat
 const response = await kookee.help.chat({
   messages: [{ role: 'user', content: 'How do I reset my password?' }],
+  sessionId: 'optional-session-id', // maintain conversation context across calls
 });
 
 // Streaming chat
 for await (const chunk of kookee.help.chatStream({ messages })) {
   if (chunk.type === 'delta') console.log(chunk.content);
   if (chunk.type === 'sources') console.log('Sources:', chunk.sources);
+  if (chunk.type === 'done') console.log('Stream finished');
+  if (chunk.type === 'error') console.error(chunk.message);
 }
 
 // Vote on article usefulness
 await kookee.help.voteUsefulness('article-id', 'yes');
+
+// Change a previous vote
+await kookee.help.voteUsefulness('article-id', 'no', 'yes');
+
+// Remove a vote
+await kookee.help.voteUsefulness('article-id', null, 'yes');
 ```
 
 ## Changelog
@@ -110,6 +129,9 @@ const entries = await kookee.changelog.list({ page: 1, limit: 10 });
 // Filter by type: 'feature' | 'fix' | 'improvement' | 'breaking' | 'security' | 'deprecated' | 'other'
 const fixes = await kookee.changelog.list({ type: 'fix' });
 
+// Search entries
+const results = await kookee.changelog.list({ search: 'authentication' });
+
 // Order by version or date
 const sorted = await kookee.changelog.list({ orderBy: 'version', order: 'desc' });
 
@@ -118,7 +140,8 @@ const entry = await kookee.changelog.getBySlug('v1-0-0');
 const entryById = await kookee.changelog.getById('entry-uuid');
 
 // Get translations
-const translations = await kookee.changelog.getTranslationsBySlug('v1-0-0');
+const translationsBySlug = await kookee.changelog.getTranslationsBySlug('v1-0-0');
+const translationsById = await kookee.changelog.getTranslationsById('entry-uuid');
 
 // React to an entry
 await kookee.changelog.react('entry-id', { reactionType: 'fire', action: 'add' });
@@ -133,6 +156,9 @@ const announcements = await kookee.announcements.list({ page: 1, limit: 10 });
 // Filter by type: 'info' | 'warning' | 'critical' | 'promotion' | 'maintenance' | 'newFeature'
 const critical = await kookee.announcements.list({ type: 'critical' });
 
+// Order announcements
+const sorted = await kookee.announcements.list({ orderBy: 'publishedAt', order: 'desc' });
+
 // Exclude already-seen announcements
 const unseen = await kookee.announcements.list({ excludeIds: ['id1', 'id2'] });
 
@@ -157,11 +183,14 @@ const page = await kookee.pages.getBySlug('privacy-policy');
 const pageById = await kookee.pages.getById('page-uuid');
 
 // Get translations
-const translations = await kookee.pages.getTranslationsBySlug('privacy-policy');
+const translationsBySlug = await kookee.pages.getTranslationsBySlug('privacy-policy');
+const translationsById = await kookee.pages.getTranslationsById('page-uuid');
 ```
 
 ## Feedback
 
+### Reading feedback
+
 ```typescript
 // List feedback posts
 const posts = await kookee.feedback.list({ page: 1, limit: 10 });
@@ -175,6 +204,9 @@ const bugs = await kookee.feedback.list({ category: 'bug' });
 // Sort options: 'newest' | 'top' | 'trending'
 const trending = await kookee.feedback.list({ sort: 'trending' });
 
+// Search posts
+const results = await kookee.feedback.list({ search: 'dark mode' });
+
 // Get single post with comments
 const post = await kookee.feedback.getById('post-uuid');
 
@@ -185,6 +217,52 @@ await kookee.feedback.vote('post-id', { action: 'upvote' });
 const contributors = await kookee.feedback.getTopContributors({ limit: 10 });
 ```
 
+### Creating and managing feedback
+
+These operations require an `ExternalUser` to identify the author:
+
+```typescript
+import type { ExternalUser } from '@kookee/sdk';
+
+const user: ExternalUser = {
+  externalId: 'user-123',    // your system's user ID
+  name: 'Jane Doe',
+  email: 'jane@example.com', // optional
+  avatarUrl: 'https://...',  // optional
+};
+
+// Create a feedback post
+const newPost = await kookee.feedback.createPost({
+  title: 'Add dark mode',
+  description: 'It would be great to have a dark mode option.',
+  category: 'feature', // optional: 'feature' | 'improvement' | 'bug' | 'other'
+  externalUser: user,
+});
+
+// Add a comment to a post
+const comment = await kookee.feedback.createComment('post-id', {
+  content: 'Great idea, I would love this too!',
+  externalUser: user,
+});
+
+// List posts created by a specific user
+const myPosts = await kookee.feedback.listMyPosts({
+  externalId: 'user-123',
+  page: 1,
+  limit: 10,
+  status: 'open',      // optional filter
+  category: 'feature',  // optional filter
+  search: 'dark mode',  // optional search
+  sort: 'newest',       // optional sort
+});
+
+// Delete a post (only the author can delete)
+await kookee.feedback.deletePost('post-id', { externalId: 'user-123' });
+
+// Delete a comment (only the author can delete)
+await kookee.feedback.deleteComment('comment-id', { externalId: 'user-123' });
+```
+
 ## Config
 
 ```typescript
@@ -195,6 +273,13 @@ const config = await kookee.config.getByKey('feature_flags');
 const configs = await kookee.config.list({ keys: ['feature_flags', 'theme'] });
 ```
 
+## Health Check
+
+```typescript
+const health = await kookee.health();
+// { status: 'ok', projectId: '...', timestamp: '...' }
+```
+
 ## Reactions
 
 Blog posts and changelog entries support reactions:
@@ -219,6 +304,13 @@ const posts = await kookee.blog.list({ locale: 'de' });
 const post = await kookee.blog.getBySlug('hello-world', { locale: 'de', fallback: true });
 ```
 
+Translation endpoints return a `Record<string, T>` keyed by locale code:
+
+```typescript
+const translations = await kookee.blog.getTranslationsBySlug('hello-world');
+// { en: BlogPost, de: BlogPost, fr: BlogPost, ... }
+```
+
 ## Paginated Response
 
 All list endpoints return a paginated response:
@@ -249,21 +341,57 @@ try {
 }
 ```
 
-## Configuration
+## Code Block Styles
+
+The SDK ships an optional CSS file for styling code blocks in content HTML (VS Code Dark+ theme):
 
 ```typescript
-const kookee = new Kookee({
-  apiKey: 'your-api-key',
-  baseUrl: 'https://api.kookee.dev', // optional, defaults to production API
-});
+import '@kookee/sdk/styles/code.css';
 ```
 
+Or via CDN:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@kookee/sdk/styles/code.css">
+```
+
+This provides:
+- Syntax-highlighted code blocks with a dark theme
+- Copy-to-clipboard button styling
+- Language label display
+- Inline code styling (red on pink background)
+
 ## TypeScript
 
 The SDK is written in TypeScript and provides full type definitions:
 
 ```typescript
-import type { BlogPost, BlogPostListItem, BlogTag, PaginatedResponse } from '@kookee/sdk';
+import type {
+  BlogPost,
+  BlogPostListItem,
+  BlogTag,
+  BlogTagWithCount,
+  Page,
+  PageListItem,
+  HelpArticle,
+  HelpArticleListItem,
+  HelpCategory,
+  HelpSearchResult,
+  HelpChatResponse,
+  HelpChatStreamChunk,
+  ChangelogEntry,
+  ChangelogEntryListItem,
+  Announcement,
+  AnnouncementListItem,
+  FeedbackPost,
+  FeedbackPostListItem,
+  FeedbackComment,
+  FeedbackTopContributor,
+  ExternalUser,
+  PublicConfig,
+  PaginatedResponse,
+  KookeeConfig,
+} from '@kookee/sdk';
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kookee/sdk",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "description": "Official Kookee SDK - Access your blog, changelog, help center, and more",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",