@warriorteam/redai-zalo-sdk 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 RedAI Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,448 @@
+# RedAI Zalo SDK
+
+A comprehensive TypeScript/JavaScript SDK for Zalo APIs, providing easy-to-use interfaces for:
+
+- **Official Account (OA) API** - Manage your Zalo Official Account
+- **Zalo Notification Service (ZNS)** - Send template-based notification messages
+- **Social API** - Access user social information and authentication
+- **Group Message Framework (GMF)** - Send messages to Zalo groups
+- **User Management** - Comprehensive user profile and tag management
+- **Content Management** - Upload and manage media content (images, files, articles)
+- **Video Upload** - Upload and manage video content with processing
+- **Tag Management** - User tagging and segmentation
+- **Webhook handling** - Process Zalo webhook events
+
+## Features
+
+- 🚀 **TypeScript Support** - Full type safety and IntelliSense
+- 🔐 **OAuth 2.0 Flow** - Complete authentication handling
+- 🔄 **Auto Retry** - Built-in retry mechanism for failed requests
+- 📝 **Comprehensive Logging** - Debug and monitor API calls
+- 🛡️ **Error Handling** - Detailed error information and handling
+- 📦 **Zero Dependencies** - Only requires axios and form-data
+- 🎯 **Promise-based** - Modern async/await support
+
+## Installation
+
+```bash
+npm install redai-zalo-sdk
+```
+
+## Development
+
+### Build from source
+
+```bash
+# Clone the repository
+git clone https://github.com/redai/redai-zalo-sdk.git
+cd redai-zalo-sdk
+
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+
+# Run examples
+npm run dev
+```
+
+## Quick Start
+
+### Initialize the SDK
+
+```typescript
+import { ZaloSDK } from "redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret",
+  debug: true, // Enable debug logging
+});
+```
+
+### Authentication Flow
+
+#### Official Account (OA) Authentication
+
+```typescript
+// 1. Create authorization URL
+const authUrl = zalo.createOAAuthUrl("https://your-app.com/callback");
+console.log("Visit:", authUrl);
+
+// 2. Exchange authorization code for access token
+const accessToken = await zalo.getOAAccessToken(
+  "authorization-code-from-callback",
+  "https://your-app.com/callback"
+);
+
+console.log("Access Token:", accessToken.access_token);
+```
+
+#### Social API Authentication
+
+```typescript
+// 1. Generate PKCE for security (recommended)
+const pkce = zalo.generatePKCE();
+
+// 2. Create authorization URL
+const authUrl = zalo.createSocialAuthUrl("https://your-app.com/callback");
+
+// 3. Exchange code for access token
+const accessToken = await zalo.getSocialAccessToken(
+  "authorization-code",
+  "https://your-app.com/callback",
+  pkce.code_verifier
+);
+```
+
+### Official Account Operations
+
+```typescript
+// Get OA information
+const oaInfo = await zalo.getOAInfo(accessToken.access_token);
+console.log("OA Name:", oaInfo.name);
+console.log("Followers:", oaInfo.num_follower);
+
+// Check message quota
+const quota = await zalo.getMessageQuota(accessToken.access_token);
+console.log("Daily Quota:", quota.daily_quota);
+console.log("Remaining:", quota.remaining_quota);
+
+// Get detailed quota information
+const detailedQuota = await zalo.oa.getQuotaSummary(accessToken.access_token);
+console.log("Consultation Quota:", detailedQuota.consultation);
+console.log("Transaction Quota:", detailedQuota.transaction);
+```
+
+### Social API Operations
+
+```typescript
+// Get user information
+const userInfo = await zalo.getSocialUserInfo(
+  accessToken.access_token,
+  "id,name,picture,birthday"
+);
+
+console.log("User ID:", userInfo.id);
+console.log("Name:", userInfo.name);
+console.log("Avatar:", userInfo.picture?.data.url);
+```
+
+### Token Management
+
+```typescript
+// Refresh OA access token
+const newOAToken = await zalo.refreshOAAccessToken(refreshToken);
+
+// Refresh Social access token
+const newSocialToken = await zalo.refreshSocialAccessToken(refreshToken);
+
+// Validate token
+const isValid = await zalo.validateAccessToken(accessToken.access_token, "oa");
+```
+
+## Advanced Usage
+
+### Custom API Requests
+
+```typescript
+// Make custom API calls
+const customData = await zalo.customRequest(
+  "POST",
+  "/v3.0/oa/message/cs",
+  accessToken.access_token,
+  {
+    recipient: { user_id: "user-id" },
+    message: { text: "Hello from SDK!" },
+  }
+);
+```
+
+### File Upload
+
+```typescript
+import fs from "fs";
+
+// Upload image
+const fileBuffer = fs.readFileSync("image.jpg");
+const uploadResult = await zalo.uploadFile(
+  "/v2.0/oa/upload/image",
+  accessToken.access_token,
+  fileBuffer,
+  "image.jpg"
+);
+
+console.log("Uploaded URL:", uploadResult.data.url);
+```
+
+### Error Handling
+
+```typescript
+import { ZaloSDKError } from "redai-zalo-sdk";
+
+try {
+  const oaInfo = await zalo.getOAInfo(accessToken.access_token);
+} catch (error) {
+  if (error instanceof ZaloSDKError) {
+    console.error("Zalo API Error:", error.message);
+    console.error("Error Code:", error.code);
+    console.error("Details:", error.details);
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret",
+
+  // Optional configurations
+  timeout: 30000, // Request timeout in ms (default: 30000)
+  debug: false, // Enable debug logging (default: false)
+  apiBaseUrl: "https://openapi.zalo.me", // Custom API base URL
+
+  // Retry configuration
+  retry: {
+    attempts: 3, // Number of retry attempts (default: 3)
+    delay: 1000, // Delay between retries in ms (default: 1000)
+  },
+});
+```
+
+## API Reference
+
+### ZaloSDK Class
+
+#### Constructor
+
+- `new ZaloSDK(config: ZaloSDKConfig)`
+
+#### Authentication Methods
+
+- `createOAAuthUrl(redirectUri: string, state?: string): string`
+- `createSocialAuthUrl(redirectUri: string, state?: string): string`
+- `getOAAccessToken(code: string, redirectUri: string): Promise<AccessToken>`
+- `getSocialAccessToken(code: string, redirectUri: string, codeVerifier?: string): Promise<AccessToken>`
+- `refreshOAAccessToken(refreshToken: string): Promise<AccessToken>`
+- `refreshSocialAccessToken(refreshToken: string): Promise<AccessToken>`
+
+#### OA Methods
+
+- `getOAInfo(accessToken: string): Promise<OAInfo>`
+- `getMessageQuota(accessToken: string): Promise<MessageQuota>`
+
+#### Social Methods
+
+- `getSocialUserInfo(accessToken: string, fields?: string): Promise<SocialUserInfo>`
+
+#### Utility Methods
+
+- `validateAccessToken(accessToken: string, scope?: 'oa' | 'social'): Promise<boolean>`
+- `generatePKCE(): PKCEConfig`
+- `testConnection(): Promise<boolean>`
+
+### Services
+
+#### AuthService
+
+- Complete OAuth 2.0 flow handling
+- PKCE support for Social API
+- Token validation and refresh
+
+#### OAService
+
+- Official Account information management
+- Quota monitoring and management
+- Profile updates
+
+## Error Handling
+
+The SDK throws `ZaloSDKError` for all Zalo API related errors:
+
+```typescript
+class ZaloSDKError extends Error {
+  code: number; // Zalo API error code
+  details?: any; // Additional error details
+}
+```
+
+Common error codes:
+
+- `-216`: Invalid access token
+- `-201`: Invalid parameters
+- `-223`: Quota exceeded
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides comprehensive type definitions:
+
+```typescript
+import {
+  ZaloSDK,
+  ZaloSDKConfig,
+  AccessToken,
+  OAInfo,
+  SocialUserInfo,
+  ZaloSDKError,
+} from "redai-zalo-sdk";
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some 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 support and questions:
+
+- Create an issue on GitHub
+- Contact RedAI team
+
+### ZNS (Zalo Notification Service)
+
+```typescript
+// Send ZNS notification
+await zalo.zns.sendMessage(accessToken, {
+  phone: "0123456789",
+  template_id: "your-template-id",
+  template_data: {
+    customer_name: "John Doe",
+    order_id: "12345",
+  },
+});
+
+// Get ZNS quota
+const quota = await zalo.zns.getQuotaInfo(accessToken);
+
+// Manage ZNS templates
+const templates = await zalo.zns.getTemplateList(accessToken);
+const template = await zalo.zns.createTemplate(accessToken, {
+  templateName: "Order Confirmation",
+  templateContent:
+    "Hello {{customer_name}}, your order {{order_id}} is confirmed.",
+  templateType: 3, // Confirmation type
+});
+```
+
+### Group Messaging
+
+```typescript
+// Send text message to group
+await zalo.groupMessage.sendTextMessage(accessToken, groupId, {
+  type: "text",
+  text: "Hello everyone!",
+});
+
+// Send image to group
+await zalo.groupMessage.sendImageMessage(accessToken, groupId, {
+  type: "image",
+  imageUrl: "https://example.com/image.jpg",
+  caption: "Check this out!",
+});
+
+// Get group information
+const groupInfo = await zalo.groupMessage.getGroupInfo(accessToken, groupId);
+const members = await zalo.groupMessage.getGroupMembers(accessToken, groupId);
+```
+
+### User Management
+
+```typescript
+// Get user profile
+const profile = await zalo.userManagement.getUserProfile(accessToken, userId);
+
+// Tag management
+await zalo.tag.createTag(accessToken, "VIP Customer");
+await zalo.tag.tagUser(accessToken, userId, ["VIP Customer", "Premium"]);
+const userTags = await zalo.tag.getUserTags(accessToken, userId);
+
+// Get followers list
+const followers = await zalo.userManagement.getFollowersList(accessToken);
+```
+
+### Content Management
+
+```typescript
+// Upload image
+const imageResult = await zalo.content.uploadImage(accessToken, imageBuffer);
+
+// Create article
+const article = await zalo.content.createArticle(accessToken, {
+  title: "Welcome to our service",
+  body: "Article content here...",
+  cover_photo_id: imageResult.data.attachment_id,
+});
+
+// Share article to user
+await zalo.content.shareArticle(accessToken, userId, article.data.id);
+```
+
+### Video Upload
+
+```typescript
+// Upload video
+const uploadResult = await zalo.videoUpload.uploadVideo(
+  accessToken,
+  videoBuffer,
+  "video.mp4"
+);
+
+// Wait for processing completion
+const finalResult = await zalo.videoUpload.waitForUploadCompletion(
+  accessToken,
+  uploadResult.data.token
+);
+
+if (finalResult.status === "ready") {
+  // Send video message
+  await zalo.videoUpload.sendVideoMessage(
+    accessToken,
+    userId,
+    finalResult.attachment_id,
+    "Check out this video!"
+  );
+}
+```
+
+### Social API
+
+```typescript
+// Get user social information
+const userInfo = await zalo.social.getUserInfo(accessToken);
+
+// Get friends list
+const friends = await zalo.social.getFriendsList(accessToken);
+
+// Post to timeline
+await zalo.social.postToTimeline(accessToken, "Hello from Zalo SDK!");
+```
+
+## Changelog
+
+### v1.0.0
+
+- Initial release
+- Official Account API support
+- ZNS (Zalo Notification Service) support
+- Group Message Framework (GMF) support
+- Social API support
+- User Management features
+- Content and Video Upload capabilities
+- Tag Management system
+- Comprehensive webhook handling
+- Social API support
+- Authentication flow
+- TypeScript support

package/dist/clients/base-client.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Base HTTP client for Zalo API
+ */
+import { AxiosInstance } from "axios";
+import { ZaloSDKConfig, Logger, RequestConfig } from "../types/common";
+/**
+ * Base client for making HTTP requests to Zalo API
+ */
+export declare class BaseClient {
+    protected readonly axios: AxiosInstance;
+    protected readonly logger: Logger;
+    protected readonly config: Required<ZaloSDKConfig>;
+    constructor(config: ZaloSDKConfig);
+    /**
+     * Setup axios interceptors for logging and error handling
+     */
+    private setupInterceptors;
+    /**
+     * Sanitize headers for logging (remove sensitive information)
+     */
+    private sanitizeHeaders;
+    /**
+     * Handle axios errors and log them
+     */
+    private handleAxiosError;
+    /**
+     * Make a GET request
+     */
+    protected get<T = any>(url: string, accessToken?: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * Make a POST request
+     */
+    protected post<T = any>(url: string, accessToken?: string, data?: any, params?: Record<string, any>): Promise<T>;
+    /**
+     * Make a PUT request
+     */
+    protected put<T = any>(url: string, accessToken?: string, data?: any, params?: Record<string, any>): Promise<T>;
+    /**
+     * Make a DELETE request
+     */
+    protected delete<T = any>(url: string, accessToken?: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * Upload file using FormData
+     */
+    protected uploadFile<T = any>(url: string, accessToken: string, file: Buffer | NodeJS.ReadableStream, filename: string, additionalFields?: Record<string, any>): Promise<T>;
+    /**
+     * Make a generic HTTP request with retry logic
+     */
+    protected request<T = any>(config: RequestConfig): Promise<T>;
+    /**
+     * Validate Zalo API response for errors
+     */
+    private validateZaloResponse;
+    /**
+     * Determine if request should be retried
+     */
+    private shouldRetry;
+    /**
+     * Create SDK error from axios error
+     */
+    private createSDKError;
+    /**
+     * Delay execution for specified milliseconds
+     */
+    private delay;
+}
+//# sourceMappingURL=base-client.d.ts.map

package/dist/clients/base-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-client.d.ts","sourceRoot":"","sources":["../../src/clients/base-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAc,EACZ,aAAa,EAId,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,aAAa,EAEb,MAAM,EAEN,aAAa,EACd,MAAM,iBAAiB,CAAC;AAEzB;;GAEG;AACH,qBAAa,UAAU;IACrB,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IACxC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;gBAEvC,MAAM,EAAE,aAAa;IA8BjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmCzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;cACa,GAAG,CAAC,CAAC,GAAG,GAAG,EACzB,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC;IASb;;OAEG;cACa,IAAI,CAAC,CAAC,GAAG,GAAG,EAC1B,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,GAAG,EACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC;IAUb;;OAEG;cACa,GAAG,CAAC,CAAC,GAAG,GAAG,EACzB,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,GAAG,EACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC;IAUb;;OAEG;cACa,MAAM,CAAC,CAAC,GAAG,GAAG,EAC5B,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC;IASb;;OAEG;cACa,UAAU,CAAC,CAAC,GAAG,GAAG,EAChC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,EACpC,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC;IAsBb;;OAEG;cACa,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC;IAiDnE;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA0B5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;OAEG;IACH,OAAO,CAAC,cAAc;IAoBtB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}