esoul-sdk 0.3.0 → 0.6.0

package/dist/manifest.d.ts

@@ -75,6 +75,128 @@ export declare const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{
     clientSecretEnv?: string | undefined;
     headerNames?: string[] | undefined;
 }>;
+/**
+ * WHO MAY REACH A SURFACE — the access level of one op, route or kickable task.
+ *
+ * Every entry point of an app has always been owner-or-editor-only, which is
+ * the right default and the wrong ONLY option: an app with customers needs a
+ * catalogue anyone may read and an order anyone signed in may place.
+ *
+ *   write  (default) — people who may edit the workspace. Today's behaviour.
+ *   read            — anyone who may see it, including a read-only member.
+ *   public          — anyone on the app's public share link, signed in or not.
+ *
+ * `requires: "account"` adds "…but they must be signed in", answered with
+ * `login-required` (and a way back) rather than a flat refusal, so the app can
+ * render a sign-in wall instead of an error.
+ *
+ * NOTHING opens by default. A level is opt-in per NAME, and the install card
+ * lists every public door before the owner presses Install.
+ */
+export declare const PLUGIN_ACCESS_LEVELS: readonly ["write", "read", "public"];
+export type PluginAccessLevel = (typeof PLUGIN_ACCESS_LEVELS)[number];
+export declare const PluginSurfaceEntrySchema: z.ZodObject<{
+    access: z.ZodDefault<z.ZodOptional<z.ZodEnum<["write", "read", "public"]>>>;
+    requires: z.ZodOptional<z.ZodLiteral<"account">>;
+}, "strict", z.ZodTypeAny, {
+    access: "public" | "write" | "read";
+    requires?: "account" | undefined;
+}, {
+    access?: "public" | "write" | "read" | undefined;
+    requires?: "account" | undefined;
+}>;
+/** Normalised view of any surface list: every declared name, in order. */
+export declare function surfaceNames(list: unknown): string[];
+/** The access a surface declares. Absent, unknown or array-form → `write`. */
+export declare function surfaceAccess(list: unknown, name: string): {
+    level: PluginAccessLevel;
+    requiresAccount: boolean;
+};
+/** Every name in this list that is reachable without a workspace session. */
+export declare function publicSurfaceNames(list: unknown): string[];
+/**
+ * WHAT THE APP CALLS ITS PEOPLE.
+ *
+ * The platform knows owner / member / visitor / anonymous. A shop thinks in
+ * customer / staff / owner. An app declares its own words and how the
+ * platform's kinds map onto them, and the owner can override the word for one
+ * person and one app in the sharing settings — the `appRoles` column that has
+ * carried a "Phase 5+" comment since it was added, and that nothing has ever
+ * written.
+ *
+ * `describe` is not decoration: it is what the role picker shows the owner when
+ * they are deciding what to give somebody.
+ */
+export declare const PluginRolesSchema: z.ZodEffects<z.ZodObject<{
+    vocabulary: z.ZodArray<z.ZodString, "many">;
+    default: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        owner: z.ZodOptional<z.ZodString>;
+        "member-edit": z.ZodOptional<z.ZodString>;
+        "member-readonly": z.ZodOptional<z.ZodString>;
+        visitor: z.ZodOptional<z.ZodString>;
+        anonymous: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        owner?: string | undefined;
+        "member-edit"?: string | undefined;
+        "member-readonly"?: string | undefined;
+        visitor?: string | undefined;
+        anonymous?: string | undefined;
+        agent?: string | undefined;
+    }, {
+        owner?: string | undefined;
+        "member-edit"?: string | undefined;
+        "member-readonly"?: string | undefined;
+        visitor?: string | undefined;
+        anonymous?: string | undefined;
+        agent?: string | undefined;
+    }>>>;
+    describe: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    vocabulary: string[];
+    default: {
+        owner?: string | undefined;
+        "member-edit"?: string | undefined;
+        "member-readonly"?: string | undefined;
+        visitor?: string | undefined;
+        anonymous?: string | undefined;
+        agent?: string | undefined;
+    };
+    describe?: Record<string, string> | undefined;
+}, {
+    vocabulary: string[];
+    default?: {
+        owner?: string | undefined;
+        "member-edit"?: string | undefined;
+        "member-readonly"?: string | undefined;
+        visitor?: string | undefined;
+        anonymous?: string | undefined;
+        agent?: string | undefined;
+    } | undefined;
+    describe?: Record<string, string> | undefined;
+}>, {
+    vocabulary: string[];
+    default: {
+        owner?: string | undefined;
+        "member-edit"?: string | undefined;
+        "member-readonly"?: string | undefined;
+        visitor?: string | undefined;
+        anonymous?: string | undefined;
+        agent?: string | undefined;
+    };
+    describe?: Record<string, string> | undefined;
+}, {
+    vocabulary: string[];
+    default?: {
+        owner?: string | undefined;
+        "member-edit"?: string | undefined;
+        "member-readonly"?: string | undefined;
+        visitor?: string | undefined;
+        anonymous?: string | undefined;
+        agent?: string | undefined;
+    } | undefined;
+    describe?: Record<string, string> | undefined;
+}>;
 export declare const PluginManifestSchema: z.ZodObject<{
     manifestVersion: z.ZodLiteral<1>;
     /** Directory name under src/plugins/. Kebab-case. */
@@ -109,12 +231,42 @@ export declare const PluginManifestSchema: z.ZodObject<{
         email?: string | undefined;
         url?: string | undefined;
     }>>;
-    /** Tasks the BROWSER may kick via /api/inngest/send-event. */
-    kickableTasks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Tasks the BROWSER may kick via /api/inngest/send-event. Array or name→access. */
+    kickableTasks: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{
+        access: z.ZodDefault<z.ZodOptional<z.ZodEnum<["write", "read", "public"]>>>;
+        requires: z.ZodOptional<z.ZodLiteral<"account">>;
+    }, "strict", z.ZodTypeAny, {
+        access: "public" | "write" | "read";
+        requires?: "account" | undefined;
+    }, {
+        access?: "public" | "write" | "read" | undefined;
+        requires?: "account" | undefined;
+    }>>]>>>;
     /** Push-ingress endpoints — POST|GET /api/plugins/<id>/webhook/<name>. */
     webhooks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
