@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/catalog/requests.service.d.ts

@@ -1,162 +1,250 @@
 import type { LocalizedName } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import { ApiError } from "../errors.js";
-type Trx = Transaction<KernelDatabase>;
-export type CatalogRequestStage = "org" | "deployment";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { CatalogService, type MarketplaceImportResult } from "./catalog.service.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
+import { OrgCatalogService } from "./org-catalog.service.js";
+import { PluginImport } from "./plugin-import.js";
+import type { RequestActorOpts } from "./request-rules.js";
+export type CatalogRequestKind = "access" | "import" | "enable" | "connector_setup";
 export type CatalogRequestStatus = "pending" | "approved" | "rejected" | "cancelled";
-export type CatalogDecision = "approve" | "reject";
-/** A catalog request (the inbox's `catalog_request`, the enterprise admin request list). */
+/** A pending connector a `connector_setup` request waits for (ruling P4-T6-5). */
+export interface SetupRequestConnector {
+    /** The agent's `pendingConnectors[].key` (the bind route's `:key`). */
+    key: string;
+    label: string;
+    /** `template`: made from a platform connector template; `needs`: a hand-configured one. */
+    kind: "template" | "needs";
+    /**
+     * What configures it, so an org admin acts from the request without opening the agent (fix
+     * round 1): `template.id` is the platform connector template's id (pick an org connector made
+     * from it, or `POST connector-templates/:id/connectors`), `displayName` its display name (null
+     * once the template row is gone); `needs` the protocol (the connector kind to pick), the endpoint
+     * and the tools of the hand-configured connector the template recorded.
+     */
+    source: {
+        template: {
+            id: string;
+            displayName: LocalizedName | null;
+        };
+    } | {
+        needs: {
+            protocol: "mcp" | "openapi";
+            endpoint: string;
+            tools: string[];
+        };
+    };
+    /** The tool names the agent takes once bound; null = all of the connector's tools. */
+    tools: string[] | null;
+    /** The tool names the entry tightens a policy for (names only, sorted). */
+    policies: string[];
+}
+/**
+ * A catalog request (spec §5.1): the inbox's `catalog_request` (pending `enable` and
+ * `connector_setup` requests, for the org admins) and `catalog_request_decided` (the requester's
+ * decided requests), and the super admin's list (`access` and `import`). `item` is null for an
+ * `import` request until its confirm writes the item, and always for `connector_setup`; `entry` is
+ * the marketplace entry of an `import` request. A `connector_setup` request (ruling P4-7) names its
+ * agent (`agent`) and what it still waits for (`connectors`); both are null for other kinds.
+ */
 export interface CatalogRequestView {
     id: string;
     orgId: string;
     orgName: string;
+    kind: CatalogRequestKind;
     item: {
         id: string;
         name: string;
         displayName: LocalizedName | null;
-    };
-    version: string | null;
-    stage: CatalogRequestStage;
+    } | null;
+    entry: {
+        marketplaceId: string | null;
+        name: string;
+        version: string | null;
+    } | null;
+    /**
+     * The agent of a `connector_setup` request: its current name, `deleted` once soft-deleted (the
+     * request is then cancelled). Null for other kinds.
+     */
+    agent: {
+        id: string;
+        name: string;
+        deleted: boolean;
+    } | null;
+    /**
+     * The pending connectors a `connector_setup` request waits for, with their labels from the
+     * agent's current version (keys it no longer has are left out; empty once closed). Null for
+     * other kinds.
+     */
+    connectors: SetupRequestConnector[] | null;
     status: CatalogRequestStatus;
     note: string;
+    /** The optional reason of a rejection. */
+    reason: string | null;
     requestedBy: string | null;
     /** 申请人的显示名（账号已删除为 null）。 */
     requestedByName: string | null;
     decidedBy: string | null;
     decidedAt: string | null;
