@janbox/contentful-marketplace-sdk 2.0.0 → 3.0.0-alpha.0

package/README.md

@@ -1,6 +1,6 @@
 # @janbox/contentful-marketplace-sdk
 
-TypeScript SDK for querying iChiba marketplace content from Contentful GraphQL.
+TypeScript SDK for querying iChiba marketplace content from the internal headless CMS Delivery API (REST, Contentful CDA style).
 
 ## Features
 
@@ -11,17 +11,15 @@ TypeScript SDK for querying iChiba marketplace content from Contentful GraphQL.
 
 ## Installation
 
-`contentful` is a peer dependency and must be installed in your app.
-
 ```bash
 # pnpm
-pnpm add @janbox/contentful-marketplace-sdk contentful
+pnpm add @janbox/contentful-marketplace-sdk
 
 # npm
-npm install @janbox/contentful-marketplace-sdk contentful
+npm install @janbox/contentful-marketplace-sdk
 
 # yarn
-yarn add @janbox/contentful-marketplace-sdk contentful
+yarn add @janbox/contentful-marketplace-sdk
 ```
 
 ## Quick Start
@@ -31,15 +29,13 @@ import {
   ContentfulSDK,
   getBannerCollections,
 } from "@janbox/contentful-marketplace-sdk";
-import type { CreateClientParams } from "contentful";
-
-const clientOptions: CreateClientParams = {
-  space: process.env.CONTENTFUL_SPACE_ID!,
-  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
-  environment: "master", // optional, defaults to "master"
-};
 
