@omni-gate/sse-sdk-api 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @omni-gate/sse-sdk-api
 
-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.
+[中文](./README_CN.md)
+
+ESM-only TypeScript SDK for OmniGate backend services to use the sse-service: issue SSE connection tickets for users and push events to users, apps or topics.
+
+## Requirements
+
+- Node.js 20.19 or later (ESM only)
+- The sse-service must be reachable on the internal network. It runs as a single instance; `/ticket` and `/notification` are internal only (blocked at the gateway), no apiKey needed
+
+## Installation
+
+```bash
+pnpm add @omni-gate/sse-sdk-api        # inside the workspace use "workspace:*"
+```
+
+## Initialization
+
+```typescript
+import SseServiceApi from '@omni-gate/sse-sdk-api';
+
+SseServiceApi.initialize({
+    portal: 'http://omni-sse/webservice',  // internal sse-service address
+    timeout: 5000                          // pushes are side effects, keep it short
+});
+
+const sseApi = SseServiceApi.getInstance();
+```
+
+When push is optional, initialize only if an address is configured and check `SseServiceApi.isInitialized()` before calling.
+
+## Tags
+
+Connections receive pushes by tag, formatted `{tenantCode}|{type}|{id}`:
+
+```typescript
+import {SseTags} from '@omni-gate/sse-sdk-api';
+
+SseTags.user('T001', 'zhangsan');   // T001|U|zhangsan  user (used by omni-portal)
+SseTags.app('T001', 'BIG_SCREEN');  // T001|A|BIG_SCREEN app
+SseTags.topic('T001', 'orders');    // T001|T|orders     topic
+SseTags.parse('T001|U|zhangsan');   // {tenantCode, type, id}, or null when malformed
+```
+
+Tenant code and id must be non-empty and contain no spaces or `|`; otherwise an error is thrown.
+
+## Connection tickets
+
+After authenticating the user, a backend service requests a ticket and hands it to the browser. A ticket is valid for 120 seconds and can be used once:
+
+```typescript
+const ticket = await sseApi.createUserTicket(user.tenantCode, user.accountCode);
+return {ticket};
+```
+
+Browser:
+
+```typescript
+const source = new EventSource(`/api/omni/sse/webservice/connection/${encodeURIComponent(ticket)}?token=${jwt}`);
+source.addEventListener('todo-changed', e => { /* JSON.parse(e.data) */ });
+source.onerror = () => {
+    source.close();
+    // tickets are single-use: back off, request a new ticket and reconnect (see omni-portal PortalEvents)
+};
+```
+
+Never let the browser choose the tag: the tag decides whose messages it receives and must be built on the server from the logged-in user.
+
+## Pushing events
+
+```typescript
+const {count} = await sseApi.sendToUser('T001', 'zhangsan', 'todo-changed', {groupId: 12});   // count = 0 when offline
+const {count: total, failed} = await sseApi.sendToUsers('T001', ['zhangsan', 'lisi'], 'message-received', {});
+await sseApi.sendToTag('T001', SseTags.topic('T001', 'orders'), 'order-created', {orderNo: 'SO-001'});
+```
+
+- `event` is the browser `addEventListener` name; `data` is sent as JSON.
+- Delivery is best effort: offline users miss events and nothing is replayed. Persist anything that must arrive (e.g. inbox messages) and use the push only to tell the browser to refresh.
+- Push after the transaction commits, and catch and log errors so they do not affect the business result.
+
+## Error handling
+
+HTTP errors are mapped by `@omni-gate/sdk-core`: 400 → `IllegalParameterError` (invalid ticket / tag), 503 → `ServiceUnavailableError` (connection limit reached);
+network errors and unmapped status codes throw `ServiceApiError`.
+
+## Build and publish
+
+```bash
+pnpm build
+pnpm test:modules
+pnpm publish:public
+```

package/README_CN.md

