@smartdoca/web-plugin-registry 0.1.0

package/dist/LICENSING.md

@@ -0,0 +1,57 @@
+# Licensing
+
+[简体中文](LICENSING.zh-CN.md)
+
+Doca uses a dual-licensing model for code owned by the Doca copyright holders.
+
+## Open-source license
+
+Unless a file or package says otherwise, Doca-owned code in this repository is
+available under the GNU Affero General Public License version 3 only
+(`AGPL-3.0-only`). The full license text is in [LICENSE](LICENSE).
+
+The AGPL permits commercial use. When its conditions apply, it requires the
+corresponding source to remain available under the AGPL, including for modified
+versions offered to users over a network. “Open source” and “free of charge” are
+not the same thing, and the AGPL obligations do not depend on whether an operator
+charges money.
+
+## Commercial license
+
+Organizations that want to use Doca-owned code in a proprietary product without
+the AGPL obligations may obtain a separate commercial license from the Doca
+copyright holders. A commercial license exists only when both parties have
+entered into a written agreement. This repository does not itself grant that
+alternative license.
+
+## Packages and editors
+
+The same licensing direction applies to Doca-owned packages and editors,
+including the Doca plugin SDK and the Slate, presentation, spreadsheet,
+Markdown, and canvas editor packages. Each released npm artifact must:
+
+- carry an accurate license field and license notice;
+- link to the public source repository and the exact source tag for that version;
+- include the build scripts and dependency lock needed to produce the artifact;
+- preserve all notices and license obligations of third-party components.
+
+The historical archives under `vendor/` are development and recovery inputs.
+They are not the long-term public distribution channel. Before the public
+release, active editor dependencies must be rebuilt from their public tagged
+sources, published to npm, and consumed by Doca through registry versions.
+
+## Third-party software and assets
+
+The dual license covers only material for which the Doca copyright holders can
+grant these rights. Third-party libraries, fonts, media, generated artifacts,
+and other bundled material retain their own licenses. Their notices and source
+or attribution requirements must be followed independently.
+
+No trademark rights are granted by either the AGPL or this licensing summary.
+
+## Contributions
+
+Dual licensing requires the project to retain the rights needed to offer future
+commercial licenses. See [CONTRIBUTING.md](CONTRIBUTING.md) before submitting
+code. This document is a project policy summary, not a substitute for the
+license text or legal advice.

package/dist/LICENSING.zh-CN.md

