react-native-nitro-ali-push 0.0.0-stage → 1.0.0

package/src/index.ts

@@ -0,0 +1,284 @@
+/**
+ * react-native-nitro-ali-push —— 阿里云移动推送 React Native 封装（Nitro Modules）。
+ *
+ * 提供账号 / 标签 / 别名绑定、设备号获取、角标管理，以及统一的推送消息事件订阅。
+ * 原生实现基于 Nitro Modules（HybridObject），iOS 端为 Swift、Android 端为 Kotlin，
+ * 由 `nitrogen` 代码生成器生成桥接层。
+ *
+ * @packageDocumentation
+ */
+import { NitroModules } from 'react-native-nitro-modules';
+
+import type { AliPushPlugin } from './specs/AliPushPlugin.nitro';
+import { ALI_PUSH_EVENT } from './types';
+import type { AliPushEvent, AliPushMessage, AliPushTagTarget } from './types';
+
+/**
+ * 原生模块实例（Nitro HybridObject）。
+ *
+ * 若宿主工程未正确集成 Nitro 或缺少原生实现，会在此处抛错。
+ *
+ * @internal
+ */
+const AliPushNative = NitroModules.createHybridObject<AliPushPlugin>('AliPushPlugin');
+
+/**
+ * 初始化阿里云推送。
+ *
+ * @remarks
+ * **Android**：调用此方法并通过 `appKey` / `appSecret` 向阿里云推送服务注册应用，
+ * 必须在 `App` 挂载前调用。需要在 `AndroidManifest.xml` 中配置推送 `AppKey` /
+ * `AppSecret`（见 README）。
+ *
+ * **iOS**：推送初始化在原生 `AppDelegate` 中通过 `CloudPushSDK` 完成，此方法在
+ * iOS 上为无操作。
+ *
+ * @param appKey - 阿里云推送控制台分配的 AppKey。
+ * @param appSecret - 阿里云推送控制台分配的 AppSecret。
+ * @returns 初始化完成的 Promise。
+ *
+ * @example
+ * ```ts
+ * await AliPush.initPush('your_app_key', 'your_app_secret');
+ * ```
+ */
+export function initPush(appKey: string, appSecret: string): Promise<void> {
+  return AliPushNative.initPush(appKey, appSecret);
+}
+
+/**
+ * 获取设备唯一标识 `deviceId`。
+ *
+ * @returns 解析为设备 `deviceId` 字符串的 Promise。
+ *
+ * @example
+ * ```ts
+ * const deviceId = await AliPush.getDeviceId();
+ * console.log(deviceId);
+ * ```
+ */
+export function getDeviceId(): Promise<string> {
+  return AliPushNative.getDeviceId();
+}
+
+/**
+ * 绑定账号。
+ *
+ * @param account - 待绑定的账号（字符串，长度建议 ≤ 64）。
+ * @returns 操作完成的 Promise。
+ */
+export function bindAccount(account: string): Promise<void> {
+  return AliPushNative.bindAccount(account);
+}
+
+/**
+ * 解绑账号（解绑当前已绑定账号）。
+ *
+ * @returns 操作完成的 Promise。
+ */
+export function unbindAccount(): Promise<void> {
+  return AliPushNative.unbindAccount();
+}
+
+/**
+ * 绑定标签。
+ *
+ * @param target - 目标类型：`1` 设备 / `2` 账号 / `3` 别名。
+ * @param tags - 标签数组（字符串）。
+ * @param alias - 别名（可空，仅 `target = 3` 时生效）。
+ * @returns 操作完成的 Promise。
+ *
+ * @example
+ * ```ts
+ * await AliPush.bindTag(1, ['news', 'sports'], null);
+ * ```
+ */
+export function bindTag(
+  target: AliPushTagTarget,
+  tags: string[],
+  alias: string | null,
+): Promise<void> {
+  return AliPushNative.bindTag(target, tags, alias);
+}
+
+/**
+ * 解绑标签。参数语义同 {@link bindTag}。
+ *
+ * @param target - 目标类型：`1` 设备 / `2` 账号 / `3` 别名。
+ * @param tags - 待解绑的标签数组。
+ * @param alias - 别名（可空）。
+ * @returns 操作完成的 Promise。
+ */
+export function unbindTag(
+  target: AliPushTagTarget,
+  tags: string[],
+  alias: string | null,
+): Promise<void> {
+  return AliPushNative.unbindTag(target, tags, alias);
+}
+
+/**
+ * 列出当前已绑定的标签。
+ *
+ * @param target - 目标类型：`1` 设备 / `2` 账号 / `3` 别名。
+ * @returns 解析为服务端响应字符串（含标签列表）的 Promise。
+ */
+export function listTags(target: AliPushTagTarget): Promise<string> {
+  return AliPushNative.listTags(target);
+}
+
+/**
+ * 添加别名。
+ *
+ * @param alias - 待添加的别名。
+ * @returns 操作完成的 Promise。
+ */
+export function addAlias(alias: string): Promise<void> {
+  return AliPushNative.addAlias(alias);
+}
+
+/**
+ * 移除别名。
+ *
+ * @param alias - 待移除的别名。
+ * @returns 操作完成的 Promise。
+ */
+export function removeAlias(alias: string): Promise<void> {
+  return AliPushNative.removeAlias(alias);
+}
+
+/**
+ * 列出当前已添加的别名。
+ *
+ * @returns 解析为服务端响应字符串（含别名列表）的 Promise。
+ */
+export function listAliases(): Promise<string> {
+  return AliPushNative.listAliases();
+}
+
+/**
+ * 设置应用角标（桌面图标右上角数字）。
+ *
+ * @param badge - 角标数字，`0` 表示清除。
+ * @returns 操作完成的 Promise。
+ */
+export function setApplicationIconBadgeNumber(badge: number): Promise<void> {
+  return AliPushNative.setApplicationIconBadgeNumber(badge);
+}
+
+/**
+ * 获取应用当前角标数字。
+ *
+ * @returns 解析为当前角标数字的 Promise。
+ */
+export function getApplicationIconBadgeNumber(): Promise<number> {
+  return AliPushNative.getApplicationIconBadgeNumber();
+}
+
+/**
+ * 获取 App 冷启动（被通知唤起）时缓存的首条推送消息。
+ *
+ * @remarks
+ * 当 App 完全退出后被通知点击唤起，JS 尚未完成订阅的窗口期内到达的消息会被原生端
+ * 缓存，待 JS 就绪后通过此方法或 {@link ALI_PUSH_EVENT} 事件返回。
+ *
+ * @returns 缓存消息对象，无则 `null`。
+ */
+export function getInitialMessage(): Promise<AliPushMessage | null> {
+  return AliPushNative.getInitialMessage();
+}
+
+/**
+ * 获取 iOS 通知授权状态。
+ *
+ * @remarks Android 平台固定返回 `true`（Android 不做通知权限前置拦截）。
+ *
+ * @returns 解析为是否已授权的布尔值 Promise。
+ */
+export function getAuthorizationStatus(): Promise<boolean> {
+  return AliPushNative.getAuthorizationStatus();
+}
+
+/**
+ * 将角标数字同步到阿里云服务端。
+ *
+ * @remarks 仅 iOS 有效，Android 为无操作。
+ *
+ * @param badge - 角标数字。
+ * @returns 操作完成的 Promise。
+ */
+export function syncBadgeNum(badge: number): Promise<void> {
+  return AliPushNative.syncBadgeNum(badge);
+}
+
+/**
+ * 订阅推送消息事件。
+ *
+ * @param event - 事件名，本库仅支持 {@link ALI_PUSH_EVENT}（`'aliyunPushReceived'`）。
+ * @param listener - 回调，参数为 {@link AliPushMessage}。
+ * @returns 退订函数，调用即可取消该监听。
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = AliPush.addEventListener('aliyunPushReceived', (msg) => {
+ *   console.log('收到推送', msg.title, msg.body);
+ * });
+ * // 不再需要时
+ * unsubscribe();
+ * ```
+ */
+export function addEventListener(
+  event: AliPushEvent,
+  listener: (message: AliPushMessage) => void,
+): () => void {
+  if (event !== ALI_PUSH_EVENT) {
+    console.warn(`[react-native-nitro-ali-push] Unsupported event: ${event}`);
+    return () => {};
+  }
+  return AliPushNative.addListener(listener);
+}
+
+/**
+ * 取消订阅推送消息事件。
+ *
+ * @param unsubscribe - {@link addEventListener} 返回的退订函数。
+ *
+ * @example
+ * ```ts
+ * AliPush.removeEventListener(unsubscribe);
+ * ```
+ */
+export function removeEventListener(unsubscribe: () => void): void {
+  unsubscribe?.();
+}
+
+/**
+ * 默认导出对象（同时支持具名与默认导入）。
+ *
+ * @public
+ */
+const AliPush = {
+  initPush,
+  getDeviceId,
+  bindAccount,
+  unbindAccount,
+  bindTag,
+  unbindTag,
+  listTags,
+  addAlias,
+  removeAlias,
+  listAliases,
+  setApplicationIconBadgeNumber,
+  getApplicationIconBadgeNumber,
+  getInitialMessage,
+  getAuthorizationStatus,
+  syncBadgeNum,
+  addEventListener,
+  removeEventListener,
+  /** 事件名常量，便于 `addEventListener(AliPush.ALI_PUSH_EVENT, ...)`。 */
+  ALI_PUSH_EVENT,
+};
+
+export { ALI_PUSH_EVENT };
+export type { AliPushEvent, AliPushMessage, AliPushTagTarget };
+export default AliPush;