@@ -0,0 +1,99 @@
+# @omni-gate/sse-sdk-api
+
+[English](./README.md)
+
+供 OmniGate 内部后端服务调用 sse-service 的纯 ESM TypeScript SDK：为用户申请 SSE 连接票据，向用户、应用或主题推送事件。
+
+## 环境要求
+
+- Node.js 20.19 或更高版本（纯 ESM）
+- 能在内网访问 sse-service。sse-service 单实例部署，`/ticket`、`/notification` 只在内网开放（网关阻断），不需要 apiKey
+
+## 安装
+
+```bash
+pnpm add @omni-gate/sse-sdk-api        # 工作区内使用 "workspace:*"
+```
+
+## 初始化
+
+```typescript
+import SseServiceApi from '@omni-gate/sse-sdk-api';
+
+SseServiceApi.initialize({
+    portal: 'http://omni-sse/webservice',  // sse-service 内部地址
+    timeout: 5000                          // 推送是旁路操作，建议设短一些
+});
+
+const sseApi = SseServiceApi.getInstance();
+```
+
+推送是可选能力时，可以只在配置了地址时初始化，调用前用 `SseServiceApi.isInitialized()` 判断。
+
+## 标签
+
+连接按标签接收推送，格式 `{tenantCode}|{类型}|{标识}`：
+
+```typescript
+import {SseTags} from '@omni-gate/sse-sdk-api';
+
+SseTags.user('T001', 'zhangsan');   // T001|U|zhangsan  用户（omni-portal 使用）
+SseTags.app('T001', 'BIG_SCREEN');  // T001|A|BIG_SCREEN 应用
+SseTags.topic('T001', 'orders');    // T001|T|orders     主题
+SseTags.parse('T001|U|zhangsan');   // {tenantCode, type, id}，格式不对返回 null
+```
+
+租户编码和标识不能为空，也不能包含空格或 `|`，否则抛出异常。
+
+## 申请连接票据
+
+业务服务在确认当前用户身份后申请票据，交给前端建立连接。票据 120 秒内有效、只能用一次：
+
+```typescript
+// 例如 GET /tenant/me/sse-ticket 的实现
+const ticket = await sseApi.createUserTicket(user.tenantCode, user.accountCode);
+return {ticket};
+```
+
+前端：
+
+```typescript
+const source = new EventSource(`/api/omni/sse/webservice/connection/${encodeURIComponent(ticket)}?token=${jwt}`);
+source.addEventListener('todo-changed', e => { /* JSON.parse(e.data) */ });
+source.onerror = () => {
+    source.close();
+    // 票据是一次性的：退避后重新申请票据再连接（参见 omni-portal 的 PortalEvents）
+};
+```
+
+不要让前端自己指定标签申请票据：标签决定能收到谁的消息，必须由服务端按登录用户构建。
+
+## 推送
+
+```typescript
+// 推送给用户的所有连接；count 为成功写出的连接数，用户不在线时为 0
+const {count} = await sseApi.sendToUser('T001', 'zhangsan', 'todo-changed', {groupId: 12});
+
+// 推送给多个用户（去重，单个失败不影响其他人）
+const {count: total, failed} = await sseApi.sendToUsers('T001', ['zhangsan', 'lisi'], 'message-received', {});
+
+// 按标签推送：标签必须属于该租户
+await sseApi.sendToTag('T001', SseTags.topic('T001', 'orders'), 'order-created', {orderNo: 'SO-001'});
+```
+
+- `event` 是前端 `addEventListener` 的事件名；`data` 以 JSON 发送。
+- 推送不保证送达：离线用户收不到，也不会补发。需要可靠送达的内容（如站内消息）先落库，推送只用来提醒前端刷新。
+- 推送通常不应影响业务结果，建议在事务提交后调用，并捕获异常只记日志。
+
+## 错误处理
+
+HTTP 错误按 `@omni-gate/sdk-core` 的规则映射：400 → `IllegalParameterError`（票据/标签无效），503 → `ServiceUnavailableError`（连接数已达上限），
+网络错误和未映射的状态码抛 `ServiceApiError`。
+
+## 构建与发布
+
+```bash
+pnpm build          # 输出到 dist/
+pnpm test:modules   # 验证 ESM 入口
+pnpm publish:public
+```