-    /** Server ops — POST /api/plugins/<id>/op/<name> (platform-gated). */
-    ops: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Server ops — POST /api/plugins/<id>/op/<name>. Array or name→access. */
+    ops: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{
+        access: z.ZodDefault<z.ZodOptional<z.ZodEnum<["write", "read", "public"]>>>;
+        requires: z.ZodOptional<z.ZodLiteral<"account">>;
+    }, "strict", z.ZodTypeAny, {
+        access: "public" | "write" | "read";
+        requires?: "account" | undefined;
+    }, {
+        access?: "public" | "write" | "read" | undefined;
+        requires?: "account" | undefined;
+    }>>]>>>;
+    /** Server routes the app brings with it — `pluginServer.routes` in server.ts, mounted at
+     * `/api/plugins/<id>/route/<name>` on install (GET and POST; may stream). */
+    routes: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{
+        access: z.ZodDefault<z.ZodOptional<z.ZodEnum<["write", "read", "public"]>>>;
+        requires: z.ZodOptional<z.ZodLiteral<"account">>;
+    }, "strict", z.ZodTypeAny, {
+        access: "public" | "write" | "read";
+        requires?: "account" | undefined;
+    }, {
+        access?: "public" | "write" | "read" | undefined;
+        requires?: "account" | undefined;
+    }>>]>>>;
     /** Poll cadences for durable tasks (the offline-safe pull lane). */
     pollTasks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
         task: z.ZodString;
@@ -139,6 +291,77 @@ export declare const PluginManifestSchema: z.ZodObject<{
     }>>;
     /** Reserved for the review/consent flow. */
     scopes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** The app's own role vocabulary (see PluginRolesSchema). */
