@bzbs/react-api-client 1.4.12 → 1.4.13

package/README.md

@@ -1,82 +1,1035 @@
-# Installing
+# @bzbs/react-api-client
 
-Using npm :
+A TypeScript API client library for integrating with Buzzebees services. Provides strongly-typed methods for authentication, campaigns, profiles, shopping carts, notifications, and more.
+
+**Version:** 1.4.12 | **License:** ISC | **Author:** Buzzebees Co., Ltd.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Architecture](#architecture)
+- [API Reference](#api-reference)
+  - [AuthenticateApi](#authenticateapi)
+  - [CampaignApi](#campaignapi)
+  - [ProfileApi](#profileapi)
+  - [CartApi](#cartapi)
+  - [CategoryApi](#categoryapi)
+  - [CouponApi](#couponapi)
+  - [NotificationApi](#notificationapi)
+  - [HistoryApi](#historyapi)
+  - [RegistrationApi](#registrationapi)
+  - [AddressApi](#addressapi)
+  - [BadgeApi](#badgeapi)
+  - [ConsentApi](#consentapi)
+  - [DashboardApi](#dashboardapi)
+  - [LineApi](#lineapi)
+  - [PlaceApi](#placeapi)
+  - [PointLogApi](#pointlogapi)
+  - [StampApi](#stampapi)
+  - [RequestHelpApi (Forum)](#requesthelpapi-forum)
+  - [SettingApi](#settingapi)
+  - [Blob](#blob)
+- [Response Handling](#response-handling)
+- [Error Handling](#error-handling)
+- [Models](#models)
+- [Development](#development)
+- [Build Output](#build-output)
+
+---
+
+## Installation
 
 ```bash
-npm i @bzbs/react-api-client
+npm install @bzbs/react-api-client
 ```
 
-Once the package is installed, you can import the library using import or require approach:
+## Quick Start
 
-```js
+```typescript
+import axios from 'axios';
 import { BzbsService } from '@bzbs/react-api-client';
+
+// 1. Create an Axios instance with default headers
+const axiosClient = axios.create({
+  headers: {
+    'Content-Type': 'application/json',
+    'App-Id': '<your-app-id>',
+    'Ocp-Apim-Subscription-Key': '<your-subscription-key>',
+  },
+});
+
+// 2. Define base URLs
+const baseUrl = 'https://apigateway.buzzebees.com/api/';
+const lineUrl = 'https://api.line.me/';       // Optional, pass "" to skip
+const blobUrl = 'https://blob.buzzebees.com/'; // Blob storage URL
+
+// 3. Create the service
+const bzbsService = new BzbsService(axiosClient, baseUrl, lineUrl, blobUrl);
+
+// 4. Use any API
+const result = await bzbsService.campaignApi.campaigns({
+  config: 'campaign_buzzebeesdemo',
+  byConfig: true,
+  skip: 0,
+  top: 10,
+});
+
+if (result.type === 'success') {
+  console.log(result.model); // Campaign[]
+}
+```
+
+## Configuration
+
+### Constructor
+
+```typescript
+new BzbsService(client: AxiosInstance, baseUrl: string, baseLineUrl: string, baseBlobUrl: string)
 ```
 
-You must to have AxiosInstance, Base URL and Line URL for library require:
+| Parameter | Type | Description |
+|---|---|---|
+| `client` | `AxiosInstance` | Pre-configured Axios instance with headers/interceptors |
+| `baseUrl` | `string` | Buzzebees API base URL |
+| `baseLineUrl` | `string` | LINE API base URL (pass `""` to skip LINE API initialization) |
+| `baseBlobUrl` | `string` | Blob storage base URL |
+
+### Setting Headers
+
+Configure your Axios instance with required headers before creating `BzbsService`:
 
-```js
+```typescript
 const axiosClient = axios.create({});
-const baseUrl = 'https://www.xxx-api.com/api/';
-const lineUrl = 'https://api.line.me/v2/bot/';
+
+// Set default headers
+axiosClient.defaults.headers.common = {
+  'Content-Type': 'application/json, multipart/form-data',
+  'App-Id': '<your-app-id>',
+  'Ocp-Apim-Subscription-Key': '<your-subscription-key>',
+};
+
+// Add auth token via interceptor
+axiosClient.interceptors.request.use((config) => {
+  const token = getStoredToken(); // your token retrieval logic
+  if (token) {
+    config.headers.Authorization = token;
+  }
+  return config;
+});
 ```
 
-And defind const and export libraty to using:
+### Dynamic URL Updates
+
+You can update base URLs at runtime:
 
-```js
-export const bzbsService = new BzbsService(axiosClient, baseUrl, lineUrl);
+```typescript
+bzbsService.setBaseUrl('https://new-api.buzzebees.com/api/');
+bzbsService.setBlobUrl('https://new-blob.buzzebees.com/');
+bzbsService.setLineUrl('https://api.line.me/');
 ```
 
-If you have default header you can add to AxiosInstance brfore:
+---
 
-```js
-const defaultOptions = {
-  headers: {
-    'Content-Type': 'application/json, multipart/form-data',
-    'App-Id': 2952697274802274,
-    'Ocp-Apim-Subscription-Key': '89c1d9bafb65486aa02606f63cb86b5c',
-  },
-};
+## Architecture
+
+The library follows a layered service architecture:
 
-axiosClient.defaults.headers.common = defaultOptions.headers;
+```
+BzbsService (entry point)
+ ├── AuthenticateApi     → auth/
+ ├── BadgeApi            → profile/me/badges
+ ├── CampaignApi         → campaign/
+ ├── CartApi             → cart/
+ ├── CategoryApi         → campaigncat/
+ ├── ConsentApi          → consent/
+ ├── CouponApi           → coupon/
+ ├── DashboardApi        → dashboard/
+ ├── HistoryApi          → redeem/
+ ├── LineApi             → LINE OAuth (optional)
+ ├── NotificationApi     → noti/
+ ├── PlaceApi            → place/
+ ├── PointLogApi         → log/points
+ ├── ProfileApi          → profile/me
+ ├── RegistrationApi     → auth/register
+ ├── AddressApi          → profile/me/address, main/
+ ├── StampApi            → stamp/
+ ├── RequestHelpApi      → buzz/, profile/me/help
+ ├── SettingApi          → setting/
+ └── Blob                → blob storage
 ```
 
-## Example
+All API classes extend `BaseService`, which provides:
+- HTTP methods: `get`, `post`, `put`, `delete`, `patch`
+- Automatic response normalization
+- Error handling with typed responses
+- URL construction utilities
+- FormData creation utility
 
-Create service-config.tsx file:
+### Directory Structure
 
-```tsx
-import { BzbsService } from '@bzbs/react-api-client';
-import axios from 'axios';
+```
+src/
+├── api/
+│   ├── base-service.ts          # Abstract base with HTTP methods
+│   ├── bzbs-service.ts          # Main service aggregator
+│   ├── address/address-api.ts
+│   ├── auth/auth-api.ts
+│   ├── badge/badge-api.ts
+│   ├── blob/blob.ts
+│   ├── campaign/campaign-api.ts
+│   ├── cart/cart-api.ts
+│   ├── category/category-api.ts
+│   ├── consent/consent-api.ts
+│   ├── coupon/coupon-api.ts
+│   ├── dashboard/dashboard-api.ts
+│   ├── history/history-api.ts
+│   ├── line/line-api.ts
+│   ├── notification/notification-api.ts
+│   ├── place/place-api.ts
+│   ├── point-log/point-log-api.ts
+│   ├── profile/profile-api.ts
+│   ├── registration/registration-api.ts
+│   ├── request-help/request-help-api.ts
+│   ├── setting/setting-api.ts
+│   └── stamp/stamp-api.ts
+├── models/                      # TypeScript interfaces
+└── index.ts                     # Re-exports everything
+```
 
-const defaultOptions = {
-  headers: {
-    'Content-Type': 'application/json, multipart/form-data',
-    'App-Id': 2952697274802274,
-    'Ocp-Apim-Subscription-Key': '89c1d9bafb65486aa02606f63cb86b5c',
-  },
+---
+
+## API Reference
+
+Every API method returns `Promise<ServiceResponse<T>>`. All methods accept an optional `requestOptions` parameter as the last argument for custom headers or query params.
+
+### RequestOptions
+
+```typescript
+type RequestOptions = {
+  headers?: { [key: string]: string };
+  params?: { [key: string]: string };
+  data?: any;
+  baseUrl?: string;
 };
+```
+
+---
+
+### AuthenticateApi
+
+Accessed via `bzbsService.authApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `deviceLogin(params)` | Login with device UUID | `LoginResponse` |
+| `facebookLogin(params)` | Login with Facebook access token | `LoginResponse` |
+| `googleLogin(params)` | Login with Google ID token | `LoginResponse` |
+| `lineLogin(params)` | Login with LINE credentials | `LoginResponse` |
+| `appleLogin(params)` | Login with Apple ID token + refresh token | `LoginResponse` |
+| `appleToken(params)` | Request Apple refresh token | `AppleToken` |
+| `usernamePasswordLogin(params)` | Login with username/password | `LoginResponse` |
+| `connectLine(params)` | Connect/login with LINE | `LoginResponse` |
+| `connectFacebook(params)` | Connect/login with Facebook | `LoginResponse` |
+| `connectGoogle(params)` | Connect/login with Google | `LoginResponse` |
+| `connectApple(params)` | Connect/login with Apple | `LoginResponse` |
+| `logout(params)` | Logout user | `unknown` |
+| `forgetPassword(params)` | Send forget password request | `ForgetPasswordResponse` |
+| `resetPassword(params)` | Reset user password | `StatusResponse` |
+| `otp(params)` | Request OTP via GET | `OtpResponse` |
+| `otpV2(params)` | Request OTP via POST | `OtpResponse` |
+| `otpEmail(params)` | Request OTP via email | `OtpResponse` |
+| `confirmOtp(params)` | Confirm OTP | `ConfirmOtpResponse` |
+| `validateOtp(params)` | Validate OTP | `ValidateOtpResponse` |
+| `resume(params)` | Refresh token (session resume) | `ResumeResponse` |
+| `updateDevice(params)` | Update device token for push notifications | `ResumeResponse` |
+| `version(clientVersion)` | Get app version info | `Version` |
+| `versionRaw(clientVersion)` | Get raw version info | `any` |
+
+#### Login Example
+
+```typescript
+const result = await bzbsService.authApi.deviceLogin({
+  appId: 'your-app-id',
+  uuid: 'device-uuid',
+  deviceLocale: 'en',
+  os: 'ios 17.0',
+  platform: 'iPhone',
+  deviceNotificationEnabled: true,
+  clientVersion: 'ios_myapp1.0.0',
+  deviceToken: 'fcm-token',
+  macAddress: 'device-mac-address',
+});
+
+if (result.type === 'success') {
+  const { token, userId, jwt } = result.model;
+  // Store token for subsequent requests
+}
+```
+
+#### OTP Flow Example
+
+```typescript
+// 1. Request OTP
+const otpResult = await bzbsService.authApi.otp({
+  uuid: 'device-uuid',
+  appId: 'your-app-id',
+  contactNumber: '0812345678',
+});
+
+// 2. Validate OTP
+if (otpResult.type === 'success') {
+  const validateResult = await bzbsService.authApi.validateOtp({
+    appId: 'your-app-id',
+    otp: '123456',
+    refCode: otpResult.model.refcode,
+    type: 'contact_number',
+    contactNumber: '0812345678',
+  });
+}
+```
+
+---
+
+### CampaignApi
+
+Accessed via `bzbsService.campaignApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `campaigns(params)` | List campaigns with filtering/sorting | `Campaign[]` |
+| `favoriteCampaigns(params)` | List user's favorite campaigns | `Campaign[]` |
+| `campaignDetails(params)` | Get campaign details by ID | `CampaignDetail` |
+| `addToFavorite(id)` | Add campaign to favorites | `FavoriteResponse` |
+| `removeFromFavorite(params)` | Remove campaign from favorites | `FavoriteResponse` |
+| `redeem(params)` | Redeem a campaign | `RedeemResponse` |
+| `bulkRedeem(params)` | Redeem a campaign in bulk | `RedeemResponse` |
+
+#### Campaign List Parameters
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `config` | `string` | Yes | Campaign list configuration name |
+| `cat` | `string` | No | Category filter |
+| `byConfig` | `boolean` | No | Filter by configuration |
+| `skip` | `number` | No | Pagination offset |
+| `top` | `number` | No | Number of items to retrieve |
+| `keyword` | `string` | No | Search keyword |
+| `sortBy` | `string` | No | Sort order |
+| `center` | `string` | No | Geo coordinates for location-based search |
+| `hashTags` | `string` | No | Filter by hashtags |
+| `sponsorId` | `string` | No | Sponsor filter |
+| `minPoints` | `string` | No | Minimum points filter |
+| `maxPoints` | `string` | No | Maximum points filter |
+
+#### Example
+
+```typescript
+// List campaigns
+const campaigns = await bzbsService.campaignApi.campaigns({
+  config: 'campaign_buzzebeesdemo',
+  byConfig: true,
+  skip: 0,
+  top: 20,
+  keyword: 'coffee',
+  sortBy: 'popular',
+});
+
+// Redeem a campaign
+const redeem = await bzbsService.campaignApi.redeem({
+  id: '12345',
+  contactNumber: '0812345678',
+});
+```
+
+---
+
+### ProfileApi
+
+Accessed via `bzbsService.profileApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `profile()` | Get current user profile | `ProfileResponse` |
+| `updateProfile(params)` | Update user profile (supports image upload) | `ProfileResponse` |
+| `changePassword(params)` | Change user password | `StatusResponse` |
+| `updateShipping(params)` | Update shipping information | `unknown` |
+| `changeContactNumber(params)` | Change contact number (v1) | `ConfirmOtpResponse` |
+| `changeContactNumberV2(params)` | Change contact number (v2) | `any` |
+| `changeContactNumberV3(params)` | Change contact number by user ID (v3) | `any` |
+| `points()` | Get user's current points | `UpdatedPoints` |
+| `expiringPoints()` | Get user's expiring points | `ExpiringPoints` |
+| `deactivate()` | Deactivate user profile | `unknown` |
+
+#### Profile Update Example
+
+```typescript
+// Update profile with image
+const result = await bzbsService.profileApi.updateProfile({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  contactNumber: '0812345678',
+  gender: 'male',
+  birthDate: 946684800, // Unix timestamp in seconds
+  profileImage: fileObject, // File, { uri, name, type }, or object
+});
+```
+
+---
+
+### CartApi
+
+Accessed via `bzbsService.cartApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `addCart(params)` | Add item to cart | `CartCountResponse` |
+| `cartCount()` | Get cart item count | `CartCountResponse` |
+| `cartAccess(params)` | Get cart access token for web landing | `CartAccessResponse` |
+
+```typescript
+await bzbsService.cartApi.addCart({ id: 'campaign-123', qty: 2 });
+const count = await bzbsService.cartApi.cartCount();
+```
+
+---
+
+### CategoryApi
+
+Accessed via `bzbsService.categoryApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `categories(params)` | Get campaign categories | `Category[]` |
+
+```typescript
+const categories = await bzbsService.categoryApi.categories({
+  config: 'campaign_buzzebeesdemo',
+  byConfig: true,
+});
+```
+
+---
+
+### CouponApi
+
+Accessed via `bzbsService.couponApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `processCodes(params)` | Process coupon codes | `CouponResponse` |
+
+```typescript
+const result = await bzbsService.couponApi.processCodes({
+  codes: 'ABCD-1234-EFGH',
+});
+```
+
+---
+
+### NotificationApi
+
+Accessed via `bzbsService.notificationApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `notifications(params)` | Get notifications list | `Notification[]` |
+| `read(params)` | Mark notifications as read | `unknown` |
+
+```typescript
+const notifs = await bzbsService.notificationApi.notifications({
+  mode: 'new',       // 'new' | 'all'
+  sortBy: 'createdate_desc',
+  top: 20,
+  skip: 0,
+});
+
+// Mark as read
+await bzbsService.notificationApi.read({
+  ids: 'rowKey1,rowKey2',
+});
+```
+
+---
+
+### HistoryApi
+
+Accessed via `bzbsService.historyApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `redeemHistories(params)` | Get redeem history | `Purchase[]` |
+| `use(params)` | Mark a redeemed item as used | `UseCampaignResponse` |
+
+```typescript
+const history = await bzbsService.historyApi.redeemHistories({
+  byConfig: true,
+  config: 'campaign_buzzebeesdemo',
+  skip: 0,
+  top: 20,
+});
+
+// Use a coupon
+await bzbsService.historyApi.use({ redeemKey: 'ABC123_1' });
+```
+
+---
+
+### RegistrationApi
+
+Accessed via `bzbsService.registerApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `validateRegister(params)` | Validate registration (triggers OTP) | `OtpResponse` |
+| `register(params)` | Register a new user | `RegistrationResponse` |
+
+**Validation Error Codes:**
+- `2078` - Duplicate contact number
+- `2089` - Duplicate email
+- `401` - Duplicate username
+
+```typescript
+// Step 1: Validate
+const validation = await bzbsService.registerApi.validateRegister({
+  appId: 'your-app-id',
+  username: 'johndoe',
+  email: 'john@example.com',
+  contactNumber: '0812345678',
+});
+
+// Step 2: Register (after OTP verification)
+const registration = await bzbsService.registerApi.register({
+  appId: 'your-app-id',
+  uuid: 'device-uuid',
+  macAddress: 'mac-address',
+  os: 'ios 17.0',
+  platform: 'iPhone',
+  clientVersion: 'ios_myapp1.0.0',
+  deviceNotificationEnable: true,
+  username: 'johndoe',
+  password: 'securepass',
+  confirmPassword: 'securepass',
+  firstName: 'John',
+  lastName: 'Doe',
+  contactNumber: '0812345678',
+  otp: '123456',
+  refCode: 'ABC123',
+  options: {},
+});
+```
+
+---
+
+### AddressApi
+
+Accessed via `bzbsService.addressApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `zipCodes(params)` | Look up zip code information | `ZipCode[]` |
+| `provinces()` | Get Thailand provinces | `Province[]` |
+| `districts(params)` | Get districts by province | `District[]` |
+| `subDistricts(params)` | Get sub-districts by province/district | `SubDistrict[]` |
+| `userAddresses()` | Get user's saved addresses | `Address[]` |
+| `updateAddress(params)` | Create or update an address | `Address` |
+| `deleteAddress(params)` | Delete an address | `unknown` |
+| `userTaxAddresses()` | Get user's tax addresses | `Address[]` |
+| `updateTaxAddress(params)` | Create or update a tax address | `Address` |
+| `deleteTaxAddress(params)` | Delete a tax address | `unknown` |
+
+```typescript
+// Get provinces
+const provinces = await bzbsService.addressApi.provinces();
+
+// Get districts for a province
+const districts = await bzbsService.addressApi.districts({
+  provinceCode: '10',
+});
+
+// Save an address
+await bzbsService.addressApi.updateAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  address: '123 Main St',
+  provinceCode: '10',
+  provinceName: 'Bangkok',
+  districtCode: '1001',
+  districtName: 'Phra Nakhon',
+  zipcode: '10200',
+  contactNumber: '0812345678',
+  isDefault: true,
+});
+```
+
+---
+
+### BadgeApi
 
-var axiosClient = axios.create({});
-axiosClient.defaults.headers.common = defaultOptions.headers;
+Accessed via `bzbsService.badgeApi`.
 
-const baseUrl = 'https://apigateway.buzzebees-uat.com/api/';
-const lineUrl = 'https://api.line.me/v2/bot/';
+| Method | Description | Returns |
+|---|---|---|
+| `badges(params)` | Get user badges | `Badge[]` |
 
-export const bzbsService = new BzbsService(axiosClient, baseUrl, lineUrl);
+```typescript
+const badges = await bzbsService.badgeApi.badges({});
+// Or filter by badge ID
+const badge = await bzbsService.badgeApi.badges({ badgeId: '123' });
 ```
 
-Using service API in another files:
+---
 
-```tsx
-import { bzbsService } from './src/service-config';
+### ConsentApi
 
-const campaigList = async () => {
-  await bzbsService.campaignApi?.campaign({
-    config: 'campaign_buzzebeesdemo',
-    byConfig: true,
-    skip: 0,
-    top: 10,
-    deviceLocale: 1054,
+Accessed via `bzbsService.consentApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `consent()` | Get user's consent status | `Consent` |
+| `updateConsent(params)` | Update consent preferences | `Consent` |
+| `unconsent()` | Withdraw all consent | `unknown` |
+
+```typescript
+// Get consent
+const consent = await bzbsService.consentApi.consent();
+
+// Update consent
+await bzbsService.consentApi.updateConsent({
+  termsAndConditions: '1.0',
+  dataPrivacy: '1.0',
+  marketingOption: '1.0',
+  email: '1',          // '0' or '1'
+  sms: '1',
+  notification: '1',
+  line: '0',
+});
+```
+
+---
+
+### DashboardApi
+
+Accessed via `bzbsService.dashboardApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `mainDashboard(params)` | Get main dashboard data | `Dashboard[]` |
+| `subDashboard(params)` | Get sub-dashboard data | `Dashboard[]` |
+
+```typescript
+const dashboard = await bzbsService.dashboardApi.mainDashboard({
+  appName: 'buzzebeesdemo',
+  locale: 1054, // Thai locale
+});
+
+const subDashboard = await bzbsService.dashboardApi.subDashboard({
+  dashboardName: 'featured',
+  locale: 1054,
+});
+```
+
+---
+
+### LineApi
+
+Accessed via `bzbsService.lineApi` (only initialized if `baseLineUrl` is provided).
+
+| Method | Description | Returns |
+|---|---|---|
+| `lineAuth(params)` | Authenticate with LINE OAuth | `LineAuthResponse` |
+
+```typescript
+if (bzbsService.lineApi) {
+  const lineAuth = await bzbsService.lineApi.lineAuth({
+    grantType: 'authorization_code',
+    code: 'auth-code-from-line',
+    clientId: 'line-channel-id',
+    clientSecret: 'line-channel-secret',
+    redirectUrl: 'https://myapp.com/callback',
   });
+}
+```
+
+---
+
+### PlaceApi
+
+Accessed via `bzbsService.placeApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `placeList(params)` | List places with location search | `Place[]` |
+| `place(params)` | Get place details | `Place` |
+| `addToFavourite(params)` | Add place to favorites | `unknown` |
+| `removeFromFavourite(params)` | Remove place from favorites | `unknown` |
+
+```typescript
+const places = await bzbsService.placeApi.placeList({
+  agencyId: '123',
+  center: '13.7563,100.5018', // lat,lng
+  distance: 5000,
+  top: 20,
+  keyword: 'cafe',
+});
+```
+
+---
+
+### PointLogApi
+
+Accessed via `bzbsService.pointLogApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `getPointLog(params)` | Get point transaction log | `PointLog[]` |
+
+```typescript
+const logs = await bzbsService.pointLogApi.getPointLog({
+  month: '2025-01',
+  type: 'earn',  // 'earn' | 'burn' | etc.
+  top: 50,
+});
+```
+
+---
+
+### StampApi
+
+Accessed via `bzbsService.stampApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `createStamp(params)` | Create a new stamp | `CreateStampResponse` |
+| `stamps(options)` | List all stamps | `Stamp[]` |
+| `stampProfile(params)` | Get stamp card profile/details | `StampProfileResponse` |
+
+```typescript
+const stamps = await bzbsService.stampApi.stamps({});
+
+const profile = await bzbsService.stampApi.stampProfile({
+  id: 'stamp-123',
+  cardId: 'card-456',
+});
+```
+
+---
+
+### RequestHelpApi (Forum)
+
+Accessed via `bzbsService.forumApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `helpCode(params)` | Get help request code | `RequestHelpCode` |
+| `requestHelpList(params)` | List help request messages | `ChatMessage[]` |
+| `requestDetail(params)` | Get help request detail | `ChatMessage` |
+| `postRequestHelp(params)` | Post a help request (supports image) | `ChatMessage` |
+| `comments(params)` | Get comments on a post | `ChatMessage[]` |
+| `postComment(params)` | Post a comment (supports image) | `ChatMessage` |
+| `like(params)` | Like a post | `LikeForumResponse` |
+| `unlike(params)` | Unlike a post | `LikeForumResponse` |
+
+```typescript
+// Create a help request
+const helpCode = await bzbsService.forumApi.helpCode({
+  os: 'ios 17.0',
+  platform: 'iPhone',
+  clientVersion: 'ios_myapp1.0.0',
+});
+
+// Post a message
+await bzbsService.forumApi.postRequestHelp({
+  requestId: 'req-123',
+  message: 'I need help with my order',
+  image: imageFile, // optional File
+});
+```
+
+---
+
+### SettingApi
+
+Accessed via `bzbsService.settingApi`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `accessKey(params)` | Get access key for web landing pages | `AccessTokenResponse` |
+
+```typescript
+const accessKey = await bzbsService.settingApi.accessKey({
+  data: JSON.stringify({
+    app_id: 'your-app-id',
+    campaign_id: 12345,
+    locale: 1054,
+    return_url: 'myapp://callback',
+    version: '2',
+  }),
+});
+```
+
+---
+
+### Blob
+
+Accessed via `bzbsService.blob`.
+
+| Method | Description | Returns |
+|---|---|---|
+| `consentVersion(appId)` | Get PDPA consent version | `ConsentVersion` |
+| `maintenance(appId)` | Get maintenance configuration | `Maintenance` |
+| `blob(path)` | Fetch any blob storage path | `unknown` |
+
+```typescript
+const consentVersion = await bzbsService.blob.consentVersion('your-app-id');
+const maintenance = await bzbsService.blob.maintenance('your-app-id');
+```
+
+---
+
+## Response Handling
+
+All API methods return `ServiceResponse<T>`, a discriminated union type:
+
+```typescript
+type ServiceResponse<T> = SuccessResponse<T> | ErrorResponse;
+```
+
+### Success Response
+
+```typescript
+type SuccessResponse<T> = {
+  type: 'success';
+  model: T;              // The typed response data
+  response: AxiosResponse; // Raw Axios response
+};
+```
+
+### Error Response
+
+```typescript
+type ErrorResponse = ClientError | ServerError;
+
+type ServerError = {
+  type: 'server-error';
+  error: BzbsErrorResponse;  // { requestId, error: { id, message, code, type } }
+  statusCode: number;
+  response: AxiosResponse;
 };
+
+type ClientError = {
+  type: 'client-error';
+  message: string;
+  details?: any;
+};
+```
+
+### Usage Pattern
+
+```typescript
+const result = await bzbsService.campaignApi.campaigns({
+  config: 'campaign_list',
+});
+
+switch (result.type) {
+  case 'success':
+    // result.model is Campaign[]
+    console.log(result.model);
+    break;
+
+  case 'server-error':
+    // Server returned an error
+    console.error(result.error.error?.message);
+    console.error('Status:', result.statusCode);
+    break;
+
+  case 'client-error':
+    // Network error or client-side issue
+    console.error(result.message);
+    break;
+}
 ```
+
+### Response Normalization
+
+The library automatically handles both uppercase and lowercase API response formats:
+- `{ Success: true, Data: ... }` and `{ success: true, data: ... }` are both supported
+- HTTP 204 responses return an empty object as the model
+- Non-standard responses (without success flags) are treated as raw data
+
+---
+
+## Error Handling
+
+### BzbsErrorResponse
+
+```typescript
+interface BzbsErrorResponse {
+  requestId?: string;
+  error?: {
+    id?: number;
+    message?: string;
+    code?: number;
+    type?: string;
+  };
+}
+```
+
+### Common Error Codes
+
+| Code | Description |
+|---|---|
+| `401` | Unauthorized / Duplicate username |
+| `2078` | Duplicate contact number |
+| `2089` | Duplicate email |
+
+---
+
+## Models
+
+All TypeScript interfaces are exported from `@bzbs/react-api-client` and can be imported directly:
+
+```typescript
+import {
+  Campaign,
+  CampaignDetail,
+  ProfileResponse,
+  LoginResponse,
+  Purchase,
+  // ... etc
+} from '@bzbs/react-api-client';
+```
+
+### Key Models
+
+| Model | Description |
+|---|---|
+| `LoginResponse` | Token, userId, jwt, consent status, points |
+| `Campaign` | Campaign list item (ID, name, points, dates, images) |
+| `CampaignDetail` | Full campaign details with pictures, subcampaigns, conditions |
+| `ProfileResponse` | User profile with personal info, address, shipping, marketing preferences |
+| `Purchase` | Redeem history item with usage status, voucher info, delivery status |
+| `Address` | User address with full Thailand address structure, tax fields |
+| `Notification` | Push notification with object type, category, read status |
+| `Place` | Store/place with location, services, working hours |
+| `Dashboard` | Dashboard configuration item with images and metadata |
+| `Consent` | User consent status for terms, privacy, marketing channels, cookies |
+| `ConsentVersion` | PDPA consent version from blob storage |
+| `Maintenance` | App maintenance configuration |
+| `Badge` | User badge information |
+| `Category` | Campaign category |
+| `PointLog` | Point transaction record |
+| `Stamp` | Stamp card information |
+| `StampProfileResponse` | Stamp card profile details |
+| `OtpResponse` | OTP request response with reference code |
+| `ConfirmOtpResponse` | OTP confirmation result |
+| `ValidateOtpResponse` | OTP validation result |
+| `RedeemResponse` | Campaign redemption result |
+| `FavoriteResponse` | Favorite toggle response |
+| `UseCampaignResponse` | Coupon usage result |
+| `CartCountResponse` | Cart item count |
+| `CartAccessResponse` | Cart web landing access token |
+| `AccessTokenResponse` | Web landing access token |
+| `LineAuthResponse` | LINE OAuth token response |
+| `AppleToken` | Apple refresh token response |
+| `ResumeResponse` | Session resume/token refresh response |
+| `Version` | App version info |
+| `RegistrationResponse` | Registration result |
+| `ForgetPasswordResponse` | Password reset request result |
+| `StatusResponse` | Generic status response |
+| `RequestHelpCode` | Help request code |
+| `ChatMessage` | Forum/help chat message |
+| `LikeForumResponse` | Forum like/unlike result |
+| `Province` | Thailand province |
+| `District` | Thailand district |
+| `SubDistrict` | Thailand sub-district |
+| `ZipCode` | Zip code information |
+| `UpdatedPoints` | User points with timestamp |
+| `ExpiringPoints` | User expiring points info |
+| `PointUnit` | Point service unit configuration |
+
+---
+
+## Development
+
+### Prerequisites
+
+- Node.js
+- npm
+
+### Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library (CJS + ESM + type declarations)
+npm run build
+
+# Run tests in watch mode with coverage
+npm test
+
+# Lint source files
+npm run lint
+
+# Auto-fix lint issues
+npm run lint:fix
+
+# Format code with Prettier
+npm run format
+```
+
+### Publishing
+
+```bash
+npm run patch   # Build, bump patch version, publish
+npm run minor   # Build, bump minor version, publish
+npm run major   # Build, bump major version, publish
+```
+
+### Adding a New API
+
+1. Create a new directory under `src/api/` (e.g., `src/api/my-feature/`)
+2. Create an API class that extends `BaseService`:
+
+```typescript
+import { AxiosInstance } from 'axios';
+import { BaseService, RequestOptions, ServiceResponse } from '../base-service';
+import { MyModel } from '../../models/my-model';
+
+export class MyFeatureApi extends BaseService {
+  constructor(client: AxiosInstance, baseUrl: string) {
+    super(client, baseUrl);
+  }
+
+  public async getItems(
+    params: { id: string; options?: { [key: string]: unknown } },
+    requestOptions?: RequestOptions
+  ): Promise<ServiceResponse<MyModel[]>> {
+    return await this.get<MyModel[]>(
+      `my-feature/${params.id}`,
+      { ...params.options },
+      requestOptions
+    );
+  }
+}
+```
+
+3. Create model interfaces in `src/models/`
+4. Export from `src/models/index.ts` and `src/api/index.ts`
+5. Add the API to `BzbsService` class and its `setBaseUrl()` method
+
+---
+
+## Build Output
+
+The build process (tsup) generates:
+
+| File | Format | Description |
+|---|---|---|
+| `dist/index.js` | CommonJS | For `require()` usage |
+| `dist/index.mjs` | ES Module | For `import` usage |
+| `dist/index.d.ts` | TypeScript | Type declarations |
+| `dist/*.map` | Source Maps | For debugging |