@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/catalog/org-catalog.controller.js

@@ -7,55 +7,33 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Res } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Res } from "@nestjs/common";
 import { z } from "zod";
-import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
+import { orgIconScope, PluginIcons } from "../extensions/plugin-icons.js";
+import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { roleAtLeast } from "../orgs/roles.js";
-import { CredentialValue } from "../tools/connectors.controller.js";
+import { CatalogConnectorInput, CatalogGuideQuery, CatalogMarketplaceRequestBody, CatalogRequestBody, CatalogRequestsListQuery, OrgPluginInstallBody, OrgPluginSwitchBody, } from "./org-catalog.schemas.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
-import { PluginInstaller } from "./plugin-install.js";
+import { PluginInstaller, } from "./plugin-install.js";
 import { CatalogRequestsService } from "./requests.service.js";
-const RequestBody = z
+/** The connectors body (ruling P2-10): the input of missing connectors, by template id, as at install. */
+const ConnectorsBody = z
     .object({
-    note: z.string().max(1000).optional(),
-    version: z.string().min(1).max(256).optional(),
+    inputs: z.object({ connectors: z.record(z.string(), CatalogConnectorInput) }).strict(),
 })
     .strict();
-const ConnectorInput = z
+/**
+ * One more connector from a platform connector template (ruling P4-T6-8): its name and an
+ * install's connector input (`config`).
+ */
+const TemplateConnectorBody = z
     .object({
     name: z.string().trim().min(1).max(80).optional(),
-    slug: z.string().max(24).optional(),
-    endpoint: z.record(z.string(), z.unknown()).optional(),
-    credential: CredentialValue.optional(),
-    client: z
-        .object({
-        clientId: z.string().min(1).max(500),
-        clientSecret: z.string().min(1).max(4000).optional(),
-    })
-        .strict()
-        .optional(),
-})
-    .strict();
-/** The org install body: the version (default the latest), template input, the extension's org config. */
-const InstallBody = z
-    .object({
-    version: z.string().min(1).max(256).optional(),
-    connectors: z.record(z.string(), ConnectorInput).optional(),
-    extensionConfig: z.record(z.string(), z.unknown()).optional(),
-})
-    .strict();
-/** The upgrade preview body: the target version. */
-const UpgradePreviewBody = z.object({ version: z.string().min(1).max(256) }).strict();
-/** The upgrade body: the target version, the preview's diffHash, the inputs it listed. */
-const UpgradeBody = z
-    .object({
-    version: z.string().min(1).max(256),
-    diffHash: z.string().regex(/^[0-9a-f]{64}$/),
-    connectors: z.record(z.string(), ConnectorInput).optional(),
-    extensionConfig: z.record(z.string(), z.unknown()).optional(),
+    config: CatalogConnectorInput.omit({ name: true }),
 })
     .strict();
 /**
@@ -70,51 +48,69 @@ export async function sendCatalogIcon(reply, icon) {
         .header("cache-control", "private, max-age=300")
         .send(Buffer.from(icon.data.buffer, icon.data.byteOffset, icon.data.byteLength));
 }
-const DecideBody = z.object({ decision: z.enum(["approve", "reject"]) }).strict();
-const AdminListQuery = z.object({
-    status: z.enum(["pending", "approved", "rejected", "cancelled"]).optional(),
-});
-class CatalogRequestsQuery extends createZodDto(AdminListQuery, "CatalogRequestsQuery") {
+const DecideBody = z
+    .object({ approve: z.boolean(), reason: z.string().max(1000).optional() })
+    .strict();
+class CatalogGuideQueryDto extends createZodDto(CatalogGuideQuery, "CatalogGuideQuery") {
+}
+class CatalogRequestsQuery extends createZodDto(CatalogRequestsListQuery, "CatalogRequestsQuery") {
 }
 class CatalogDecideBody extends createZodDto(DecideBody, "CatalogDecideBody") {
 }
-class OrgPluginInstallBody extends createZodDto(InstallBody, "OrgPluginInstallBody") {
+class OrgPluginInstallBodyDto extends createZodDto(OrgPluginInstallBody, "OrgPluginInstallBody") {
+}
+class OrgPluginConnectorsBody extends createZodDto(ConnectorsBody, "OrgPluginConnectorsBody") {
 }
-class CatalogRequestBody extends createZodDto(RequestBody, "CatalogRequestBody") {
+class OrgPluginSwitchBodyDto extends createZodDto(OrgPluginSwitchBody, "OrgPluginSwitchBody") {
 }
-class OrgPluginUpgradeBody extends createZodDto(UpgradeBody, "OrgPluginUpgradeBody") {
+class OrgTemplateConnectorBody extends createZodDto(TemplateConnectorBody, "OrgTemplateConnectorBody") {
 }
-class OrgPluginUpgradePreviewBody extends createZodDto(UpgradePreviewBody, "OrgPluginUpgradePreviewBody") {
+class CatalogRequestBodyDto extends createZodDto(CatalogRequestBody, "CatalogRequestBody") {
+}
+class CatalogMarketplaceRequestBodyDto extends createZodDto(CatalogMarketplaceRequestBody, "CatalogMarketplaceRequestBody") {
 }
 /**
- * The enterprise catalog from an organization's view (`/api/v1/orgs/:orgId/...`, human users only):
+ * The platform catalog from an organization's view (`/api/v1/orgs/:orgId/...`, human users only):
  * - `GET catalog` (`catalog.read`, member and up; members do not see disabled items);
- * - `POST catalog/:itemId/requests` (`catalog.request`): a member request, into the org admins'
- *   inbox;
- * - `POST catalog/:itemId/install`: the route only requires `catalog.read`; the service re-checks
+ * - `POST catalog/:itemId/requests` (`catalog.request`; `access` needs an org admin): requests
+ *   under plugin scope (spec §5.1), `enable` into the org admins' inbox, `access` to the super
+ *   admin; `POST marketplace-requests` (org admins): an `import` request for a marketplace entry;
+ * - `PUT catalog/:itemId/switch` (scope phase 1): `{ enabled: true, inputs? }` installs -> 200 `{ item }`;
+ *   `{ enabled: false, confirm? }` -> 200 `{ preview, confirm }`, then with the hash 200 `{ item }`;
+ * - `POST catalog/:itemId/install` (an alias of switching on, no longer creates requests): the route only requires `catalog.read`; the service re-checks
  *   the plugin's component actions (`org.extensions.manage` for an extension, `connectors.manage`
  *   for templates, `skills.manage` for skills) inside the org row lock; needs_approval without a
  *   grant -> 202 `{ request }`, otherwise 201 `{ installed, install }` (the install view);
  * - `GET / DELETE plugin-installs[/:installId]` (`org.extensions.manage`; uninstall re-checks the
  *   plugin's component actions in the service);
- * - `POST plugin-installs/:installId/upgrade/preview` and `.../upgrade` (spec §10; the route only
- *   requires `catalog.read`, the service re-checks the component actions of both versions):
- *   preview -> 200 `{ from, to, diffHash, components, inputs, templates }`; upgrade -> 200 `{ install }`, or
- *   202 `{ request }` for a needs_approval item without a grant;
- * - `POST catalog-requests/:id/decide` (`catalog.decide`, org admins).
+ * - no per-org upgrade: a platform plugin has one version for the deployment, updated by the super
+ *   admin (`PUT /admin/catalog/items/:id/update`, ruling F2);
+ * - `POST connector-templates/:templateId/connectors` (`connectors.manage`): one more connector
+ *   from a platform connector template on in the org (ruling P4-T6-8);
+ * - `POST catalog-requests/:id/decide` (`catalog.decide`, org admins; `enable` and
+ *   `connector_setup` requests, `{ approve, reason? }`; a `connector_setup` request is only
+ *   rejected here, ruling P4-T6-6), `POST catalog-requests/:id/dismiss` (the requester, a decided
+ *   request).
  */
 let OrgCatalogController = class OrgCatalogController {
     catalog;
     requests;
     pluginInstaller;
-    constructor(catalog, requests, pluginInstaller) {
+    icons;
+    guides;
+    constructor(catalog, requests, pluginInstaller, icons, guides) {
         this.catalog = catalog;
         this.requests = requests;
         this.pluginInstaller = pluginInstaller;
+        this.icons = icons;
+        this.guides = guides;
     }
+    /** The org's catalog; each item carries `icon`, its icon's URL here (null without one). */
     async list(principal, org) {
         const p = requireUser(principal);
-        return { items: await this.catalog.list(org.orgId, p.account.id) };
+        const items = await this.catalog.list(org.orgId, p.account.id);
+        const icons = await this.icons.ofItems(items.map((i) => i.id), orgIconScope(org));
+        return { items: items.map((i) => ({ ...i, icon: icons.get(i.id) ?? null })) };
     }
     /**
      * Item detail and what the install wizard needs (members do not see disabled items -> 404
@@ -129,13 +125,52 @@ let OrgCatalogController = class OrgCatalogController {
      * -> 404 `catalog.icon_not_found`; members do not see disabled items.
      */
     async icon(org, itemId, reply) {
-        const icon = await this.catalog.icon(itemId, roleAtLeast(org.role, "admin"));
+        const icon = await this.catalog.icon(itemId, roleAtLeast(org.role, "admin"), org.orgId);
         await sendCatalogIcon(reply, icon);
     }
+    /**
+     * A setup guide of the item, rendered for this org (spec 2026-11-09-setup-guides-v2-design.md
+     * §7.2): the document's blocks with the place's variables filled in, its modes, audiences and
+     * checks, the unresolved variables with their reasons, the drift hash and the target. The item
+     * must be one the org's catalog shows; the place and audience's action (`channels.manage`,
+     * `connectors.manage`, `connectors.use`) is checked by the service.
+     */
+    async guide(org, itemId, guideId, q) {
+        return { guide: await this.guides.render(org, itemId, guideId, q) };
+    }
+    /**
+     * A request for an item (spec §5.1): `enable` (members and up, an item that is off) or `access`
+     * (org admins, a `named` item shown to the org) -> 201 `{ request }`.
+     */
     async request(principal, org, itemId, body) {
         const p = requireUser(principal);
         const tokenId = patTokenId(p);
-        return this.requests.request(org.orgId, p.account.id, itemId, body, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+        return {
+            request: await this.requests.requestItem(org.orgId, p.account.id, itemId, body, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
+        };
+    }
+    /**
+     * An org admin asks for a marketplace entry to be imported (deployment setting
+     * `orgMarketplaceBrowse`) -> 201 `{ request }`.
+     */
+    async marketplaceRequest(principal, org, body) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        return {
+            request: await this.requests.requestImport(org.orgId, p.account.id, body, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
+        };
+    }
+    async setSwitch(principal, org, itemId, body) {
+        const p = requireUser(principal);
+        const r = await this.catalog.setSwitch(org.orgId, p.account.id, itemId, body.enabled
+            ? {
+                enabled: true,
+                ...(body.inputs !== undefined && {
+                    inputs: body.inputs,
+                }),
+            }
+            : { enabled: false, ...(body.confirm !== undefined && { confirm: body.confirm }) }, patTokenId(p));
+        return r.kind === "done" ? { item: r.item } : { preview: r.preview, confirm: r.confirm };
     }
     async install(principal, org, itemId, body, reply) {
         const p = requireUser(principal);
@@ -144,32 +179,55 @@ let OrgCatalogController = class OrgCatalogController {
         const { status: _status, ...rest } = r;
         return rest;
     }
-    async listInstalls(org) {
-        return { installs: await this.pluginInstaller.list(org.orgId) };
-    }
-    async uninstall(principal, org, installId) {
+    /**
+     * Creates the connectors an installed plugin is missing (ruling P2-10: a connector template on
+     * in the org without a connector there, e.g. added by a platform update; the plugin shows
+     * `needs_config`): `{ inputs: { connectors: { <templateId>: input } } }` with the same input
+     * checks as an install; recorded on the install -> 201 `{ connectors: [{ templateId,
+     * connectorId }] }`. Not installed -> 404 `plugin.install_not_found`; a template not missing ->
+     * 400 `validation_failed`.
+     */
+    async configureConnectors(principal, org, itemId, body) {
         const p = requireUser(principal);
         const tokenId = patTokenId(p);
-        return this.pluginInstaller.uninstall(org.orgId, p.account.id, installId, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+        return {
+            connectors: await this.pluginInstaller.configureConnectors(org.orgId, p.account.id, itemId, body.inputs, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
+        };
     }
-    upgradePreview(principal, org, installId, body) {
+    /**
+     * One more connector from a platform connector template on in the org (rulings P4-7, P4-T6-8):
+     * `{ name?, config: { slug?, endpoint?, credential?, client? } }` with the checks of an install
+     * -> 201 `{ connector, issues }` (as `POST connectors`). A template not usable in the org -> 404
+     * `component.not_found`; off there -> 409 `component.off`; input errors -> 400 at `config.*`.
+     */
+    async templateConnector(principal, org, templateId, body) {
         const p = requireUser(principal);
-        return this.catalog.upgradePreview(org.orgId, p.account.id, installId, body.version);
+        const tokenId = patTokenId(p);
+        return this.pluginInstaller.addTemplateConnector(org.orgId, p.account.id, templateId, {
+            config: body.config,
+            ...(body.name !== undefined && { name: body.name }),
+        }, tokenId !== undefined ? { actorTokenId: tokenId } : {});
     }
-    async upgrade(principal, org, installId, body, reply) {
+    async listInstalls(org) {
+        return { installs: await this.pluginInstaller.list(org.orgId) };
+    }
+    async uninstall(principal, org, installId) {
         const p = requireUser(principal);
-        const r = await this.catalog.upgrade(org.orgId, p.account.id, installId, body, patTokenId(p));
-        reply.status(r.status);
-        const { status: _status, ...rest } = r;
-        return rest;
+        const tokenId = patTokenId(p);
+        return this.catalog.uninstall(org.orgId, p.account.id, installId, tokenId);
     }
     async decide(principal, org, id, body) {
         const p = requireUser(principal);
         const tokenId = patTokenId(p);
         return {
-            request: await this.requests.decideOrg(org.orgId, p.account.id, id, body.decision, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
+            request: await this.requests.decideOrg(org.orgId, p.account.id, id, body, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
         };
     }
+    /** The requester dismisses a decided request from the inbox -> 204. */
+    async dismiss(principal, org, id) {
+        const p = requireUser(principal);
+        await this.requests.dismiss(org.orgId, p.account.id, id);
+    }
 };
 __decorate([
     Get("catalog"),
@@ -191,23 +249,64 @@ __decorate([
     __param(1, Param("itemId")),
     __param(2, Res())
 ], OrgCatalogController.prototype, "icon", null);
+__decorate([
+    Get("catalog/:itemId/guides/:guideId"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentOrg()),
+    __param(1, Param("itemId")),
+    __param(2, Param("guideId")),
+    __param(3, ZQuery(CatalogGuideQueryDto))
+], OrgCatalogController.prototype, "guide", null);
 __decorate([
     Post("catalog/:itemId/requests"),
+    HttpCode(201),
     OrgAction("catalog.request"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("itemId")),
-    __param(3, ZBody(CatalogRequestBody))
+    __param(3, ZBody(CatalogRequestBodyDto))
 ], OrgCatalogController.prototype, "request", null);
+__decorate([
+    Post("marketplace-requests"),
+    HttpCode(201),
+    OrgAction("catalog.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZBody(CatalogMarketplaceRequestBodyDto))
+], OrgCatalogController.prototype, "marketplaceRequest", null);
+__decorate([
+    Put("catalog/:itemId/switch"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("itemId")),
+    __param(3, ZBody(OrgPluginSwitchBodyDto))
+], OrgCatalogController.prototype, "setSwitch", null);
 __decorate([
     Post("catalog/:itemId/install"),
     OrgAction("catalog.read"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("itemId")),
-    __param(3, ZBody(OrgPluginInstallBody)),
+    __param(3, ZBody(OrgPluginInstallBodyDto)),
     __param(4, Res({ passthrough: true }))
 ], OrgCatalogController.prototype, "install", null);
+__decorate([
+    Post("catalog/:itemId/connectors"),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("itemId")),
+    __param(3, ZBody(OrgPluginConnectorsBody))
+], OrgCatalogController.prototype, "configureConnectors", null);
+__decorate([
+    Post("connector-templates/:templateId/connectors"),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("templateId")),
+    __param(3, ZBody(OrgTemplateConnectorBody))
+], OrgCatalogController.prototype, "templateConnector", null);
 __decorate([
     Get("plugin-installs"),
     OrgAction("org.extensions.manage"),
@@ -220,24 +319,6 @@ __decorate([
     __param(1, CurrentOrg()),
     __param(2, Param("installId"))
 ], OrgCatalogController.prototype, "uninstall", null);
-__decorate([
-    Post("plugin-installs/:installId/upgrade/preview"),
-    HttpCode(200),
-    OrgAction("catalog.read"),
-    __param(0, CurrentPrincipal()),
-    __param(1, CurrentOrg()),
-    __param(2, Param("installId")),
-    __param(3, ZBody(OrgPluginUpgradePreviewBody))
-], OrgCatalogController.prototype, "upgradePreview", null);
-__decorate([
-    Post("plugin-installs/:installId/upgrade"),
-    OrgAction("catalog.read"),
-    __param(0, CurrentPrincipal()),
-    __param(1, CurrentOrg()),
-    __param(2, Param("installId")),
-    __param(3, ZBody(OrgPluginUpgradeBody)),
-    __param(4, Res({ passthrough: true }))
-], OrgCatalogController.prototype, "upgrade", null);
 __decorate([
     Post("catalog-requests/:id/decide"),
     HttpCode(200),
@@ -247,14 +328,28 @@ __decorate([
     __param(2, Param("id")),
     __param(3, ZBody(CatalogDecideBody))
 ], OrgCatalogController.prototype, "decide", null);
+__decorate([
+    Post("catalog-requests/:id/dismiss"),
+    HttpCode(204),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], OrgCatalogController.prototype, "dismiss", null);
 OrgCatalogController = __decorate([
     Controller("api/v1/orgs/:orgId"),
     __param(0, Inject(OrgCatalogService)),
     __param(1, Inject(CatalogRequestsService)),
-    __param(2, Inject(PluginInstaller))
+    __param(2, Inject(PluginInstaller)),
+    __param(3, Inject(PluginIcons)),
+    __param(4, Inject(PluginGuides))
 ], OrgCatalogController);
 export { OrgCatalogController };
-/** Enterprise admins decide deployment-level catalog requests (`/api/v1/admin/catalog/requests`). */
+/**
+ * Super admins decide `access` and `import` requests (`/api/v1/admin/catalog/requests`):
+ * approving an `import` returns the prepared import (`import: { stagingId, review, ... }`), confirmed
+ * with `POST /api/v1/admin/catalog/imports/:stagingId/confirm`.
+ */
 let AdminCatalogRequestsController = class AdminCatalogRequestsController {
     requests;
     constructor(requests) {
@@ -268,9 +363,7 @@ let AdminCatalogRequestsController = class AdminCatalogRequestsController {
     async decide(principal, id, body) {
         const p = requireUser(principal);
         const tokenId = patTokenId(p);
-        return {
-            request: await this.requests.decideDeployment(p.account.id, id, body.decision, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
-        };
+        return this.requests.decideDeployment(p.account.id, id, body, tokenId !== undefined ? { actorTokenId: tokenId } : {});
     }
 };
 __decorate([
@@ -286,7 +379,7 @@ __decorate([
 ], AdminCatalogRequestsController.prototype, "decide", null);
 AdminCatalogRequestsController = __decorate([
     Controller("api/v1/admin/catalog/requests"),
-    EnterpriseAdmin(),
+    SuperAdmin(),
     __param(0, Inject(CatalogRequestsService))
 ], AdminCatalogRequestsController);
 export { AdminCatalogRequestsController };

package/dist/catalog/org-catalog.schemas.d.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const CatalogRequestBody: z.ZodObject<{
+    kind: z.ZodEnum<{
+        access: "access";
+        enable: "enable";
+    }>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** An org admin's request for a marketplace entry not in the catalog yet. */
+export declare const CatalogMarketplaceRequestBody: z.ZodObject<{
+    marketplaceId: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const CatalogConnectorInput: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    client: z.ZodOptional<z.ZodObject<{
+        clientId: z.ZodString;
+        clientSecret: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * The org install body: template input, the extension's org config. No version: an org installs the
+ * platform version (one per deployment, ruling P2-17).
+ */
+export declare const OrgPluginInstallBody: z.ZodObject<{
+    connectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        client: z.ZodOptional<z.ZodObject<{
+            clientId: z.ZodString;
+            clientSecret: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    extensionConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/** The switch body: on (with the install inputs), or off (with the preview's hash to confirm). */
+export declare const OrgPluginSwitchBody: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    inputs: z.ZodOptional<z.ZodObject<{
+        connectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            slug: z.ZodOptional<z.ZodString>;
+            endpoint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            client: z.ZodOptional<z.ZodObject<{
+                clientId: z.ZodString;
+                clientSecret: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+        extensionConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+    confirm: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** `:itemId` as the routes take it (`@Param`). */
+export declare const CatalogItemPathParams: z.ZodObject<{
+    itemId: z.ZodString;
+}, z.core.$strip>;
+/** `:itemId` / `:guideId` of the guide route (`@Param`). */
+export declare const CatalogGuidePathParams: z.ZodObject<{
+    itemId: z.ZodString;
+    guideId: z.ZodString;
+}, z.core.$strip>;
+/** `:installId` as the uninstall route takes it (`@Param`). */
+export declare const PluginInstallPathParams: z.ZodObject<{
+    installId: z.ZodString;
+}, z.core.$strip>;
+/** The super admin's request list filter. */
+export declare const CatalogRequestsListQuery: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        approved: "approved";
+        cancelled: "cancelled";
+        pending: "pending";
+        rejected: "rejected";
+    }>>;
+}, z.core.$strip>;
+/**
+ * `GET catalog/:itemId/guides/:guideId` (spec 2026-11-09-setup-guides-v2-design.md §7.2): the mode
+ * and audience to render (the place's, checked by the service), the document language, and the
+ * target: a channel connection or the name typed so far on 新建渠道 (`channel-connection`), a
+ * connector made from the template (`connector-template`).
+ */
+export declare const CatalogGuideQuery: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodString>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+    connectionId: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    connectorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const ORG_CATALOG_ROUTES: readonly RouteSchemas[];

package/dist/catalog/org-catalog.schemas.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { CredentialValue } from "../tools/connectors.schemas.js";
+export const CatalogRequestBody = z
+    .object({
+    kind: z.enum(["access", "enable"]),
+    note: z.string().max(1000).optional(),
+})
+    .strict();
+/** An org admin's request for a marketplace entry not in the catalog yet. */
+export const CatalogMarketplaceRequestBody = z
+    .object({
+    marketplaceId: z.string().min(1).max(100),
+    name: z.string().min(1).max(214),
+    version: z.string().min(1).max(256),
+    note: z.string().max(1000).optional(),
+})
+    .strict();
+export const CatalogConnectorInput = z
+    .object({
+    name: z.string().trim().min(1).max(80).optional(),
+    slug: z.string().max(24).optional(),
+    endpoint: z.record(z.string(), z.unknown()).optional(),
+    credential: CredentialValue.optional(),
+    client: z
+        .object({
+        clientId: z.string().min(1).max(500),
+        clientSecret: z.string().min(1).max(4000).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+/**
+ * The org install body: template input, the extension's org config. No version: an org installs the
+ * platform version (one per deployment, ruling P2-17).
+ */
+export const OrgPluginInstallBody = z
+    .object({
+    connectors: z.record(z.string(), CatalogConnectorInput).optional(),
+    extensionConfig: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+/** The switch body: on (with the install inputs), or off (with the preview's hash to confirm). */
+export const OrgPluginSwitchBody = z
+    .object({
+    enabled: z.boolean(),
+    inputs: OrgPluginInstallBody.optional(),
+    confirm: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
+})
+    .strict();
+/** `:itemId` as the routes take it (`@Param`). */
+export const CatalogItemPathParams = z.object({ itemId: z.string().min(1) });
+/** `:itemId` / `:guideId` of the guide route (`@Param`). */
+export const CatalogGuidePathParams = CatalogItemPathParams.extend({
+    guideId: z.string().min(1).max(64),
+});
+/** `:installId` as the uninstall route takes it (`@Param`). */
+export const PluginInstallPathParams = z.object({ installId: z.string().min(1) });
+/** The super admin's request list filter. */
+export const CatalogRequestsListQuery = z.object({
+    status: z.enum(["pending", "approved", "rejected", "cancelled"]).optional(),
+});
+/**
+ * `GET catalog/:itemId/guides/:guideId` (spec 2026-11-09-setup-guides-v2-design.md §7.2): the mode
+ * and audience to render (the place's, checked by the service), the document language, and the
+ * target: a channel connection or the name typed so far on 新建渠道 (`channel-connection`), a
+ * connector made from the template (`connector-template`).
+ */
+export const CatalogGuideQuery = z
+    .object({
+    mode: z.string().min(1).max(64).optional(),
+    audience: z.enum(["admin", "member"]).optional(),
+    locale: z.enum(["en", "zh"]).optional(),
+    connectionId: z.string().min(1).max(100).optional(),
+    name: z.string().max(100).optional(),
+    connectorId: z.string().min(1).max(100).optional(),
+})
+    .strict();
+export const ORG_CATALOG_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/catalog" },
+    { route: "GET /api/v1/orgs/:orgId/catalog/:itemId", params: CatalogItemPathParams },
+    {
+        route: "GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId",
+        params: CatalogGuidePathParams,
+        query: CatalogGuideQuery,
+    },
+    {
+        route: "POST /api/v1/orgs/:orgId/catalog/:itemId/requests",
+        params: CatalogItemPathParams,
+        body: CatalogRequestBody,
+    },
+    { route: "POST /api/v1/orgs/:orgId/marketplace-requests", body: CatalogMarketplaceRequestBody },
+    {
+        route: "PUT /api/v1/orgs/:orgId/catalog/:itemId/switch",
+        params: CatalogItemPathParams,
+        body: OrgPluginSwitchBody,
+    },
+    { route: "GET /api/v1/orgs/:orgId/plugin-installs" },
+    {
+        route: "DELETE /api/v1/orgs/:orgId/plugin-installs/:installId",
+        params: PluginInstallPathParams,
+    },
+    { route: "GET /api/v1/admin/catalog/requests", query: CatalogRequestsListQuery },
+];