@smartdoca/plugin-sdk 0.1.0

package/dist/platform.d.ts

@@ -0,0 +1,176 @@
+import type { JsonObject, MaybePromise } from "@smartdoca/plugin-contracts";
+export interface PluginPrincipal {
+    readonly id: string;
+    readonly displayName: string;
+    readonly publicId: string;
+    readonly admin: boolean;
+}
+export interface PluginRequestContext {
+    readonly requestId: string;
+    readonly principal: PluginPrincipal;
+    readonly signal: AbortSignal;
+}
+export interface PluginUser extends PluginPrincipal {
+    readonly login: string;
+    readonly status: string;
+    readonly createdAt: string;
+    readonly profile: JsonObject;
+    readonly profileRevision: number;
+    readonly contacts: readonly {
+        kind: string;
+        value: string;
+        verified: boolean;
+    }[];
+}
+export interface DirectoryUser {
+    readonly id: string;
+    readonly display_name: string;
+    readonly public_id: string | null;
+    readonly avatar: string | null;
+    readonly avatar_asset_id: string | null;
+}
+export interface UsersServiceV1 {
+    /** Trusted server task revalidation; does not grant access to business resources. */
+    status(id: string): Promise<{
+        readonly id: string;
+        readonly status: string;
+    } | null>;
+    get(context: PluginRequestContext, id: string): Promise<PluginUser | null>;
+    /** Trusted server-only inventory for initial reconciliation; never expose directly to browsers. */
+    list(input?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        items: readonly PluginUser[];
+        cursor: string | null;
+    }>;
+    search(context: PluginRequestContext, query: string): Promise<readonly DirectoryUser[]>;
+}
+export interface PluginResource {
+    readonly pluginId: string;
+    readonly type: string;
+    readonly id: string;
+}
+export interface PermissionSource {
+    readonly pluginId: string;
+    readonly resourceType: string;
+    authorize(principalId: string, resourceId: string, action: string): Promise<boolean>;
+}
+export interface DirectoryRelation {
+    readonly userId: string;
+    readonly relationId: string;
+    readonly revision: string;
+}
+export interface DirectorySource {
+    readonly id: string;
+    readonly schemaVersion: 1;
+    /** Indexed current relations from the plugin's own database. */
+    related(principalId: string, input: {
+        cursor: string | null;
+        limit: number;
+        signal: AbortSignal;
+    }): Promise<{
+        items: readonly DirectoryRelation[];
+        cursor: string | null;
+    }>;
+    /** Recheck candidates against current sharing, returning only still-visible user IDs. */
+    verify(principalId: string, candidates: readonly DirectoryRelation[], signal: AbortSignal): Promise<readonly string[]>;
+}
+export interface PermissionsServiceV1 {
+    register(source: PermissionSource): () => void;
+    registerDirectory(source: DirectorySource): () => void;
+    authorize(context: PluginRequestContext, resource: PluginResource, action: string): Promise<boolean>;
+}
+export interface PluginHttpRequest extends PluginRequestContext {
+    readonly params: Readonly<Record<string, string>>;
+    readonly query: Readonly<Record<string, unknown>>;
+    readonly body: unknown;
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    readonly rawBody: Uint8Array;
+}
+export interface PluginHttpResponse {
+    status(code: number): PluginHttpResponse;
+    header(name: string, value: string | readonly string[]): PluginHttpResponse;
+    redirect(location: string, code?: 302 | 303 | 307 | 308): void;
+}
+export type PluginExternalRequest = Omit<PluginHttpRequest, "principal"> & {
+    readonly principal: null;
+};
+interface PluginRouteBase {
+    readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    readonly path: string;
+    /** Defaults to 1 MiB. Trusted plugins may explicitly request up to 32 MiB. */
+    readonly bodyLimit?: number;
+    readonly schema?: {
+        readonly body?: JsonObject;
+        readonly querystring?: JsonObject;
+        readonly params?: JsonObject;
+    };
+}
+export type PluginRoute = PluginRouteBase & ({
+    readonly auth?: "session";
+    readonly admin?: boolean;
+    handle(request: PluginHttpRequest, response: PluginHttpResponse): MaybePromise<unknown>;
+} | {
+    readonly auth: "external";
+    /** Verify OAuth state or webhook signature. No host session is implied. */
+    verify(request: PluginExternalRequest): MaybePromise<boolean>;
+    handle(request: PluginExternalRequest, response: PluginHttpResponse): MaybePromise<unknown>;
+});
+export interface HttpServiceV1 {
+    /** Trusted deployment origin, never constructed from request headers. */
+    callbackUrl(pluginId: string, path: string): string;
+    /** External routes must explicitly verify their external identity. */
+    register(pluginId: string, routes: readonly PluginRoute[]): Promise<() => Promise<void>>;
+}
+export interface OperationPolicy {
+    readonly id: string;
+    check(input: {
+        readonly principalId: string;
+        readonly action: string;
+        readonly facts: JsonObject;
+    }): Promise<void>;
+}
+export interface PoliciesServiceV1 {
+    register(policy: OperationPolicy): () => void;
+    check(principalId: string, action: string, facts?: JsonObject): Promise<void>;
+}
+export declare const usersServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<UsersServiceV1>;
+export declare const permissionsServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<PermissionsServiceV1>;
+export declare const httpServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<HttpServiceV1>;
+export declare const policiesServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<PoliciesServiceV1>;
+export interface PluginIntegrationEvent {
+    readonly sequence: number;
+    readonly id: string;
+    readonly type: string;
+    readonly payload: JsonObject;
+    readonly createdAt: string;
+}
+export interface EventsServiceV1 {
+    /** Durable ordered stream. Persist the last processed sequence in the plugin data store. */
+    read(after: number, limit?: number): Promise<readonly PluginIntegrationEvent[]>;
+}
+export declare const eventsServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<EventsServiceV1>;
+export interface PluginNotificationInput {
+    readonly recipientId: string;
+    readonly key: string;
+    readonly title: string;
+    readonly body: string;
+    /** Local application route, e.g. /mail/inbox?message=123. No origin or hash. */
+    readonly path: string;
+    readonly resource: {
+        readonly type: string;
+        readonly id: string;
+    };
+}
+export interface NotificationsServiceV1 {
+    publish(pluginId: string, input: PluginNotificationInput): Promise<{
+        id: string;
+    }>;
+    withdraw(pluginId: string, input: {
+        recipientId: string;
+        key: string;
+    }): Promise<void>;
+}
+export declare const notificationsServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<NotificationsServiceV1>;
+export {};