package/dist/SseServiceApi.d.ts

@@ -0,0 +1,54 @@
+import { CommonServiceApi } from '@omni-gate/sdk-core';
+import type { SseApiConfigOptions, SsePushResult } from './types.js';
+/**
+ * sse-service 服务端 SDK（内部服务调用）。
+ *
+ * - 申请票据：业务服务确认用户身份后，为其标签申请一次性票据（120 秒有效）交给前端，
+ *   前端用 `/connection/{ticket}` 建立 EventSource 连接；票据只能用一次，断线后要重新申请。
+ * - 推送：按用户或按标签推送事件，返回成功写出的连接数，用户不在线时为 0。
+ *
+ * sse-service 单实例部署、只在内网暴露；`/ticket`、`/notification` 不对外开放。
+ */
+export default class SseServiceApi extends CommonServiceApi {
+    private static instance?;
+    private constructor();
+    /**
+     * 初始化单例（服务启动时调用一次）
+     */
+    static initialize(config: SseApiConfigOptions): SseServiceApi;
+    static getInstance(): SseServiceApi;
+    /** 是否已初始化（推送是可选能力时，可据此跳过） */
+    static isInitialized(): boolean;
+    /**
+     * 为标签申请一次性连接票据
+     * @param tag 用 SseTags 构建的标签
+     * @returns 票据
+     */
+    createTicket(tag: string): Promise<string>;
+    /**
+     * 为用户申请连接票据
+     */
+    createUserTicket(tenantCode: string, accountCode: string): Promise<string>;
+    /**
+     * 推送给用户的所有连接
+     * @param event 事件名，前端用 addEventListener(event) 接收
+     * @param data 事件数据（JSON）
+     */
+    sendToUser(tenantCode: string, accountCode: string, event: string, data?: unknown): Promise<SsePushResult>;
+    /**
+     * 推送给多个用户；单个失败不影响其他用户
+     * @returns 成功写出的连接总数与失败的账号
+     */
+    sendToUsers(tenantCode: string, accountCodes: Array<string>, event: string, data?: unknown): Promise<{
+        count: number;
+        failed: Array<{
+            accountCode: string;
+            error: unknown;
+        }>;
+    }>;
+    /**
+     * 按标签推送；标签必须属于 tenantCode 的租户
+     */
+    sendToTag(tenantCode: string, tag: string, event: string, data?: unknown): Promise<SsePushResult>;
+}
+//# sourceMappingURL=SseServiceApi.d.ts.map

package/dist/SseServiceApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SseServiceApi.d.ts","sourceRoot":"","sources":["../src/SseServiceApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAC,mBAAmB,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAEnE;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,gBAAgB;IAEvD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAgB;IAExC,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa;IAU7D,MAAM,CAAC,WAAW,IAAI,aAAa;IAOnC,6BAA6B;IAC7B,MAAM,CAAC,aAAa,IAAI,OAAO;IAI/B;;;;OAIG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQhD;;OAEG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIhF;;;;OAIG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAMpH;;;OAGG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,OAAY,GAChG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,KAAK,CAAC;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,OAAO,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;IAetF;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,aAAa,CAAC;CAU9G"}

package/dist/SseServiceApi.js

