@redonvn/zalo-ads-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @redonvn/zalo-ads-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK TypeScript cho toàn bộ hệ sinh thái Zalo Ads (`ads.zalo.me`, `page.ads.zalo.me`, `form.ads.zalo.me`, `profile.ads.zalo.me`, `api.widget.zalo.me`, `widget.chat.zalo.me`).
+
+Hỗ trợ:
+- **Silent OAuth2 PKCE SSO (`ZaloAuthManager`)**: Chỉ cần truyền duy nhất cookie `zpsid` (hoặc nguyên chuỗi Cookie trình duyệt có chứa `zpsid=...`), SDK tự động đổi ra `PLAY_SESSION`, `XSRF-TOKEN`, `zf_id` và `Authorization` token cho từng domain.
+- **Lưu trữ phiên trên RAM hoặc Redis (`ZaloSessionStore`)**:
+  - `MemoryZaloSessionStore`: L1 RAM cache có giới hạn số lượng tài khoản theo cơ chế LRU (`maxAccounts`).
+  - `RedisZaloSessionStore`: L2 Redis shared cache kèm Distributed Lock (`setNX`), tương thích trực tiếp với `RedisService` của `redai-v201-be-app-staging` và `ioredis`.
+  - `TieredZaloSessionStore`: Kết hợp 2 tầng **L1 RAM (0ms) + L2 Redis (chia sẻ giữa nhiều worker/pod + giữ phiên khi restart server)**.
+- **Quản lý Đa Tài Khoản / Đa Integration (`ZaloAdsIntegrationManager`)**: Cô lập phiên theo `integrationId` (hoặc tự động tách `accountKey` từ `zpsid`), tự động phát hiện khi người dùng cập nhật `zpsid` mới (`zpsidFingerprint`) để làm mới phiên.
+
+---
+
+## 1. Sử dụng đơn lẻ (Mặc định tự cache trong RAM theo tài khoản)
+
+```ts
+import { ZaloAdsSdk } from "@redonvn/zalo-ads-sdk";
+
+const sdk = new ZaloAdsSdk({
+  zpsid: "g_kQ.330114198.434.TmeTxcUlEkNnYvVsQwywvHBSIDPKdmlKKvu3tSnRUwvf5VqMPj4FAmslEkK",
+  // Tùy chọn: truyền thêm integrationId và redis nếu muốn lưu thẳng xuống Redis
+  // integrationId: "eb18102a-...",
+  // redis: this.redisService,
+});
+
+const whoami = await sdk.ads.getApiWhoami();
+const rules = await sdk.ads.listAutomatedRules({ ruleName: "" });
+const oas = await sdk.instantPages.listOfficialAccounts();
+const formSession = await sdk.forms.getAuthSession();
+```
+
+---
+
+## 2. Quản lý nhiều Integration trên Backend (`redai-v201-be-app-staging`) với RAM + Redis
+
+Trên `redai-v201-be-app-staging`, mỗi người dùng có thể kết nối nhiều Zalo Ads Integration (`integrationId`). Sử dụng `ZaloAdsIntegrationManager` để quản lý tập trung:
+
+```ts
+import { Injectable } from "@nestjs/common";
+import { RedisService } from "@shared/services/redis.service";
+import { GenericIntegrationCredentialService } from "@modules/integration/shared/credentials/generic-integration-credential.service";
+import { ZaloAdsIntegrationManager, ZaloAdsSdk } from "@redonvn/zalo-ads-sdk";
+
+@Injectable()
+export class ZaloAdsClientFactoryService {
+  public readonly manager: ZaloAdsIntegrationManager;
+
+  constructor(
+    private readonly redisService: RedisService,
+    private readonly credentialService: GenericIntegrationCredentialService,
+  ) {
+    this.manager = new ZaloAdsIntegrationManager({
+      // Truyền trực tiếp RedisService của backend -> Tự động bật Tiered Store (L1 RAM + L2 Redis + Distributed Lock)
+      // Nếu không truyền `redis`, Manager tự động dùng MemoryZaloSessionStore (RAM LRU).
+      redis: this.redisService,
+      redisKeyPrefix: "zalo_ads:sso",
+      maxAccountsInMemory: 500,
+
+      // Tự động lấy zpsid đã giải mã từ Credential Vault theo integrationId
+      resolveCredentials: async (integrationId: string) => {
+        const bound = await this.credentialService.resolveBound(integrationId);
+        const creds = bound.credentials as Record<string, string>;
+        return {
+          zpsid: creds.zpsid || creds.cookie,
+          zoawSek: creds.zoawSek,
+        };
+      },
+    });
+  }
+
+  /** Lấy SDK thực thi cho bất kỳ integrationId nào của người dùng */
+  async getSdkForIntegration(integrationId: string): Promise<ZaloAdsSdk> {
+    return this.manager.forIntegration(integrationId);
+  }
+
+  /** Dùng khi người dùng bấm "Kết nối / Kiểm tra kết nối" (Auth Connect Flow) */
+  async verifyAndWarmup(integrationId: string, zpsidOrCookie: string) {
+    return this.manager.verifyIntegration({
+      integrationId,
+      zpsid: zpsidOrCookie,
+    });
+  }
+
+  /** Xóa sạch phiên trong RAM + Redis khi người dùng sửa/xóa Integration */
+  async invalidate(integrationId: string): Promise<void> {
+    await this.manager.invalidateIntegration(integrationId);
+  }
+}
+```