@appthen/sdk-core 0.0.0

package/dist-cjs/index.d.ts

@@ -0,0 +1,616 @@
+/**
+ * @appthen/sdk-core
+ *
+ * 平台无关的 Conversation Hub SDK 核心。
+ *
+ * V0 先对齐目前已经落地的 Hub API：
+ * - open-platform/token
+ * - subject-directory/open/*
+ * - conversation-runtime/open/*
+ * - 内部 JWT 保护的查询接口（messages / conversations）
+ */
+export declare const SDK_VERSION = "0.1.0";
+export type RequestMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+export interface HttpRequestOptions {
+    method: RequestMethod;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+export interface HttpResponse<T> {
+    status: number;
+    data: T;
+    headers: Record<string, string>;
+}
+export interface HttpAdapter {
+    request<T>(options: HttpRequestOptions): Promise<HttpResponse<T>>;
+}
+export interface AuthProvider {
+    getToken(): Promise<string | null>;
+    setToken(token: string | null): Promise<void>;
+}
+export interface RealtimeSubscription<TEvent = unknown> extends AsyncIterable<TEvent> {
+    close(): Promise<void>;
+}
+export interface RealtimeAdapter {
+    connect?(token?: string | null): Promise<void>;
+    disconnect?(): Promise<void>;
+    subscribeConversation?(_conversationId: string): Promise<RealtimeSubscription<unknown>>;
+    publishConversationEvent?(_conversationId: string, _event: Record<string, unknown>): Promise<void>;
+    joinRoom?(room: string): Promise<void>;
+    leaveRoom?(room: string): Promise<void>;
+    onGlobalEvent?(handler: (event: Record<string, unknown>) => void): () => void;
+}
+export interface ConversationTypingStateInput {
+    conversationId: string;
+    isTyping: boolean;
+    senderSubjectId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ConversationReadStateInput {
+    conversationId: string;
+    messageId: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TenantAppTokenPayload {
+    tenantId: string;
+    appId?: string;
+    appName?: string;
+    actingSubjectId?: string;
+    actingMode?: string;
+    scopes?: string[];
+    accessKey?: string;
+    exp?: number;
+    iat?: number;
+    [key: string]: unknown;
+}
+export interface IssueAppTokenInput {
+    accessKey: string;
+    accessSecret: string;
+    actingSubjectId?: string;
+    actingMode?: string;
+    requestedScopes?: string[];
+}
+export interface IssueAppTokenResult {
+    token: string;
+    tokenType?: string;
+    expiresIn?: number;
+    app?: TenantAppTokenPayload;
+    [key: string]: unknown;
+}
+export interface ExternalIdentityInput {
+    source: string;
+    externalKey: string;
+    identityKind?: string;
+    displayName?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateSubjectInput {
+    subjectId: string;
+    classId: string;
+    displayName: string;
+    avatar?: string;
+    avatarUrl?: string;
+    status?: string;
+    tags?: string[];
+    profile?: Record<string, unknown>;
+    searchableMeta?: Record<string, unknown>;
+    externalIdentity?: ExternalIdentityInput;
+}
+export interface CreateInternalSubjectInput extends CreateSubjectInput {
+    tenantId: string;
+}
+export interface CreateSubjectClassInput {
+    classId: string;
+    label: string;
+    ontology: string;
+    scope?: string;
+    lifecycle?: string;
+    status?: string;
+    description?: string;
+    notes?: string;
+    tags?: string[];
+    openRegistration?: boolean;
+    instanceMatcher?: Record<string, unknown>;
+    requiredExternalIdentity?: Record<string, unknown>;
+    capabilitySchema?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateInternalSubjectClassInput extends CreateSubjectClassInput {
+    tenantId: string;
+}
+export interface SubjectRecord {
+    tenantId: string;
+    subjectId: string;
+    classId: string;
+    kind: string;
+    displayName: string;
+    avatar?: string;
+    status?: string;
+    tags?: string[];
+    profile?: Record<string, unknown>;
+    searchableMeta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface SubjectContext {
+    subject: SubjectRecord;
+    subjectClass?: Record<string, unknown>;
+    memberships?: Record<string, unknown>[];
+    organizationNodeIds?: string[];
+    membershipRelations?: string[];
+    [key: string]: unknown;
+}
+export interface QuerySubjectsInput {
+    tenantId: string;
+    classId?: string;
+    kind?: string;
+    status?: string;
+    tag?: string;
+    displayName?: string;
+}
+export interface ConversationTypeRecord {
+    tenantId: string;
+    typeId: string;
+    label?: string;
+    name?: string;
+    status?: string;
+    audiencePolicy?: Record<string, unknown>;
+    creatorPolicy?: Record<string, unknown>;
+    messagePolicy?: ChatHubMessagePolicy;
+    [key: string]: unknown;
+}
+export interface ChatHubMessagePolicy {
+    allowRichText?: boolean;
+    allowCopy?: boolean;
+    allowReply?: boolean;
+    allowForward?: boolean;
+    allowMultiForwardSelection?: boolean;
+    allowDelete?: boolean;
+    allowRevoke?: boolean;
+    [key: string]: unknown;
+}
+export interface CreateConversationTypeInput {
+    typeId: string;
+    label?: string;
+    name?: string;
+    conversationKind?: string;
+    status?: string;
+    welcomeMessage?: string;
+    audiencePolicy?: Record<string, unknown>;
+    creatorPolicy?: Record<string, unknown>;
+    messagePolicy?: ChatHubMessagePolicy;
+    defaultCapabilities?: Record<string, unknown>[];
+    optionalCapabilities?: Record<string, unknown>[];
+    restrictedCapabilities?: Record<string, unknown>[];
+    triggeredCapabilities?: Record<string, unknown>[];
+    capabilityTiers?: Record<string, string[]>;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface CreateInternalConversationTypeInput extends CreateConversationTypeInput {
+    tenantId: string;
+}
+export interface ConversationRecord {
+    tenantId: string;
+    conversationId: string;
+    typeId?: string;
+    title: string;
+    createdBySubjectId?: string;
+    parentConversationId?: string;
+    type?: string;
+    status?: string;
+    relation?: string;
+    metadata?: Record<string, unknown>;
+    unreadCount?: number | null;
+    pinnedByMe?: boolean | null;
+    mutedByMe?: boolean | null;
+    [key: string]: unknown;
+}
+export interface CreateConversationInput {
+    conversationId: string;
+    typeId?: string;
+    title: string;
+    welcomeMessage?: string;
+    createdBySubjectId?: string;
+    parentConversationId?: string;
+    type?: string;
+    status?: string;
+    relation?: string;
+    visibilityPolicy?: Record<string, unknown>;
+    audienceSnapshot?: Record<string, unknown>;
+    contextPolicy?: Record<string, unknown>;
+    messagePolicy?: ChatHubMessagePolicy;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateParticipantInput {
+    conversationId: string;
+    subjectId: string;
+    role?: string;
+    status?: string;
+    visibilityScope?: Record<string, unknown>;
+    capabilityScope?: Record<string, unknown>;
+}
+export interface ConversationParticipantRecord {
+    tenantId: string;
+    conversationId: string;
+    subjectId: string;
+    role?: string;
+    status?: string;
+    visibilityScope?: Record<string, unknown>;
+    capabilityScope?: Record<string, unknown>;
+    organizationNodeIds?: string[];
+    membershipRelations?: string[];
+    [key: string]: unknown;
+}
+export interface QueryParticipantsInput {
+    tenantId?: string;
+    conversationId: string;
+    status?: string;
+}
+export interface ConversationMessageRecord {
+    tenantId: string;
+    messageId: string;
+    conversationId: string;
+    sequence?: number;
+    senderSubjectId: string;
+    kind?: string;
+    content: Record<string, unknown>;
+    mentionedSubjectIds?: string[];
+    visibility?: Record<string, unknown>;
+    status?: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface CreateMessageInput {
+    conversationId: string;
+    messageId: string;
+    senderSubjectId?: string;
+    kind?: string;
+    content: Record<string, unknown>;
+    mentionedSubjectIds?: string[];
+    visibility?: Record<string, unknown>;
+    status?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateInternalMessageInput extends CreateMessageInput {
+    tenantId: string;
+}
+export interface QueryMessagesInput {
+    tenantId?: string;
+    conversationId: string;
+    limit?: number;
+    beforeCreatedAt?: string;
+    afterSequence?: number;
+}
+export interface UpdateMessageInput {
+    status?: string;
+    content?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    actorSubjectId?: string;
+}
+export interface UpdateInternalMessageInput extends UpdateMessageInput {
+    tenantId: string;
+}
+export interface QueryConversationsInput {
+    tenantId?: string;
+    typeId?: string;
+    status?: string;
+    createdBySubjectId?: string;
+    subjectId?: string;
+}
+export interface CreateInternalConversationInput extends CreateConversationInput {
+    tenantId: string;
+}
+export interface CreateInternalParticipantInput extends CreateParticipantInput {
+    tenantId: string;
+}
+export interface ResolveCapabilitiesResult {
+    defaultCapabilities?: Record<string, unknown>[];
+    optionalCapabilities?: Record<string, unknown>[];
+    restrictedCapabilities?: Record<string, unknown>[];
+    triggeredCapabilities?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+export type ChatHubAuthMode = 'internal_jwt' | 'tenant_app_token';
+export interface ChatHubAuthConfig {
+    mode: ChatHubAuthMode;
+    appTokenInput?: IssueAppTokenInput;
+}
+export interface ChatHubTenantConfig {
+    tenantId: string;
+}
+export interface ChatHubSubjectClassPreset {
+    classId: string;
+    label: string;
+    ontology: string;
+    scope: string;
+    lifecycle: string;
+    status?: string;
+    instanceMatcher: Record<string, unknown>;
+    openRegistration?: boolean;
+    requiredExternalIdentity?: Record<string, unknown>;
+    tags?: string[];
+    notes?: string;
+}
+export interface ChatHubSubjectPreset {
+    subjectId: string;
+    classId: string;
+    displayName: string;
+    status?: string;
+    avatarUrl?: string;
+    profile?: Record<string, unknown>;
+    tags?: string[];
+}
+export interface ChatHubConversationTypePreset {
+    typeId: string;
+    name: string;
+    label?: string;
+    conversationKind?: string;
+    status?: string;
+    welcomeMessage?: string;
+    creatorPolicy?: Record<string, unknown>;
+    audiencePolicy?: Record<string, unknown>;
+    messagePolicy?: ChatHubMessagePolicy;
+    defaultCapabilities?: Record<string, unknown>[];
+    optionalCapabilities?: Record<string, unknown>[];
+    restrictedCapabilities?: Record<string, unknown>[];
+    triggeredCapabilities?: Record<string, unknown>[];
+    capabilityTiers?: Record<string, string[]>;
+    metadata?: Record<string, unknown>;
+}
+export interface ChatHubConversationPreset {
+    title: string;
+    typeId: string;
+    createdBySubjectId: string;
+    status?: string;
+    relation?: string;
+    parentConversationId?: string;
+    metadata?: Record<string, unknown>;
+    participants: Array<{
+        subjectId: string;
+        role?: string;
+        status?: string;
+    }>;
+}
+export interface ChatHubAppConfig {
+    auth: ChatHubAuthConfig;
+    tenant: ChatHubTenantConfig;
+    subjectClasses?: ChatHubSubjectClassPreset[];
+    subjects?: ChatHubSubjectPreset[];
+    conversationType?: ChatHubConversationTypePreset;
+    conversation?: ChatHubConversationPreset;
+}
+export declare function resolveChatHubMessagePolicy(value: unknown): Required<Pick<ChatHubMessagePolicy, 'allowRichText' | 'allowCopy' | 'allowReply' | 'allowForward' | 'allowMultiForwardSelection' | 'allowDelete' | 'allowRevoke'>>;
+export interface ChatHubBootstrapResult {
+    tenantId: string;
+    subjectClassIds: string[];
+    subjectIds: string[];
+    conversationTypeId?: string;
+    conversation?: ConversationRecord;
+}
+export interface SendTextMessageOptions {
+    conversationId: string;
+    senderSubjectId: string;
+    text: string;
+    attachments?: unknown[];
+    messageId?: string;
+    mentionedSubjectIds?: string[];
+    metadata?: Record<string, unknown>;
+    status?: string;
+}
+export interface SendChatHubMessageOptions {
+    conversationId: string;
+    senderSubjectId: string;
+    kind: string;
+    content: Record<string, unknown>;
+    messageId?: string;
+    mentionedSubjectIds?: string[];
+    metadata?: Record<string, unknown>;
+    status?: string;
+}
+export interface ListChatHubMessagesOptions {
+    conversationId: string;
+    limit?: number;
+    beforeCreatedAt?: string;
+    afterSequence?: number;
+}
+export interface UpdateChatHubMessageOptions {
+    messageId: string;
+    status?: string;
+    content?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    actorSubjectId?: string;
+}
+export interface ListChatHubMessagesPageResult {
+    items: ConversationMessageRecord[];
+    hasMore: boolean;
+    nextBeforeCreatedAt?: string;
+}
+export type ChatHubMessageWatchReason = 'initial' | 'realtime_event' | 'fallback' | 'manual';
+export interface WatchConversationMessagesEvent {
+    reason: ChatHubMessageWatchReason;
+    messages: ConversationMessageRecord[];
+    rawEvent?: unknown;
+    afterSequence?: number;
+}
+export interface WatchConversationMessagesOptions {
+    conversationId: string;
+    limit?: number;
+    immediate?: boolean;
+    fallbackIntervalMs?: number;
+    healthcheckIntervalMs?: number;
+    pauseWhenHidden?: boolean;
+    initialLastSequence?: number;
+    onMessages: (event: WatchConversationMessagesEvent) => void | Promise<void>;
+    onEvent?: (event: unknown) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}
+export interface ChatHubMessageWatcher {
+    refresh(reason?: ChatHubMessageWatchReason): Promise<void>;
+    close(): Promise<void>;
+}
+declare class BaseApi {
+    protected readonly http: HttpAdapter;
+    protected readonly auth: AuthProvider;
+    constructor(http: HttpAdapter, auth: AuthProvider);
+    protected request<T>(options: HttpRequestOptions): Promise<T>;
+}
+export declare class OpenPlatformApi extends BaseApi {
+    issueToken(input: IssueAppTokenInput): Promise<IssueAppTokenResult>;
+    getCurrentTokenPayload(): Promise<TenantAppTokenPayload>;
+}
+export declare class SubjectDirectoryApi extends BaseApi {
+    createSubject(input: CreateSubjectInput): Promise<SubjectRecord>;
+    createSubjectClass(input: CreateSubjectClassInput): Promise<Record<string, unknown>>;
+    createSubjectInternal(input: CreateInternalSubjectInput): Promise<SubjectRecord>;
+    createSubjectClassInternal(input: CreateInternalSubjectClassInput): Promise<Record<string, unknown>>;
+    createExternalIdentity(input: ExternalIdentityInput & {
+        subjectId?: string;
+    }): Promise<Record<string, unknown>>;
+    findSubjectByExternalIdentity(query: {
+        source: string;
+        externalKey: string;
+    }): Promise<SubjectRecord | null>;
+    getSubjectContext(subjectId: string): Promise<SubjectContext>;
+    listSubjects(query: QuerySubjectsInput): Promise<SubjectRecord[]>;
+    getSubjectContextInternal(tenantId: string, subjectId: string): Promise<SubjectContext>;
+}
+export declare class ConversationTypesApi extends BaseApi {
+    create(input: CreateConversationTypeInput): Promise<ConversationTypeRecord>;
+    resolveCapabilities(typeId: string, query?: {
+        subjectId?: string;
+    }): Promise<ResolveCapabilitiesResult>;
+    createInternal(input: CreateInternalConversationTypeInput): Promise<ConversationTypeRecord>;
+    listInternal(query: {
+        tenantId: string;
+        status?: string;
+    }): Promise<ConversationTypeRecord[]>;
+}
+export declare class ConversationsApi extends BaseApi {
+    create(input: CreateConversationInput): Promise<ConversationRecord>;
+    createInternal(input: CreateInternalConversationInput): Promise<ConversationRecord>;
+    list(query?: QueryConversationsInput): Promise<ConversationRecord[]>;
+    addParticipant(input: CreateParticipantInput): Promise<Record<string, unknown>>;
+    addParticipantInternal(input: CreateInternalParticipantInput): Promise<Record<string, unknown>>;
+    listParticipants(query: QueryParticipantsInput): Promise<ConversationParticipantRecord[]>;
+}
+export declare class MessagesApi extends BaseApi {
+    create(input: CreateMessageInput): Promise<ConversationMessageRecord>;
+    createInternal(input: CreateInternalMessageInput): Promise<ConversationMessageRecord>;
+    list(query: QueryMessagesInput): Promise<ConversationMessageRecord[]>;
+    updateInternal(messageId: string, input: UpdateInternalMessageInput): Promise<ConversationMessageRecord>;
+}
+export interface ChatHubClientOptions {
+    http: HttpAdapter;
+    auth: AuthProvider;
+    realtime?: RealtimeAdapter;
+}
+export declare class ChatHubClient {
+    private readonly options;
+    readonly openPlatform: OpenPlatformApi;
+    readonly subjects: SubjectDirectoryApi;
+    readonly conversationTypes: ConversationTypesApi;
+    readonly conversations: ConversationsApi;
+    readonly messages: MessagesApi;
+    readonly realtime?: RealtimeAdapter;
+    constructor(options: ChatHubClientOptions);
+    setToken(token: string | null): Promise<void>;
+    getToken(): Promise<string | null>;
+    issueAppToken(input: IssueAppTokenInput): Promise<IssueAppTokenResult>;
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): Promise<void>;
+}
+export declare class ChatHubAppRuntime {
+    private readonly client;
+    private readonly config;
+    constructor(client: ChatHubClient, config: ChatHubAppConfig);
+    get tenantId(): string;
+    get appConfig(): ChatHubAppConfig;
+    /** 暴露底层实时适配器，供宿主加入自定义房间 / 监听全局事件（跨设备同步等）。 */
+    get realtime(): RealtimeAdapter | undefined;
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): Promise<void>;
+    subscribeConversation(conversationId: string): Promise<RealtimeSubscription<unknown> | null>;
+    publishConversationEvent(conversationId: string, event: Record<string, unknown>): Promise<void>;
+    updateConversationTyping(input: ConversationTypingStateInput): Promise<void>;
+    updateConversationRead(input: ConversationReadStateInput): Promise<void>;
+    ensureAuthenticated(): Promise<void>;
+    bootstrapConversation(): Promise<ChatHubBootstrapResult>;
+    listConversations(subjectId?: string): Promise<ConversationRecord[]>;
+    listMessages(input: string | ListChatHubMessagesOptions): Promise<ConversationMessageRecord[]>;
+    listMessagesPage(input: string | ListChatHubMessagesOptions): Promise<ListChatHubMessagesPageResult>;
+    ensureParticipant(input: CreateParticipantInput): Promise<Record<string, unknown>>;
+    watchConversationMessages(options: WatchConversationMessagesOptions): ChatHubMessageWatcher;
+    sendTextMessage(input: SendTextMessageOptions): Promise<ConversationMessageRecord>;
+    sendMessage(input: SendChatHubMessageOptions): Promise<ConversationMessageRecord>;
+    updateMessage(input: UpdateChatHubMessageOptions): Promise<ConversationMessageRecord>;
+    deleteMessage(input: Omit<UpdateChatHubMessageOptions, 'status' | 'content'>): Promise<ConversationMessageRecord>;
+    revokeMessage(input: Omit<UpdateChatHubMessageOptions, 'status' | 'content'>): Promise<ConversationMessageRecord>;
+    private ensureSubjectClasses;
+    private ensureSubjects;
+    private ensureConversationType;
+    private createConversationFromPreset;
+}
+export declare function createChatHubAppRuntime(client: ChatHubClient, config: ChatHubAppConfig): ChatHubAppRuntime;
+export interface PlatformProvisionTenantInput {
+    name: string;
+    /** 对账锚：SaaS 侧机构标识 ↔ AppThen tenantId，必填。 */
+    externalCorrelationId: string;
+    /** 该租户被授予的 platform scope，缺省 ['platform:subject:sync']。 */
+    grantScopes?: string[];
+}
+export interface PlatformProvisionTenantResult {
+    tenantId: string;
+    status: string;
+    externalCorrelationId: string;
+    grantId: string;
+    /** 仅首次开通返回（7d 有效）；认领激活时提交。 */
+    claimToken?: string;
+    /** false = 幂等命中（同 platformId + externalCorrelationId 已开通过）。 */
+    created: boolean;
+    [key: string]: unknown;
+}
+export interface PlatformExternalIdentityInput {
+    source: string;
+    externalKey: string;
+    displayLabel?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PlatformSyncSubjectInput {
+    classId: string;
+    displayName: string;
+    /** 传入且与已绑定主体不一致时返回 409。 */
+    subjectId?: string;
+    status?: string;
+    avatarUrl?: string;
+    profile?: Record<string, unknown>;
+    tags?: string[];
+    /** 命中已存在主体时是否更新其可写字段，默认 false（纯幂等）。 */
+    updateOnMatch?: boolean;
+    /** 幂等键：{source, externalKey}。重复推送只产生一个 Subject，可安全重试。 */
+    externalIdentity: PlatformExternalIdentityInput;
+}
+export interface PlatformSyncSubjectResult {
+    subjectId: string;
+    targetTenantId: string;
+    created: boolean;
+    [key: string]: unknown;
+}
+export interface PlatformResolveTenantResult {
+    tenantId: string;
+    tenantStatus: string | null;
+    externalCorrelationId: string;
+    grants: Array<{
+        grantId: string;
+        scopes: string[];
+        status: string;
+    }>;
+}
+export declare class PlatformApi extends BaseApi {
+    provisionTenant(input: PlatformProvisionTenantInput): Promise<PlatformProvisionTenantResult>;
+    syncSubject(targetTenantId: string, input: PlatformSyncSubjectInput): Promise<PlatformSyncSubjectResult>;
+    resolveTenant(externalCorrelationId: string): Promise<PlatformResolveTenantResult>;
+    toggleGrant(grantId: string, status: 'active' | 'revoked'): Promise<Record<string, unknown>>;
+}
+export {};