@@ -0,0 +1,100 @@
+import { CommonServiceApi } from '@omni-gate/sdk-core';
+import SseTags from './SseTags.js';
+/**
+ * sse-service 服务端 SDK（内部服务调用）。
+ *
+ * - 申请票据：业务服务确认用户身份后，为其标签申请一次性票据（120 秒有效）交给前端，
+ *   前端用 `/connection/{ticket}` 建立 EventSource 连接；票据只能用一次，断线后要重新申请。
+ * - 推送：按用户或按标签推送事件，返回成功写出的连接数，用户不在线时为 0。
+ *
+ * sse-service 单实例部署、只在内网暴露；`/ticket`、`/notification` 不对外开放。
+ */
+export default class SseServiceApi extends CommonServiceApi {
+    static instance;
+    constructor(config) {
+        super(config, 'SSE service');
+    }
+    /**
+     * 初始化单例（服务启动时调用一次）
+     */
+    static initialize(config) {
+        if (!SseServiceApi.instance) {
+            if (!config?.portal) {
+                throw new Error('缺少 sse-service 地址 portal');
+            }
+            SseServiceApi.instance = new SseServiceApi(config);
+        }
+        return SseServiceApi.instance;
+    }
+    static getInstance() {
+        if (!SseServiceApi.instance) {
+            throw new Error('SseServiceApi has not been initialized. Call SseServiceApi.initialize() first.');
+        }
+        return SseServiceApi.instance;
+    }
+    /** 是否已初始化（推送是可选能力时，可据此跳过） */
+    static isInitialized() {
+        return SseServiceApi.instance != null;
+    }
+    /**
+     * 为标签申请一次性连接票据
+     * @param tag 用 SseTags 构建的标签
+     * @returns 票据
+     */
+    async createTicket(tag) {
+        if (!SseTags.parse(tag)) {
+            throw new Error(`无效的 SSE 标签：${tag}`);
+        }
+        const res = await this.get('/ticket/custom', { params: { tag } });
+        return res.ticket;
+    }
+    /**
+     * 为用户申请连接票据
+     */
+    async createUserTicket(tenantCode, accountCode) {
+        return this.createTicket(SseTags.user(tenantCode, accountCode));
+    }
+    /**
+     * 推送给用户的所有连接
+     * @param event 事件名，前端用 addEventListener(event) 接收
+     * @param data 事件数据（JSON）
+     */
+    async sendToUser(tenantCode, accountCode, event, data = {}) {
+        return this.post(`/notification/user/${encodeURIComponent(event)}`, data ?? {}, {
+            headers: { 'tenant-code': tenantCode, 'account-code': accountCode }
+        });
+    }
+    /**
+     * 推送给多个用户；单个失败不影响其他用户
+     * @returns 成功写出的连接总数与失败的账号
+     */
+    async sendToUsers(tenantCode, accountCodes, event, data = {}) {
+        const accounts = Array.from(new Set(accountCodes.filter(a => a)));
+        const results = await Promise.allSettled(accounts.map(a => this.sendToUser(tenantCode, a, event, data)));
+        let count = 0;
+        const failed = [];
+        results.forEach((r, i) => {
+            if (r.status === 'fulfilled') {
+                count += r.value?.count ?? 0;
+            }
+            else {
+                failed.push({ accountCode: accounts[i], error: r.reason });
+            }
+        });
+        return { count, failed };
+    }
+    /**
+     * 按标签推送；标签必须属于 tenantCode 的租户
+     */
+    async sendToTag(tenantCode, tag, event, data = {}) {
+        const info = SseTags.parse(tag);
+        if (!info || info.tenantCode !== tenantCode) {
+            throw new Error(`SSE 标签 ${tag} 无效或不属于租户 ${tenantCode}`);
+        }
+        return this.post(`/notification/tag/${encodeURIComponent(event)}`, data ?? {}, {
+            params: { tag },
+            headers: { 'tenant-code': tenantCode }
+        });
+    }
+}
+//# sourceMappingURL=SseServiceApi.js.map

package/dist/SseServiceApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SseServiceApi.js","sourceRoot":"","sources":["../src/SseServiceApi.ts"],"names":[],"mappings":"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"}

package/dist/SseTags.d.ts