package/dist/platform.js

@@ -0,0 +1,7 @@
+import { defineService } from "./index.js";
+export const usersServiceToken = defineService("users.v1");
+export const permissionsServiceToken = defineService("permissions.v1");
+export const httpServiceToken = defineService("http.v1");
+export const policiesServiceToken = defineService("policies.v1");
+export const eventsServiceToken = defineService("events.v1");
+export const notificationsServiceToken = defineService("notifications.v1");

package/dist/search.d.ts

@@ -0,0 +1,20 @@
+import type { PluginRequestContext } from "./platform.js";
+import type { SearchSource, SearchProjection, SearchSourceDescriptor, FederatedSearchResult, SearchRebuildResult } from "@smartdoca/search-host";
+export type * from "@smartdoca/search-host";
+export interface PluginSearchContext {
+    readonly principalId: string | null;
+    readonly signal?: AbortSignal;
+}
+export interface PluginSearchService {
+    register(source: SearchSource<PluginSearchContext>): () => void;
+    upsert(source: SearchSourceDescriptor, projections: readonly SearchProjection[]): Promise<void>;
+    delete(source: SearchSourceDescriptor, ids: readonly string[]): Promise<void>;
+    rebuild(source: SearchSourceDescriptor, signal?: AbortSignal): Promise<SearchRebuildResult>;
+    query(context: PluginRequestContext, input: {
+        source: SearchSourceDescriptor;
+        query: string;
+        offset?: number;
+        limit?: number;
+    }): Promise<FederatedSearchResult>;
+}
+export declare const searchServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<PluginSearchService>;

package/dist/search.js

@@ -0,0 +1,2 @@
+import { defineService } from "./index.js";
+export const searchServiceToken = defineService("search.v1");

package/dist/testing.d.ts

@@ -0,0 +1,20 @@
+import { type DocaPlugin, type JsonObject, type ServiceToken } from "@smartdoca/plugin-contracts";
+export interface PluginContractHarnessOptions {
+    readonly config?: JsonObject;
+    readonly services?: readonly {
+        readonly token: ServiceToken<any>;
+        readonly value: any;
+    }[];
+}
+export interface PluginContractHarnessResult {
+    readonly pluginId: string;
+    readonly phases: readonly string[];
+    readonly disposed: boolean;
+}
+/**
+ * Runs one plugin through the public lifecycle without application globals.
+ * Domain harnesses can provide fake capability Services and inspect them after
+ * this function returns. Provider/contribution collisions and missing required
+ * injections use the same SDK stores as production.
+ */
+export declare function runPluginContractHarness<Config extends JsonObject = JsonObject>(plugin: DocaPlugin<Config>, options?: PluginContractHarnessOptions): Promise<PluginContractHarnessResult>;