-ContentfulSDK.configure(clientOptions);
+ContentfulSDK.configure({
+  url: "https://headless-cms.ichiba.net/delivery/janbox",
+  headers: {
+    Authorization: `Bearer ${process.env.CMS_DELIVERY_TOKEN}`,
+  },
+});
 
 const result = await getBannerCollections({
   slot: "home_hero",
@@ -59,20 +55,34 @@ console.log(result.items);
 
 Configure the SDK once before calling entry methods.
 
+| Parameter | Type                     | Required | Description                               |
+|-----------|--------------------------|----------|-------------------------------------------|
+| `url`     | `string`                 | ✅       | Delivery API base URL, e.g. `https://headless-cms.ichiba.net/delivery/janbox` |
+| `method`  | `string`                 | —        | Deprecated and ignored: requests are always `GET` |
+| `headers` | `Record<string, string>` | —        | Custom headers, usually `Authorization: Bearer cdel_...` |
+
 ```ts
 ContentfulSDK.configure({
-  space: "your-space-id",
-  accessToken: "your-delivery-access-token",
-  environment: "master",
+  url: "https://test-headless-cms.ichiba.net/delivery/janbox", // QC
+  headers: {
+    Authorization: "Bearer cdel_your-delivery-key",
+  },
 });
 ```
 
 Notes:
 
-- `environment` defaults to `"master"` if omitted.
-- The SDK sends requests to `https://graphql.contentful.com/content/v1/...`.
+- The SDK sends `GET {url}/entries?...` with `Accept: application/json`. Custom headers are merged on top.
+- Keep the delivery key server-side: call the SDK from your server (route handler, BFF), never from browser JavaScript.
 - Runtime requires `fetch` (Node.js 18+ recommended).
 
+## Breaking changes in 3.0.0
+
+1. `url` is now the Delivery API base URL of the internal CMS, and `headers` carries the delivery key (`Authorization: Bearer cdel_...`). `method` is still accepted but ignored.
+2. The delivery key must stay on the server, so the SDK must be called server-side.
+3. Types built on the `contentful` package are removed: `TypeXxxSkeleton`, the generic `TypeXxx<Modifiers, Locales>` types, and the `DocArticleEntry`, `DocCategoryEntry` and `HyperlinkEntry` aliases. `TypeXxxFields` are kept as plain interfaces.
+4. Entry ids are the new CMS ids (GUIDs). Old Contentful ids must be migrated by the apps: the CMS rejects them with `400 InvalidQuery`, which the SDK throws as `Error("Request failed: 400 ...")`.
+
 ## API Methods
 
 Collection methods return `{ page, total, size, items }`.
@@ -199,6 +209,21 @@ const keywords = await getKeywordCollections({
 });
 ```
 
+### Policy and Terms
+
+- `getPolicyAndTerms(options?)` — returns a single entry (`limit: 1`), throws `404` if not found
+
+```ts
+const policy = await getPolicyAndTerms({
+  marketCode: "vn",
+  locale: "vi",
+});
+
+// policy shape: { sys: { id }, title, locale, content: { json, links } | null }
+```
+
+Filters `marketCode` / `locale` with global fallback (entries where `markets` / `locale` is not set are included).
+
 ## Error Handling
 
 `getBlogPostDetail`, `getDocCategoryDetail`, and `getDocArticleDetail` throw:
@@ -230,8 +255,8 @@ This supports global fallback content.
 The package exports:
 
 - client and entry functions from `src/client` and `src/entries`
-- Contentful schema types from `src/types`
-- entry aliases such as `BlogPostEntry`, `DocArticleEntry`, and `DocCategoryEntry`
+- content model field types (`TypeXxxFields`) and CMS response types (`CmsEntry`, `CmsAsset`, `CmsLink`, `CmsCollection`) from `src/types`
+- response item types such as `BlogPostGraphQLItem` and `DocArticleGraphQLItem` (names kept from 2.x)
 
 ## Development
 
@@ -242,3 +267,10 @@ pnpm install
 pnpm --filter @janbox/contentful-marketplace-sdk build
 pnpm --filter @janbox/contentful-marketplace-sdk test
 ```
+
+Unit tests (`*.unit.test.ts`) mock `fetch` and always run. Integration tests (`*.test.ts`) call a real Delivery API and are skipped unless these variables are set (e.g. in `packages/marketplace-sdk/.env`):
+
+```bash
+VITE_CMS_DELIVERY_URL=https://test-headless-cms.ichiba.net/delivery/janbox
+VITE_CMS_DELIVERY_TOKEN=cdel_your-delivery-key
+```

package/dist/client/index.d.ts

@@ -1,5 +1,8 @@
+import { CmsCollection, CmsEntry } from '../types';
+import { QueryParams } from '../utils/query';
 export interface ContentfulSDKConfig {
     url: string;
+    /** @deprecated Ignored: requests are always GET. Kept so existing configs still type-check. */
     method?: string;
     headers?: Record<string, string>;
 }
@@ -7,5 +10,5 @@ export declare class ContentfulSDK {
     private static _config;
     static get config(): ContentfulSDKConfig;
     static configure(params: ContentfulSDKConfig): void;
-    static graphqlQuery<T extends object>(query: string, variables?: Record<string, any>): Promise<T>;
+    static getEntries<T = CmsEntry>(params: QueryParams): Promise<CmsCollection<T>>;
 }

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

@@ -1,28 +1,26 @@
 import { PaginatedResponse } from '../utils';
-import { GraphQLAsset, TypeBannerCollectionSkeleton } from '../types';
-import { Entry, EntrySys } from 'contentful';
-import { HyperlinkEntry } from './hyperlink';
-type BannerCollectionEntry = Entry<TypeBannerCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id">;
+import { GraphQLAsset, TypeBannerCollectionFields } from '../types';
+import { HyperlinkGraphQLItem } from './hyperlink';
+type GraphQLEntrySys = {
+    id: string;
+};
 export type BannerCollectionGraphQLItem = {
     sys: GraphQLEntrySys;
     bannersCollection: {
         items: Array<{
             sys: GraphQLEntrySys;
-            hyperlink: ({
-                sys: GraphQLEntrySys;
-            } & Pick<HyperlinkEntry["fields"], "label" | "url" | "target" | "marketHandling">) | null;
+            hyperlink: HyperlinkGraphQLItem | null;
             media: GraphQLAsset;
             name: string;
         }>;
     };
-} & Pick<BannerCollectionEntry["fields"], "name" | "slot" | "platform">;
+} & Pick<TypeBannerCollectionFields, "name" | "slot" | "platform">;
 export type GetBannerCollectionsResponse = PaginatedResponse<BannerCollectionGraphQLItem>;
 export declare const getBannerCollections: ({ slot, page, size, platform, marketCode, locale, }: {
-    slot: BannerCollectionEntry["fields"]["slot"];
+    slot: TypeBannerCollectionFields["slot"];
     page?: number;
     size?: number;
-    platform?: BannerCollectionEntry["fields"]["platform"][number];
+    platform?: TypeBannerCollectionFields["platform"][number];
     marketCode?: string;
     locale?: string;
 }) => Promise<GetBannerCollectionsResponse>;

package/dist/entries/blog-category.d.ts

@@ -1,14 +1,12 @@
 import { PaginatedResponse } from '../utils';
-import { GraphQLAsset, TypeBlogCategorySkeleton } from '../types';
+import { GraphQLAsset, TypeBlogCategoryFields } from '../types';
 import { GraphQLSeo } from './seo';
-import { Entry } from 'contentful';
-type BlogCategoryEntry = Entry<TypeBlogCategorySkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 export type BlogCategoryGraphQLItem = {
     sys: {
         id: string;
     };
     featuredImage: GraphQLAsset | null;
-} & Pick<BlogCategoryEntry["fields"], "title" | "slug">;
+} & Pick<TypeBlogCategoryFields, "title" | "slug">;
 export interface BlogCategoryDetailGraphQLItem extends BlogCategoryGraphQLItem {
     description: string | null;
     seo: GraphQLSeo | null;
@@ -27,4 +25,3 @@ export declare const getBlogCategoryDetail: ({ id, slug, marketCode, locale, }:
     marketCode?: string;
     locale?: string;
 }) => Promise<GetBlogCategoryDetailResponse>;