@@ -0,0 +1,17 @@
+import type { SseTagInfo } from './types.js';
+/**
+ * SSE 标签：`{tenantCode}|{U|A|T}|{标识}`，与 sse-service 的格式一致。
+ * 连接按标签接收推送；按标签推送时 sse-service 要求标签属于调用时传入的租户。
+ */
+declare const SseTags: {
+    /** 用户标签：推送给该用户的所有连接（如 omni-portal） */
+    user: (tenantCode: string, accountCode: string) => string;
+    /** 应用标签：推送给某个应用（如大屏、移动端）的连接 */
+    app: (tenantCode: string, appCode: string) => string;
+    /** 主题标签：推送给订阅某个主题的连接 */
+    topic: (tenantCode: string, topic: string) => string;
+    /** 解析标签，格式不对时返回 null */
+    parse: (tag: string) => SseTagInfo | null;
+};
+export default SseTags;
+//# sourceMappingURL=SseTags.d.ts.map

package/dist/SseTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SseTags.d.ts","sourceRoot":"","sources":["../src/SseTags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAa,MAAM,YAAY,CAAC;AAYvD;;;GAGG;AACH,QAAA,MAAM,OAAO;IACT,sCAAsC;uBACnB,MAAM,eAAe,MAAM,KAAG,MAAM;IACvD,+BAA+B;sBACb,MAAM,WAAW,MAAM,KAAG,MAAM;IAClD,wBAAwB;wBACJ,MAAM,SAAS,MAAM,KAAG,MAAM;IAClD,wBAAwB;iBACX,MAAM,KAAG,UAAU,GAAG,IAAI;CAI1C,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/SseTags.js

@@ -0,0 +1,27 @@
+const TAG_PATTERN = /^([^|\s]+)\|([UAT])\|([^|\s]+)$/;
+const build = (tenantCode, type, id) => {
+    const tag = `${tenantCode}|${type}|${id}`;
+    if (!TAG_PATTERN.test(tag)) {
+        throw new Error(`无效的 SSE 标签：${tag}（租户编码和标识不能为空，也不能包含空格或 "|"）`);
+    }
+    return tag;
+};
+/**
+ * SSE 标签：`{tenantCode}|{U|A|T}|{标识}`，与 sse-service 的格式一致。
+ * 连接按标签接收推送；按标签推送时 sse-service 要求标签属于调用时传入的租户。
+ */
+const SseTags = {
+    /** 用户标签：推送给该用户的所有连接（如 omni-portal） */
+    user: (tenantCode, accountCode) => build(tenantCode, 'U', accountCode),
+    /** 应用标签：推送给某个应用（如大屏、移动端）的连接 */
+    app: (tenantCode, appCode) => build(tenantCode, 'A', appCode),
+    /** 主题标签：推送给订阅某个主题的连接 */
+    topic: (tenantCode, topic) => build(tenantCode, 'T', topic),
+    /** 解析标签，格式不对时返回 null */
+    parse: (tag) => {
+        const m = TAG_PATTERN.exec(tag ?? '');
+        return m ? { tenantCode: m[1], type: m[2], id: m[3] } : null;
+    }
+};
+export default SseTags;
+//# sourceMappingURL=SseTags.js.map

