@tencentcloud/web-push 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## [1.0.0] - 2025-12-17
+
+### Added
+
+- 🎉 Initial release
+- ✨ Service Worker-based push notification support
+- ✨ Complete TypeScript type definitions
+- ✨ Event-driven message handling mechanism
+- ✨ Built-in analytics functionality
+- ✨ Local state persistence
+- ✨ VAPID authentication support
+- ✨ Cross-platform push notification support
+
+### Features
+
+- 📱 Support for message received, notification clicked, and message revoked events
+- 🔧 Flexible device identifier management
+- 📊 Automatic message delivery and click rate statistics
+- 🎯 Seamless integration with Chat SDK
+- 💾 Automatic state recovery
+- 🔒 Secure push subscription management
+
+### API Interface
+
+- `registerPush()` - Register push service
+- `unRegisterPush()` - Unregister push service
+- `addPushListener()` - Add event listener
+- `removePushListener()` - Remove event listener
+
+### Browser Support
+
+- Chrome 50+
+- Firefox 44+
+- Safari 16+
+- Edge 17+
+
+### Development Tools
+
+- Vite build tool
+- TypeScript support
+- Jest unit testing
+- ESLint code linting
+- Complete example application

package/README.md

@@ -0,0 +1,241 @@
+# Tencent Cloud Web Push SDK
+
+A web-based push notification SDK built on modern Web APIs including Service Worker, Push API, and Notification API.
+
+## Features
+
+- 🚀 Built on modern Web standard APIs
+- 📱 Cross-platform push notification support
+- 🔧 TypeScript support
+- 📊 Built-in analytics functionality
+- 🎯 Event-driven architecture
+- 💾 Local state persistence
+- 🔒 Secure VAPID authentication
+
+## Browser Support
+
+- Chrome 50+
+- Firefox 44+
+- Safari 16+
+- Edge 17+
+
+## Integration Step
+
+### Step 1: Integrating @Tencentcloud/Web-Push
+
+【npm】
+
+```bash
+npm install @tencentcloud/web-push --save
+```
+
+【yarn】
+
+```bash
+yarn add @tencentcloud/web-push
+```
+
+### Step 2: Configure the Service Worker File
+
+After integrating `@tencentcloud/web-push`, copy the **Service Worker (sw.js)** to your project's **root directory**. After website deployment, ensure this file can be accessed through `https://your-domain.com/sw.js`. Otherwise, the browser will be unable to register the **Service Worker**.
+
+> **Note:**
+>
+> - The sw.js file **must be placed in the website's root directory** to work properly due to browser security restrictions.
+> - The sw.js file can only be registered successfully under **HTTPS connection (or local development environment localhost)**. Ensure your live production environment website supports **HTTPS**.
+
+**Role of the public directory**: In modern front-end projects (such as Vue, React, Next.js, etc.), **the public directory is a unique directory whose content will not be compiled or renamed during build**. Files placed in the public directory will be copied to the website's root directory as-is.
+
+> **Note:**
+>
+> - Place sw.js in the src or other directories, and it may be compiled or renamed (such as changed into sw.123abcde.js) by packaging tools (Webpack/Vite), thereby failing to register correctly.
+> - If your project **does not have a public directory** (such as old-style HTML projects), place **sw.js** directly in the same directory as **index.html** to ensure it is located in the root directory after build output.
+
+【macOS】
+
+```bash
+cp node_modules/@tencentcloud/web-push/dist/sw.js public/sw.js
+```
+
+【Windows】
+
+```bash
+copy node_modules\@tencentcloud\web-push\dist\sw.js public\sw.js
+```
+
+### Step 3: **Register for Push Services**
+
+In your homepage (for example: `index.js`), add `@tencentcloud/web-push` and register.
+
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >Parameter</td>
+
+<td rowspan="1" colSpan="1" >Type</td>
+
+<td rowspan="1" colSpan="1" >Description</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >SDKAppID</td>
+
+<td rowspan="1" colSpan="1" >Number</td>
+
+<td rowspan="1" colSpan="1" >The SDKAppID for the push service Push. For reference: [Prerequisites > Enabling a Service](https://write.woa.com/#ef1e073e-23da-422d-b06b-f13fcda46734) to obtain the SDKAppID.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >appKey</td>
+
+<td rowspan="1" colSpan="1" >String</td>
+
+<td rowspan="1" colSpan="1" >The client key for the push service Push. For reference: [Prerequisites > Enabling a Service](https://write.woa.com/#ef1e073e-23da-422d-b06b-f13fcda46734) to obtain the AppKey.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >userID</td>
+
+<td rowspan="1" colSpan="1" >String</td>
+
+<td rowspan="1" colSpan="1" >Register the userID for push services. User's Unique Identifier, defined by you, can only include uppercase and lowercase letters (a-z, A-Z), numbers (0-9), underscores, and hyphens.</td>
+</tr>
+</table>
+
+```javascript
+import WebPush from '@tencentcloud/web-push';
+
+const SDKAppID = 0; // Your SDKAppID
+const appKey = ''; // client key
+const userID = ''; // user ID
+
+// Register for push service
+await WebPush.registerPush({ SDKAppID, appKey, userID });
+
+// Listen to push messages
+WebPush.addPushListener(WebPush.EVENT.MESSAGE_RECEIVED, (message) => {
+  console.log('received push message:', message);
+});
+
+// Listen to notification click
+WebPush.addPushListener(WebPush.EVENT.NOTIFICATION_CLICKED, (data) => {
+  console.log('notification clicked:', data);
+});
+```
+
+## API Reference
+
+### Methods
+
+| API                  | Parameters                                          | Description                |
+| -------------------- | --------------------------------------------------- | -------------------------- |
+| `registerPush`       | `options: RegisterPushOptions`                      | Register push service      |
+| `unRegisterPush`     | -                                                   | Unregister push service    |
+| `addPushListener`    | `eventName: EVENT, listener: Function<EventResult>` | Add push event listener    |
+| `removePushListener` | `eventName: EVENT, listener: Function<EventResult>` | Remove push event listener |
+
+### Type Definitions
+
+```typescript
+interface RegisterPushOptions {
+  SDKAppID: number;
+  appKey: string;
+  userID: string;
+  serviceWorkerPath?: string;
+  chat?: any;
+}
+
+enum EVENT {
+  MESSAGE_RECEIVED = 'message_received',
+  MESSAGE_REVOKED = 'message_revoked',
+  NOTIFICATION_CLICKED = 'notification_clicked',
+}
+
+interface Message {
+  ID: string;
+  type:
+    | 'TIMTextElem'
+    | 'TIMImageElem'
+    | 'TIMSoundElem'
+    | 'TIMVideoFileElem'
+    | 'TIMFileElem'
+    | 'TIMCustomElem'
+    | 'TIMRelayElem'
+    | 'TIMLocationElem'
+    | 'TIMFaceElem';
+  payload: any;
+  conversationID: string;
+  conversationType: 'C2C' | 'GROUP';
+  to: string;
+  from: string;
+  flow: string;
+  time: number;
+  status: string;
+  isRevoked: boolean;
+  nick: string;
+  avatar: string;
+  isPeerRead: boolean;
+  nameCard: string;
+  atUserList: string[];
+  cloudCustomData: string;
+  isDeleted: boolean;
+  isModified: boolean;
+  needReadReceipt: boolean;
+  readReceiptInfo: any;
+  isBroadcastMessage: boolean;
+  isSupportExtension: boolean;
+  receiverList?: string[];
+  revoker: string;
+  sequence: number;
+  progress: number;
+  revokerInfo: {
+    userID: string;
+    nick: string;
+    avatar: string;
+  };
+  revokeReason: string;
+  hasRiskContent: boolean;
+}
+
+interface MessageReceivedResult {
+  message: Message;
+}
+
+interface MessageRevokedResult {
+  messageID: string;
+}
+
+interface MessageNotificationClickedResult {
+  ext: string;
+}
+
+interface EventResult {
+  data:
+    | MessageReceivedResult
+    | MessageRevokedResult
+    | MessageNotificationClickedResult;
+}
+```
+
+### Event Types
+
+- `MESSAGE_RECEIVED`: Received a push message
+- `MESSAGE_REVOKED`: Message was revoked
+- `NOTIFICATION_CLICKED`: Notification was clicked
+
+## Important Notes
+
+### Service Worker Scope
+
+Service Workers must be placed in the website's root directory (e.g., `/sw.js`) to control push messages across the entire website. Placing them in subdirectories will not function correctly.
+
+### HTTPS Requirement
+
+The Web Push API requires websites to use the HTTPS protocol (except for local development environments using localhost).
+
+### Browser Permissions
+
+Users need to authorize notification permissions upon first use. Please guide users to authorize permissions at appropriate times.
+
+## License
+
+MIT License

package/index.d.ts

@@ -0,0 +1,112 @@
+export declare enum EVENT {
+    MESSAGE_RECEIVED = "message_received",
+    MESSAGE_REVOKED = "message_revoked",
+    NOTIFICATION_CLICKED = "notification_clicked"
+}
+
+export declare interface EventResult {
+    data: MessageReceivedResult | MessageRevokedResult | MessageNotificationClickedResult;
+}
+
+export declare interface Message {
+    ID: String;
+    type: 'TIMTextElem' | 'TIMImageElem' | 'TIMSoundElem' | 'TIMVideoFileElem' | 'TIMFileElem' | 'TIMCustomElem' | 'TIMRelayElem' | 'TIMLocationElem' | 'TIMFaceElem';
+    payload: any;
+    conversationID: String;
+    conversationType: 'C2C' | 'GROUP';
+    to: String;
+    from: String;
+    flow: String;
+    time: Number;
+    status: String;
+    isRevoked: Boolean;
+    nick: String;
+    avatar: String;
+    isPeerRead: Boolean;
+    nameCard: String;
+    atUserList: String[];
+    cloudCustomData: String;
+    isDeleted: Boolean;
+    isModified: Boolean;
+    needReadReceipt: Boolean;
+    readReceiptInfo: any;
+    isBroadcastMessage: Boolean;
+    isSupportExtension: Boolean;
+    receiverList?: String[];
+    revoker: String;
+    sequence: Number;
+    progress: Number;
+    revokerInfo: {
+        userID: String;
+        nick: String;
+        avatar: String;
+    };
+    revokeReason: String;
+    hasRiskContent: Boolean;
+}
+
+export declare interface MessageNotificationClickedResult {
+    ext: String;
+}
+
+export declare interface MessageReceivedResult {
+    message: Message;
+}
+
+export declare interface MessageRevokedResult {
+    messageID: String;
+}
+
+export declare interface RegisterPushOptions {
+    SDKAppID: number;
+    appKey: string;
+    userID: string;
+    serviceWorkerPath?: string;
+    chat?: any;
+}
+
+declare const webPush: WebPushSDK_2;
+export default webPush;
+export { webPush }
+
+export declare interface WebPushSDK {
+    registerPush(options?: RegisterPushOptions): Promise<any>;
+    unRegisterPush(): Promise<any>;
+    addPushListener(eventName: EVENT, listener: (data: EventResult) => void): any;
+    removePushListener(eventName: EVENT, listener: (data: EventResult) => void): any;
+}
+
+declare class WebPushSDK_2 implements WebPushSDK {
+    static instance: WebPushSDK_2;
+    private eventEmitter;
+    private serviceWorkerManager;
+    private isRegistered;
+    private registrationID;
+    private chat;
+    private SDKAppID;
+    private appKey;
+    private vapidPublicKey;
+    EVENT: typeof EVENT;
+    VERSION: string;
+    constructor();
+    static getInstance(): WebPushSDK_2;
+    registerPush(options?: RegisterPushOptions): Promise<string>;
+    unRegisterPush(): Promise<boolean>;
+    addPushListener(eventName: EVENT, listener: Function): string;
+    removePushListener(eventName: EVENT, listener: Function): boolean;
+    private checkBrowserSupport;
+    private requestNotificationPermission;
+    private chatLogin;
+    private getSystemPermissionMessage;
+    private showSystemPermissionAlert;
+    private getBrowserInstType;
+    private setToken;
+    private initializeBrowserCompatibility;
+    private setupInternalListeners;
+    private pushStatistics;
+    private saveState;
+    private restoreState;
+    private clearState;
+}
+
+export { }