@@ -0,0 +1,48 @@
+# 许可说明
+
+[English](LICENSING.md)
+
+Doca 对其版权所有者拥有权利的代码采用双许可模式。
+
+## 开源许可证
+
+除非文件或包中另有说明，本仓库内由 Doca 版权所有者拥有的代码默认采用
+GNU Affero General Public License version 3 only（`AGPL-3.0-only`）。完整条款见
+[LICENSE](LICENSE)。
+
+AGPL 允许商业使用。当其条件适用时，分发软件或将修改后的版本作为网络服务提供给
+用户，需要继续按 AGPL 提供对应源码。是否收费并不是 AGPL 义务的判断条件，“开源”
+也不等于“免费”。
+
+## 商业许可证
+
+希望在闭源产品中使用 Doca 自研代码、且不希望承担 AGPL 义务的组织，可以向 Doca
+版权所有者申请单独的商业许可证。只有双方签署书面协议后，商业许可证才成立；本仓库
+本身不授予该替代许可证。
+
+## 子包与编辑器
+
+同一许可方向适用于 Doca 自研的子包和编辑器，包括插件 SDK，以及 Slate 富文本、
+演示文稿、表格、Markdown 和画板编辑器。每个正式发布的 npm 制品必须：
+
+- 使用准确的许可证字段并携带许可证说明；
+- 链接公开源码仓库以及与该版本精确对应的 Git tag；
+- 提供生成该制品所需的构建脚本和依赖锁文件；
+- 保留所有第三方组件要求的许可证及声明。
+
+`vendor/` 中的历史压缩包是开发和恢复输入，不作为长期公开分发渠道。正式开源前，
+当前使用的编辑器依赖应从公开且已打 tag 的源码重新构建并发布到 npm，Doca 再改为
+使用 registry 版本。
+
+## 第三方软件与素材
+
+双许可只覆盖 Doca 版权所有者有权授予许可的内容。第三方库、字体、媒体、生成产物及
+其他随附内容继续适用各自许可证，其声明、源码提供或署名要求需要独立履行。
+
+AGPL 和本文均不授予商标使用权。
+
+## 外部贡献
+
+双许可要求项目持续保有提供商业许可证所需的权利。提交代码前请阅读
+[CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。本文只是项目政策摘要，不能替代
+许可证原文或专业法律意见。

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+export type ClientPluginTarget = "web" | "mobile";
+export type PluginLocale = "zh" | "en";
+export type RegistryDisposer = () => void;
+export type RegistryConflictCode = "DUPLICATE_CONTRIBUTION_ID" | "DUPLICATE_CONTRIBUTION_PATH" | "INVALID_CONTRIBUTION" | "EVENT_SEQUENCE_CONFLICT";
+export declare class RegistryConflictError extends Error {
+    readonly code: RegistryConflictCode;
+    readonly contributionId: string;
+    readonly name = "RegistryConflictError";
+    constructor(code: RegistryConflictCode, message: string, contributionId: string);
+}
+export interface ClientPluginManifest {
+    readonly pluginId: string;
+    readonly version: string;
+    readonly targets: readonly ClientPluginTarget[];
+    readonly routes?: readonly string[];
+    readonly navigation?: readonly string[];
+    readonly adminPanels?: readonly string[];
+    readonly conversationKinds?: readonly string[];
+}
+export interface OwnedContribution {
+    readonly id: string;
+    readonly pluginId: string;
+    readonly order?: number;
+}
+/**
+ * A synchronous, effect-owned registry. Registration either succeeds
+ * atomically or leaves no record behind; the returned disposer is idempotent.
+ */
+export declare class EffectRegistry<T extends OwnedContribution> {
+    #private;
+    readonly point: string;
+    readonly conflictKey?: ((contribution: T) => string | undefined) | undefined;
+    constructor(point: string, conflictKey?: ((contribution: T) => string | undefined) | undefined);
+    register(contribution: T): RegistryDisposer;
+    get(id: string): T | undefined;
+    getByConflictKey(key: string): T | undefined;
+    list(): readonly T[];
+}
+export interface RouteMatch {
+    readonly path: string;
+    readonly params: Readonly<Record<string, string>>;
+}
+export interface WebRouteContribution<Context = unknown, View = unknown> extends OwnedContribution {
+    readonly path: string;
+    render(context: Context, match: RouteMatch): View;
+}
+export interface WebNavigationContribution<Icon = unknown> extends OwnedContribution {
+    readonly scope: string;
+    readonly path: string;
+    readonly labelKey: string;
+    readonly icon?: Icon;
+    readonly entitlement?: string;
+}
+export interface WebAdminPanelContribution<Context = unknown, View = unknown, Icon = unknown> extends OwnedContribution {
+    readonly tab: string;
+    readonly group: string;
+    readonly labelKey: string;
+    readonly icon?: Icon;
+    render(context: Context): View;
+}
+export interface WebSettingsFieldContribution<Context = unknown, View = unknown> extends OwnedContribution {
+    readonly path: string;
+    readonly labelKey: string;
+    render(context: Context): View;
+}
+export interface WebAIBlockContribution<Context = unknown, View = unknown> extends OwnedContribution {
+    readonly kind: string;
+    render(payload: unknown, context: Context): View;
+}
+export interface WebSearchResultContribution<Context = unknown, View = unknown> extends OwnedContribution {
+    readonly kind: string;
+    render(result: unknown, context: Context): View;
+}
+export type KnowledgeSourceSelection = "document" | "file" | "folder" | "url" | "config";
+export interface WebKnowledgeSourceContribution<Context = unknown, View = unknown> extends OwnedContribution {
+    readonly sourceKind: string;
+    /** Plugin catalog key shown on the knowledge-relations page. */
+    readonly labelKey?: string;
+    /**
+     * Host picker used to bind one target.
+     * `config` means the plugin renders its own form and calls `context.bind`.
+     */
+    readonly selection?: KnowledgeSourceSelection;
+    render(config: unknown, context: Context): View;
+}
+export interface WebFilePickerContribution<Context = unknown, View = unknown> extends OwnedContribution {
+    readonly capability: string;
+    render(context: Context): View;
+}
+export interface PluginMessagesContribution extends OwnedContribution {
+    readonly messages: Readonly<Record<PluginLocale, Readonly<Record<string, string>>>>;
+}
+export interface WebPluginTypes {
+    readonly View: unknown;
+    readonly Icon: unknown;
+    readonly RouteContext: unknown;
+    readonly AdminContext: unknown;
+    readonly SettingsContext: unknown;
+    readonly AIBlockContext: unknown;
+    readonly SearchResultContext: unknown;
+    readonly KnowledgeSourceContext: unknown;
+    readonly FilePickerContext: unknown;
+}
+export type DefaultWebPluginTypes = {
+    readonly View: unknown;
+    readonly Icon: unknown;
+    readonly RouteContext: unknown;
+    readonly AdminContext: unknown;
+    readonly SettingsContext: unknown;
+    readonly AIBlockContext: unknown;
+    readonly SearchResultContext: unknown;
+    readonly KnowledgeSourceContext: unknown;
+    readonly FilePickerContext: unknown;
+};
+export interface WebPluginBundle<T extends WebPluginTypes = DefaultWebPluginTypes> {
+    readonly manifest: ClientPluginManifest;
+    readonly routes?: readonly WebRouteContribution<T["RouteContext"], T["View"]>[];
+    readonly navigation?: readonly WebNavigationContribution<T["Icon"]>[];
+    readonly adminPanels?: readonly WebAdminPanelContribution<T["AdminContext"], T["View"], T["Icon"]>[];
+    readonly settingsFields?: readonly WebSettingsFieldContribution<T["SettingsContext"], T["View"]>[];
+    readonly aiBlocks?: readonly WebAIBlockContribution<T["AIBlockContext"], T["View"]>[];
+    readonly searchResults?: readonly WebSearchResultContribution<T["SearchResultContext"], T["View"]>[];
+    readonly knowledgeSources?: readonly WebKnowledgeSourceContribution<T["KnowledgeSourceContext"], T["View"]>[];
+    readonly filePickers?: readonly WebFilePickerContribution<T["FilePickerContext"], T["View"]>[];
+    readonly messages?: readonly PluginMessagesContribution[];
+}
+export declare class WebPluginRegistry<T extends WebPluginTypes = DefaultWebPluginTypes> {
+    #private;
+    readonly routes: EffectRegistry<WebRouteContribution<T["RouteContext"], T["View"]>>;
+    readonly navigation: EffectRegistry<WebNavigationContribution<T["Icon"]>>;
+    readonly adminPanels: EffectRegistry<WebAdminPanelContribution<T["AdminContext"], T["View"], T["Icon"]>>;
+    readonly settingsFields: EffectRegistry<WebSettingsFieldContribution<T["SettingsContext"], T["View"]>>;
+    readonly aiBlocks: EffectRegistry<WebAIBlockContribution<T["AIBlockContext"], T["View"]>>;
+    readonly searchResults: EffectRegistry<WebSearchResultContribution<T["SearchResultContext"], T["View"]>>;
+    readonly knowledgeSources: EffectRegistry<WebKnowledgeSourceContribution<T["KnowledgeSourceContext"], T["View"]>>;
+    readonly filePickers: EffectRegistry<WebFilePickerContribution<T["FilePickerContext"], T["View"]>>;
+    readonly messages: EffectRegistry<PluginMessagesContribution>;
+    register(bundle: WebPluginBundle<T>): RegistryDisposer;
+    manifests(): readonly ClientPluginManifest[];
+    resolveRoute(path: string): {
+        readonly contribution: WebRouteContribution<T["RouteContext"], T["View"]>;
+        readonly match: RouteMatch;
+    } | undefined;
+    translate(locale: string | undefined, key: string, values?: Readonly<Record<string, unknown>>): string;
+}
+export interface MobileRouteContribution<Context = unknown, View = unknown> extends OwnedContribution {
+    readonly path: string;
+    render(context: Context, match: RouteMatch): View;
+}
+export interface MobileTabContribution<Icon = unknown> extends OwnedContribution {
+    readonly route: string;
+    readonly labelKey: string;
+    readonly icon?: Icon;
+}
+export interface MobilePluginTypes {
+    readonly View: unknown;
+    readonly Icon: unknown;
+    readonly RouteContext: unknown;
+    readonly NodeContext: unknown;
+    readonly FilePickerContext: unknown;
+}
+export type DefaultMobilePluginTypes = {
+    readonly View: unknown;
+    readonly Icon: unknown;
+    readonly RouteContext: unknown;
+    readonly NodeContext: unknown;
+    readonly FilePickerContext: unknown;
+};
+export interface MobilePluginBundle<T extends MobilePluginTypes = DefaultMobilePluginTypes> {
+    readonly manifest: ClientPluginManifest;
+    readonly routes?: readonly MobileRouteContribution<T["RouteContext"], T["View"]>[];
+    readonly tabs?: readonly MobileTabContribution<T["Icon"]>[];
+    readonly aiNodes?: readonly WebAIBlockContribution<T["NodeContext"], T["View"]>[];
+    readonly searchResults?: readonly WebSearchResultContribution<T["NodeContext"], T["View"]>[];
+    readonly filePickers?: readonly WebFilePickerContribution<T["FilePickerContext"], T["View"]>[];
+    readonly messages?: readonly PluginMessagesContribution[];
+}
+export declare class MobilePluginRegistry<T extends MobilePluginTypes = DefaultMobilePluginTypes> {
+    #private;
+    readonly routes: EffectRegistry<MobileRouteContribution<T["RouteContext"], T["View"]>>;
+    readonly tabs: EffectRegistry<MobileTabContribution<T["Icon"]>>;
+    readonly aiNodes: EffectRegistry<WebAIBlockContribution<T["NodeContext"], T["View"]>>;
+    readonly searchResults: EffectRegistry<WebSearchResultContribution<T["NodeContext"], T["View"]>>;
+    readonly filePickers: EffectRegistry<WebFilePickerContribution<T["FilePickerContext"], T["View"]>>;
+    readonly messages: EffectRegistry<PluginMessagesContribution>;
+    register(bundle: MobilePluginBundle<T>): RegistryDisposer;
+    manifests(): readonly ClientPluginManifest[];
+}
+export interface ConversationEvent<Payload = unknown> {
+    readonly kind: string;
+    readonly id: string;
+    readonly seq: number;
+    readonly type: string;
+    readonly payload: Payload;
+    readonly schemaVersion?: number;
+    readonly settled?: boolean;
+    readonly turnId?: string;
+    readonly stepId?: string;
+}
+export interface ConversationDefinition<State = unknown, Node = unknown> extends OwnedContribution {
+    readonly kind: string;
+    isStart(event: ConversationEvent): boolean;
+    start(event: ConversationEvent): State;
+    update(state: State, event: ConversationEvent): State;
+    materialize(state: State, context: {
+        readonly key: string;
+        readonly events: readonly ConversationEvent[];
+    }): Node;
+}
+export interface MaterializedConversationNode<Node = unknown> {
+    readonly key: string;
+    readonly kind: string;
+    readonly id: string;
+    readonly firstSeq: number;
+    readonly lastSeq: number;
+    readonly settled: boolean;
+    readonly definitionId: string;
+    readonly value: Node;
+}
+export interface GenericConversationFact {
+    readonly type: "generic-event";
+    readonly kind: string;
+    readonly id: string;
+    readonly events: readonly ConversationEvent[];
+}
+export type ConversationNode<Node = unknown> = MaterializedConversationNode<Node> | MaterializedConversationNode<GenericConversationFact>;
+/**
+ * Stores events by stable (kind,id,seq) and replays each stream from sorted
+ * sequence numbers for every projection. Arrival order never affects output.
+ */
+export declare class ConversationAssembler<Node = unknown> {
+    #private;
+    readonly definitions: EffectRegistry<ConversationDefinition<unknown, Node>>;
+    append(event: ConversationEvent): boolean;
+    appendAll(events: readonly ConversationEvent[]): readonly ConversationNode<Node>[];
+    clear(kind?: string, id?: string): void;
+    snapshot(): readonly ConversationNode<Node>[];
+}