@janbox/contentful-marketplace-sdk 1.0.0 → 1.0.2

package/README.md

@@ -6,7 +6,7 @@ TypeScript SDK for querying iChiba marketplace content from Contentful GraphQL.
 
 - Typed API for marketplace content entries.
 - Built-in market/language filtering in query builders.
-- `find*` methods with 404 handling.
+- Single-entry methods with 404 handling.
 - Works in both ESM and CJS builds.
 
 ## Installation
@@ -29,7 +29,7 @@ yarn add @janbox/contentful-marketplace-sdk contentful
 ```ts
 import {
   ContentfulSDK,
-  listBannerCollectionEntries,
+  listBannerCollections,
 } from "@janbox/contentful-marketplace-sdk";
 import type { CreateClientParams } from "contentful";
 
@@ -41,7 +41,7 @@ const clientOptions: CreateClientParams = {
 
 ContentfulSDK.configure(clientOptions);
 
-const result = await listBannerCollectionEntries({
+const result = await listBannerCollections({
   slot: "home_hero",
   marketCode: "vn",
   language: "en",
@@ -78,10 +78,10 @@ All methods return `{ data: ... }`.
 
 ### Banner Collection
 
-- `listBannerCollectionEntries(options)`
+- `listBannerCollections(options)`
 
 ```ts
