@janbox/contentful-marketplace-sdk 0.0.9 → 1.0.1

package/README.md

@@ -1,363 +1,205 @@
-# iChiba Contentful SDK
+# @janbox/contentful-marketplace-sdk
 
-A TypeScript SDK for accessing iChiba marketplace content from Contentful CMS. This SDK provides type-safe methods to retrieve banners, blog posts, documentation articles, and other content types with market and language filtering support.
+TypeScript SDK for querying iChiba marketplace content from Contentful GraphQL.
 
 ## Features
 
-- 🔒 **Type-safe**: Full TypeScript support with auto-generated types from Contentful schemas
-- 🌐 **Multi-market**: Built-in filtering by market and language
-- 📝 **Content Types**: Support for banners, blog posts, documentation, and more
-- 🚀 **Easy to use**: Simple API with intuitive method names
-- 🎯 **Selective queries**: Optimized queries with field selection
-- ⚡ **Performance**: Built on top of the official Contentful SDK
+- Typed API for marketplace content entries.
+- Built-in market/language filtering in query builders.
+- `find*` methods with 404 handling.
+- Works in both ESM and CJS builds.
 
 ## Installation
 
+`contentful` is a peer dependency and must be installed in your app.
+
 ```bash
-# Using npm
-npm install @janbox/contentful-marketplace-sdk
+# pnpm
+pnpm add @janbox/contentful-marketplace-sdk contentful
 
-# Using yarn
-yarn add @janbox/contentful-marketplace-sdk
+# npm
+npm install @janbox/contentful-marketplace-sdk contentful
 
-# Using pnpm
-pnpm add @janbox/contentful-marketplace-sdk
+# yarn
+yarn add @janbox/contentful-marketplace-sdk contentful
 ```
 
 ## Quick Start
 
-### 1. Configure the SDK
-
-```typescript
-import { ContentfulSDK } from '@janbox/contentful-marketplace-sdk';
-
-// Initialize the SDK with your Contentful credentials
-ContentfulSDK.configure({
-  space: 'your-space-id',
-  accessToken: 'your-access-token',
-  environment: 'master', // optional, defaults to 'master'
+```ts
+import {
+  ContentfulSDK,
+  listBannerCollectionEntries,
+} 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);
+
+const result = await listBannerCollectionEntries({
+  slot: "home_hero",
+  marketCode: "vn",
+  language: "en",
+  platform: "WEB",
+  limit: 10,
 });
+
+console.log(result.data);
 ```
 
-### 2. Fetch Content
-
-```typescript
-import { 
-  listBannerEntries, 
-  listBlogPostEntries, 
-  findBlogPostEntry,
-  listDocCategoryEntries,
-  listDocArticleEntries 
-} from '@janbox/contentful-marketplace-sdk';
-
-// Get banners for a specific market and language
-const banners = await listBannerEntries({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.platform[in]': 'WEB',
-    limit: 10
-  }
-});
+## Configuration
 
-// Get blog posts
-const blogPosts = await listBlogPostEntries({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    order: '-sys.createdAt',
-    limit: 5
-  }
-});
+### `ContentfulSDK.configure(params)`
 
-// Find a specific blog post by slug
-const blogPost = await findBlogPostEntry({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.slug': 'how-to-shop-online'
-  }
-});
+Configure the SDK once before calling entry methods.
 
