@bzbs/react-api-client 1.4.14 → 1.4.15

package/README.md

@@ -1,8 +1,11 @@
 # @bzbs/react-api-client
 
-A TypeScript API client library for integrating with Buzzebees services. Provides strongly-typed methods for authentication, campaigns, profiles, shopping carts, notifications, and more.
+A TypeScript library providing a type-safe API client for Buzzebees loyalty and reward services. Supports authentication, campaigns, user profiles, shopping carts, notifications, stamps, consent management, and more.
 
-**Version:** 1.4.12 | **License:** ISC | **Author:** Buzzebees Co., Ltd.
+**Version:** 1.4.14 | **License:** ISC | **Author:** Buzzebees Co., Ltd.
+**Repository:** [Azure DevOps](https://dev.azure.com/buzzebees/Buzzebees/_git/React_API_Client)
+
+---
 
 ## Table of Contents
 
@@ -10,6 +13,9 @@ A TypeScript API client library for integrating with Buzzebees services. Provide
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
 - [Architecture](#architecture)
+- [BzbsService Properties](#bzbsservice-properties)
+- [Response Handling](#response-handling)
+- [Complete API Endpoint Table](#complete-api-endpoint-table)
 - [API Reference](#api-reference)
   - [AuthenticateApi](#authenticateapi)
   - [CampaignApi](#campaignapi)
@@ -31,10 +37,11 @@ A TypeScript API client library for integrating with Buzzebees services. Provide
   - [RequestHelpApi (Forum)](#requesthelpapi-forum)
   - [SettingApi](#settingapi)
   - [Blob](#blob)
-- [Response Handling](#response-handling)
-- [Error Handling](#error-handling)
-- [Models](#models)
-- [Development](#development)
+- [Models Reference](#models-reference)
+- [BaseService Utilities](#baseservice-utilities)
+- [Testing Guide](#testing-guide)
+- [Development Commands](#development-commands)
+- [Adding a New API](#adding-a-new-api)
 - [Build Output](#build-output)
 
 ---
@@ -45,6 +52,14 @@ A TypeScript API client library for integrating with Buzzebees services. Provide
 npm install @bzbs/react-api-client
 ```
 
+Peer dependency: `axios`
+
+```bash
+npm install axios
+```
+
+---
+
 ## Quick Start
 
 ```typescript
@@ -81,6 +96,8 @@ if (result.type === 'success') {
 }
 ```
 
+---
+
 ## Configuration
 
 ### Constructor
@@ -122,8 +139,6 @@ axiosClient.interceptors.request.use((config) => {
 
 ### Dynamic URL Updates
 
-You can update base URLs at runtime:
-
 ```typescript
 bzbsService.setBaseUrl('https://new-api.buzzebees.com/api/');
 bzbsService.setBlobUrl('https://new-blob.buzzebees.com/');
@@ -134,9 +149,10 @@ bzbsService.setLineUrl('https://api.line.me/');
 
 ## Architecture
 
-The library follows a layered service architecture:
-
 ```
+Consumer Code
+     │
+     ▼
 BzbsService (entry point)
  ├── AuthenticateApi     → auth/
  ├── BadgeApi            → profile/me/badges
@@ -158,12 +174,18 @@ BzbsService (entry point)
  ├── RequestHelpApi      → buzz/, profile/me/help
  ├── SettingApi          → setting/
  └── Blob                → blob storage
+          │
+          ▼
+     BaseService          ← Abstract HTTP layer
+          │
+          ▼
+     AxiosInstance        ← Consumer-injected, fully configurable
 ```
 
 All API classes extend `BaseService`, which provides:
 - HTTP methods: `get`, `post`, `put`, `delete`, `patch`
-- Automatic response normalization
-- Error handling with typed responses
+- Automatic response normalization (handles both `{ Success, Data }` and `{ success, data }` formats)
+- Error handling with typed `ServiceResponse<T>`
 - URL construction utilities
 - FormData creation utility
 
@@ -200,11 +222,92 @@ src/
 
 ---
 
-## API Reference
+## BzbsService Properties
 
-Every API method returns `Promise<ServiceResponse<T>>`. All methods accept an optional `requestOptions` parameter as the last argument for custom headers or query params.
+| Property | Type | Description |
+|---|---|---|
+| `authApi` | `AuthenticateApi` | Authentication, login, OTP, session management |
+| `badgeApi` | `BadgeApi` | User badges and missions |
+| `campaignApi` | `CampaignApi` | Campaigns, redemption, favorites |
+| `cartApi` | `CartApi` | Shopping cart |
+| `categoryApi` | `CategoryApi` | Campaign categories |
+| `consentApi` | `ConsentApi` | PDPA / privacy consent |
+| `couponApi` | `CouponApi` | Coupon code processing |
+| `dashboardApi` | `DashboardApi` | Dashboard content |
+| `historyApi` | `HistoryApi` | Redemption history, voucher usage |
+| `lineApi` | `LineApi \| undefined` | LINE OAuth (only if `baseLineUrl` provided) |
+| `notificationApi` | `NotificationApi` | Push notifications |
+| `placeApi` | `PlaceApi` | Locations / stores |
+| `pointLogApi` | `PointLogApi` | Point transaction logs |
+| `profileApi` | `ProfileApi` | User profile, points, account |
+| `registerApi` | `RegistrationApi` | User registration |
+| `addressApi` | `AddressApi` | Addresses, provinces, districts |
+| `stampApi` | `StampApi` | Stamp cards |
+| `forumApi` | `RequestHelpApi` | Help/support forum (Buzz) |
+| `settingApi` | `SettingApi` | Web landing / cart settings |
+| `blob` | `Blob` | Blob storage, maintenance, consent versions |
 
-### RequestOptions
+---
+
+## Response Handling
+
+All API methods return `Promise<ServiceResponse<T>>`, a discriminated union:
+
+```typescript
+type ServiceResponse<T> = SuccessResponse<T> | ErrorResponse;
+
+type SuccessResponse<T> = {
+  type: 'success';
+  model: T;              // The typed response data
+  response: AxiosResponse;
+};
+
+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: 'main' });
+
+switch (result.type) {
+  case 'success':
+    console.log(result.model); // Campaign[]
+    break;
+
+  case 'server-error':
+    console.error(result.error.error?.message);
+    console.error('Status:', result.statusCode);
+    break;
+
+  case 'client-error':
+    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
+
+### Custom Request Headers
+
+Pass `RequestOptions` as the last argument to any API method:
 
 ```typescript
 type RequestOptions = {
@@ -213,13 +316,122 @@ type RequestOptions = {
   data?: any;
   baseUrl?: string;
 };
+
+const response = await bzbsService.profileApi.profile(undefined, {
+  headers: { 'Accept-Language': 'th' },
+});
 ```
 
 ---
 
+## Complete API Endpoint Table
+
+> All endpoints are relative to `baseUrl` (constructor param), except `LineApi` (uses `baseLineUrl`) and `Blob` (uses `baseBlobUrl`).
+>
+> **Feature Tags:** `#auth` `#campaign` `#cart` `#category` `#consent` `#coupon` `#dashboard` `#history` `#line` `#notification` `#place` `#points` `#profile` `#registration` `#address` `#stamp` `#forum` `#setting` `#blob`
+
+| Service | Method | HTTP | Endpoint | Key Parameters | Return Model | Tags |
+|---|---|---|---|---|---|---|
+| `authApi` | `deviceLogin` | POST | `auth/device_login` | appId, uuid, deviceLocale, os, platform, deviceToken, macAddress; opt: otp, refcode, contact_number | `LoginResponse` | `#auth` |
+| `authApi` | `facebookLogin` | POST | `auth/login` | accessToken, appId, uuid, deviceLocale, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth` |
+| `authApi` | `googleLogin` | POST | `auth/google_login` | idToken, appId, uuid, deviceLocale, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth` |
+| `authApi` | `lineLogin` | POST | `auth/line_login` | idToken, lineAccessToken, authorizationCode, appId, uuid, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth #line` |
+| `authApi` | `appleLogin` | POST | `auth/apple_login` | idToken, refreshToken, appId, uuid, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth` |
+| `authApi` | `appleToken` | POST | `auth/apple_token` | authorizationCode, idToken, appId, os, platform, macAddress, clientVersion | `AppleToken` | `#auth` |
+| `authApi` | `usernamePasswordLogin` | POST | `auth/bzbs_login` | username, password, appId, uuid, deviceLocale, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth` |
+| `authApi` | `connectLine` | POST | `auth/line_login` | idToken, lineAccessToken, authorizationCode, appId, uuid, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth #line` |
+| `authApi` | `connectFacebook` | POST | `auth/login` | accessToken, appId, uuid, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth` |
+| `authApi` | `connectGoogle` | POST | `auth/google_login` | idToken, appId, uuid, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth` |
+| `authApi` | `connectApple` | POST | `auth/apple_login` | idToken, refreshToken, appId, uuid, os, platform, deviceToken, macAddress | `LoginResponse` | `#auth` |
+| `authApi` | `logout` | POST | `auth/logout` | uuid | `unknown` | `#auth` |
+| `authApi` | `forgetPassword` | GET | `profile/{contact}/forget_password` | contact, type (`email`\|`contact_number`) | `ForgetPasswordResponse` | `#auth #profile` |
+| `authApi` | `resetPassword` | POST | `profile/{contact}/forget_password` | contact, refCode, newPassword; opt: otp | `StatusResponse` | `#auth #profile` |
+| `authApi` | `otp` | GET | `auth/otp` | uuid, appId, contactNumber; opt: channel | `OtpResponse` | `#auth` |
+| `authApi` | `otpV2` | POST | `auth/otp` | appId, contactNumber; opt: channel | `OtpResponse` | `#auth` |
+| `authApi` | `otpEmail` | GET | `auth/otp_email` | uuid, appId, email; opt: channel | `OtpResponse` | `#auth` |
+| `authApi` | `confirmOtp` | POST | `auth/bzbs_authen` | otp, refCode, contactNumber | `ConfirmOtpResponse` | `#auth` |
+| `authApi` | `validateOtp` | POST | `auth/validate_otp` | appId, otp, refCode, type; opt: contactNumber, email, use, channel | `ValidateOtpResponse` | `#auth` |
+| `authApi` | `resume` | POST | `auth/device_resume` | uuid, deviceAppId, os, platform, macAddress, deviceNotificationEnabled, clientVersion, deviceToken | `ResumeResponse` | `#auth` |
+| `authApi` | `updateDevice` | POST | `auth/update_device` | uuid, deviceAppId, os, platform, macAddress, deviceNotificationEnabled, clientVersion, deviceToken | `ResumeResponse` | `#auth` |
+| `authApi` | `version` | GET | `auth/version` | clientVersion | `Version` | `#auth` |
+| `authApi` | `versionRaw` | GET | `auth/version` | clientVersion | `any` | `#auth` |
+| `badgeApi` | `badges` | GET | `profile/me/badges` | opt: badgeId | `Badge[]` | `#profile` |
+| `campaignApi` | `campaigns` | GET | `campaign` | config; opt: cat, byConfig, skip, top, locale, keyword, startDate, sponsorId, maxPoints, minPoints, sortBy, center, hashTags, locationAgencyId | `Campaign[]` | `#campaign` |
+| `campaignApi` | `favoriteCampaigns` | GET | `profile/me/favourite_campaign` | opt: skip, top, locale | `Campaign[]` | `#campaign #profile` |
+| `campaignApi` | `campaignDetails` | GET | `campaign/{id}` | id; opt: deviceLocale | `CampaignDetail` | `#campaign` |
+| `campaignApi` | `addToFavorite` | POST | `campaign/{id}/favourite` | id | `FavoriteResponse` | `#campaign` |
+| `campaignApi` | `removeFromFavorite` | DELETE | `campaign/{id}/favourite` | id | `FavoriteResponse` | `#campaign` |
+| `campaignApi` | `redeem` | POST | `campaign/{id}/redeem` | id; opt: addressKey, contactNumber, pointUnit, spPoints | `RedeemResponse` | `#campaign #points` |
+| `campaignApi` | `bulkRedeem` | POST | `campaign/{id}/bulkredeem` | id, quantity; opt: addressKey, contactNumber, pointUnit, spPoints | `RedeemResponse` | `#campaign #points` |
+| `cartApi` | `addCart` | POST | `cart/{id}/add` | id; opt: mode, qty, sideCampaignJson | `CartCountResponse` | `#cart #campaign` |
+| `cartApi` | `cartCount` | GET | `cart/count` | opt: options | `CartCountResponse` | `#cart` |
+| `cartApi` | `cartAccess` | POST | `setting` | errorUrl, successUrl, returnUrl, appId, appName | `CartAccessResponse` | `#cart #setting` |
+| `categoryApi` | `categories` | GET | `campaigncat/menu` | config; opt: byConfig | `Category[]` | `#category #campaign` |
+| `consentApi` | `consent` | GET | `consent` | opt: options | `Consent` | `#consent` |
+| `consentApi` | `updateConsent` | POST | `consent` | opt: termsAndConditions, dataPrivacy, marketingOption, consentAge, email, sms, notification, line, analyticsBuzzebeesCookies, analyticsFirebaseCookies, analyticsGoogleCookies, analyticsMetaCookies, analyticsOtherCookies, functionalCookies, marketingCookies, necessaryCookies | `Consent` | `#consent` |
+| `consentApi` | `unconsent` | POST | `consent/unconsent` | opt: options | `unknown` | `#consent` |
+| `couponApi` | `processCodes` | POST | `coupon/process` | codes (string) | `CouponResponse` | `#coupon #campaign` |
+| `dashboardApi` | `mainDashboard` | GET | `dashboard/main` | appName, locale | `Dashboard[]` | `#dashboard` |
+| `dashboardApi` | `subDashboard` | GET | `dashboard/{dashboardName}` | dashboardName, locale | `Dashboard[]` | `#dashboard` |
+| `historyApi` | `redeemHistories` | GET | `redeem` | byConfig, config, skip, top; opt: locale, startDate, endDate | `Purchase[]` | `#history #campaign` |
+| `historyApi` | `use` | POST | `redeem/{redeemKey}/use` | redeemKey | `UseCampaignResponse` | `#history #campaign` |
+| `lineApi` | `lineAuth` | POST | `oauth2/v2.1/token` _(baseLineUrl)_ | grantType, code, clientId, clientSecret, redirectUrl | `LineAuthResponse` | `#line #auth` |
+| `notificationApi` | `notifications` | GET | `noti` | mode (`new`\|`all`), sortBy (`createdate_desc`\|`createdate_asc`); opt: top, skip | `Notification[]` | `#notification` |
+| `notificationApi` | `read` | POST | `noti/read` | ids (comma-separated) | `unknown` | `#notification` |
+| `placeApi` | `placeList` | GET | `place` | agencyId, center, distance, top; opt: provinceCode, category, mode, requiredCampaign, keyword, isFavourite | `Place[]` | `#place` |
+| `placeApi` | `place` | GET | `place/{id}` | id, agencyId; opt: requiredCampaign, isFavourite | `Place` | `#place` |
+| `placeApi` | `addToFavourite` | POST | `place/{id}/favourite` | id | `unknown` | `#place` |
+| `placeApi` | `removeFromFavourite` | POST | `place/{id}/unfavourite` | id | `unknown` | `#place` |
+| `pointLogApi` | `getPointLog` | GET | `log/points` | month; opt: type, lastRowKey, top | `PointLog[]` | `#points #profile` |
+| `profileApi` | `profile` | GET | `profile/me` | opt: options | `ProfileResponse` | `#profile` |
+| `profileApi` | `updateProfile` | POST | `profile/me` | opt: profileImage (File), firstName, lastName, contactNumber, email, notification, locale, title, gender, birthDate, address, subdistrictCode, districtCode, provinceCode, countryCode, zipCode, idCard, passport, maritalStatus, displayName, latitude, longitude, income, interests, region, occupation, remark, ... | `ProfileResponse` | `#profile` |
+| `profileApi` | `changePassword` | POST | `profile/me/change_password` | current, change | `StatusResponse` | `#profile #auth` |
+| `profileApi` | `updateShipping` | POST | `profile/me/shipping` | opt: shippingFirstName, shippingLastName, shippingProvinceCode, shippingDistrictCode, shippingSubDistrictCode, shippingZipCode, shippingAddress, shippingContactNumber, ... | `unknown` | `#profile #address` |
+| `profileApi` | `changeContactNumber` | POST | `auth/change_authen` | contactNumber, otp, refCode; opt: idCard | `ConfirmOtpResponse` | `#profile #auth` |
+| `profileApi` | `changeContactNumberV2` | POST | `profile/me/contact_number` | contactNumber, otp, refCode | `any` | `#profile #auth` |
+| `profileApi` | `changeContactNumberV3` | POST | `profile/{userId}/contact_number` | userId, contactNumber, otp, refCode | `any` | `#profile #auth` |
+| `profileApi` | `points` | GET | `profile/me/updated_points` | opt: options | `UpdatedPoints` | `#profile #points` |
+| `profileApi` | `expiringPoints` | GET | `profile/me/allexpiring_points` | opt: options | `ExpiringPoints` | `#profile #points` |
+| `profileApi` | `deactivate` | POST | `profile/me/deactivate` | opt: options | `unknown` | `#profile` |
+| `registerApi` | `validateRegister` | POST | `auth/validate_register` | appId, username, email, contactNumber | `OtpResponse` | `#registration #auth` |
+| `registerApi` | `register` | POST | `auth/register` | appId, uuid, macAddress, os, platform, clientVersion, deviceNotificationEnable, username, password, confirmPassword, firstName, lastName, contactNumber, otp, refCode, options; opt: address, gender, birthdate, email, refUserCode, termAndConditionVersion, dataPrivacyVersion, marketingOptionsVersion, consentAge, emailMarketing, smsMarketing, notificationMarketing, lineMarketing, phoneMarketing | `RegistrationResponse` | `#registration #auth` |
+| `addressApi` | `zipCodes` | GET | `main/postcode` | opt: zipCode | `ZipCode[]` | `#address` |
+| `addressApi` | `provinces` | GET | `main/province` | opt: options | `Province[]` | `#address` |
+| `addressApi` | `districts` | GET | `main/district` | opt: provinceCode | `District[]` | `#address` |
+| `addressApi` | `subDistricts` | GET | `main/subdistrict` | opt: provinceCode, districtCode | `SubDistrict[]` | `#address` |
+| `addressApi` | `userAddresses` | GET | `profile/me/addresses` | opt: options | `Address[]` | `#address #profile` |
+| `addressApi` | `updateAddress` | POST | `profile/me/address` | opt: name, addressName, firstName, lastName, address, zipcode, provinceCode, provinceName, districtCode, districtName, subDistrictCode, subDistrictName, contactNumber, countryCode, countryName, isDefault, rowKey | `Address` | `#address #profile` |
+| `addressApi` | `deleteAddress` | DELETE | `profile/me/address` | opt: rowKey | `unknown` | `#address #profile` |
+| `addressApi` | `userTaxAddresses` | GET | `profile/me/taxes` | opt: options | `Address[]` | `#address #profile` |
+| `addressApi` | `updateTaxAddress` | POST | `profile/me/tax` | opt: rowKey, taxId, isDefault, personType, title, name, firstName, lastName, email, contactNumber, companyName, address, addressName, floor, building, moo, road, room, soi, village, districtCode, provinceName, subDistrictCode, zipcode | `Address` | `#address #profile` |
+| `addressApi` | `deleteTaxAddress` | DELETE | `profile/me/tax` | opt: rowKey | `unknown` | `#address #profile` |
+| `stampApi` | `createStamp` | POST | `stamp/create` | opt: imei, issuer, os, platform | `CreateStampResponse` | `#stamp` |
+| `stampApi` | `stamps` | GET | `stamp` | options | `Stamp[]` | `#stamp` |
+| `stampApi` | `stampProfile` | GET | `stamp/{id}/profile` | id, cardId | `StampProfileResponse` | `#stamp` |
+| `forumApi` | `helpCode` | POST | `profile/me/help` | os, platform, clientVersion | `RequestHelpCode` | `#forum #profile` |
+| `forumApi` | `requestHelpList` | GET | `buzz/{requestId}/list` | requestId | `ChatMessage[]` | `#forum` |
+| `forumApi` | `requestDetail` | GET | `buzz/{buzzKey}` | buzzKey | `ChatMessage` | `#forum` |
+| `forumApi` | `postRequestHelp` | POST | `buzz/{requestId}/buzz` | requestId, message; opt: image (File) | `ChatMessage` | `#forum` |
+| `forumApi` | `comments` | GET | `buzz/{buzzKey}/comments` | buzzKey; opt: lastRowKey | `ChatMessage[]` | `#forum` |
+| `forumApi` | `postComment` | POST | `buzz/{buzzKey}/comments` | buzzKey, message; opt: image (File) | `ChatMessage` | `#forum` |
+| `forumApi` | `like` | POST | `buzz/{buzzKey}/like` | buzzKey | `LikeForumResponse` | `#forum` |
+| `forumApi` | `unlike` | DELETE | `buzz/{buzzKey}/like` | buzzKey | `LikeForumResponse` | `#forum` |
+| `settingApi` | `accessKey` | POST | `setting` | data (JSON: app_id, campaign_id, locale, return_url, version; opt: redeem_key) | `AccessTokenResponse` | `#setting #campaign` |
+| `blob` | `consentVersion` | GET | `pdpaconsent/{appId}/version` _(baseBlobUrl)_ | appId | `ConsentVersion` | `#blob #consent` |
+| `blob` | `maintenance` | GET | `config/maintenance/{appId}.json` _(baseBlobUrl)_ | appId | `Maintenance` | `#blob` |
+| `blob` | `blob` | GET | `{path}` _(baseBlobUrl)_ | path | `unknown` | `#blob` |
+
+---
+
+## API Reference
+
+Every method accepts an optional `requestOptions` as the last argument for custom headers or query params.
+
+---
+
 ### AuthenticateApi
 
-Accessed via `bzbsService.authApi`.
+`bzbsService.authApi` — Authentication, login providers, OTP, session management.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -230,26 +442,27 @@ Accessed via `bzbsService.authApi`.
 | `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` |
+| `connectLine(params)` | Connect/link LINE to existing account | `LoginResponse` |
+| `connectFacebook(params)` | Connect/link Facebook to existing account | `LoginResponse` |
+| `connectGoogle(params)` | Connect/link Google to existing account | `LoginResponse` |
+| `connectApple(params)` | Connect/link Apple to existing account | `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` |
+| `resetPassword(params)` | Reset user password with OTP | `StatusResponse` |
+| `otp(params)` | Request OTP (GET) | `OtpResponse` |
+| `otpV2(params)` | Request OTP (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` |
+| `confirmOtp(params)` | Confirm OTP for authentication | `ConfirmOtpResponse` |
+| `validateOtp(params)` | Validate OTP (generic) | `ValidateOtpResponse` |
+| `resume(params)` | Resume/refresh session | `ResumeResponse` |
+| `updateDevice(params)` | Update device push token | `ResumeResponse` |
 | `version(clientVersion)` | Get app version info | `Version` |
 | `versionRaw(clientVersion)` | Get raw version info | `any` |
 
-#### Login Example
+#### Examples
 
 ```typescript
+// Device login
 const result = await bzbsService.authApi.deviceLogin({
   appId: 'your-app-id',
   uuid: 'device-uuid',
@@ -262,25 +475,14 @@ const result = await bzbsService.authApi.deviceLogin({
   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',
+// OTP flow
+const otpResult = await bzbsService.authApi.otpV2({
   appId: 'your-app-id',
   contactNumber: '0812345678',
 });
 
-// 2. Validate OTP
 if (otpResult.type === 'success') {
-  const validateResult = await bzbsService.authApi.validateOtp({
+  const validated = await bzbsService.authApi.validateOtp({
     appId: 'your-app-id',
     otp: '123456',
     refCode: otpResult.model.refcode,
@@ -294,7 +496,7 @@ if (otpResult.type === 'success') {
 
 ### CampaignApi
 
-Accessed via `bzbsService.campaignApi`.
+`bzbsService.campaignApi` — Campaign listing, details, redemption, and favorites.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -317,14 +519,12 @@ Accessed via `bzbsService.campaignApi`.
 | `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 |
+| `center` | `string` | No | Geo coordinates (`lat,lng`) 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({
@@ -333,7 +533,6 @@ const campaigns = await bzbsService.campaignApi.campaigns({
   skip: 0,
   top: 20,
   keyword: 'coffee',
-  sortBy: 'popular',
 });
 
 // Redeem a campaign
@@ -347,7 +546,7 @@ const redeem = await bzbsService.campaignApi.redeem({
 
 ### ProfileApi
 
-Accessed via `bzbsService.profileApi`.
+`bzbsService.profileApi` — User profile management, points, password, contact number.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -360,9 +559,7 @@ Accessed via `bzbsService.profileApi`.
 | `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
+| `deactivate()` | Deactivate user account | `unknown` |
 
 ```typescript
 // Update profile with image
@@ -372,8 +569,8 @@ const result = await bzbsService.profileApi.updateProfile({
   email: 'john@example.com',
   contactNumber: '0812345678',
   gender: 'male',
-  birthDate: 946684800, // Unix timestamp in seconds
-  profileImage: fileObject, // File, { uri, name, type }, or object
+  birthDate: 946684800,   // Unix timestamp in seconds
+  profileImage: fileObject,
 });
 ```
 
@@ -381,7 +578,7 @@ const result = await bzbsService.profileApi.updateProfile({
 
 ### CartApi
 
-Accessed via `bzbsService.cartApi`.
+`bzbsService.cartApi` — Shopping cart management.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -398,7 +595,7 @@ const count = await bzbsService.cartApi.cartCount();
 
 ### CategoryApi
 
-Accessed via `bzbsService.categoryApi`.
+`bzbsService.categoryApi` — Campaign categories.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -415,11 +612,11 @@ const categories = await bzbsService.categoryApi.categories({
 
 ### CouponApi
 
-Accessed via `bzbsService.couponApi`.
+`bzbsService.couponApi` — Coupon code processing.
 
 | Method | Description | Returns |
 |---|---|---|
-| `processCodes(params)` | Process coupon codes | `CouponResponse` |
+| `processCodes(params)` | Process one or more coupon codes | `CouponResponse` |
 
 ```typescript
 const result = await bzbsService.couponApi.processCodes({
@@ -431,7 +628,7 @@ const result = await bzbsService.couponApi.processCodes({
 
 ### NotificationApi
 
-Accessed via `bzbsService.notificationApi`.
+`bzbsService.notificationApi` — Push notification management.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -440,23 +637,20 @@ Accessed via `bzbsService.notificationApi`.
 
 ```typescript
 const notifs = await bzbsService.notificationApi.notifications({
-  mode: 'new',       // 'new' | 'all'
+  mode: 'new',               // 'new' | 'all'
   sortBy: 'createdate_desc',
   top: 20,
   skip: 0,
 });
 
-// Mark as read
-await bzbsService.notificationApi.read({
-  ids: 'rowKey1,rowKey2',
-});
+await bzbsService.notificationApi.read({ ids: 'rowKey1,rowKey2' });
 ```
 
 ---
 
 ### HistoryApi
 
-Accessed via `bzbsService.historyApi`.
+`bzbsService.historyApi` — Redemption history and voucher usage.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -471,7 +665,6 @@ const history = await bzbsService.historyApi.redeemHistories({
   top: 20,
 });
 
-// Use a coupon
 await bzbsService.historyApi.use({ redeemKey: 'ABC123_1' });
 ```
 
@@ -479,17 +672,17 @@ await bzbsService.historyApi.use({ redeemKey: 'ABC123_1' });
 
 ### RegistrationApi
 
-Accessed via `bzbsService.registerApi`.
+`bzbsService.registerApi` — New user registration with OTP verification.
 
 | Method | Description | Returns |
 |---|---|---|
-| `validateRegister(params)` | Validate registration (triggers OTP) | `OtpResponse` |
+| `validateRegister(params)` | Validate registration and trigger OTP | `OtpResponse` |
 | `register(params)` | Register a new user | `RegistrationResponse` |
 
 **Validation Error Codes:**
-- `2078` - Duplicate contact number
-- `2089` - Duplicate email
-- `401` - Duplicate username
+- `2078` — Duplicate contact number
+- `2089` — Duplicate email
+- `401` — Duplicate username
 
 ```typescript
 // Step 1: Validate
@@ -525,7 +718,7 @@ const registration = await bzbsService.registerApi.register({
 
 ### AddressApi
 
-Accessed via `bzbsService.addressApi`.
+`bzbsService.addressApi` — User addresses and Thailand geographical data.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -534,22 +727,19 @@ Accessed via `bzbsService.addressApi`.
 | `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` |
+| `updateAddress(params)` | Create or update a delivery 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',
@@ -568,15 +758,14 @@ await bzbsService.addressApi.updateAddress({
 
 ### BadgeApi
 
-Accessed via `bzbsService.badgeApi`.
+`bzbsService.badgeApi` — User badges and mission progress.
 
 | Method | Description | Returns |
 |---|---|---|
-| `badges(params)` | Get user badges | `Badge[]` |
+| `badges(params)` | Get user badges (opt: filter by badgeId) | `Badge[]` |
 
 ```typescript
 const badges = await bzbsService.badgeApi.badges({});
-// Or filter by badge ID
 const badge = await bzbsService.badgeApi.badges({ badgeId: '123' });
 ```
 
@@ -584,7 +773,7 @@ const badge = await bzbsService.badgeApi.badges({ badgeId: '123' });
 
 ### ConsentApi
 
-Accessed via `bzbsService.consentApi`.
+`bzbsService.consentApi` — PDPA and marketing consent management.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -592,16 +781,18 @@ Accessed via `bzbsService.consentApi`.
 | `updateConsent(params)` | Update consent preferences | `Consent` |
 | `unconsent()` | Withdraw all consent | `unknown` |
 
-```typescript
-// Get consent
-const consent = await bzbsService.consentApi.consent();
+**`consentAge`** accepts one of:
+- `'0'` — user has not consented to age verification
+- `'1'` — user has consented (age confirmed)
+- The user's actual age as a string (e.g. `'25'`)
 
-// Update consent
+```typescript
 await bzbsService.consentApi.updateConsent({
   termsAndConditions: '1.0',
   dataPrivacy: '1.0',
   marketingOption: '1.0',
-  email: '1',          // '0' or '1'
+  consentAge: '25',  // '0' | '1' | actual age string
+  email: '1',        // '0' or '1'
   sms: '1',
   notification: '1',
   line: '0',
@@ -612,7 +803,7 @@ await bzbsService.consentApi.updateConsent({
 
 ### DashboardApi
 
-Accessed via `bzbsService.dashboardApi`.
+`bzbsService.dashboardApi` — Dashboard content configuration.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -625,7 +816,7 @@ const dashboard = await bzbsService.dashboardApi.mainDashboard({
   locale: 1054, // Thai locale
 });
 
-const subDashboard = await bzbsService.dashboardApi.subDashboard({
+const sub = await bzbsService.dashboardApi.subDashboard({
   dashboardName: 'featured',
   locale: 1054,
 });
@@ -635,7 +826,7 @@ const subDashboard = await bzbsService.dashboardApi.subDashboard({
 
 ### LineApi
 
-Accessed via `bzbsService.lineApi` (only initialized if `baseLineUrl` is provided).
+`bzbsService.lineApi` — LINE OAuth token exchange. Only initialized when `baseLineUrl` is provided. Uses `baseLineUrl` as the base URL.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -657,7 +848,7 @@ if (bzbsService.lineApi) {
 
 ### PlaceApi
 
-Accessed via `bzbsService.placeApi`.
+`bzbsService.placeApi` — Location/store management with geo-search.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -680,16 +871,16 @@ const places = await bzbsService.placeApi.placeList({
 
 ### PointLogApi
 
-Accessed via `bzbsService.pointLogApi`.
+`bzbsService.pointLogApi` — Point transaction history.
 
 | Method | Description | Returns |
 |---|---|---|
-| `getPointLog(params)` | Get point transaction log | `PointLog[]` |
+| `getPointLog(params)` | Get point transaction log by month | `PointLog[]` |
 
 ```typescript
 const logs = await bzbsService.pointLogApi.getPointLog({
   month: '2025-01',
-  type: 'earn',  // 'earn' | 'burn' | etc.
+  type: 'earn',
   top: 50,
 });
 ```
@@ -698,7 +889,7 @@ const logs = await bzbsService.pointLogApi.getPointLog({
 
 ### StampApi
 
-Accessed via `bzbsService.stampApi`.
+`bzbsService.stampApi` — Stamp card system.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -719,28 +910,26 @@ const profile = await bzbsService.stampApi.stampProfile({
 
 ### RequestHelpApi (Forum)
 
-Accessed via `bzbsService.forumApi`.
+`bzbsService.forumApi` — Help/support forum (Buzz chat system).
 
 | 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` |
+| `requestHelpList(params)` | List messages in a help request | `ChatMessage[]` |
+| `requestDetail(params)` | Get a specific message | `ChatMessage` |
+| `postRequestHelp(params)` | Post a help message (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',
@@ -752,7 +941,7 @@ await bzbsService.forumApi.postRequestHelp({
 
 ### SettingApi
 
-Accessed via `bzbsService.settingApi`.
+`bzbsService.settingApi` — Web landing page access tokens.
 
 | Method | Description | Returns |
 |---|---|---|
@@ -774,12 +963,12 @@ const accessKey = await bzbsService.settingApi.accessKey({
 
 ### Blob
 
-Accessed via `bzbsService.blob`.
+`bzbsService.blob` — Blob storage retrieval. Uses `baseBlobUrl` as base URL.
 
 | Method | Description | Returns |
 |---|---|---|
-| `consentVersion(appId)` | Get PDPA consent version | `ConsentVersion` |
-| `maintenance(appId)` | Get maintenance configuration | `Maintenance` |
+| `consentVersion(appId)` | Get PDPA consent document version | `ConsentVersion` |
+| `maintenance(appId)` | Get app maintenance configuration | `Maintenance` |
 | `blob(path)` | Fetch any blob storage path | `unknown` |
 
 ```typescript
@@ -789,183 +978,245 @@ const maintenance = await bzbsService.blob.maintenance('your-app-id');
 
 ---
 
-## Response Handling
+## Models Reference
 
-All API methods return `ServiceResponse<T>`, a discriminated union type:
+All TypeScript interfaces are exported from `@bzbs/react-api-client`:
 
 ```typescript
-type ServiceResponse<T> = SuccessResponse<T> | ErrorResponse;
+import {
+  Campaign,
+  CampaignDetail,
+  ProfileResponse,
+  LoginResponse,
+  Purchase,
+  // ... etc
+} from '@bzbs/react-api-client';
 ```
 
-### Success Response
+### Authentication Models
 
-```typescript
-type SuccessResponse<T> = {
-  type: 'success';
-  model: T;              // The typed response data
-  response: AxiosResponse; // Raw Axios response
-};
-```
+| Model | Key Fields |
+|---|---|
+| `LoginResponse` | Token, UserId, UserCode, Username, Points, Consent fields, ProfileImage, Locale |
+| `ResumeResponse` | Same structure as LoginResponse |
+| `AppleToken` | refresh_token, id_token |
+| `LineAuthResponse` | access_token, token_type, refresh_token, expires_in, scope, id_token |
+| `OtpResponse` | refcode, channel, expiredate, expireinseconds |
+| `ConfirmOtpResponse` | status, token |
+| `ValidateOtpResponse` | validatecode |
+| `ForgetPasswordResponse` | status, refcode, expiredate, expireinseconds |
+| `RegistrationResponse` | Registration result with Buzzebees user account |
+| `Version` | allow_use, has_new_version, welcome_page_times |
+
+### Campaign Models
+
+| Model | Key Fields |
+|---|---|
+| `Campaign` | ID, Name, Points, StartDate, EndDate, CategoryId, ImageUrl, Quantity, IsLike |
+| `CampaignDetail` | All Campaign fields + images (Picture[]), SubCampaigns, conditions, terms |
+| `Picture` | ID, Type, Sequence, ImageUrl |
+| `SubCampaign` | ID, Name, styles (SubCampaignStyle[]), quantity, points |
+| `RedeemResponse` | RedeemKey, PrivilegeMessageEN, PrivilegeMessageTH, UpdatedPoints, ExpiryDate |
+| `UseCampaignResponse` | PrivilegeMessageEN, PrivilegeMessageTH, redeemKey, points |
+| `FavoriteResponse` | totalLike, isLike |
+| `CouponResponse` | success/error results per code |
+| `Purchase` | RedeemKey, CampaignName, ExpiryDate, Status, Points, barcode, images |
+
+### Cart Models
+
+| Model | Key Fields |
+|---|---|
+| `CartCountResponse` | cart_count |
+| `CartAccessResponse` | success, access key |
 
-### Error Response
+### Profile & Points Models
 
-```typescript
-type ErrorResponse = ClientError | ServerError;
+| Model | Key Fields |
+|---|---|
+| `ProfileResponse` | UserId, Name, FirstName, LastName, Email, Contact_Number, address fields, TermAndCondition, DataPrivacy, MarketingOption, ConsentAge (0=not consented, 1=consented, or actual age), EmailMarketing, SMSMarketing, NotificationMarketing, LineMarketing, Token, Jwt, updated_points, Info1–Info10 (60+ fields) |
+| `UpdatedPoints` | points, time |
+| `ExpiringPoints` | expiringPoints, expiryDate |
+| `Badge` | badgeId, name, description, imageUrl, missions (Mission[]) |
+| `Mission` | missionId, name, current, target, isCompleted |
+| `PointLog` | UserId, Info, Detail, Points, Type, Timestamp |
 
-type ServerError = {
-  type: 'server-error';
-  error: BzbsErrorResponse;  // { requestId, error: { id, message, code, type } }
-  statusCode: number;
-  response: AxiosResponse;
-};
+### Address & Location Models
 
-type ClientError = {
-  type: 'client-error';
-  message: string;
-  details?: any;
-};
-```
+| Model | Key Fields |
+|---|---|
+| `Address` | rowKey, name, firstName, lastName, address, zipcode, province/district/subdistrict codes and names, contactNumber, isDefault, taxId |
+| `Province` | province_code, province_name_th, province_name_en |
+| `District` | district_code, district_name_th, district_name_en, province_code |
+| `SubDistrict` | subdistrict_code, subdistrict_name_th, zip_code |
+| `ZipCode` | Hierarchical address with zone info |
+| `Place` | id, name, latitude, longitude, address, workingHours, services, isFavorite |
 
-### Usage Pattern
+### Consent & Settings Models
 
-```typescript
-const result = await bzbsService.campaignApi.campaigns({
-  config: 'campaign_list',
-});
+| Model | Key Fields |
+|---|---|
+| `Consent` | TermAndCondition, DataPrivacy, MarketingOption, SMSMarketing, NotificationMarketing, LineMarketing, cookie consent flags |
+| `ConsentVersion` | version values per consent type |
+| `Version` | allow_use, has_new_version, welcome_page_times |
+| `Maintenance` | isUnderMaintenance, message, startDate, endDate |
 
-switch (result.type) {
-  case 'success':
-    // result.model is Campaign[]
-    console.log(result.model);
-    break;
+### Stamp & Dashboard Models
 
-  case 'server-error':
-    // Server returned an error
-    console.error(result.error.error?.message);
-    console.error('Status:', result.statusCode);
-    break;
+| Model | Key Fields |
+|---|---|
+| `Stamp` | stampId, cardId, count, maxCount, rewards, expiry |
+| `StampProfileResponse` | stamp card profile with history |
+| `CreateStampResponse` | result of stamp creation |
+| `Dashboard` | id, name, menuItems, images, startDate, endDate |
+| `Category` | id, name (TH/EN), subcategories, imageUrl |
 
-  case 'client-error':
-    // Network error or client-side issue
-    console.error(result.message);
-    break;
-}
-```
+### Notification & Forum Models
 
-### Response Normalization
+| Model | Key Fields |
+|---|---|
+| `Notification` | notiId, title, message, objectType, imageUrl, expireDate, isRead |
+| `ChatMessage` | buzzKey, message, images, sender info, likes, comments count, createdDate (65+ fields) |
+| `LikeForumResponse` | likeCount, isLiked |
+| `RequestHelpCode` | helpCode |
 
-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 & Response Models
+
+| Model | Key Fields |
+|---|---|
+| `BzbsErrorResponse` | requestId, error: { id, message, code, type } |
+| `StatusResponse` | status |
+| `AccessTokenResponse` | token key |
+
+**Common Error Codes:**
+
+| Code | Description |
+|---|---|
+| `401` | Unauthorized / Duplicate username |
+| `2078` | Duplicate contact number |
+| `2089` | Duplicate email |
 
 ---
 
-## Error Handling
+## BaseService Utilities
 
-### BzbsErrorResponse
+### createFormData
+
+Static method for building `multipart/form-data` payloads. Skips `undefined`, `null`, and empty string values — preserves `0` and `false`.
 
 ```typescript
-interface BzbsErrorResponse {
-  requestId?: string;
-  error?: {
-    id?: number;
-    message?: string;
-    code?: number;
-    type?: string;
-  };
-}
+const formData = BaseService.createFormData(
+  { name: 'John', age: 0, active: false },
+  'profileImage',   // optional file field key
+  imageFile         // optional File object
+);
 ```
 
-### Common Error Codes
+### setBaseUrl / setLineUrl / setBlobUrl
 
-| Code | Description |
-|---|---|
-| `401` | Unauthorized / Duplicate username |
-| `2078` | Duplicate contact number |
-| `2089` | Duplicate email |
+Update base URLs at runtime (propagates to all sub-services):
+
+```typescript
+bzbsService.setBaseUrl('https://new-api.buzzebees.com/api/');
+bzbsService.setLineUrl('https://api.line.me/');
+bzbsService.setBlobUrl('https://new-blob.buzzebees.com/');
+```
 
 ---
 
-## Models
+## Testing Guide
+
+Tests are in the `tests/` directory, mirroring `src/` structure.
 
-All TypeScript interfaces are exported from `@bzbs/react-api-client` and can be imported directly:
+### Test Utilities (`tests/helpers/test-utils.ts`)
 
 ```typescript
 import {
-  Campaign,
-  CampaignDetail,
-  ProfileResponse,
-  LoginResponse,
-  Purchase,
-  // ... etc
-} from '@bzbs/react-api-client';
+  createMockClient,
+  createSuccessResponse,
+  createRawSuccessResponse,
+  createServerErrorResponse,
+  createAxiosError,
+  createDeviceParams,
+} from '../helpers/test-utils';
+
+// Create mocked Axios instance
+const { client, mockRequest } = createMockClient();
+
+// Mock a wrapped success response: { Success: true, Data: {...} }
+mockRequest.mockResolvedValue(createSuccessResponse({ id: '123' }));
+
+// Mock a raw success (no wrapper)
+mockRequest.mockResolvedValue(createRawSuccessResponse({ id: '123' }));
+
+// Mock a server error response
+mockRequest.mockResolvedValue(createServerErrorResponse());
+
+// Mock a network error (client error)
+mockRequest.mockRejectedValue(createAxiosError());
+
+// Standard device parameters (appId, uuid, os, platform, clientVersion, macAddress, deviceToken, ...)
+const deviceParams = createDeviceParams();
 ```
 
-### Key Models
+### Test Pattern
 
-| 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 |
+```typescript
+import { AuthenticateApi } from '../../src/api/auth/auth-api';
+import { createMockClient, createSuccessResponse, createDeviceParams } from '../helpers/test-utils';
 
----
+describe('AuthenticateApi', () => {
+  let api: AuthenticateApi;
+  let mockRequest: jest.Mock;
 
-## Development
+  beforeEach(() => {
+    const { client, mockRequest: mock } = createMockClient();
+    mockRequest = mock;
+    api = new AuthenticateApi(client, 'https://api.buzzebees.com/');
+  });
+
+  it('deviceLogin returns success', async () => {
+    const data = { Token: 'abc', UserId: '1' };
+    mockRequest.mockResolvedValue(createSuccessResponse(data));
+
+    const result = await api.deviceLogin(createDeviceParams());
+
+    expect(result.type).toBe('success');
+    if (result.type === 'success') {
+      expect(result.model.Token).toBe('abc');
+    }
+    expect(mockRequest).toHaveBeenCalledWith(
+      expect.objectContaining({ url: 'auth/device_login', method: 'post' })
+    );
+  });
+
+  it('deviceLogin handles server error', async () => {
+    mockRequest.mockResolvedValue(createServerErrorResponse());
 
-### Prerequisites
+    const result = await api.deviceLogin(createDeviceParams());
 
-- Node.js
-- npm
+    expect(result.type).toBe('server-error');
+  });
+});
+```
 
-### Commands
+### Run Tests
+
+```bash
+npm test                        # Watch mode with coverage
+npx jest --coverage             # Single run with coverage
+npx jest tests/api/auth         # Run specific folder
+npx jest --testNamePattern otp  # Run tests matching pattern
+```
+
+---
+
+## Development Commands
 
 ```bash
 # Install dependencies
 npm install
 
-# Build the library (CJS + ESM + type declarations)
+# Build (CJS + ESM + type declarations → dist/)
 npm run build
 
 # Run tests in watch mode with coverage
@@ -979,20 +1230,18 @@ 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
+# Publish (build + version bump + npm publish)
+npm run patch   # 1.4.14 → 1.4.15
+npm run minor   # 1.4.14 → 1.5.0
+npm run major   # 1.4.14 → 2.0.0
 ```
 
-### Adding a New API
+---
+
+## 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`:
+1. Create `src/api/my-feature/my-feature-api.ts`:
 
 ```typescript
 import { AxiosInstance } from 'axios';
@@ -1005,31 +1254,35 @@ export class MyFeatureApi extends BaseService {
   }
 
   public async getItems(
-    params: { id: string; options?: { [key: string]: unknown } },
+    params: { id: string },
     requestOptions?: RequestOptions
   ): Promise<ServiceResponse<MyModel[]>> {
-    return await this.get<MyModel[]>(
-      `my-feature/${params.id}`,
-      { ...params.options },
-      requestOptions
-    );
+    return await this.get<MyModel[]>(`my-feature/${params.id}`, {}, 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
+2. Create model interface in `src/models/my-model.ts` and export from `src/models/index.ts`
+3. Export from `src/api/index.ts`
+4. Add to `BzbsService` constructor and `setBaseUrl()` method in `src/api/bzbs-service.ts`
 
 ---
 
 ## 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 |
+
+### Package Exports
+
+```json
+{
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts"
+}
+```