@kookee/sdk 0.0.37 → 0.0.39

package/README.md

@@ -4,7 +4,7 @@ Official TypeScript SDK for [Kookee](https://kookee.dev) - the headless CMS for
 
 ## Features
 
-- **Lightweight** - Only ~6.41 KB KB minified (ESM), no bloat
+- **Lightweight** - Small minified footprint (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
@@ -408,7 +408,27 @@ const post = await kookee.blog.getBySlug('hello-world');
 renderFull(post.contentHtml); // ✅ available on detail
 ```
 
-Entries also expose `categoryId: string | null` — there is **no nested `category` object** on any entry response. If you need category metadata (name, slug, icon), fetch it separately via `kookee.help.categories()` (or the equivalent list) and join by `categoryId` on the client.
+## Categories on entries
+
+Every entry response (list *and* detail) includes both `categoryId: string | null` **and** a resolved `category: EntryCategoryRef | null`. No client-side join required:
+
+```typescript
+const results = await kookee.help.search({ query: 'how to reset password' });
+for (const result of results) {
+  // result.category is already populated by the server
+  console.log(result.title, '→', result.category?.name);
+}
+
+type EntryCategoryRef = {
+  id: string;
+  slug: string;
+  name: string;
+  icon: string | null;
+  description: string | null;
+};
+```
+
+When an entry has no category assigned, `category` is `null` and `categoryId` is `null` — guard accordingly.
 
 ## Error Handling
 
@@ -460,6 +480,7 @@ import type {
   EntryTag,
   EntryTagWithCount,
   EntryCategory,
+  EntryCategoryRef,
   EntryComment,
   EntryTranslationSummary,
   EntryTranslationsMap,
@@ -538,6 +559,7 @@ import type {
   ReactResponse,
 
   // Common
+  ApiError,
   PublicConfig,
   PaginatedResponse,
   PaginationParams,
@@ -545,19 +567,41 @@ import type {
   OrderDirection,
   KookeeConfig,
   HealthCheckResponse,
+
+  // Module request parameter shapes
+  EntriesListParams,
+  EntriesGetByIdParams,
+  EntriesGetBySlugParams,
+  EntriesGetCommentsParams,
+  EntriesGetCategoriesParams,
+  BlogListParams,
+  BlogGetBySlugParams,
+  BlogGetByIdParams,
+  BlogGetCommentsParams,
+  HelpCategoriesParams,
+  HelpListParams,
+  HelpSearchParams,
+  HelpGetBySlugParams,
+  HelpGetByIdParams,
+  HelpGetCommentsParams,
+  ChangelogListParams,
+  ChangelogGetBySlugParams,
+  ChangelogGetByIdParams,
+  ChangelogGetCommentsParams,
+  PagesListParams,
+  PagesGetBySlugParams,
+  PagesGetByIdParams,
+  PagesGetCommentsParams,
+  AnnouncementListParams,
+  AnnouncementGetByIdParams,
+  AnnouncementGetCommentsParams,
+  ConfigListParams,
+  FeedbackListParams,
+  FeedbackVoteParams,
+  FeedbackTopContributorsParams,
 } from '@kookee/sdk';
 ```
 
-### Breaking type changes from 0.0.36
-
-Version 0.0.37 aligns the SDK types with the real server response shapes. The old types lied about three things and crashed at runtime. If you're upgrading, note:
-
-- **`BlogEntry`, `HelpArticleEntry`, `ChangelogEntry`, `PageEntry`, `AnnouncementEntry`, `GenericEntry`, `TypedEntry`, `AnyEntry` are gone.** Each one was split into a `*ListItem` (for list/search responses) and a `*Detail` (for single-entry responses). The compiler will now stop you from accessing `contentHtml` on a list item — it was never returned by the server there, and reading it crashed.
-- **`BaseEntry.category` is gone.** The server never returned a nested `{ name, slug }` object; only `categoryId: string | null`. Join against `kookee.help.categories()` (or the equivalent) on the client if you need the full category.
-- **`HelpSearchResult` is now an alias of `HelpArticleListItem`.** The fictional `matchedChunk` field is gone (the server never returned it). Same category rule as above.
-- **`PaginatedResponse<T>.offset` is gone.** Entry list endpoints never returned it; use `page` instead.
-- **Translation endpoints now return `EntryTranslationsMap`** (`{ id, slug, locale, title }` keyed by locale), not a full entry map. Fetch the full body with `getBySlug` / `getById` when needed.
-
 ## License
 
 MIT

package/dist/index.d.cts

@@ -28,7 +28,6 @@ interface PublicConfig {
 }
 interface HealthCheckResponse {
     status: 'ok';
-    projectId: string;
     timestamp: string;
 }
 type ReactionType = 'fire' | 'heart' | 'rocket' | 'eyes' | 'mindblown';
@@ -63,7 +62,7 @@ interface HelpChatSource {
     slug: string | null;
     title: string;
     visibility: string | null;
-    metadata: Record<string, NonNullable<unknown>> | null;
+    metadata: Record<string, unknown> | null;
     category: HelpChatSourceCategory | null;
 }
 type HelpChatStreamChunk = {
@@ -205,12 +204,15 @@ type AnnouncementType = 'info' | 'warning' | 'critical' | 'promotion' | 'mainten
 /**
  * Author shape returned on public entry responses.
  *
- * NOTE: `name` and `image` can be `null` on the server side.
+ * NOTE: `name` and `image` can be `null` on the server side. `isTeamMember`
+ * is only populated on comment responses (where the server can tell whether
+ * the commenter is a project member) — it is not set on entry author fields.
  */
 interface EntryAuthor {
     id: string;
     name: string | null;
     image: string | null;
+    isTeamMember?: boolean;
 }
 interface EntryTag {
     id: string;
@@ -236,6 +238,19 @@ interface EntryComment {
     updatedAt: string;
     author: EntryAuthor;
 }
+/**
+ * Resolved category attached to a public entry response.
+ *
+ * This is the server's `EntryCategory` row projected down to the fields
+ * that are safe/useful to expose publicly.
+ */
+interface EntryCategoryRef {
+    id: string;
+    slug: string;
+    name: string;
+    icon: string | null;
+    description: string | null;
+}
 /**
  * Fields that appear on BOTH list and detail entry responses.
  */
@@ -249,12 +264,13 @@ interface BaseEntry {
     locale: string;
     translationGroupId: string;
     categoryId: string | null;
+    category: EntryCategoryRef | null;
     coverImageUrl: string | null;
     position: number;
     views: number;
     metaTitle: string | null;
     metaDescription: string | null;
-    metadata: Record<string, NonNullable<unknown>> | null;
+    metadata: Record<string, unknown> | null;
     reactions: Record<string, number>;
     createdAt: string;
     updatedAt: string;
@@ -585,4 +601,4 @@ declare class Kookee {
     health(): Promise<HealthCheckResponse>;
 }
 
-export { type AnnouncementDetail, type AnnouncementGetByIdParams, type AnnouncementGetCommentsParams, type AnnouncementListItem, type AnnouncementListParams, AnnouncementModule, type AnnouncementType, type AnnouncementTypeSpecific, type AnyEntryDetail, type AnyEntryListItem, type ApiError, type BaseEntry, type BlogEntryDetail, type BlogEntryListItem, type BlogGetByIdParams, type BlogGetBySlugParams, type BlogGetCommentsParams, type BlogListParams, BlogModule, type BlogTypeSpecific, type ChangelogEntryDetail, type ChangelogEntryListItem, type ChangelogGetByIdParams, type ChangelogGetBySlugParams, type ChangelogGetCommentsParams, type ChangelogListParams, ChangelogModule, type ChangelogType, type ChangelogTypeSpecific, type ConfigListParams, ConfigModule, type CreateFeedbackCommentParams, type CreateFeedbackPostParams, type CreatedFeedbackComment, type CreatedFeedbackPost, type DeleteFeedbackCommentParams, type DeleteFeedbackCommentResponse, type DeleteFeedbackPostParams, type DeleteFeedbackPostResponse, type EntriesGetByIdParams, type EntriesGetBySlugParams, type EntriesGetCategoriesParams, type EntriesGetCommentsParams, type EntriesListParams, EntriesModule, type EntryAuthor, type EntryCategory, type EntryComment, type EntryDetailFields, type EntryStatus, type EntryTag, type EntryTagWithCount, type EntryTranslationSummary, type EntryTranslationsMap, type EntryType, type ExternalUser, type FeedbackAssignee, type FeedbackAuthor, type FeedbackColumnType, type FeedbackComment, type FeedbackKanbanColumn, type FeedbackListParams, FeedbackModule, type FeedbackPost, type FeedbackPostCategory, type FeedbackPostListItem, type FeedbackSortOption, type FeedbackTopContributor, type FeedbackTopContributorsParams, type FeedbackVoteParams, type FeedbackVoteResponse, type GenericEntryDetail, type GenericEntryListItem, type HealthCheckResponse, type HelpArticleDetail, type HelpArticleListItem, type HelpArticleTypeSpecific, type HelpArticleVisibility, type HelpCategoriesParams, type HelpChatMessage, type HelpChatParams, type HelpChatResponse, type HelpChatSource, type HelpChatSourceCategory, type HelpChatStreamChunk, type HelpGetByIdParams, type HelpGetBySlugParams, type HelpGetCommentsParams, type HelpListParams, HelpModule, type HelpSearchParams, type HelpSearchResult, Kookee, KookeeApiError, type KookeeConfig, type KookeeUser, type ListMyFeedbackPostsParams, type LocaleOptions, type OrderDirection, type PageEntryDetail, type PageEntryListItem, type PageTypeSpecific, type PagesGetByIdParams, type PagesGetBySlugParams, type PagesGetCommentsParams, type PagesListParams, PagesModule, type PaginatedResponse, type PaginationParams, type PublicConfig, type ReactParams, type ReactResponse, type ReactionType, type TypeSpecific, type TypedEntryDetail, type TypedEntryListItem };
+export { type AnnouncementDetail, type AnnouncementGetByIdParams, type AnnouncementGetCommentsParams, type AnnouncementListItem, type AnnouncementListParams, AnnouncementModule, type AnnouncementType, type AnnouncementTypeSpecific, type AnyEntryDetail, type AnyEntryListItem, type ApiError, type BaseEntry, type BlogEntryDetail, type BlogEntryListItem, type BlogGetByIdParams, type BlogGetBySlugParams, type BlogGetCommentsParams, type BlogListParams, BlogModule, type BlogTypeSpecific, type ChangelogEntryDetail, type ChangelogEntryListItem, type ChangelogGetByIdParams, type ChangelogGetBySlugParams, type ChangelogGetCommentsParams, type ChangelogListParams, ChangelogModule, type ChangelogType, type ChangelogTypeSpecific, type ConfigListParams, ConfigModule, type CreateFeedbackCommentParams, type CreateFeedbackPostParams, type CreatedFeedbackComment, type CreatedFeedbackPost, type DeleteFeedbackCommentParams, type DeleteFeedbackCommentResponse, type DeleteFeedbackPostParams, type DeleteFeedbackPostResponse, type EntriesGetByIdParams, type EntriesGetBySlugParams, type EntriesGetCategoriesParams, type EntriesGetCommentsParams, type EntriesListParams, EntriesModule, type EntryAuthor, type EntryCategory, type EntryCategoryRef, type EntryComment, type EntryDetailFields, type EntryStatus, type EntryTag, type EntryTagWithCount, type EntryTranslationSummary, type EntryTranslationsMap, type EntryType, type ExternalUser, type FeedbackAssignee, type FeedbackAuthor, type FeedbackColumnType, type FeedbackComment, type FeedbackKanbanColumn, type FeedbackListParams, FeedbackModule, type FeedbackPost, type FeedbackPostCategory, type FeedbackPostListItem, type FeedbackSortOption, type FeedbackTopContributor, type FeedbackTopContributorsParams, type FeedbackVoteParams, type FeedbackVoteResponse, type GenericEntryDetail, type GenericEntryListItem, type HealthCheckResponse, type HelpArticleDetail, type HelpArticleListItem, type HelpArticleTypeSpecific, type HelpArticleVisibility, type HelpCategoriesParams, type HelpChatMessage, type HelpChatParams, type HelpChatResponse, type HelpChatSource, type HelpChatSourceCategory, type HelpChatStreamChunk, type HelpGetByIdParams, type HelpGetBySlugParams, type HelpGetCommentsParams, type HelpListParams, HelpModule, type HelpSearchParams, type HelpSearchResult, Kookee, KookeeApiError, type KookeeConfig, type KookeeUser, type ListMyFeedbackPostsParams, type LocaleOptions, type OrderDirection, type PageEntryDetail, type PageEntryListItem, type PageTypeSpecific, type PagesGetByIdParams, type PagesGetBySlugParams, type PagesGetCommentsParams, type PagesListParams, PagesModule, type PaginatedResponse, type PaginationParams, type PublicConfig, type ReactParams, type ReactResponse, type ReactionType, type TypeSpecific, type TypedEntryDetail, type TypedEntryListItem };

package/dist/index.d.ts

@@ -28,7 +28,6 @@ interface PublicConfig {
 }
 interface HealthCheckResponse {
     status: 'ok';
-    projectId: string;
     timestamp: string;
 }
 type ReactionType = 'fire' | 'heart' | 'rocket' | 'eyes' | 'mindblown';
@@ -63,7 +62,7 @@ interface HelpChatSource {
     slug: string | null;
     title: string;
     visibility: string | null;
-    metadata: Record<string, NonNullable<unknown>> | null;
+    metadata: Record<string, unknown> | null;
     category: HelpChatSourceCategory | null;
 }
 type HelpChatStreamChunk = {
@@ -205,12 +204,15 @@ type AnnouncementType = 'info' | 'warning' | 'critical' | 'promotion' | 'mainten
 /**
  * Author shape returned on public entry responses.
  *
- * NOTE: `name` and `image` can be `null` on the server side.
+ * NOTE: `name` and `image` can be `null` on the server side. `isTeamMember`
+ * is only populated on comment responses (where the server can tell whether
+ * the commenter is a project member) — it is not set on entry author fields.
  */
 interface EntryAuthor {
     id: string;
     name: string | null;
     image: string | null;
+    isTeamMember?: boolean;
 }
 interface EntryTag {
     id: string;
@@ -236,6 +238,19 @@ interface EntryComment {
     updatedAt: string;
     author: EntryAuthor;
 }
+/**
+ * Resolved category attached to a public entry response.
+ *
+ * This is the server's `EntryCategory` row projected down to the fields
+ * that are safe/useful to expose publicly.
+ */
+interface EntryCategoryRef {
+    id: string;
+    slug: string;
+    name: string;
+    icon: string | null;
+    description: string | null;
+}
 /**
  * Fields that appear on BOTH list and detail entry responses.
  */
@@ -249,12 +264,13 @@ interface BaseEntry {
     locale: string;
     translationGroupId: string;
     categoryId: string | null;
+    category: EntryCategoryRef | null;
     coverImageUrl: string | null;
     position: number;
     views: number;
     metaTitle: string | null;
     metaDescription: string | null;
-    metadata: Record<string, NonNullable<unknown>> | null;
+    metadata: Record<string, unknown> | null;
     reactions: Record<string, number>;
     createdAt: string;
     updatedAt: string;
@@ -585,4 +601,4 @@ declare class Kookee {
     health(): Promise<HealthCheckResponse>;
 }
 
-export { type AnnouncementDetail, type AnnouncementGetByIdParams, type AnnouncementGetCommentsParams, type AnnouncementListItem, type AnnouncementListParams, AnnouncementModule, type AnnouncementType, type AnnouncementTypeSpecific, type AnyEntryDetail, type AnyEntryListItem, type ApiError, type BaseEntry, type BlogEntryDetail, type BlogEntryListItem, type BlogGetByIdParams, type BlogGetBySlugParams, type BlogGetCommentsParams, type BlogListParams, BlogModule, type BlogTypeSpecific, type ChangelogEntryDetail, type ChangelogEntryListItem, type ChangelogGetByIdParams, type ChangelogGetBySlugParams, type ChangelogGetCommentsParams, type ChangelogListParams, ChangelogModule, type ChangelogType, type ChangelogTypeSpecific, type ConfigListParams, ConfigModule, type CreateFeedbackCommentParams, type CreateFeedbackPostParams, type CreatedFeedbackComment, type CreatedFeedbackPost, type DeleteFeedbackCommentParams, type DeleteFeedbackCommentResponse, type DeleteFeedbackPostParams, type DeleteFeedbackPostResponse, type EntriesGetByIdParams, type EntriesGetBySlugParams, type EntriesGetCategoriesParams, type EntriesGetCommentsParams, type EntriesListParams, EntriesModule, type EntryAuthor, type EntryCategory, type EntryComment, type EntryDetailFields, type EntryStatus, type EntryTag, type EntryTagWithCount, type EntryTranslationSummary, type EntryTranslationsMap, type EntryType, type ExternalUser, type FeedbackAssignee, type FeedbackAuthor, type FeedbackColumnType, type FeedbackComment, type FeedbackKanbanColumn, type FeedbackListParams, FeedbackModule, type FeedbackPost, type FeedbackPostCategory, type FeedbackPostListItem, type FeedbackSortOption, type FeedbackTopContributor, type FeedbackTopContributorsParams, type FeedbackVoteParams, type FeedbackVoteResponse, type GenericEntryDetail, type GenericEntryListItem, type HealthCheckResponse, type HelpArticleDetail, type HelpArticleListItem, type HelpArticleTypeSpecific, type HelpArticleVisibility, type HelpCategoriesParams, type HelpChatMessage, type HelpChatParams, type HelpChatResponse, type HelpChatSource, type HelpChatSourceCategory, type HelpChatStreamChunk, type HelpGetByIdParams, type HelpGetBySlugParams, type HelpGetCommentsParams, type HelpListParams, HelpModule, type HelpSearchParams, type HelpSearchResult, Kookee, KookeeApiError, type KookeeConfig, type KookeeUser, type ListMyFeedbackPostsParams, type LocaleOptions, type OrderDirection, type PageEntryDetail, type PageEntryListItem, type PageTypeSpecific, type PagesGetByIdParams, type PagesGetBySlugParams, type PagesGetCommentsParams, type PagesListParams, PagesModule, type PaginatedResponse, type PaginationParams, type PublicConfig, type ReactParams, type ReactResponse, type ReactionType, type TypeSpecific, type TypedEntryDetail, type TypedEntryListItem };
+export { type AnnouncementDetail, type AnnouncementGetByIdParams, type AnnouncementGetCommentsParams, type AnnouncementListItem, type AnnouncementListParams, AnnouncementModule, type AnnouncementType, type AnnouncementTypeSpecific, type AnyEntryDetail, type AnyEntryListItem, type ApiError, type BaseEntry, type BlogEntryDetail, type BlogEntryListItem, type BlogGetByIdParams, type BlogGetBySlugParams, type BlogGetCommentsParams, type BlogListParams, BlogModule, type BlogTypeSpecific, type ChangelogEntryDetail, type ChangelogEntryListItem, type ChangelogGetByIdParams, type ChangelogGetBySlugParams, type ChangelogGetCommentsParams, type ChangelogListParams, ChangelogModule, type ChangelogType, type ChangelogTypeSpecific, type ConfigListParams, ConfigModule, type CreateFeedbackCommentParams, type CreateFeedbackPostParams, type CreatedFeedbackComment, type CreatedFeedbackPost, type DeleteFeedbackCommentParams, type DeleteFeedbackCommentResponse, type DeleteFeedbackPostParams, type DeleteFeedbackPostResponse, type EntriesGetByIdParams, type EntriesGetBySlugParams, type EntriesGetCategoriesParams, type EntriesGetCommentsParams, type EntriesListParams, EntriesModule, type EntryAuthor, type EntryCategory, type EntryCategoryRef, type EntryComment, type EntryDetailFields, type EntryStatus, type EntryTag, type EntryTagWithCount, type EntryTranslationSummary, type EntryTranslationsMap, type EntryType, type ExternalUser, type FeedbackAssignee, type FeedbackAuthor, type FeedbackColumnType, type FeedbackComment, type FeedbackKanbanColumn, type FeedbackListParams, FeedbackModule, type FeedbackPost, type FeedbackPostCategory, type FeedbackPostListItem, type FeedbackSortOption, type FeedbackTopContributor, type FeedbackTopContributorsParams, type FeedbackVoteParams, type FeedbackVoteResponse, type GenericEntryDetail, type GenericEntryListItem, type HealthCheckResponse, type HelpArticleDetail, type HelpArticleListItem, type HelpArticleTypeSpecific, type HelpArticleVisibility, type HelpCategoriesParams, type HelpChatMessage, type HelpChatParams, type HelpChatResponse, type HelpChatSource, type HelpChatSourceCategory, type HelpChatStreamChunk, type HelpGetByIdParams, type HelpGetBySlugParams, type HelpGetCommentsParams, type HelpListParams, HelpModule, type HelpSearchParams, type HelpSearchResult, Kookee, KookeeApiError, type KookeeConfig, type KookeeUser, type ListMyFeedbackPostsParams, type LocaleOptions, type OrderDirection, type PageEntryDetail, type PageEntryListItem, type PageTypeSpecific, type PagesGetByIdParams, type PagesGetBySlugParams, type PagesGetCommentsParams, type PagesListParams, PagesModule, type PaginatedResponse, type PaginationParams, type PublicConfig, type ReactParams, type ReactResponse, type ReactionType, type TypeSpecific, type TypedEntryDetail, type TypedEntryListItem };

package/package.json

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