@ymxjs/ymx-jiguang 1.0.1

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@ymxjs/ymx-jiguang",
+  "version": "1.0.1",
+  "description": "TypeScript definitions for ymx plugin ymx-jiguang",
+  "types": "types.d.ts",
+  "keywords": [
+    "ymx",
+    "ymxjs",
+    "ymx-jiguang"
+  ],
+  "homepage": "https://zsite.cc/market/ymx-jiguang",
+  "author": "ymx",
+  "license": "MIT",
+  "dependencies": {
+    "@ymxjs/core": "^1.260831.0"
+  },
+  "files": [
+    "types.d.ts"
+  ]
+}

package/readme.md

@@ -0,0 +1,25 @@
+ymxjs 插件类型声明
+=======
+
+[ymx-jiguang](https://zsite.cc/market/ymx-jiguang)  
+推送 极光 消息通知 别名 标签
+
+- 安装
+```bash
+npm install --save-dev @ymxjs/ymx-jiguang
+```
+
+- 配置 `tsconfig.json`
+```json
+{
+  "compilerOptions": {
+    "types": ["@ymxjs/ymx-jiguang"]
+  }
+}
+```
+
+- 使用
+```ts
+const plugin = ymx.requirePlugin('ymx-jiguang') as YmxJiguang;
+//...
+```

package/types.d.ts

@@ -0,0 +1,322 @@
+
+declare namespace YmxJiguang {
+
+  /**
+   * 插件错误码
+   */
+  enum ErrorCode {
+    /** SDK 尚未初始化（等待用户同意隐私协议后静默初始化） */
+    NotInitialized = 'NOT_INITIALIZED',
+    /** SDK 初始化失败（appKey 无效等） */
+    InitFailed = 'INIT_FAILED',
+  }
+
+  /**
+   * 插件打包配置
+   *
+   * appKey 在[极光控制台](https://www.jiguang.cn/)创建应用后获取，
+   * 与应用打包时配置。插件在用户同意隐私协议后静默初始化。
+   */
+  interface Config {
+    /**
+     * 极光推送 AppKey（在初始化之前设置）
+     */
+    appKey: string;
+    /**
+     * 初始化成功后是否请求通知权限，取值 0-10（秒），配置大于 0 时插件初始化成功后会请求通知权限
+     * @default 0
+     */
+    requestEnableNotificationDelay?: number;
+  }
+
+  /**
+   * 获取 Registration ID 结果
+   */
+  interface RegistrationIdResult {
+    /**
+     * 消息接收设备唯一标识（registrationId）
+     */
+    registrationId: string;
+  }
+
+  /**
+   * 推送状态结果
+   */
+  interface PushStoppedResult {
+    /**
+     * 推送是否已停止
+     * - `true` 已停止
+     * - `false` 未停止
+     */
+    stopped: boolean;
+  }
+
+  /**
+   * 别名参数
+   */
+  interface AliasData {
+    /**
+     * 别名
+     */
+    alias: string;
+  }
+
+  /**
+   * 别名操作结果
+   */
+  interface AliasResult {
+    /**
+     * 别名
+     */
+    alias: string;
+  }
+
+  /**
+   * 标签参数
+   */
+  interface TagsData {
+    /**
+     * 标签数组
+     */
+    tags: string[];
+  }
+
+  /**
+   * 标签操作结果
+   */
+  interface TagsResult {
+    /**
+     * 标签数组
+     */
+    tags: string[];
+  }
+
+  /**
+   * 推送消息（消息类事件的 `data` 字段格式）
+   *
+   * 与平台 jsBridge 的消息格式一致：
+   * - `messageId` 极光下发消息的编号
+   * - `payload` 消息内容（JSON 字符串，可用 `JSON.parse` 转换）
+   * - `extra` 附加内容（JSON 字符串，可用 `JSON.parse` 转换）
+   */
+  interface PushMessage {
+    /**
+     * 极光下发消息的编号
+     */
+    messageId?: string;
+    /**
+     * 消息内容（JSON 字符串）
+     */
+    payload?: string;
+    /**
+     * 附加内容（JSON 字符串）
+     */
+    extra?: string;
+  }
+}
+
+/**
+ * [极光推送](https://docs.jiguang.cn/jpush/client/HarmonyOS)
+ *
+ * 提供消息推送、标签别名、推送状态控制等能力。
+ *
+ * - 使用前需在[极光控制台](https://www.jiguang.cn/)创建应用，获取 AppKey 复制到本插件的打包配置
+ * - 插件在用户同意隐私协议后自动初始化；推送消息与操作结果通过 `setListener` 异步回传，
+ *   eventName 为 `onRegister` / `onConnected` / `onCustomMessage` / `onClickMessage` /
+ *   `onArrivedMessage` / `onJMessageExtra` / `onTagOperatorResult` / `onAliasOperatorResult` /
+ *   `onCommandResult` 等，回调 data 为 `{ action, data }` 结构，消息类事件的 `data` 格式见 `PushMessage`
+ *
+ * @example
+ * ``` ts
+ * const jpush = ymx.requirePlugin('ymx-jiguang') as YmxJiguang;
+ *
+ * // 设置消息监听器（推送消息与操作结果异步回传）
+ * jpush.setListener((eventName, data) => {
+ *   if (eventName === 'onRegister') {
+ *     console.log('registrationId:', data.data.registrationId);
+ *   } else if (eventName === 'onCustomMessage') {
+ *     console.log('自定义消息:', data.data.payload);
+ *   } else if (eventName === 'onClickMessage') {
+ *     console.log('通知点击:', data.data.payload);
+ *   }
+ * });
+ *
+ * // 插件在用户同意隐私协议后自动初始化（使用打包配置 appKey）
+ *
+ * // 获取 registrationId
+ * const res = await jpush.getRegistrationId();
+ * console.log(res.registrationId);
+ *
+ * // 设置别名
+ * await jpush.setAlias({ alias: 'user_1234' });
+ *
+ * // 设置标签
+ * await jpush.setTags({ tags: ['tag1', 'tag2'] });
+ *
+ * // 停止推送 / 恢复推送
+ * await jpush.stopPush();
+ * await jpush.resumePush();
+ * ```
+ */
+interface YmxJiguang extends JsApiBase {
+
+  /**
+   * 获取消息接收设备唯一标识（registrationId）
+   *
+   * 可用于极光控制台创建推送时指定设备。
+   *
+   * @returns registrationId
+   * @example
+   * ``` ts
+   * const res = await jpush.getRegistrationId();
+   * console.log(res.registrationId);
+   * ```
+   */
+  getRegistrationId(): Promise<YmxJiguang.RegistrationIdResult>;
+
+  /**
+   * 检查推送是否已停止
+   *
+   * @returns 推送状态（`stopped` 为 true 表示已停止）
+   * @example
+   * ``` ts
+   * const res = await jpush.isPushStopped();
+   * console.log(res.stopped);
+   * ```
+   */
+  isPushStopped(): Promise<YmxJiguang.PushStoppedResult>;
+
+  /**
+   * 停止推送
+   *
+   * 停止后无法收到推送消息，可调用 `resumePush` 恢复。
+   *
+   * @example
+   * ``` ts
+   * await jpush.stopPush();
+   * ```
+   */
+  stopPush(): Promise<void>;
+
+  /**
+   * 恢复推送
+   *
+   * 恢复接收推送消息。
+   *
+   * @example
+   * ``` ts
+   * await jpush.resumePush();
+   * ```
+   */
+  resumePush(): Promise<void>;
+
+  /**
+   * 设置别名
+   *
+   * 别名用于定向推送；实际操作结果在 `setListener` 的 eventName `onAliasOperatorResult` 中异步返回。
+   *
+   * @param data 别名参数（`alias` 必填）
+   * @returns 操作已发起（结果异步回传）
+   * @example
+   * ``` ts
+   * await jpush.setAlias({ alias: 'user_1234' });
+   * ```
+   */
+  setAlias(data: YmxJiguang.AliasData): Promise<YmxJiguang.AliasResult>;
+
+  /**
+   * 删除别名
+   *
+   * 删除当前绑定的别名；实际操作结果在 `setListener` 的 eventName `onAliasOperatorResult` 中异步返回。
+   *
+   * @returns 操作已发起（结果异步回传）
+   * @example
+   * ``` ts
+   * await jpush.deleteAlias();
+   * ```
+   */
+  deleteAlias(): Promise<YmxJiguang.AliasResult>;
+
+  /**
+   * 获取当前绑定的别名
+   *
+   * 实际结果在 `setListener` 的 eventName `onAliasOperatorResult` 中异步返回，本方法 Promise 返回该结果。
+   *
+   * @returns 当前别名
+   * @example
+   * ``` ts
+   * const res = await jpush.getAlias();
+   * console.log(res.alias);
+   * ```
+   */
+  getAlias(): Promise<YmxJiguang.AliasResult>;
+
+  /**
+   * 设置标签（覆盖式）
+   *
+   * 覆盖设置当前绑定的标签；实际操作结果在 `setListener` 的 eventName `onTagOperatorResult` 中异步返回。
+   *
+   * @param data 标签参数（`tags` 必填）
+   * @returns 操作已发起（结果异步回传）
+   * @example
+   * ``` ts
+   * await jpush.setTags({ tags: ['tag1', 'tag2'] });
+   * ```
+   */
+  setTags(data: YmxJiguang.TagsData): Promise<YmxJiguang.TagsResult>;
+
+  /**
+   * 新增标签
+   *
+   * 追加绑定标签；实际操作结果在 `setListener` 的 eventName `onTagOperatorResult` 中异步返回。
+   *
+   * @param data 标签参数（`tags` 必填）
+   * @returns 操作已发起（结果异步回传）
+   * @example
+   * ``` ts
+   * await jpush.addTags({ tags: ['tag3'] });
+   * ```
+   */
+  addTags(data: YmxJiguang.TagsData): Promise<YmxJiguang.TagsResult>;
+
+  /**
+   * 删除指定标签
+   *
+   * 删除指定标签；实际操作结果在 `setListener` 的 eventName `onTagOperatorResult` 中异步返回。
+   *
+   * @param data 标签参数（`tags` 必填）
+   * @returns 操作已发起（结果异步回传）
+   * @example
+   * ``` ts
+   * await jpush.deleteTags({ tags: ['tag1'] });
+   * ```
+   */
+  deleteTags(data: YmxJiguang.TagsData): Promise<YmxJiguang.TagsResult>;
+
+  /**
+   * 清空所有标签
+   *
+   * 清空当前绑定的全部标签；实际操作结果在 `setListener` 的 eventName `onTagOperatorResult` 中异步返回。
+   *
+   * @returns 操作已发起（结果异步回传）
+   * @example
+   * ``` ts
+   * await jpush.cleanTags();
+   * ```
+   */
+  cleanTags(): Promise<YmxJiguang.TagsResult>;
+
+  /**
+   * 获取当前绑定的所有标签
+   *
+   * 实际结果在 `setListener` 的 eventName `onTagOperatorResult` 中异步返回，本方法 Promise 返回该结果。
+   *
+   * @returns 当前标签数组
+   * @example
+   * ``` ts
+   * const res = await jpush.getAllTags();
+   * console.log(res.tags);
+   * ```
+   */
+  getAllTags(): Promise<YmxJiguang.TagsResult>;
+}