+    roles: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        vocabulary: z.ZodArray<z.ZodString, "many">;
+        default: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+            owner: z.ZodOptional<z.ZodString>;
+            "member-edit": z.ZodOptional<z.ZodString>;
+            "member-readonly": z.ZodOptional<z.ZodString>;
+            visitor: z.ZodOptional<z.ZodString>;
+            anonymous: z.ZodOptional<z.ZodString>;
+            agent: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        }, {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        }>>>;
+        describe: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        vocabulary: string[];
+        default: {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        };
+        describe?: Record<string, string> | undefined;
+    }, {
+        vocabulary: string[];
+        default?: {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        } | undefined;
+        describe?: Record<string, string> | undefined;
+    }>, {
+        vocabulary: string[];
+        default: {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        };
+        describe?: Record<string, string> | undefined;
+    }, {
+        vocabulary: string[];
+        default?: {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        } | undefined;
+        describe?: Record<string, string> | undefined;
+    }>>;
     /**
      * Tools of OTHER apps in the workspace this plugin's UI may invoke through
      * `useWorkspaceTools()` — "<applicationType>:<tool base name>", e.g.
@@ -248,17 +471,140 @@ export declare const PluginManifestSchema: z.ZodObject<{
         label: string;
         connectionKey: string;
     }>, "many">>>;
-}, "strip", z.ZodTypeAny, {
+    /**
+     * SLOTS this app needs filled (S9). `contract` names what must stand there
+     * ("stock/v1"); the OWNER picks which app fills it, and the platform checks
+     * at bind time that the provider really has every tool, event and table the
+     * contract requires. A required slot nothing fills refuses at the seam
+     * (`not-bound`); an optional one is simply absent.
+     */
+    uses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        contract: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        optional: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        contract: string;
+        label?: string | undefined;
+        optional?: boolean | undefined;
+    }, {
+        contract: string;
+        label?: string | undefined;
+        optional?: boolean | undefined;
+    }>>>;
+    /**
+     * What this app OFFERS other apps, per contract id. A claim, checked at bind
+     * time against what the app actually has — a manifest that names a tool the
+     * app does not mint refuses the binding rather than failing later inside
+     * someone's order.
+     */
+    provides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        models: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        tools?: string[] | undefined;
+        events?: string[] | undefined;
+        models?: string[] | undefined;
+    }, {
+        tools?: string[] | undefined;
+        events?: string[] | undefined;
+        models?: string[] | undefined;
+    }>>>;
+    /**
+     * The app's realtime TOPICS, and who hears each (forge-sdk-spec-and-tests
+     * §A1.3.5). `audience` is `all` (default — the instance's channel), `viewer`
+     * (one channel per person) or `role:<name>`; `mayAddress` names the roles
+     * allowed to aim a message at someone else. The platform mints a token per
+     * channel, so a customer is never handed the staff channel or another
+     * customer's — it is not filtered on arrival, it is never issued.
+     * `esoul-sdk/audience` is the one decision both sides use.
+     */
+    channel: z.ZodOptional<z.ZodObject<{
+        topics: z.ZodRecord<z.ZodString, z.ZodObject<{
+            audience: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodLiteral<"viewer">, z.ZodString]>>;
+            mayAddress: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            description?: string | undefined;
+            audience?: string | undefined;
+            mayAddress?: string[] | undefined;
+        }, {
+            description?: string | undefined;
+            audience?: string | undefined;
+            mayAddress?: string[] | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        topics: Record<string, {
+            description?: string | undefined;
+            audience?: string | undefined;
+            mayAddress?: string[] | undefined;
+        }>;
+    }, {
+        topics: Record<string, {
+            description?: string | undefined;
+            audience?: string | undefined;
+            mayAddress?: string[] | undefined;
+        }>;
+    }>>;
+    /**
+     * The app's own TABLES (forge-sdk-spec-and-tests §A1.3.4). Shape only: the
+     * rule compiler (`db/compile-rules.ts`) is what validates a field type, a
+     * rule's principals and a sealed column, and it says which key was wrong.
+     *
+     * It is declared HERE because a schema that does not know a block SILENTLY
+     * DROPS it — `z.object` strips what it has no field for. The install path
+     * parses through this schema, so for one evening an app installed from its
+     * own repository arrived with `db: undefined`, the job skipped its
+     * schema step without a word, and the app was live with no tables
+     * (2026-09-11, found by driving it). Hence `.strict()` below: a block this
+     * platform does not understand refuses the install instead of vanishing.
+     */
+    db: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        scope: z.ZodOptional<z.ZodEnum<["instance", "workspace", "user"]>>;
+        owner: z.ZodOptional<z.ZodLiteral<"creator">>;
+        fields: z.ZodRecord<z.ZodString, z.ZodString>;
+        sealed: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">>;
+        indexes: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">>;
+        rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        fields: Record<string, string>;
+        owner?: "creator" | undefined;
+        scope?: "workspace" | "instance" | "user" | undefined;
+        sealed?: string[] | undefined;
+        unique?: string[][] | undefined;
+        indexes?: string[][] | undefined;
+        rules?: Record<string, unknown> | undefined;
+    }, {
+        fields: Record<string, string>;
+        owner?: "creator" | undefined;
+        scope?: "workspace" | "instance" | "user" | undefined;
+        sealed?: string[] | undefined;
+        unique?: string[][] | undefined;
+        indexes?: string[][] | undefined;
+        rules?: Record<string, unknown> | undefined;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    version: string;
+    applicationType: string;
     description: string;
     manifestVersion: 1;
     id: string;
     name: string;
-    version: string;
-    applicationType: string;
     entry: string;
-    kickableTasks: string[];
+    kickableTasks: string[] | Record<string, {
+        access: "public" | "write" | "read";
+        requires?: "account" | undefined;
+    }>;
     webhooks: string[];
-    ops: string[];
+    ops: string[] | Record<string, {
+        access: "public" | "write" | "read";
+        requires?: "account" | undefined;
+    }>;
+    routes: string[] | Record<string, {
+        access: "public" | "write" | "read";
+        requires?: "account" | undefined;
+    }>;
     pollTasks: {
         task: string;
         everyMinutes: number;
@@ -292,17 +638,55 @@ export declare const PluginManifestSchema: z.ZodObject<{
         min: string;
         max?: string | undefined;
     } | undefined;
+    roles?: {
+        vocabulary: string[];
+        default: {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        };
+        describe?: Record<string, string> | undefined;
+    } | undefined;
     fileSources?: {
         providers: string[];
         workspace?: "read" | "readwrite" | undefined;
     } | undefined;
+    uses?: Record<string, {
+        contract: string;
+        label?: string | undefined;
+        optional?: boolean | undefined;
+    }> | undefined;
+    provides?: Record<string, {
+        tools?: string[] | undefined;
+        events?: string[] | undefined;
+        models?: string[] | undefined;
+    }> | undefined;
+    channel?: {
+        topics: Record<string, {
+            description?: string | undefined;
+            audience?: string | undefined;
+            mayAddress?: string[] | undefined;
+        }>;
+    } | undefined;
+    db?: Record<string, {
+        fields: Record<string, string>;
+        owner?: "creator" | undefined;
+        scope?: "workspace" | "instance" | "user" | undefined;
+        sealed?: string[] | undefined;
+        unique?: string[][] | undefined;
+        indexes?: string[][] | undefined;
+        rules?: Record<string, unknown> | undefined;
+    }> | undefined;
 }, {
+    version: string;
+    applicationType: string;
     description: string;
     manifestVersion: 1;
     id: string;
     name: string;
-    version: string;
-    applicationType: string;
     entry: string;
     icon?: string | undefined;
     author?: {
@@ -310,9 +694,19 @@ export declare const PluginManifestSchema: z.ZodObject<{
         email?: string | undefined;
         url?: string | undefined;
     } | undefined;
-    kickableTasks?: string[] | undefined;
+    kickableTasks?: string[] | Record<string, {
+        access?: "public" | "write" | "read" | undefined;
+        requires?: "account" | undefined;
+    }> | undefined;
     webhooks?: string[] | undefined;
-    ops?: string[] | undefined;
+    ops?: string[] | Record<string, {
+        access?: "public" | "write" | "read" | undefined;
+        requires?: "account" | undefined;
+    }> | undefined;
+    routes?: string[] | Record<string, {
+        access?: "public" | "write" | "read" | undefined;
+        requires?: "account" | undefined;
+    }> | undefined;
     pollTasks?: {
         task: string;
         everyMinutes: number;
@@ -322,6 +716,18 @@ export declare const PluginManifestSchema: z.ZodObject<{
         max?: string | undefined;
     } | undefined;
     scopes?: string[] | undefined;
+    roles?: {
+        vocabulary: string[];
+        default?: {
+            owner?: string | undefined;
+            "member-edit"?: string | undefined;
+            "member-readonly"?: string | undefined;
+            visitor?: string | undefined;
+            anonymous?: string | undefined;
+            agent?: string | undefined;
+        } | undefined;
+        describe?: Record<string, string> | undefined;
+    } | undefined;
     workspaceTools?: string[] | undefined;
     connections?: {
         key: string;
@@ -344,6 +750,32 @@ export declare const PluginManifestSchema: z.ZodObject<{
         label: string;
         connectionKey: string;
     }[] | undefined;
+    uses?: Record<string, {
+        contract: string;
+        label?: string | undefined;
+        optional?: boolean | undefined;
+    }> | undefined;
+    provides?: Record<string, {
+        tools?: string[] | undefined;
+        events?: string[] | undefined;
+        models?: string[] | undefined;
+    }> | undefined;
+    channel?: {
+        topics: Record<string, {
+            description?: string | undefined;
+            audience?: string | undefined;
+            mayAddress?: string[] | undefined;
+        }>;
+    } | undefined;
+    db?: Record<string, {
+        fields: Record<string, string>;
+        owner?: "creator" | undefined;
+        scope?: "workspace" | "instance" | "user" | undefined;
+        sealed?: string[] | undefined;
+        unique?: string[][] | undefined;
+        indexes?: string[][] | undefined;
+        rules?: Record<string, unknown> | undefined;
+    }> | undefined;
 }>;
 export type PluginManifest = z.infer<typeof PluginManifestSchema>;
 export type PluginConnectionDecl = z.infer<typeof PluginConnectionSchema>;