package/src/specs/AliPushPlugin.nitro.ts

@@ -0,0 +1,104 @@
+/**
+ * 阿里云推送（react-native-nitro-ali-push）的 Nitro 原生接口规格。
+ *
+ * 本文件由 `nitrogen`（Nitro 代码生成器）读取，生成 C++ 桥接层以及 iOS Swift /
+ * Android Kotlin 的实现桩。每个方法签名即为 JS 调用名（驼峰），与
+ * {@link "../index"} 中的封装函数一一对应。
+ *
+ * 事件订阅采用 Nitro 的回调约定：`addListener` 接收一个 JS 回调，返回用于
+ * 退订的 `() => void` 闭包（Nitro 会自动跨语言封送函数类型）。
+ *
+ * @packageDocumentation
+ */
+import { type HybridObject, type AnyMap } from 'react-native-nitro-modules';
+
+import type { AliPushMessage } from '../types';
+
+/**
+ * 推送消息事件回调类型。
+ *
+ * 参数即 {@link AliPushMessage}，由原生端通过 {@link AliPushPlugin.addListener}
+ * 注册的回调回传。
+ */
+export type AliPushListener = (message: AliPushMessage) => void;
+
+/**
+ * 阿里云推送原生模块（HybridObject）规格。
+ *
+ * - iOS 实现语言：`swift`（`HybridAliPushPlugin`）
+ * - Android 实现语言：`kotlin`（`HybridAliPushPlugin`）
+ *
+ * @public
+ */
+export interface AliPushPlugin
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  /**
+   * 初始化阿里云推送。
+   *
+   * - **Android**：通过 `appKey` / `appSecret` 向阿里云推送服务注册应用。
+   * - **iOS**：初始化在原生 `AppDelegate` 中完成（见 README），此方法为无操作。
+   */
+  initPush(appKey: string, appSecret: string): Promise<void>;
+
+  /** 获取设备唯一标识 `deviceId`。 */
+  getDeviceId(): Promise<string>;
+
+  /** 绑定账号。 */
+  bindAccount(account: string): Promise<void>;
+
+  /** 解绑账号。 */
+  unbindAccount(): Promise<void>;
+
+  /**
+   * 绑定标签。
+   *
+   * @param target 目标类型（1 设备 / 2 账号 / 3 别名）。
+   * @param tags 标签数组。
+   * @param alias 别名（可空）。
+   */
+  bindTag(target: number, tags: string[], alias: string | null): Promise<void>;
+
+  /**
+   * 解绑标签。
+   *
+   * @param target 目标类型（1 设备 / 2 账号 / 3 别名）。
+   * @param tags 标签数组。
+   * @param alias 别名（可空）。
+   */
+  unbindTag(target: number, tags: string[], alias: string | null): Promise<void>;
+
+  /** 列出当前标签（返回服务端响应字符串）。 */
+  listTags(target: number): Promise<string>;
+
+  /** 添加别名。 */
+  addAlias(alias: string): Promise<void>;
+
+  /** 移除别名。 */
+  removeAlias(alias: string): Promise<void>;
+
+  /** 列出当前别名（返回服务端响应字符串）。 */
+  listAliases(): Promise<string>;
+
+  /** 设置应用角标数字。 */
+  setApplicationIconBadgeNumber(badge: number): Promise<void>;
+
+  /** 获取应用当前角标数字。 */
+  getApplicationIconBadgeNumber(): Promise<number>;
+
+  /** 获取 App 冷启动（被通知唤起）时缓存的首条推送消息，无则 `null`。 */
+  getInitialMessage(): Promise<AliPushMessage | null>;
+
+  /** 获取 iOS 通知授权状态（Android 固定返回 `true`）。 */
+  getAuthorizationStatus(): Promise<boolean>;
+
+  /** 同步角标到阿里云服务端（仅 iOS 有效，Android 为无操作）。 */
+  syncBadgeNum(badge: number): Promise<void>;
+
+  /**
+   * 订阅推送消息事件。
+   *
+   * @param listener 收到消息时的回调。
+   * @returns 退订函数，调用即可取消该监听。
+   */
+  addListener(listener: AliPushListener): () => void;
+}