-    /** 组织管理员批准并升级到企业管理员时的批准人与时间（没有升级为 null）。 */
-    orgDecidedBy: string | null;
-    orgDecidedAt: string | null;
+    /** The prepared import of an approved `import` request that is not confirmed yet. */
+    stagingId: string | null;
     createdAt: string;
 }
+/** A decision: approve, or reject with an optional reason the requester sees. */
+export interface CatalogDecision {
+    approve: boolean;
+    reason?: string | undefined;
+}
 /** 申请列表一次最多返回的条数。 */
 export declare const CATALOG_REQUESTS_LIST_MAX = 200;
 /**
- * Before an org creates a component from the catalog (enabling an extension, creating a connector
- * from a template, importing a skill), re-checks the item policy in the caller's transaction (C22):
- * deleted or disabled -> `catalog.item_disabled`; needs_approval without an enterprise admin grant
- * for this org -> `catalog.approval_required`; allow or granted -> passes. A dependency's
- * components pass `approvedBy`, the item the org is installing (spec §10: approval follows the
- * installed plugin only): the dependency's own item must still be live and not disabled, and the
- * approval is judged by `approvedBy`.
- */
-export declare function assertItemInstallable(t: Trx, orgId: string, itemId: string, approvedBy?: string): Promise<void>;
-/**
- * The extensions among `plugins` whose own catalog item (the non-deleted item with the same name) is
- * disabled (FOR SHARE: exclusive with policy changes). A disabled item is a master switch: no path
- * (direct enabling, its item, another plugin) can newly enable its extension (Ruling M-5).
- */
-export declare function disabledPluginItems(db: KernelDb | Trx, plugins: readonly string[]): Promise<string[]>;
-/**
- * Throws `catalog.item_disabled` when a plugin's own catalog item is disabled (the message names
- * the plugin).
- */
-export declare function pluginItemDisabled(names: readonly string[]): ApiError;
-/**
- * When an org enables an extension directly (not by installing from an item, e.g.
- * `PUT /orgs/:orgId/extensions/:extension`), it is judged by every catalog item that brought it into the
- * deployment (`extension_catalog_sources`), and **the strictest wins**: any source disabled ->
- * `catalog.item_disabled`; otherwise any source needs_approval without a grant of that item to the
- * org -> `catalog.approval_required`; all allow / granted -> passes. Deleted items no longer count
- * as sources (an enterprise admin deleting an item withdraws its constraint). No source (not
- * installed through the catalog) -> not bound by catalog policy.
- */
-export declare function assertPluginSourcesInstallable(t: Trx, orgId: string, plugin: string): Promise<void>;
-/** 审计里带上 PAT（个人令牌发起时）。 */
-export interface RequestActorOpts {
-    actorTokenId?: string;
-}
-/**
- * Cancels catalog requests still pending in the caller's transaction (when the item or the org is
- * deleted), status `cancelled` (the decider is the actor). Each one audits
- * `catalog.request_cancelled` (with the reason). Returns how many were cancelled.
- */
-export declare function cancelPendingRequests(t: Trx, where: {
-    itemId: string;
-} | {
-    orgId: string;
-}, actor: string, reason: "item_removed" | "org_deleted", opts?: RequestActorOpts): Promise<number>;
-/**
- * Catalog requests and approvals (C22 / F-AF). Two levels:
- * - a member request (stage `org`) goes to the org admins' inbox, an org admin (`catalog.decide`)
- *   approves or rejects it; when the item is needs_approval without a grant for this org, approving
- *   moves the request to stage `deployment` (still pending) for the enterprise admins to decide;
- * - an org admin installing a needs_approval item without a grant -> creates a stage `deployment`
- *   request (or moves the existing pending one there);
- * - an enterprise admin approving a stage `deployment` request -> writes a grant
- *   (`catalog_org_grants`, valid across versions), after which org admins can install.
- * One pending request per org and item (partial unique index; org-side writes all run inside the
- * org row lock, in order). No in-process state.
+ * Catalog requests under plugin scope (spec §5.1). Three kinds, one pending request per (org,
+ * kind, item or entry) (partial unique indexes; org-side writes run inside the org row lock):
+ * - `enable`: a member asks the org admins to switch on an item that is off in the org (an
+ *   `optional` item); an org admin approving it switches the item on, as that admin;
+ * - `access`: an org admin asks the super admin for a `named` item shown to orgs outside its
+ *   list; approving adds the org to the list (`CatalogScopeService.addOrg`), the scope sync then
+ *   installs it;
+ * - `import`: an org admin asks for a marketplace entry not in the catalog (deployment setting
+ *   `orgMarketplaceBrowse`); approving prepares the import and returns its staging, the request
+ *   resolves when the super admin confirms it (scope default `named` = the requesting org);
+ * - `connector_setup` (ruling P4-7): one per agent (`agent_id`, `pending_keys`), asking the org
+ *   admins to set up an agent's pending connectors; written by the agents module
+ *   (`PendingConnectorRequests`), closed by binding (`approved`) or the agent's deletion
+ *   (`cancelled`); here it is listed and rejected.
+ * A rejection stores an optional reason. Decided requests show in the requester's inbox until
+ * dismissed. No in-process state.
  */
 export declare class CatalogRequestsService {
-    private readonly db;
-    constructor(db: KernelDb);
+    private readonly kdb;
+    /** The org row and super admin locks: both join the caller's transaction. */
+    private readonly orgLock;
+    private readonly adminLock;
+    private readonly orgCatalog;
+    private readonly scope;
+    private readonly catalog;
+    private readonly config;
+    private readonly pluginImport;
+    readonly txHost: TransactionHost;
+    /** Serializes the approvals of one `import` request (`@WithLock`). */
+    readonly lockService: LockService;
+    constructor(kdb: KernelDb, 
+    /** The org row and super admin locks: both join the caller's transaction. */
+    orgLock: OrgLock, adminLock: SuperAdminLock, orgCatalog: OrgCatalogService, scope: CatalogScopeService, catalog: CatalogService, config: KernelConfigService, pluginImport: PluginImport, txHost: TransactionHost, 
+    /** Serializes the approvals of one `import` request (`@WithLock`). */
+    lockService: LockService);
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    private get db();
     /**
-     * A member request (`catalog.request`, re-checked inside the org row lock). Item missing /
-     * deleted -> `catalog.item_not_found`; disabled -> org admins get `catalog.item_disabled`,
-     * members get `catalog.item_not_found` (members do not see disabled items). An existing pending
-     * request is returned as is (`created: false`), no new one. Audits `catalog.requested`.
+     * A request for a catalog item (`POST /orgs/:orgId/catalog/:itemId/requests`): `enable`
+     * (`catalog.request`, members and up) or `access` (`catalog.decide`, org admins), checked first.
+     * The item as the org sees it: absent (missing, deleted, hidden, disabled for a member) ->
+     * `catalog.item_not_found`; disabled -> `catalog.item_disabled` for an org admin; its extension
+     * unable to run on the platform -> `catalog.request_invalid`; `access` needs
+     * `not_offered`, `enable` needs `off` (else `catalog.request_invalid`); a pending request of the
+     * kind -> `catalog.request_pending`. Audits `catalog.requested`.
      */
-    request(orgId: string, actor: string, itemId: string, input: {
+    requestItem(orgId: string, actor: string, itemId: string, input: {
+        kind: "access" | "enable";
         note?: string | undefined;
-        version?: string | undefined;
-    }, opts?: RequestActorOpts): Promise<{
-        request: CatalogRequestView;
-        created: boolean;
-    }>;
-    private pendingRow;
+    }, opts?: RequestActorOpts): Promise<CatalogRequestView>;
+    /** The role check alone, before any item error (a member cannot probe items by error codes). */
+    private authorize;
+    private writeItemRequest;
     /**
-     * An org admin installing a needs_approval item without a grant: in the caller's transaction (the
-     * caller has locked the org row and re-checked the role) creates a stage `deployment` request; an
-     * existing pending request is moved to deployment (a member request goes to the enterprise admins
-     * with it). Returns the request id. Audits `catalog.requested`.
+     * An org admin asks for a marketplace entry to be imported (`POST /orgs/:orgId/
+     * marketplace-requests`, `catalog.decide`). The deployment setting `orgMarketplaceBrowse` off ->
+     * `catalog.marketplace_browse_disabled`; the marketplace or the entry / version missing ->
+     * `marketplace.not_found` / `marketplace.entry_not_found`; a deprecated version ->
+     * `marketplace.entry_deprecated`; a live item of that name ->
+     * `catalog.request_invalid` (ask for access instead) when the org can see or request that item
+     * (a hidden one is not revealed: the request is accepted); a pending request for the entry ->
+     * `catalog.request_pending`. Audits `catalog.requested`.
      */
-    requestDeployment(t: Trx, orgId: string, actor: string, item: {
-        id: string;
+    requestImport(orgId: string, actor: string, input: {
+        marketplaceId: string;
         name: string;
-    }, version: string | null, opts?: RequestActorOpts): Promise<string>;
+        version: string;
+        note?: string | undefined;
+    }, opts?: RequestActorOpts): Promise<CatalogRequestView>;
+    private writeImportRequest;
     /**
-     * 安装成功后：本组织该条目仍 pending 的申请（成员申请 stage org，以及之前因 needs_approval 建的 stage deployment
-     * 申请——条目之后改成 allow 再装的就不会一直挂着）标为 approved（安装者即决定人），收件箱与企业管理员列表随之清空。
-     * 在调用方事务里执行。
+     * An org admin decides a member's `enable` or `connector_setup` request (`catalog.decide`). Not
+     * this org's request of those kinds -> `catalog.request_not_found`; decided ->
+     * `catalog.request_decided`. Approving an `enable` request switches the item on in the org as the
+     * deciding admin ({@link OrgCatalogService.setSwitch}: its errors, e.g. inputs the install
+     * needs, leave the request pending); the install itself resolves the request. A
+     * `connector_setup` request is approved only by binding its connectors (ruling P4-T6-6):
+     * approving it -> `catalog.request_invalid`. Rejecting stores the reason. Audits
+     * `catalog.request_decided`.
      */
-    resolveByInstall(t: Trx, orgId: string, itemId: string, actor: string, opts?: RequestActorOpts): Promise<void>;
+    decideOrg(orgId: string, actor: string, requestId: string, decision: CatalogDecision, opts?: RequestActorOpts): Promise<CatalogRequestView>;
+    /** The item of a pending `enable` request of the org (the decider re-checked). */
+    private pendingOrgRequest;
     /**
-     * An org admin decides a member request (`catalog.decide`, re-checked inside the org row lock;
-     * the request row FOR UPDATE). Not this org's request -> `catalog.request_not_found`; already
-     * decided or handed to the enterprise admins -> `catalog.request_decided`. On approval: item
-     * deleted or disabled -> `catalog.item_disabled`; needs_approval without a grant -> moved to stage
-     * deployment (still pending); otherwise approved. Audits `catalog.request_decided`.
+     * A super admin decides an `access` or `import` request (re-checked inside the super
+     * admin lock; the request row FOR UPDATE). Missing or an `enable` request ->
+     * `catalog.request_not_found`; decided -> `catalog.request_decided`. Approving `access`: the item
+     * deleted or disabled -> `catalog.item_disabled`, the org deleted -> not found; otherwise the org
+     * joins the item's `named` list. Approving `import` prepares the import of the entry and returns
+     * it; the request stays pending, linked to the staging, until that confirm commits (approving
+     * again prepares a new one). Audits `catalog.request_decided` (`catalog.request_import_prepared`
+     * for an import's approval).
      */
-    decideOrg(orgId: string, actor: string, requestId: string, decision: CatalogDecision, opts?: RequestActorOpts): Promise<CatalogRequestView>;
+    decideDeployment(actor: string, requestId: string, decision: CatalogDecision, opts?: RequestActorOpts): Promise<{
+        request: CatalogRequestView;
+        import?: MarketplaceImportResult;
+    }>;
+    /**
+     * Approves an `import` request, one approval of a request at a time (across replicas): an item
+     * of the entry's name that holds the requested version already (one hidden from the org, which
+     * is why the request was accepted) -> the org joins its `named` list at once, nothing imported;
+     * a staging linked by an earlier approval and not expired -> that staging again; otherwise the
+     * import is prepared and linked. The confirm of a staging adds the org to an item that exists by
+     * then (`PluginImport.commit`).
+     */
+    private approveImport;
+    /** A pending `access` / `import` request (the row locked; the super admin re-checked). */
+    private pendingDeploymentRequest;
+    /** Links a still pending `import` request to its prepared staging. */
+    private linkStaging;
     /**
-     * An enterprise admin decides a stage deployment request (re-checked inside the enterprise admin
-     * lock; the request row FOR UPDATE). Missing or still at the org stage ->
-     * `catalog.request_not_found`; already decided -> `catalog.request_decided`; on approval, item
-     * deleted or disabled -> `catalog.item_disabled`, the request's org deleted ->
-     * `catalog.request_not_found`. Approval writes a grant to `catalog_org_grants`. Audits
-     * `catalog.request_decided` (with orgId).
+     * Writes a decision (the request row FOR UPDATE): org side (`orgId`: the org admin re-checked,
+     * `enable` only) or deployment side (the super admin re-checked, `access` / `import`). An
+     * approval of an `enable` request may find it approved already by the install it triggered.
      */
-    decideDeployment(actor: string, requestId: string, decision: CatalogDecision, opts?: RequestActorOpts): Promise<CatalogRequestView>;
-    /** 企业管理员的申请列表（stage deployment；`status` 缺省 pending），新的在前。 */
+    private writeDecision;
+    /**
+     * The requester dismisses a decided request from the inbox (`POST /orgs/:orgId/
+     * catalog-requests/:id/dismiss`). Not the requester's decided request in this org ->
+     * `catalog.request_not_found`.
+     */
+    dismiss(orgId: string, accountId: string, requestId: string): Promise<void>;
+    /** 超级管理员的申请列表（`access` / `import`；`status` 缺省 pending），新的在前。 */
     listDeployment(q?: {
         status?: CatalogRequestStatus;
     }): Promise<CatalogRequestView[]>;
-    /** 待企业管理员处理的申请数（后台概览）。 */
+    /** 待超级管理员处理的申请数（后台概览）。 */
     countPendingDeployment(): Promise<number>;
     /**
-     * 收件箱：当前用户是本组织管理员（实时读角色）时，返回待他处理的成员申请（stage org、pending），新的在前；
-     * 否则为空。
+     * The inbox: when the account is an org admin of the org (the role read live), the members'
+     * pending `enable` requests and the pending `connector_setup` requests, newest first; otherwise
+     * none.
      */
     listForOrgAdmin(orgId: string, accountId: string): Promise<CatalogRequestView[]>;
-    /** 本组织各条目最新的一条申请（组织目录列表用）。 */
-    latestByItem(orgId: string): Promise<Map<string, {
-        id: string;
-        stage: CatalogRequestStage;
-        status: string;
-    }>>;
-    view(db: KernelDb | Trx, id: string): Promise<CatalogRequestView>;
+    /** The inbox: the account's decided requests in the org it has not dismissed, newest first. */
+    listDecidedForRequester(orgId: string, accountId: string): Promise<CatalogRequestView[]>;
+    /**
+     * The account's own requests in the org, pending and decided (dismissed ones too), newest first;
+     * cancelled ones are left out (the Platform tool's `requests.list-mine`).
+     */
+    listForRequester(orgId: string, accountId: string): Promise<CatalogRequestView[]>;
+    view(id: string): Promise<CatalogRequestView>;
+    /** The views of `rows`, with the display names of the connector templates setup requests name. */
+    private toViews;
     private baseQuery;
 }
-export {};