@appthen/sdk-node 0.0.0 → 0.0.2

package/dist/index.d.ts

@@ -51,8 +51,8 @@ export declare class TenantAppAuthProvider implements AuthProvider {
 }
 export declare function createChatHubNodeClient(options: CreateChatHubNodeClientOptions): ChatHubClient;
 export declare function createChatHubNodeRuntime(options: CreateChatHubNodeRuntimeOptions): ChatHubAppRuntime;
-import { PlatformApi, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult } from '@appthen/sdk-core';
-export { PlatformApi, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult, } from '@appthen/sdk-core';
+import { PlatformApi, type PlatformNotifyInput, type PlatformNotifyRequest, type PlatformNotifyResult, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult } from '@appthen/sdk-core';
+export { PlatformApi, type PlatformLazySubject, type PlatformNotifyInput, type PlatformNotifyRequest, type PlatformNotifyResult, type PlatformNotifySelector, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult, } from '@appthen/sdk-core';
 export interface CreateAppThenSdkOptions {
     baseUrl: string;
     accessKey: string;
@@ -70,11 +70,18 @@ export declare class PlatformTenantClient {
     constructor(platform: PlatformApi, tenantId: string);
     /** 幂等代同步成员：重复推送只产生一个 Subject，可安全重试。 */
     syncSubject(input: PlatformSyncSubjectInput): Promise<PlatformSyncSubjectResult>;
+    /**
+     * 按标签/条件圈人并直接触达（声明式）：sender 按声明 lazily create-or-get；
+     * 收件人 selector（标签圈人）或 receive（单点声明，如微信客服消息迁移）二选一。
+     */
+    notify(request: PlatformNotifyRequest, notify: PlatformNotifyInput): Promise<PlatformNotifyResult>;
 }
 export declare class AppThenPlatformSdk {
     private readonly http;
     readonly platform: PlatformApi;
     constructor(platform: PlatformApi, http: NodeFetchHttpAdapter);
+    /** 获取某个被授权租户的操作客户端（per-tenant，调用自动携带 targetTenantId）。 */
+    platformTenant(tenantId: string): PlatformTenantClient;
     /** 代开通租户（目标租户尚不存在，故在 sdk 根上而非 tenant client）。 */
     provisionTenant(input: PlatformProvisionTenantInput): Promise<PlatformProvisionTenantResult>;
     /** 对账：externalCorrelationId → tenantId + grants。未命中抛 CORRELATION_MISMATCH。 */

package/dist/index.js

@@ -178,12 +178,23 @@ export class PlatformTenantClient {
     async syncSubject(input) {
         return this.platform.syncSubject(this.tenantId, input);
     }
+    /**
+     * 按标签/条件圈人并直接触达（声明式）：sender 按声明 lazily create-or-get；
+     * 收件人 selector（标签圈人）或 receive（单点声明，如微信客服消息迁移）二选一。
+     */
+    async notify(request, notify) {
+        return this.platform.notify(this.tenantId, request, notify);
+    }
 }
 export class AppThenPlatformSdk {
     constructor(platform, http) {
         this.http = http;
         this.platform = platform;
     }
+    /** 获取某个被授权租户的操作客户端（per-tenant，调用自动携带 targetTenantId）。 */
+    platformTenant(tenantId) {
+        return new PlatformTenantClient(this.platform, tenantId);
+    }
     /** 代开通租户（目标租户尚不存在，故在 sdk 根上而非 tenant client）。 */
     async provisionTenant(input) {
         return this.platform.provisionTenant(input);

package/dist-cjs/index.d.ts

@@ -51,8 +51,8 @@ export declare class TenantAppAuthProvider implements AuthProvider {
 }
 export declare function createChatHubNodeClient(options: CreateChatHubNodeClientOptions): ChatHubClient;
 export declare function createChatHubNodeRuntime(options: CreateChatHubNodeRuntimeOptions): ChatHubAppRuntime;
-import { PlatformApi, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult } from '@appthen/sdk-core';
-export { PlatformApi, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult, } from '@appthen/sdk-core';
+import { PlatformApi, type PlatformNotifyInput, type PlatformNotifyRequest, type PlatformNotifyResult, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult } from '@appthen/sdk-core';
+export { PlatformApi, type PlatformLazySubject, type PlatformNotifyInput, type PlatformNotifyRequest, type PlatformNotifyResult, type PlatformNotifySelector, type PlatformProvisionTenantInput, type PlatformProvisionTenantResult, type PlatformResolveTenantResult, type PlatformSyncSubjectInput, type PlatformSyncSubjectResult, } from '@appthen/sdk-core';
 export interface CreateAppThenSdkOptions {
     baseUrl: string;
     accessKey: string;
@@ -70,11 +70,18 @@ export declare class PlatformTenantClient {
     constructor(platform: PlatformApi, tenantId: string);
     /** 幂等代同步成员：重复推送只产生一个 Subject，可安全重试。 */
     syncSubject(input: PlatformSyncSubjectInput): Promise<PlatformSyncSubjectResult>;
+    /**
+     * 按标签/条件圈人并直接触达（声明式）：sender 按声明 lazily create-or-get；
+     * 收件人 selector（标签圈人）或 receive（单点声明，如微信客服消息迁移）二选一。
+     */
+    notify(request: PlatformNotifyRequest, notify: PlatformNotifyInput): Promise<PlatformNotifyResult>;
 }
 export declare class AppThenPlatformSdk {
     private readonly http;
     readonly platform: PlatformApi;
     constructor(platform: PlatformApi, http: NodeFetchHttpAdapter);
+    /** 获取某个被授权租户的操作客户端（per-tenant，调用自动携带 targetTenantId）。 */
+    platformTenant(tenantId: string): PlatformTenantClient;
     /** 代开通租户（目标租户尚不存在，故在 sdk 根上而非 tenant client）。 */
     provisionTenant(input: PlatformProvisionTenantInput): Promise<PlatformProvisionTenantResult>;
     /** 对账：externalCorrelationId → tenantId + grants。未命中抛 CORRELATION_MISMATCH。 */

package/dist-cjs/index.js

@@ -203,6 +203,13 @@ class PlatformTenantClient {
     async syncSubject(input) {
         return this.platform.syncSubject(this.tenantId, input);
     }
+    /**
+     * 按标签/条件圈人并直接触达（声明式）：sender 按声明 lazily create-or-get；
+     * 收件人 selector（标签圈人）或 receive（单点声明，如微信客服消息迁移）二选一。
+     */
+    async notify(request, notify) {
+        return this.platform.notify(this.tenantId, request, notify);
+    }
 }
 exports.PlatformTenantClient = PlatformTenantClient;
 class AppThenPlatformSdk {
@@ -210,6 +217,10 @@ class AppThenPlatformSdk {
         this.http = http;
         this.platform = platform;
     }
+    /** 获取某个被授权租户的操作客户端（per-tenant，调用自动携带 targetTenantId）。 */
+    platformTenant(tenantId) {
+        return new PlatformTenantClient(this.platform, tenantId);
+    }
     /** 代开通租户（目标租户尚不存在，故在 sdk 根上而非 tenant client）。 */
     async provisionTenant(input) {
         return this.platform.provisionTenant(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthen/sdk-node",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "AppThen Conversation Hub SDK - Node.js server adapter",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,10 +16,11 @@
   "files": [
     "dist",
     "README.md",
-    "dist-cjs"
+    "dist-cjs",
+    "skills"
   ],
   "dependencies": {
-    "@appthen/sdk-core": "0.0.0"
+    "@appthen/sdk-core": "0.0.2"
   },
   "sideEffects": false,
   "license": "UNLICENSED",

package/skills/appthen-platform-sdk/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: appthen-platform-sdk
+description: 对接 AppThen 开放平台「服务商（代运营）」能力时使用。当任务涉及：用 @appthen/sdk-node 接入 AppThen、代开通租户、幂等同步成员（含 tags 一次推全）、按标签/条件圈人触达（notify 发消息/通知）、externalCorrelationId 对账、启停授权、认领激活（claimToken）时读取本技能。触发词：appthen sdk、sdk-node、代运营、服务商接入、platform token、代同步、notify、触达、按标签推送、claimToken。
+---
+
+# AppThen Platform SDK（@appthen/sdk-node）使用指南
+
+## 模型（先读，避免用错）
+
+- 心智模型与**微信第三方平台同构**：你的 SaaS 后端 = 服务商（第三方平台），AppThen 的每个租户 = 公众号。**所有能力都是"给单一租户"的，你只是代替被授权租户调用。**
+- 凭证：`accessKey` / `accessSecret` **永远只存在于你的后端**。platform token（2h）由 SDK 自动换取与刷新——**不要自己管 token**。
+- 授权是双向的：代开通 → 实验室管理员凭 `claimToken` 认领激活（≈扫码授权）→ grant `active` 后才能代操作。
+- **零预建（声明式贯穿）**：主体类（classId）、通知会话类型（typeId）、sender / receiver 都不用预建——随调用声明 lazily 自动创建（幂等键 = externalIdentity）。
+- 本包是 monorepo `packages/appthen-sdk`（`@appthen/sdk-core/node/web/react` 四包）；本技能随包分发，agent 可整体 symlink 到自己的 skills 目录。
+
+## 安装
+
+```bash
+# AppThen 仓库内：workspace 直接可用（packages/appthen-sdk）
+# 外部 SaaS（发布后）：
+pnpm add @appthen/sdk-node
+```
+
+## 快速开始
+
+```ts
+import { createAppThenSdk } from '@appthen/sdk-node';
+
+const sdk = createAppThenSdk({
+  baseUrl: 'https://<appthen-host>',
+  accessKey: process.env.APPTHEN_ACCESS_KEY!,       // AppThen 控制台「接入凭证」创建（带 platformId）
+  accessSecret: process.env.APPTHEN_ACCESS_SECRET!, // 仅创建时一次明文展示，入库你的密钥管理
+});
+
+// 1) 代开通租户——幂等：同 externalCorrelationId 重复调用返回已有租户（created:false）
+const provisioned = await sdk.provisionTenant({
+  name: 'XX 检测实验室',
+  externalCorrelationId: 'lims_org_10086', // 对账锚：LIMS 机构 ID ↔ AppThen tenantId，必填
+});
+// 首次返回 claimToken（7d）→ 交给实验室管理员完成认领激活（见下）
+
+// 2) 按租户组织调用（per-tenant client，自动携带 targetTenantId）
+const lab = sdk.platformTenant(provisioned.tenantId);
+await lab.syncSubject({
+  classId: 'class_lims_member',            // 不存在会自动创建（external 类）
+  displayName: '张三',
+  tags: ['lims:type:app', 'lims:dept:88'], // 事件时一次推全（整体覆盖）
+  updateOnMatch: true,                     // 命中已存在时覆盖更新（未传字段保留）
+  externalIdentity: { source: 'lims', externalKey: 'user_001' }, // 幂等键，可安全重试
+});
+
+// 3) 对账（防串租户）
+const resolved = await sdk.resolveTenant('lims_org_10086');
+// → { tenantId, tenantStatus, grants: [{ grantId, scopes, status }] }
+
+// 4) 启停授权
+await sdk.toggleGrant(grantId, 'revoked'); // 或 'active'
+```
+
+## 认领激活（走用户 JWT，非 platform token）
+
+认领是**租户管理员的动作**（信任锚），必须用该管理员的用户 JWT：
+
+```ts
+await sdk.claimTenant(tenantId, claimToken, userJwt);
+// 租户 pending → active，grant pending → active
+```
+
+## 触达（notify）：声明式，无 subjectId 概念
+
+发送者/收件人都是声明式的（`{source, externalKey, displayName, avatarUrl?}`），服务端 lazily create-or-get（幂等键 = externalIdentity，同一 id 只建一次）——调用方只需本地维护 id/昵称/头像。
+
+```ts
+// 路径 ① 标签圈人（运营触达，多标签取交集）
+const result = await lab.notify(
+  { selector: { tags: ['lims:role:admin', 'lims:type:app'] } },
+  {
+    classId: 'class_lims_member',        // 本次触达涉及的外部主体类
+    sender: { source: 'lims', externalKey: 'kf_001', displayName: '客服小王' },
+    typeId: 'type_lims_notify',          // 通知会话类型（不存在则自动创建）
+    kind: 'text',
+    content: { text: '明日 22:00 系统维护' },
+  },
+);
+
+// 路径 ② 单点声明收件人（如微信公众号客服消息迁移：客服=sender、微信用户=receive 全部 lazily 建主体）
+await lab.notify(
+  { receive: { source: 'wechat', externalKey: 'wx_123', displayName: '微信用户' } },
+  { classId: 'class_lims_member', sender: { source: 'lims', externalKey: 'kf_001', displayName: '客服小王' }, typeId: 'type_lims_notify', kind: 'text', content: { text: 'hi' } },
+);
+// → { matched, delivered, failed }
+```
+
+前置：grant 需含 `platform:message:send`。语音播报走 `kind` 扩展（渲染层解释）。
+
+## 幂等与错误处理纪律
+
+| 场景 | 行为 | 你该做的 |
+|---|---|---|
+| 重复 syncSubject 同一 externalKey | 返回已有主体（`created:false`） | **安全重试**，无需自行去重 |
+| `GRANT_NOT_FOUND` (403) | 该租户未授权给你 | 检查代开通 / 认领流程是否完成 |
+| `GRANT_INACTIVE` (403) | grant 为 pending / revoked | pending = 等认领；revoked = 被停用或解除 |
+| `PLATFORM_SCOPE_DENIED` (403) | token 缺对应 scope | 换 token 时 `requestedScopes` 补上 |
+| `CORRELATION_MISMATCH` (403) | externalCorrelationId 对不上 | **停止操作**，人工核对租户映射 |
+| `TENANT_PENDING_CLAIM` / 已认领 (409) | 租户待认领 / 已认领过 | 引导管理员走认领流程 |
+
+## 职责边界（不要做）
+
+- ❌ 前端 / 浏览器**永远不要**持有 accessSecret——前端用 `@appthen/sdk-web`（后端签发的短期 token）。
+- ❌ 不要绕过 SDK 手工管 token（2h 过期 + 60s 刷新提前量 + 并发刷新去重已内置）。
+- ❌ 认领是租户管理员动作，不要在你的后端"代管理员认领"。
+- ❌ 不要每类资源各写一套准入逻辑——获得方式统一走 `distribution` 维度（见契约文档补丁）。
+
+## 权威文档
+
+- API 契约（字段级签名 / 错误码 / 状态机 / 冻结 gate）：`docs/service-provider-platform-api.md`
+- 授权事件通知 SaaS（§6.1）与租户侧解除授权（§4.7）：⏳ 待实现
+- 代安装工作台（§4.3）：⏳ 依赖工作台分发制（mkt-10）落地