-export {};

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

@@ -1,7 +1,5 @@
-import { TypeBlogCollectionSkeleton, GraphQLAsset } from '../types';
+import { GraphQLAsset, TypeBlogCollectionFields } from '../types';
 import { PaginatedResponse } from '../utils';
-import { Entry } from 'contentful';
-type BlogCollectionEntry = Entry<TypeBlogCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
 type BlogCollectionCategoryGraphQLItem = {
     sys: {
         id: string;
@@ -17,7 +15,7 @@ export type BlogCollectionGraphQLItem = {
     featuredImage: GraphQLAsset | null;
     categoryId: string | null;
     collectionId: string | null;
-} & Pick<BlogCollectionEntry["fields"], "name" | "type" | "order">;
+} & Pick<TypeBlogCollectionFields, "name" | "type" | "order">;
 export type GetBlogCollectionsResponse = PaginatedResponse<BlogCollectionGraphQLItem>;
 export declare const getBlogCollections: ({ marketCode, locale, page, size, }?: {
     marketCode?: string;

package/dist/entries/blog-post.d.ts

@@ -1,9 +1,11 @@
-import { GraphQLAsset, GraphQLAssetLink, TypeBlogPostSkeleton } from '../types';
+import { GraphQLAsset, GraphQLAssetLink, TypeBlogPostFields } from '../types';
 import { PaginatedResponse } from '../utils';
-import { Entry, EntrySys } from 'contentful';
 import { GraphQLSeo } from './seo';
-type BlogPostEntry = Entry<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id" | "createdAt" | "updatedAt">;
+type GraphQLEntrySys = {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+};
 type BlogPostCategoryGraphQLItem = {
     sys: Pick<GraphQLEntrySys, "id">;
     title: string;
@@ -15,14 +17,14 @@ export type BlogPostGraphQLItem = {
     categoriesCollection: {
         items: BlogPostCategoryGraphQLItem[];
     } | null;
-} & Pick<BlogPostEntry["fields"], "title" | "shortDescription" | "slug">;
+} & Pick<TypeBlogPostFields, "title" | "shortDescription" | "slug">;
 export interface BlogPostDetailGraphQLItem extends BlogPostGraphQLItem {
     author: {
         name: string;
         avatar: GraphQLAsset | null;
     } | null;
     content: {
-        json: BlogPostEntry["fields"]["content"];
+        json: TypeBlogPostFields["content"];
         links: {
             assets: {
                 block: GraphQLAssetLink[];

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

@@ -1,10 +1,8 @@
 import { PaginatedResponse } from '../utils';
-import { GraphQLAsset, TypeBrandCollectionSkeleton, TypeBrandSkeleton } from '../types';
-import { Entry, EntrySys } from 'contentful';
-import { HyperlinkEntry } from './hyperlink';
-type BrandEntry = Entry<TypeBrandSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type BrandCollectionEntry = Entry<TypeBrandCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id">;
+import { GraphQLAsset, TypeBrandCollectionFields, TypeBrandFields, TypeHyperlinkFields } from '../types';
+type GraphQLEntrySys = {
+    id: string;
+};
 export type BrandCollectionGraphQLItem = {
     sys: GraphQLEntrySys;
     brandsCollection: {
@@ -13,10 +11,10 @@ export type BrandCollectionGraphQLItem = {
             logo: GraphQLAsset | null;
             hyperlink: ({
                 sys: GraphQLEntrySys;
-            } & Pick<HyperlinkEntry["fields"], "label" | "url" | "target" | "marketHandling">) | null;
-        } & Pick<BrandEntry["fields"], "name">>;
+            } & Pick<TypeHyperlinkFields, "label" | "url" | "target" | "marketHandling">) | null;
+        } & Pick<TypeBrandFields, "name">>;
     };
-} & Pick<BrandCollectionEntry["fields"], "name" | "slot">;
+} & Pick<TypeBrandCollectionFields, "name" | "slot">;
 export type GetBrandCollectionsResponse = PaginatedResponse<BrandCollectionGraphQLItem>;
 export declare const getBrandCollections: ({ page, size, marketCode, locale, }?: {
     page?: number;

package/dist/entries/documentation.d.ts

@@ -1,15 +1,16 @@
-import { GraphQLAsset, GraphQLAssetLink, TypeDocumentationArticleSkeleton, TypeDocumentationCategorySkeleton } from '../types';
+import { GraphQLAsset, GraphQLAssetLink, TypeDocumentationArticleFields, TypeDocumentationCategoryFields } from '../types';
 import { PaginatedResponse } from '../utils';
-import { Entry, EntrySys } from 'contentful';
 import { GraphQLSeo } from './seo';
-export type DocCategoryEntry = Entry<TypeDocumentationCategorySkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-export type DocArticleEntry = Entry<TypeDocumentationArticleSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id" | "createdAt" | "updatedAt">;
+type GraphQLEntrySys = {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+};
 export type DocCategoryGraphQLItem = {
     sys: GraphQLEntrySys;
     seo: GraphQLSeo | null;
-} & Pick<DocCategoryEntry["fields"], "title" | "slug" | "description" | "order">;
-type DocArticleCategoryGraphQLItem = Pick<DocCategoryEntry["fields"], "title" | "slug" | "description" | "order">;
+} & Pick<TypeDocumentationCategoryFields, "title" | "slug" | "description" | "order">;
+type DocArticleCategoryGraphQLItem = Pick<TypeDocumentationCategoryFields, "title" | "slug" | "description" | "order">;
 export type DocArticleGraphQLItem = {
     sys: GraphQLEntrySys;
     category: DocArticleCategoryGraphQLItem;
@@ -17,10 +18,10 @@ export type DocArticleGraphQLItem = {
         name: string;
         avatar: GraphQLAsset | null;
     } | null;
-} & Pick<DocArticleEntry["fields"], "title" | "slug">;
+} & Pick<TypeDocumentationArticleFields, "title" | "slug">;
 export interface DocArticleDetailGraphQLItem extends DocArticleGraphQLItem {
     content: {
-        json: DocArticleEntry["fields"]["content"];
+        json: TypeDocumentationArticleFields["content"];
         links: {
             assets: {
                 block: GraphQLAssetLink[];

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

@@ -1,17 +1,16 @@
 import { PaginatedResponse } from '../utils';
-import { TypeHyperlinkCollectionSkeleton } from '../types';
-import { Entry, EntrySys } from 'contentful';
-import { HyperlinkEntry } from './hyperlink';
-type HyperlinkCollectionEntry = Entry<TypeHyperlinkCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id">;
+import { TypeHyperlinkCollectionFields, TypeHyperlinkFields } from '../types';
+type GraphQLEntrySys = {
+    id: string;
+};
 export type HyperlinkCollectionGraphQLItem = {
     sys: GraphQLEntrySys;
     linksCollection: {
         items: Array<{
             sys: GraphQLEntrySys;
-        } & Pick<HyperlinkEntry["fields"], "label" | "url" | "target" | 'marketHandling'>>;
+        } & Pick<TypeHyperlinkFields, "label" | "url" | "target" | 'marketHandling'>>;
     };
-} & Pick<HyperlinkCollectionEntry["fields"], "name" | "slot" | "order">;
+} & Pick<TypeHyperlinkCollectionFields, "name" | "slot" | "order">;
 export type GetHyperlinkCollectionsResponse = PaginatedResponse<HyperlinkCollectionGraphQLItem>;
 export declare const getHyperlinkCollections: ({ page, size, marketCode, locale, }?: {
     page?: number;

package/dist/entries/hyperlink.d.ts

@@ -1,3 +1,6 @@
-import { TypeHyperlinkSkeleton } from '../types';
-import { Entry } from 'contentful';
-export type HyperlinkEntry = Entry<TypeHyperlinkSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
+import { TypeHyperlinkFields } from '../types';
+export type HyperlinkGraphQLItem = {
+    sys: {
+        id: string;
+    };
+} & Pick<TypeHyperlinkFields, "label" | "url" | "target" | "marketHandling">;

package/dist/entries/index.d.ts

@@ -7,4 +7,5 @@ export * from './documentation';
 export * from './hyperlink-collection';
 export * from './hyperlink';
 export * from './keyword-collection';
+export * from './policy-and-terms';
 export * from './seo';

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

@@ -1,11 +1,11 @@
 import { PaginatedResponse } from '../utils';
-import { TypeKeywordCollectionSkeleton } from '../types';
-import { Entry, EntrySys } from 'contentful';
-type KeywordCollectionEntry = Entry<TypeKeywordCollectionSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-type GraphQLEntrySys = Pick<EntrySys, "id">;
+import { TypeKeywordCollectionFields } from '../types';
+type GraphQLEntrySys = {
+    id: string;
+};
 export type KeywordCollectionGraphQLItem = {
     sys: GraphQLEntrySys;
-} & Pick<KeywordCollectionEntry["fields"], "name" | "slot" | "keywords">;
+} & Pick<TypeKeywordCollectionFields, "name" | "slot" | "keywords">;
 export type GetKeywordCollectionsResponse = PaginatedResponse<KeywordCollectionGraphQLItem>;
 export declare const getKeywordCollections: ({ page, size, marketCode, locale, }?: {
     page?: number;

package/dist/entries/policy-and-terms.d.ts

@@ -0,0 +1,20 @@
+import { GraphQLAssetLink, TypePolicyAndTermsFields } from '../types';
+type GraphQLEntrySys = {
+    id: string;
+};
+export type PolicyAndTermsGraphQLItem = {
+    sys: GraphQLEntrySys;
+    content: {
+        json: TypePolicyAndTermsFields["content"];
+        links: {
+            assets: {
+                block: GraphQLAssetLink[];
+            };
+        };
+    } | null;
+} & Pick<TypePolicyAndTermsFields, "title" | "locale">;
+export declare const getPolicyAndTerms: ({ marketCode, locale, }?: {
+    marketCode?: string;
+    locale?: string;
+}) => Promise<PolicyAndTermsGraphQLItem>;
+export {};