-// Get documentation categories
-const docCategories = await listDocCategoryEntries({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    order: 'fields.order'
-  }
+```ts
+ContentfulSDK.configure({
+  space: "your-space-id",
+  accessToken: "your-delivery-access-token",
+  environment: "master",
 });
 ```
 
-## Supported Content Types
-
-### 🎯 Banners
-- **Type**: `banner`
-- **Methods**: `listBannerEntries()`
-- **Fields**: name, image, redirectUrl, market, language, platform
-- **Platforms**: `MOBILE`, `WEB`
-
-### 📝 Blog Posts
-- **Type**: `blogPost`
-- **Methods**: `listBlogPostEntries()`, `findBlogPostEntry()`
-- **Fields**: title, slug, author, featuredImage, content, category, shortDescription, seo
-- **Features**: Related posts, categories, SEO metadata
-
-### 📚 Documentation
-- **Types**: `documentationCategory`, `documentationArticle`
-- **Methods**: `listDocCategoryEntries()`, `findDocCategoryEntry()`, `listDocArticleEntries()`, `findDocArticleEntry()`
-- **Features**: Hierarchical categories, searchable articles, SVG icons
-
-### 👤 Authors
-- **Type**: `author`
-- **Fields**: name, avatar
+Notes:
 
-### 🏷️ Categories
-- **Types**: `blogCategory`, `documentationCategory`
-- **Features**: SEO support, hierarchical organization
+- `environment` defaults to `"master"` if omitted.
+- The SDK sends requests to `https://graphql.contentful.com/content/v1/...`.
+- Runtime requires `fetch` (Node.js 18+ recommended).
 
-### 🔍 SEO Metadata
-- **Type**: `seo`
-- **Fields**: metaTitle, metaDescription, metaKeywords, metaRobots
+## API Methods
 
-## API Reference
+All methods return `{ data: ... }`.
 
-### Configuration
+### Banner Collection
 
-#### `ContentfulSDK.configure(params)`
+- `listBannerCollectionEntries(options)`
 
-Configure the SDK with Contentful credentials.
-
-```typescript
-ContentfulSDK.configure({
-  space: string,           // Your Contentful space ID
-  accessToken: string,     // Your Contentful access token
-  environment?: string,    // Environment (default: 'master')
-  host?: string,          // Custom host (optional)
-  // ... other Contentful client options
-});
-```
-
-### Banner Methods
-
-#### `listBannerEntries(options)`
-
-Retrieve multiple banner entries.
-
-```typescript
-const banners = await listBannerEntries({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.platform[in]': 'WEB,MOBILE',
-    limit: 10,
-    order: '-sys.createdAt'
-  }
+```ts
+await listBannerCollectionEntries({
+  slot: "home_hero",
+  limit: 20,
+  platform: "WEB",
+  marketCode: "vn",
+  language: "en",
 });
 ```
 
-### Blog Methods
-
-#### `listBlogPostEntries(options)`
+### Blog
 
-Retrieve multiple blog post entries with basic fields.
+- `listBlogPostEntries(options?)`
+- `findBlogPostEntry(options)`
 
-```typescript
+```ts
 const posts = await listBlogPostEntries({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.category.sys.id': 'category-id',
-    limit: 10,
-    skip: 0
-  }
+  marketCode: "vn",
+  language: "en",
+  limit: 10,
+  skip: 0,
 });
-```
 
-#### `findBlogPostEntry(options)`
-
-Retrieve a single blog post with full content.
-
-```typescript
 const post = await findBlogPostEntry({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.slug': 'my-blog-post'
-  }
+  slug: "how-to-shop-online",
+  marketCode: "vn",
+  language: "en",
 });
 ```
 
-### Documentation Methods
-
-#### `listDocCategoryEntries(options)`
+### Documentation
 
-Retrieve documentation categories.
+- `listDocCategoryEntries(options?)`
+- `findDocCategoryEntry(options)`
+- `listDocArticleEntries(options?)`
+- `findDocArticleEntry(options)`
 
-```typescript
+```ts
 const categories = await listDocCategoryEntries({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    order: 'fields.order'
-  }
+  marketCode: "vn",
+  language: "en",
+  limit: 10,
 });