package/dist/SseTags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SseTags.js","sourceRoot":"","sources":["../src/SseTags.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,GAAG,iCAAiC,CAAC;AAEtD,MAAM,KAAK,GAAG,CAAC,UAAkB,EAAE,IAAgB,EAAE,EAAU,EAAU,EAAE;IACvE,MAAM,GAAG,GAAG,GAAG,UAAU,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;IAC1C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,cAAc,GAAG,4BAA4B,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,GAAG;IACZ,sCAAsC;IACtC,IAAI,EAAE,CAAC,UAAkB,EAAE,WAAmB,EAAU,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,EAAE,WAAW,CAAC;IAC9F,+BAA+B;IAC/B,GAAG,EAAE,CAAC,UAAkB,EAAE,OAAe,EAAU,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC;IACrF,wBAAwB;IACxB,KAAK,EAAE,CAAC,UAAkB,EAAE,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,CAAC;IACnF,wBAAwB;IACxB,KAAK,EAAE,CAAC,GAAW,EAAqB,EAAE;QACtC,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QACtC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAe,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7E,CAAC;CACJ,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { default as SseServiceApi } from './SseServiceApi.js';
+export { default } from './SseServiceApi.js';
+export { default as SseTags } from './SseTags.js';
+export { CommonServiceApi, ServiceApiError } from '@omni-gate/sdk-core';
+export type { ErrorResponse, BaseApiConfigOptions } from '@omni-gate/sdk-core';
+export * from './types.js';
+export { AppError, UnauthenticatedError, IllegalParameterError, TimeoutError, ServiceUnavailableError } from '@omni-gate/sdk-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,IAAI,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAC,OAAO,IAAI,OAAO,EAAC,MAAM,cAAc,CAAC;AAChD,OAAO,EAAC,gBAAgB,EAAE,eAAe,EAAC,MAAM,qBAAqB,CAAC;AACtE,YAAY,EAAC,aAAa,EAAE,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAC7E,cAAc,YAAY,CAAC;AAG3B,OAAO,EACH,QAAQ,EACR,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,uBAAuB,EAC1B,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { default as SseServiceApi } from './SseServiceApi.js';
+export { default } from './SseServiceApi.js';
+export { default as SseTags } from './SseTags.js';
+export { CommonServiceApi, ServiceApiError } from '@omni-gate/sdk-core';
+export * from './types.js';
+// 异常类统一从 sdk-core 重导出
+export { AppError, UnauthenticatedError, IllegalParameterError, TimeoutError, ServiceUnavailableError } from '@omni-gate/sdk-core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,IAAI,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAC,OAAO,IAAI,OAAO,EAAC,MAAM,cAAc,CAAC;AAChD,OAAO,EAAC,gBAAgB,EAAE,eAAe,EAAC,MAAM,qBAAqB,CAAC;AAEtE,cAAc,YAAY,CAAC;AAE3B,sBAAsB;AACtB,OAAO,EACH,QAAQ,EACR,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,uBAAuB,EAC1B,MAAM,qBAAqB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import type { BaseApiConfigOptions } from '@omni-gate/sdk-core';
+/**
+ * 连接配置：portal（sse-service 内部地址，如 http://omni-sse/webservice）、timeout 等，见 @omni-gate/sdk-core
+ */
+export type SseApiConfigOptions = BaseApiConfigOptions;
+/** 标签类型：U-用户、A-应用、T-主题 */
+export type SseTagType = 'U' | 'A' | 'T';
+/** 解析后的标签 */
+export interface SseTagInfo {
+    tenantCode: string;
+    type: SseTagType;
+    id: string;
+}
+/** 推送结果 */
+export interface SsePushResult {
+    success: boolean;
+    /** 成功写出的连接数；目标不在线时为 0 */
+    count: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAEvD,0BAA0B;AAC1B,MAAM,MAAM,UAAU,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzC,aAAa;AACb,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;CACd;AAED,WAAW;AACX,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@omni-gate/sse-sdk-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Backend SDK for the OmniGate SSE service: issue connection tickets and push events to users, apps or topics",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README_CN.md"
+  ],
+  "keywords": [
+    "omnigate",
+    "sse",
+    "server-sent-events",
+    "push",
+    "sdk",
+    "typescript"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@omni-gate/sdk-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.8.6",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "clean": "rm -rf ./dist",
+    "prebuild": "npm run clean",
+    "build": "tsc -p tsconfig.json",
+    "test:modules": "node ./scripts/verify-modules.mjs",
+    "publish:public": "pnpm publish --access public"
+  }
 }