package/src/types.ts

@@ -0,0 +1,117 @@
+/**
+ * 阿里云推送（react-native-nitro-ali-push）相关的 TypeScript 类型定义。
+ *
+ * 这些类型既用于描述 JS 端 API 的入参/返回值，也用于描述原生端通过
+ * `aliyunPushReceived` 事件回传给 JS 的推送载荷结构。
+ *
+ * @packageDocumentation
+ */
+import { type AnyMap } from 'react-native-nitro-modules';
+
+/**
+ * 消息类型。
+ *
+ * - `'notification'` 通知栏消息；
+ * - `'message'` 透传 / 非通知栏消息。
+ *
+ * 抽成命名类型，供 Nitro 代码生成器（nitrogen）识别（内联联合类型不被支持）。
+ *
+ * @public
+ */
+export type AliPushMessageType = 'notification' | 'message';
+
+/**
+ * 收到消息时 App 所处的状态。
+ *
+ * - `'active'` 前台运行中；
+ * - `'inactive'` 非活跃（如来电打断）；
+ * - `'background'` 后台。
+ *
+ * 抽成命名类型，供 Nitro 代码生成器识别。
+ *
+ * @public
+ */
+export type AliPushAppState = 'active' | 'inactive' | 'background';
+
+/**
+ * 推送载荷。
+ *
+ * 无论是「通知栏消息」(notification) 还是「透传/非通知栏消息」(message)，
+ * 原生端通过 {@link ALI_PUSH_EVENT | `aliyunPushReceived`} 事件回传给 JS 的
+ * 数据结构都遵循此接口。
+ *
+ * @public
+ */
+export interface AliPushMessage {
+  /** 通知标题。 */
+  title?: string;
+  /** 通知副标题（iOS 在前台/点击场景下可能携带）。 */
+  subtitle?: string;
+  /** 通知正文 / 内容。 */
+  body?: string;
+  /** 角标数字。 */
+  badge?: number;
+  /**
+   * 自定义键值对。
+   *
+   * 即推送后台设置的 `extras` / 业务参数，键为字符串，值可为字符串、数字、
+   * 布尔或嵌套结构（经 Nitro 的 {@link AnyMap} 跨语言封送）。
+   */
+  extras?: AnyMap;
+  /**
+   * 消息类型：
+   *
+   * - `'notification'` 通知栏消息；
+   * - `'message'` 透传 / 非通知栏消息。
+   */
+  type?: AliPushMessageType;
+  /**
+   * 点击行为标识：
+   *
+   * - `'opened'` 用户点击打开；
+   * - `'removed'` 用户删除；
+   * - 其它字符串表示自定义 action 标识。
+   */
+  actionIdentifier?: string;
+  /**
+   * 收到消息时 App 所处的状态：
+   *
+   * - `'active'` 前台运行中；
+   * - `'inactive'` 非活跃（如来电打断）；
+   * - `'background'` 后台。
+   */
+  appState?: AliPushAppState;
+  /** 通知到达 / 点击的时间。iOS 为 `Date` 序列化后的值（数字时间戳或字符串）。 */
+  date?: number | string;
+}
+
+/**
+ * 本库支持监听的事件名。
+ *
+ * 目前仅支持 {@link ALI_PUSH_EVENT}。
+ *
+ * @public
+ */
+export type AliPushEvent = typeof ALI_PUSH_EVENT;
+
+/**
+ * 推送消息事件名常量。
+ *
+ * 通过 {@link addEventListener} 订阅，回调参数为 {@link AliPushMessage}。
+ *
+ * @public
+ */
+export const ALI_PUSH_EVENT = 'aliyunPushReceived' as const;
+
+/**
+ * 绑定 / 解绑标签时的目标类型。
+ *
+ * 对应阿里云推送 SDK 的 `target` 参数：
+ *
+ * - `1` 针对设备；
+ * - `2` 针对账号；
+ * - `3` 针对别名。
+ *
+ * @public
+ */
+export type AliPushTagTarget = 1 | 2 | 3;