package/dist/testing.js

@@ -0,0 +1,57 @@
+import { Context, ContributionStore, PluginContext } from "./index.js";
+import { validatePluginConfig, validatePluginManifest, } from "@smartdoca/plugin-contracts";
+/**
+ * Runs one plugin through the public lifecycle without application globals.
+ * Domain harnesses can provide fake capability Services and inspect them after
+ * this function returns. Provider/contribution collisions and missing required
+ * injections use the same SDK stores as production.
+ */
+export async function runPluginContractHarness(plugin, options = {}) {
+    const manifest = validatePluginManifest(plugin.manifest);
+    const config = validatePluginConfig(manifest, options.config);
+    const root = new Context();
+    const scope = await root.createFiberScope(`testing.${manifest.id}`);
+    const store = new ContributionStore();
+    const contributions = {
+        register(point, id, value) {
+            return store.register(scope, manifest.id, point, id, value);
+        },
+        get(point, id) {
+            return store.get(point, id);
+        },
+        list(point) {
+            return store.list(point);
+        },
+    };
+    const context = new PluginContext(scope, manifest, config, contributions);
+    const phases = [];
+    let lifecycleStarted = false;
+    try {
+        for (const service of options.services ?? [])
+            root.provide(service.token, service.value);
+        lifecycleStarted = true;
+        phases.push("discover");
+        await plugin.discover?.(context);
+        for (const token of plugin.injections?.required ?? [])
+            context.inject(token);
+        phases.push("initialize");
+        await plugin.initialize?.(context);
+        phases.push("mount");
+        await plugin.mount?.(context);
+        phases.push("ready");
+        await plugin.ready?.(context);
+    }
+    finally {
+        if (lifecycleStarted) {
+            phases.push("dispose");
+            await plugin.dispose?.(context);
+        }
+        await scope.dispose();
+        await root.dispose();
+    }
+    return Object.freeze({
+        pluginId: manifest.id,
+        phases: Object.freeze(phases),
+        disposed: scope.disposed,
+    });
+}

package/dist/web.d.ts

@@ -0,0 +1,34 @@
+export type * from "@smartdoca/web-plugin-registry";
+export interface PluginFileReference {
+    readonly id: string;
+    readonly name: string;
+    readonly mime: string;
+    readonly size: number;
+}
+export interface PluginFilePickerProps {
+    close(): void;
+    select?(file: PluginFileReference): void | Promise<void>;
+    selectFolder?(folder: {
+        id: string;
+        name: string;
+    }): void | Promise<void>;
+    accept?(file: PluginFileReference): boolean;
+}
+/** Host-injected React is the only supported renderer instance. */
+export interface PluginWebHost<ReactRuntime = unknown, Component = (props: PluginFilePickerProps) => any> {
+    readonly React: ReactRuntime;
+    readonly apiBase: string;
+    useEnvironment(): {
+        locale: "zh" | "en";
+        theme: "light" | "soft";
+    };
+    navigate(path: string): void;
+    toast(message: string, tone?: "info" | "success" | "warning" | "error"): void;
+    confirm(message: string): Promise<boolean>;
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+    readonly FilePicker: Component;
+}
+export interface PluginHttpError extends Error {
+    readonly status: number;
+    readonly requestId?: string;
+}

package/dist/web.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@smartdoca/plugin-sdk",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./platform": {
+      "types": "./dist/platform.d.ts",
+      "import": "./dist/platform.js"
+    },
+    "./files": {
+      "types": "./dist/files.d.ts",
+      "import": "./dist/files.js"
+    },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "import": "./dist/ai.js"
+    },
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "import": "./dist/search.js"
+    },
+    "./knowledge": {
+      "types": "./dist/knowledge.d.ts",
+      "import": "./dist/knowledge.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@smartdoca/plugin-contracts": "0.1.0",
+    "@smartdoca/files-capability": "0.1.0",
+    "@smartdoca/search-host": "0.1.0",
+    "@smartdoca/knowledge-capability": "0.1.0",
+    "@smartdoca/web-plugin-registry": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}