@janbox/contentful-marketplace-sdk 1.0.1 → 1.0.3

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,15 +41,16 @@ const clientOptions: CreateClientParams = {
 
 ContentfulSDK.configure(clientOptions);
 
-const result = await listBannerCollectionEntries({
+const result = await listBannerCollections({
   slot: "home_hero",
   marketCode: "vn",
   language: "en",
   platform: "WEB",
-  limit: 10,
+  page: 1,
+  size: 10,
 });
 
-console.log(result.data);
+console.log(result.items);
 ```
 
 ## Configuration
@@ -74,16 +75,18 @@ Notes:
 
 ## API Methods
 
-All methods return `{ data: ... }`.
+List methods return `{ page, total, size, items }`.
+Detail methods return the entry object directly.
 
 ### Banner Collection
 
-- `listBannerCollectionEntries(options)`
+- `listBannerCollections(options)`
 
 ```ts
-await listBannerCollectionEntries({
+await listBannerCollections({
   slot: "home_hero",
-  limit: 20,
+  page: 1,
+  size: 20,
   platform: "WEB",
   marketCode: "vn",
   language: "en",
@@ -92,84 +95,120 @@ 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,
+  page: 1,
+  size: 10,
 });
+// paging response shape: { page, total, size, items }
 
-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,
+  page: 1,
+  size: 10,
 });
+// paging response shape: { page, total, size, items }
 
-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,
+  page: 1,
+  size: 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,
+  page: 1,
+  size: 20,
 });
 
-const links = await listHyperlinkCollectionEntries({
+const links = await listHyperlinkCollections({
+  page: 1,
+  size: 20,
   marketCode: "vn",
   language: "en",
 });
 
-const keywords = await listKeywordCollectionEntries({
+const keywords = await listKeywordCollections({
   marketCode: "vn",
   language: "en",
-  limit: 20,
+  page: 1,
+  size: 20,
 });
 ```
 
 ## 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

@@ -21,14 +21,18 @@ export type BannerCollectionGraphQLItem = {
         }>;
     };
 } & Pick<BannerCollectionEntry["fields"], "name" | "slot" | "platform">;
-export type ListBannerCollectionEntriesResponse = {
-    data: BannerCollectionGraphQLItem[];
+export type ListBannerCollectionsResponse = {
+    page: number;
+    total: number;
+    size: number;
+    items: BannerCollectionGraphQLItem[];
 };
-export declare const listBannerCollectionEntries: ({ slot, limit, platform, marketCode, language, }: {
+export declare const listBannerCollections: ({ slot, page, size, platform, marketCode, language, }: {
     slot: BannerCollectionEntry["fields"]["slot"];
-    limit?: number;
+    page?: number;
+    size?: number;
     platform?: BannerCollectionEntry["fields"]["platform"][number];
     marketCode?: string;
     language?: string;
-}) => Promise<ListBannerCollectionEntriesResponse>;
+}) => Promise<ListBannerCollectionsResponse>;
 export {};

package/dist/entries/blog.d.ts

@@ -1,54 +1,55 @@
 import { TypeBlogPostSkeleton } from '../types';
 import { Entry, EntrySys } from 'contentful';
 type BlogPostEntry = Entry<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id">;
+type GraphQLEntrySys = Pick<EntrySys, "id" | "createdAt" | "updatedAt">;
 type GraphQLAsset = {
     url: string;
     width: number | null;
     height: number | null;
     contentType: string;
 };
+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">;
-export 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;
-};
-export type ListBlogPostEntriesResponse = {
-    data: BlogPostGraphQLItem[];
+    };
+    seo: GraphQLSeo | null;
+}
+export type ListBlogPostsResponse = {
+    page: number;
+    total: number;
+    size: number;
+    items: BlogPostGraphQLItem[];
 };
-export type FindBlogPostEntryResponse = {
-    data: BlogPostDetailGraphQLItem;
-};
-export declare const listBlogPostEntries: ({ marketCode, language, limit, skip, }?: {
+export type GetBlogPostDetailResponse = BlogPostDetailGraphQLItem;
+export declare const listBlogPosts: ({ marketCode, language, page, size, }?: {
     marketCode?: string;
     language?: string;
-    limit?: number;
-    skip?: number;
-}) => Promise<ListBlogPostEntriesResponse>;
-export declare const findBlogPostEntry: ({ slug, marketCode, language, }: {
-    slug: string;
+    page?: number;
+    size?: number;
+}) => 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

@@ -11,12 +11,16 @@ export type BrandCollectionGraphQLItem = {
         } & Pick<BrandEntry["fields"], "name" | "slug">>;
     };
 } & Pick<BrandCollectionEntry["fields"], "name" | "slot">;
-export type ListBrandCollectionEntriesResponse = {
-    data: BrandCollectionGraphQLItem[];
+export type ListBrandCollectionsResponse = {
+    page: number;
+    total: number;
+    size: number;
+    items: BrandCollectionGraphQLItem[];
 };
-export declare const listBrandCollectionEntries: ({ limit, marketCode, language, }?: {
-    limit?: number;
+export declare const listBrandCollections: ({ page, size, marketCode, language, }?: {
+    page?: number;
+    size?: 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,7 +10,6 @@ type GraphQLAsset = {
     contentType: string | null;
 };
 type GraphQLSeo = {
-    sys: GraphQLEntrySys;
     metaTitle: string;
     metaDescription: string | null;
     metaKeywords: string[] | null;
@@ -20,55 +19,58 @@ export type DocCategoryGraphQLItem = {
     sys: GraphQLEntrySys;
     seo: GraphQLSeo | null;
 } & Pick<DocCategoryEntry["fields"], "title" | "slug" | "description" | "order">;
+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">;
-export type ListDocCategoryEntriesResponse = {
-    data: DocCategoryGraphQLItem[];
-};
-export type FindDocCategoryEntryResponse = {
-    data: DocCategoryGraphQLItem;
-};
-export type ListDocArticleEntriesResponse = {
-    data: DocArticleGraphQLItem[];
+}
+export type ListDocCategoriesResponse = {
+    page: number;
+    total: number;
+    size: number;
+    items: DocCategoryGraphQLItem[];
 };
-export type FindDocArticleEntryResponse = {
-    data: DocArticleGraphQLItem;
+export type GetDocCategoryDetailResponse = DocCategoryGraphQLItem;
+export type ListDocArticlesResponse = {
+    page: number;
+    total: number;
+    size: number;
+    items: DocArticleGraphQLItem[];
 };
-export declare const listDocCategoryEntries: ({ marketCode, language, limit, skip, }?: {
+export type GetDocArticleDetailResponse = DocArticleDetailGraphQLItem;
+export declare const listDocCategories: ({ marketCode, language, page, size, }?: {
     marketCode?: string;
     language?: string;
-    limit?: number;
-    skip?: number;
-}) => Promise<ListDocCategoryEntriesResponse>;
-export declare const findDocCategoryEntry: ({ slug, marketCode, language, }: {
-    slug: string;
+    page?: number;
+    size?: number;
+}) => 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, page, size, }?: {
     marketCode?: string;
     language?: string;
     categorySlug?: string;
-    limit?: number;
-    skip?: number;
-}) => Promise<ListDocArticleEntriesResponse>;
-export declare const findDocArticleEntry: ({ slug, marketCode, language, }: {
-    slug: string;
+    page?: number;
+    size?: number;
+}) => 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

@@ -11,11 +11,16 @@ export type HyperlinkCollectionGraphQLItem = {
         } & Pick<HyperlinkEntry["fields"], "label" | "url" | "target" | "includesMarketCode">>;
     };
 } & Pick<HyperlinkCollectionEntry["fields"], "name" | "slot" | "order">;
-export type ListHyperlinkCollectionEntriesResponse = {
-    data: HyperlinkCollectionGraphQLItem[];
+export type ListHyperlinkCollectionsResponse = {
+    page: number;
+    total: number;
+    size: number;
+    items: HyperlinkCollectionGraphQLItem[];
 };
-export declare const listHyperlinkCollectionEntries: ({ marketCode, language, }?: {
+export declare const listHyperlinkCollections: ({ page, size, marketCode, language, }?: {
+    page?: number;
+    size?: number;
     marketCode?: string;
     language?: string;
-}) => Promise<ListHyperlinkCollectionEntriesResponse>;
+}) => Promise<ListHyperlinkCollectionsResponse>;
 export {};

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

@@ -5,12 +5,16 @@ type GraphQLEntrySys = Pick<EntrySys, "id">;
 export type KeywordCollectionGraphQLItem = {
     sys: GraphQLEntrySys;
 } & Pick<KeywordCollectionEntry["fields"], "name" | "slot" | "keywords">;
-export type ListKeywordCollectionEntriesResponse = {
-    data: KeywordCollectionGraphQLItem[];
+export type ListKeywordCollectionsResponse = {
+    page: number;
+    total: number;
+    size: number;
+    items: KeywordCollectionGraphQLItem[];
 };
-export declare const listKeywordCollectionEntries: ({ limit, marketCode, language, }?: {
-    limit?: number;
+export declare const listKeywordCollections: ({ page, size, marketCode, language, }?: {
+    page?: number;
+    size?: number;
     marketCode?: string;
     language?: string;
-}) => Promise<ListKeywordCollectionEntriesResponse>;
+}) => Promise<ListKeywordCollectionsResponse>;
 export {};