-await listBannerCollectionEntries({
+await listBannerCollections({
   slot: "home_hero",
   limit: 20,
   platform: "WEB",
@@ -92,71 +92,96 @@ await listBannerCollectionEntries({
 
 ### Blog
 
-- `listBlogPostEntries(options?)`
-- `findBlogPostEntry(options)`
+- `listBlogPosts(options?)`
+- `getBlogPostDetail({ id } | { slug })`
 
 ```ts
-const posts = await listBlogPostEntries({
+const posts = await listBlogPosts({
   marketCode: "vn",
   language: "en",
   limit: 10,
   skip: 0,
 });
 
-const post = await findBlogPostEntry({
+const post = await getBlogPostDetail({
   slug: "how-to-shop-online",
   marketCode: "vn",
   language: "en",
 });
+
+const postById = await getBlogPostDetail({
+  id: "1a2b3c4d5e",
+  marketCode: "vn",
+  language: "en",
+});
 ```
 
 ### Documentation
 
-- `listDocCategoryEntries(options?)`
-- `findDocCategoryEntry(options)`
-- `listDocArticleEntries(options?)`
-- `findDocArticleEntry(options)`
+- `listDocCategories(options?)`
+- `getDocCategoryDetail({ id } | { slug })`
+- `listDocArticles(options?)`
+- `getDocArticleDetail({ id } | { slug })`
 
 ```ts
-const categories = await listDocCategoryEntries({
+const categories = await listDocCategories({
   marketCode: "vn",
   language: "en",
   limit: 10,
 });
 
-const articles = await listDocArticleEntries({
+const category = await getDocCategoryDetail({
+  slug: "getting-started",
+  marketCode: "vn",
+  language: "en",
+});
+
+const categoryById = await getDocCategoryDetail({
+  id: "1a2b3c4d5e",
+  marketCode: "vn",
+  language: "en",
+});
+
+const articles = await listDocArticles({
   categorySlug: "getting-started",
   marketCode: "vn",
   language: "en",
   limit: 10,
 });
+// listDocArticles returns summary fields only (no content, no seo)
 
-const article = await findDocArticleEntry({
+const article = await getDocArticleDetail({
   slug: "payment-methods",
   marketCode: "vn",
   language: "en",
 });
+
+const articleById = await getDocArticleDetail({
+  id: "1a2b3c4d5e",
+  marketCode: "vn",
+  language: "en",
+});
 ```
 
 ### Brand / Hyperlink / Keyword Collections
 
-- `listBrandCollectionEntries(options?)`
-- `listHyperlinkCollectionEntries(options?)`
-- `listKeywordCollectionEntries(options?)`
+- `listBrandCollections(options?)`
+- `listHyperlinkCollections(options?)`
+- `listKeywordCollections(options?)`
 
 ```ts
-const brands = await listBrandCollectionEntries({
+const brands = await listBrandCollections({
   marketCode: "vn",
   language: "en",
   limit: 20,
 });
 
-const links = await listHyperlinkCollectionEntries({
+const links = await listHyperlinkCollections({
   marketCode: "vn",
   language: "en",
 });
 
-const keywords = await listKeywordCollectionEntries({
+const keywords = await listKeywordCollections({
   marketCode: "vn",
   language: "en",
   limit: 20,
@@ -165,11 +190,14 @@ const keywords = await listKeywordCollectionEntries({
 
 ## Error Handling
 
-`findBlogPostEntry`, `findDocCategoryEntry`, and `findDocArticleEntry` throw a `Response` with status `404` when not found.
+`getBlogPostDetail`, `getDocCategoryDetail`, and `getDocArticleDetail` throw:
+
+- `Error("Either id or slug is required.")` if neither `id` nor `slug` is provided.
+- `Response` with status `404` when no entry is found.
 
 ```ts
 try {
-  await findDocArticleEntry({ slug: "unknown-slug" });
+  await getDocArticleDetail({ slug: "unknown-slug" });
 } catch (error) {
   if (error instanceof Response && error.status === 404) {
     console.log("Entry not found");

package/dist/entries/banner-collection.d.ts

@@ -3,7 +3,7 @@ import { Entry, EntrySys } from 'contentful';
 import { HyperlinkEntry } from './hyperlink';
 type BannerCollectionEntry = Entry<TypeBannerCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 type GraphQLEntrySys = Pick<EntrySys, "id">;
-type BannerCollectionGraphQLItem = {
+export type BannerCollectionGraphQLItem = {
     sys: GraphQLEntrySys;
     bannersCollection: {
         items: Array<{
@@ -21,19 +21,14 @@ type BannerCollectionGraphQLItem = {
         }>;
     };
 } & Pick<BannerCollectionEntry["fields"], "name" | "slot" | "platform">;
-type BannerCollectionGraphQLResponse = {
-    bannerCollectionCollection: {
-        items: Array<BannerCollectionGraphQLItem>;
-    };
-};
-export type ListBannerCollectionEntriesResponse = {
-    data: BannerCollectionGraphQLResponse["bannerCollectionCollection"]["items"];
+export type ListBannerCollectionsResponse = {
+    data: BannerCollectionGraphQLItem[];
 };
-export declare const listBannerCollectionEntries: ({ slot, limit, platform, marketCode, language, }: {
+export declare const listBannerCollections: ({ slot, limit, platform, marketCode, language, }: {
     slot: BannerCollectionEntry["fields"]["slot"];
     limit?: number;
     platform?: BannerCollectionEntry["fields"]["platform"][number];
     marketCode?: string;
     language?: string;
-}) => Promise<ListBannerCollectionEntriesResponse>;
+}) => Promise<ListBannerCollectionsResponse>;
 export {};

package/dist/entries/blog.d.ts

@@ -1,59 +1,54 @@
 import { TypeBlogPostSkeleton } from '../types';
 import { Entry, EntrySys } from 'contentful';
-export type BlogPostEntry = Entry<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id">;
+type BlogPostEntry = Entry<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
+type GraphQLEntrySys = Pick<EntrySys, "id" | "createdAt" | "updatedAt">;
 type GraphQLAsset = {
-    url: string | null;
+    url: string;
     width: number | null;
     height: number | null;
-    contentType: string | null;
+    contentType: string;
 };
-type BlogPostGraphQLItem = {
+type GraphQLSeo = {
+    metaTitle: string;
+    metaDescription: string | null;
+    metaKeywords: string[] | null;
+    metaRobots: string[] | null;
+};
+type BlogPostCategoryGraphQLItem = {
+    title: string;
+    slug: string;
+};
+export type BlogPostGraphQLItem = {
     sys: GraphQLEntrySys;
-    category: {
-        sys: GraphQLEntrySys;
-        title: string;
-        slug: string;
-    } | null;
+    category: BlogPostCategoryGraphQLItem | null;
     featuredImage: GraphQLAsset | null;
 } & Pick<BlogPostEntry["fields"], "title" | "shortDescription" | "slug">;
-type BlogPostDetailGraphQLItem = BlogPostGraphQLItem & {
+export interface BlogPostDetailGraphQLItem extends BlogPostGraphQLItem {
     author: {
-        sys: GraphQLEntrySys;
         name: string;
         avatar: GraphQLAsset | null;
     } | null;
     content: {
         json: BlogPostEntry["fields"]["content"];
-    } | null;
-    seo: {
-        sys: GraphQLEntrySys;
-        metaTitle: string;
-        metaDescription: string | null;
-        metaKeywords: string[] | null;
-        metaRobots: string[] | null;
-    } | null;
-};
-type BlogPostGraphQLResponse = {
-    blogPostCollection: {
-        items: Array<BlogPostGraphQLItem>;
     };
+    seo: GraphQLSeo | null;
+}
+export type ListBlogPostsResponse = {
+    data: BlogPostGraphQLItem[];
 };
-export type ListBlogPostEntriesResponse = {
-    data: BlogPostGraphQLResponse["blogPostCollection"]["items"];
-};
-export type FindBlogPostEntryResponse = {
+export type GetBlogPostDetailResponse = {
     data: BlogPostDetailGraphQLItem;
 };
-export declare const listBlogPostEntries: ({ marketCode, language, limit, skip, }?: {
+export declare const listBlogPosts: ({ marketCode, language, limit, skip, }?: {
     marketCode?: string;
     language?: string;
     limit?: number;
     skip?: number;
-}) => Promise<ListBlogPostEntriesResponse>;
-export declare const findBlogPostEntry: ({ slug, marketCode, language, }: {
-    slug: string;
+}) => Promise<ListBlogPostsResponse>;
+export declare const getBlogPostDetail: ({ id, slug, marketCode, language, }: {
+    id?: string;
+    slug?: string;
     marketCode?: string;
     language?: string;
-}) => Promise<FindBlogPostEntryResponse>;
+}) => Promise<GetBlogPostDetailResponse>;
 export {};

package/dist/entries/brand-collection.d.ts

@@ -1,26 +1,22 @@
-import { TypeBrandCollectionSkeleton } from '../types';
+import { TypeBrandCollectionSkeleton, TypeBrandSkeleton } from '../types';
 import { Entry, EntrySys } from 'contentful';
-import { BrandEntry } from './brand';
+type BrandEntry = Entry<TypeBrandSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 type BrandCollectionEntry = Entry<TypeBrandCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 type GraphQLEntrySys = Pick<EntrySys, "id">;
-type BrandCollectionGraphQLResponse = {
-    brandCollectionCollection: {
+export type BrandCollectionGraphQLItem = {
+    sys: GraphQLEntrySys;
+    brandsCollection: {
         items: Array<{
             sys: GraphQLEntrySys;
-            brandsCollection: {
-                items: Array<{
-                    sys: GraphQLEntrySys;
-                } & Pick<BrandEntry["fields"], "name" | "slug">>;
-            };
-        } & Pick<BrandCollectionEntry["fields"], "name" | "slot">>;
+        } & Pick<BrandEntry["fields"], "name" | "slug">>;
     };
+} & Pick<BrandCollectionEntry["fields"], "name" | "slot">;
+export type ListBrandCollectionsResponse = {
+    data: BrandCollectionGraphQLItem[];
 };
-export type ListBrandCollectionEntriesResponse = {
-    data: BrandCollectionGraphQLResponse["brandCollectionCollection"]["items"];
-};
-export declare const listBrandCollectionEntries: ({ limit, marketCode, language, }?: {
+export declare const listBrandCollections: ({ limit, marketCode, language, }?: {
     limit?: number;
     marketCode?: string;
     language?: string;
-}) => Promise<ListBrandCollectionEntriesResponse>;
+}) => Promise<ListBrandCollectionsResponse>;
 export {};

package/dist/entries/documentation.d.ts

@@ -2,7 +2,7 @@ import { TypeDocumentationArticleSkeleton, TypeDocumentationCategorySkeleton } f
 import { Entry, EntrySys } from 'contentful';
 export type DocCategoryEntry = Entry<TypeDocumentationCategorySkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 export type DocArticleEntry = Entry<TypeDocumentationArticleSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id">;
+type GraphQLEntrySys = Pick<EntrySys, "id" | "createdAt" | "updatedAt">;
 type GraphQLAsset = {
     url: string | null;
     width: number | null;
@@ -10,75 +10,65 @@ type GraphQLAsset = {
     contentType: string | null;
 };
 type GraphQLSeo = {
-    sys: GraphQLEntrySys;
     metaTitle: string;
     metaDescription: string | null;
     metaKeywords: string[] | null;
     metaRobots: string[] | null;
 };
-type DocCategoryGraphQLItem = {
+export type DocCategoryGraphQLItem = {
     sys: GraphQLEntrySys;
     seo: GraphQLSeo | null;
 } & Pick<DocCategoryEntry["fields"], "title" | "slug" | "description" | "order">;
-type DocArticleGraphQLItem = {
+type DocArticleCategoryGraphQLItem = Pick<DocCategoryEntry["fields"], "title" | "slug" | "description" | "order">;
+export type DocArticleGraphQLItem = {
     sys: GraphQLEntrySys;
-    category: ({
-        sys: GraphQLEntrySys;
-        seo: GraphQLSeo | null;
-    } & Pick<DocCategoryEntry["fields"], "title" | "slug" | "description" | "order">) | null;
+    category: DocArticleCategoryGraphQLItem;
     author: {
-        sys: GraphQLEntrySys;
         name: string;
         avatar: GraphQLAsset | null;
     } | null;
+} & Pick<DocArticleEntry["fields"], "title" | "slug">;
+export interface DocArticleDetailGraphQLItem extends DocArticleGraphQLItem {
     content: {
         json: DocArticleEntry["fields"]["content"];
-    } | null;
-    seo: GraphQLSeo | null;
-} & Pick<DocArticleEntry["fields"], "title" | "slug">;
-type DocCategoryGraphQLResponse = {
-    documentationCategoryCollection: {
-        items: Array<DocCategoryGraphQLItem>;
     };
+    seo: GraphQLSeo | null;
+}
+export type ListDocCategoriesResponse = {
+    data: DocCategoryGraphQLItem[];
 };
-type DocArticleGraphQLResponse = {
-    documentationArticleCollection: {
-        items: Array<DocArticleGraphQLItem>;
-    };
-};
-export type ListDocCategoryEntriesResponse = {
-    data: DocCategoryGraphQLResponse["documentationCategoryCollection"]["items"];
-};
-export type FindDocCategoryEntryResponse = {
+export type GetDocCategoryDetailResponse = {
     data: DocCategoryGraphQLItem;
 };
-export type ListDocArticleEntriesResponse = {
-    data: DocArticleGraphQLResponse["documentationArticleCollection"]["items"];
+export type ListDocArticlesResponse = {
+    data: DocArticleGraphQLItem[];
 };
-export type FindDocArticleEntryResponse = {
-    data: DocArticleGraphQLResponse["documentationArticleCollection"]["items"][number];
+export type GetDocArticleDetailResponse = {
+    data: DocArticleDetailGraphQLItem;
 };
-export declare const listDocCategoryEntries: ({ marketCode, language, limit, skip, }?: {
+export declare const listDocCategories: ({ marketCode, language, limit, skip, }?: {
     marketCode?: string;
     language?: string;
     limit?: number;
     skip?: number;
-}) => Promise<ListDocCategoryEntriesResponse>;
-export declare const findDocCategoryEntry: ({ slug, marketCode, language, }: {
-    slug: string;
+}) => Promise<ListDocCategoriesResponse>;
+export declare const getDocCategoryDetail: ({ id, slug, marketCode, language, }: {
+    id?: string;
+    slug?: string;
     marketCode?: string;
     language?: string;
-}) => Promise<FindDocCategoryEntryResponse>;
-export declare const listDocArticleEntries: ({ marketCode, language, categorySlug, limit, skip, }?: {
+}) => Promise<GetDocCategoryDetailResponse>;
+export declare const listDocArticles: ({ marketCode, language, categorySlug, limit, skip, }?: {
     marketCode?: string;
     language?: string;
     categorySlug?: string;
     limit?: number;
     skip?: number;
-}) => Promise<ListDocArticleEntriesResponse>;
-export declare const findDocArticleEntry: ({ slug, marketCode, language, }: {
-    slug: string;
+}) => Promise<ListDocArticlesResponse>;
+export declare const getDocArticleDetail: ({ id, slug, marketCode, language, }: {
+    id?: string;
+    slug?: string;
     marketCode?: string;
     language?: string;
-}) => Promise<FindDocArticleEntryResponse>;
+}) => Promise<GetDocArticleDetailResponse>;
 export {};

package/dist/entries/hyperlink-collection.d.ts

@@ -3,23 +3,19 @@ import { Entry, EntrySys } from 'contentful';
 import { HyperlinkEntry } from './hyperlink';
 type HyperlinkCollectionEntry = Entry<TypeHyperlinkCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 type GraphQLEntrySys = Pick<EntrySys, "id">;
-type HyperlinkCollectionGraphQLResponse = {
-    hyperlinkCollectionCollection: {
+export type HyperlinkCollectionGraphQLItem = {
+    sys: GraphQLEntrySys;
+    linksCollection: {
         items: Array<{
             sys: GraphQLEntrySys;
-            linksCollection: {
-                items: Array<{
-                    sys: GraphQLEntrySys;
-                } & Pick<HyperlinkEntry["fields"], "label" | "url" | "target" | "includesMarketCode">>;
-            };
-        } & Pick<HyperlinkCollectionEntry["fields"], "name" | "slot" | "order">>;
+        } & Pick<HyperlinkEntry["fields"], "label" | "url" | "target" | "includesMarketCode">>;
     };
+} & Pick<HyperlinkCollectionEntry["fields"], "name" | "slot" | "order">;
+export type ListHyperlinkCollectionsResponse = {
+    data: HyperlinkCollectionGraphQLItem[];
 };
-export type ListHyperlinkCollectionEntriesResponse = {
-    data: HyperlinkCollectionGraphQLResponse["hyperlinkCollectionCollection"]["items"];
-};
-export declare const listHyperlinkCollectionEntries: ({ marketCode, language, }?: {
+export declare const listHyperlinkCollections: ({ marketCode, language, }?: {
     marketCode?: string;
     language?: string;
-}) => Promise<ListHyperlinkCollectionEntriesResponse>;
+}) => Promise<ListHyperlinkCollectionsResponse>;
 export {};

package/dist/entries/keyword-collection.d.ts

@@ -2,19 +2,15 @@ import { TypeKeywordCollectionSkeleton } from '../types';
 import { Entry, EntrySys } from 'contentful';
 type KeywordCollectionEntry = Entry<TypeKeywordCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 type GraphQLEntrySys = Pick<EntrySys, "id">;
-type KeywordCollectionGraphQLResponse = {
-    keywordCollectionCollection: {
-        items: Array<{
-            sys: GraphQLEntrySys;
-        } & Pick<KeywordCollectionEntry["fields"], "name" | "slot" | "keywords">>;
-    };
+export type KeywordCollectionGraphQLItem = {
+    sys: GraphQLEntrySys;
+} & Pick<KeywordCollectionEntry["fields"], "name" | "slot" | "keywords">;
+export type ListKeywordCollectionsResponse = {
+    data: KeywordCollectionGraphQLItem[];
 };
-export type ListKeywordCollectionEntriesResponse = {
-    data: KeywordCollectionGraphQLResponse["keywordCollectionCollection"]["items"];
-};
-export declare const listKeywordCollectionEntries: ({ limit, marketCode, language, }?: {
+export declare const listKeywordCollections: ({ limit, marketCode, language, }?: {
     limit?: number;
     marketCode?: string;
     language?: string;
-}) => Promise<ListKeywordCollectionEntriesResponse>;
+}) => Promise<ListKeywordCollectionsResponse>;
 export {};