-```
-
-#### `findDocCategoryEntry(options)`
 
-Find a specific documentation category.
+const articles = await listDocArticleEntries({
+  categorySlug: "getting-started",
+  marketCode: "vn",
+  language: "en",
+  limit: 10,
+});
 
-```typescript
-const category = await findDocCategoryEntry({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.slug': 'getting-started'
-  }
+const article = await findDocArticleEntry({
+  slug: "payment-methods",
+  marketCode: "vn",
+  language: "en",
 });
 ```
 
-#### `listDocArticleEntries(options)`
+### Brand / Hyperlink / Keyword Collections
 
-Retrieve documentation articles.
+- `listBrandCollectionEntries(options?)`
+- `listHyperlinkCollectionEntries(options?)`
+- `listKeywordCollectionEntries(options?)`
 
-```typescript
-const articles = await listDocArticleEntries({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.category.sys.id': 'category-id',
-    order: '-sys.updatedAt'
-  }
+```ts
+const brands = await listBrandCollectionEntries({
+  marketCode: "vn",
+  language: "en",
+  limit: 20,
 });
-```
-
-#### `findDocArticleEntry(options)`
 
-Find a specific documentation article.
+const links = await listHyperlinkCollectionEntries({
+  marketCode: "vn",
+  language: "en",
+});
 
-```typescript
-const article = await findDocArticleEntry({
-  marketId: 'vn',
-  language: 'vi',
-  query: {
-    'fields.slug': 'payment-methods'
-  }
+const keywords = await listKeywordCollectionEntries({
+  marketCode: "vn",
+  language: "en",
+  limit: 20,
 });
 ```
 
 ## Error Handling
 
-The SDK includes built-in error handling for common scenarios:
-
-```typescript
-import { NotFoundResponse } from '@janbox/contentful-marketplace-sdk';
+`findBlogPostEntry`, `findDocCategoryEntry`, and `findDocArticleEntry` throw a `Response` with status `404` when not found.
 
+```ts
 try {
-  const post = await findBlogPostEntry({
-    marketId: 'vn',
-    language: 'vi',
-    query: { 'fields.slug': 'non-existent-post' }
-  });
+  await findDocArticleEntry({ slug: "unknown-slug" });
 } catch (error) {
-  if (error instanceof NotFoundResponse) {
-    console.log('Blog post not found');
+  if (error instanceof Response && error.status === 404) {
+    console.log("Entry not found");
   }
 }
 ```
 
-## Type Definitions
-
-The SDK exports comprehensive TypeScript types for all content:
-
-```typescript
-import type {
-  // Entry Types
-  BannerEntry,
-  BlogPostEntry,
-  DocCategoryEntry,
-  DocArticleEntry,
-  
-  // Skeleton Types
-  TypeBannerSkeleton,
-  TypeBlogPostSkeleton,
-  TypeDocumentationCategorySkeleton,
-  TypeDocumentationArticleSkeleton,
-  
-  // Field Types
-  TypeBannerFields,
-  TypeBlogPostFields,
-  // ... and many more
-} from '@janbox/contentful-marketplace-sdk';
-```
+## Market/Language Filtering Behavior
 
-## Query Options
+When `marketCode` or `language` is provided, queries include both:
 
-All list methods accept Contentful's standard query parameters:
+- entries matching the given code
+- entries where that field is not set
 
-- `limit`: Number of entries to return (max 1000)
-- `skip`: Number of entries to skip
-- `order`: Sort order (e.g., '-sys.createdAt', 'fields.title')
-- `fields.*`: Filter by field values
-- `sys.*`: Filter by system properties
-- `include`: Include linked entries (0-10)
-- `select`: Choose specific fields to return
+This supports global fallback content.
 
-## Development
+## Exported Types
 
-### Prerequisites
+The package exports:
 
-- Node.js 18+
-- pnpm 8+
+- client and entry functions from `src/client` and `src/entries`
+- Contentful schema types from `src/types`
+- entry aliases such as `BlogPostEntry`, `DocArticleEntry`, and `DocCategoryEntry`
 
-### Setup
+## Development
 
-```bash
-# Clone the repository
-git clone https://github.com/your-org/ichiba-contentful-sdk.git
+From repository root:
 
-# Install dependencies
+```bash
 pnpm install
-
-# Build the SDK
-pnpm build:packages
-```
-
-### Project Structure
-
-```
-ichiba-contentful-sdk/
-├── packages/
-│   └── marketplace-sdk/
-│       ├── src/
-│       │   ├── client/         # SDK client configuration
-│       │   ├── entries/        # Content type methods
-│       │   ├── http-responses/ # Custom error responses
-│       │   ├── types/          # TypeScript type definitions
-│       │   └── index.ts        # Main export file
-│       ├── dist/               # Built files
-│       └── package.json
-├── examples/                   # Usage examples
-└── package.json
+pnpm --filter @janbox/contentful-marketplace-sdk build
+pnpm --filter @janbox/contentful-marketplace-sdk test
 ```
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Commit your changes: `git commit -m 'Add amazing feature'`
-4. Push to the branch: `git push origin feature/amazing-feature`
-5. Open a Pull Request
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Support
-
-For questions and support, please contact the iChiba development team or create an issue in the repository.
-
----
-
-**Built with ❤️ by the iChiba team**

package/dist/client/index.d.ts

@@ -1,9 +1,7 @@
-import { ContentfulClientApi, CreateClientParams } from 'contentful';
+import { CreateClientParams } from 'contentful';
 export declare class ContentfulSDK {
-    private static _client;
     private static _clientParams;
     static get clientParams(): CreateClientParams;
-    static get client(): ContentfulClientApi<undefined>;
     static configure(params: CreateClientParams): void;
     static graphqlQuery<T extends object>(query: string, variables?: Record<string, any>): Promise<T>;
 }

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

@@ -0,0 +1,34 @@
+import { 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">;
+export type BannerCollectionGraphQLItem = {
+    sys: GraphQLEntrySys;
+    bannersCollection: {
+        items: Array<{
+            sys: GraphQLEntrySys;
+            hyperlink: ({
+                sys: GraphQLEntrySys;
+            } & Pick<HyperlinkEntry["fields"], "label" | "url" | "target" | "includesMarketCode">) | null;
+            media: {
+                url: string;
+                width: number | null;
+                height: number | null;
+                contentType: string;
+            };
+            name: string;
+        }>;
+    };
+} & Pick<BannerCollectionEntry["fields"], "name" | "slot" | "platform">;
+export type ListBannerCollectionEntriesResponse = {
+    data: BannerCollectionGraphQLItem[];
+};
+export declare const listBannerCollectionEntries: ({ slot, limit, platform, marketCode, language, }: {
+    slot: BannerCollectionEntry["fields"]["slot"];
+    limit?: number;
+    platform?: BannerCollectionEntry["fields"]["platform"][number];
+    marketCode?: string;
+    language?: string;
+}) => Promise<ListBannerCollectionEntriesResponse>;
+export {};

package/dist/entries/blog.d.ts

@@ -1,13 +1,54 @@
-import { EntriesQueries, Entry } from 'contentful';
 import { TypeBlogPostSkeleton } from '../types';
-export type BlogPostEntry = Entry<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
-export declare const listBlogPostEntries: ({ query, marketId, language, }: {
-    marketId: string;
-    language: string;
-    query?: Partial<EntriesQueries<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS">>;
-}) => Promise<import('contentful').EntryCollection<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>>;
-export declare const findBlogPostEntry: ({ query, marketId, language, }: {
-    marketId: string;
-    language: string;
-    query: Partial<EntriesQueries<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS">>;
-}) => Promise<Entry<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>>;
+import { Entry, EntrySys } from 'contentful';
+type BlogPostEntry = Entry<TypeBlogPostSkeleton, "WITHOUT_UNRESOLVABLE_LINKS", string>;
+type GraphQLEntrySys = Pick<EntrySys, "id">;
+type GraphQLAsset = {
+    url: string;
+    width: number | null;
+    height: number | null;
+    contentType: string;
+};
+export type BlogPostGraphQLItem = {
+    sys: GraphQLEntrySys;
+    category: {
+        sys: GraphQLEntrySys;
+        title: string;
+        slug: string;
+    } | null;
+    featuredImage: GraphQLAsset | null;
+} & Pick<BlogPostEntry["fields"], "title" | "shortDescription" | "slug">;
+export type BlogPostDetailGraphQLItem = 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[];
+};
+export type FindBlogPostEntryResponse = {
+    data: BlogPostDetailGraphQLItem;
+};
+export declare const listBlogPostEntries: ({ marketCode, language, limit, skip, }?: {
+    marketCode?: string;
+    language?: string;
+    limit?: number;
+    skip?: number;
+}) => Promise<ListBlogPostEntriesResponse>;
+export declare const findBlogPostEntry: ({ slug, marketCode, language, }: {
+    slug: string;
+    marketCode?: string;
+    language?: string;
+}) => Promise<FindBlogPostEntryResponse>;
+export {};

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

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