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

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

@@ -1,22 +1,31 @@
 import { ExtensionRegistry } from "../extensions/registry.js";
+import { ExtensionAvailability } from "../extensions/unavailable.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { StorageService } from "../storage/storage.service.js";
-import { type CatalogIcon, type OrgCatalogDetail, type OrgCatalogItem, type OrgInstallInput, type OrgInstallResult, type OrgUpgradeResult } from "./catalog-content.js";
-import { PluginInstaller } from "./plugin-install.js";
-import { type PluginUpgradeInput, PluginUpgrader, type UpgradePreview } from "./plugin-upgrade.js";
-import { CatalogRequestsService } from "./requests.service.js";
+import { type CatalogIcon, type OrgCatalogDetail, type OrgCatalogItem, type OrgInstallInput, type OrgInstallResult } from "./catalog-content.js";
+import { PluginInstaller, type UninstallPreview, type UninstallReport } from "./plugin-install.js";
+/** The result of a switch: the item, or (switching off without `confirm`) the uninstall preview. */
+export type SwitchResult = {
+    kind: "done";
+    item: OrgCatalogItem;
+} | {
+    kind: "preview";
+    preview: UninstallPreview;
+    confirm: string;
+};
 /**
- * Organizations browse and install from the enterprise catalog (C22): members browse (without
- * disabled items) and request, org admins install. Every item is a plugin, installed with its
- * dependencies by {@link PluginInstaller}; installing requires the union of the component actions
- * of the plugins it brings in ({@link requiredActions}), re-checked inside the org row lock; item
- * disabled -> `catalog.item_disabled`; a dependency unresolved / disabled / in a cycle ->
- * `catalog.dependency_*`; an extension or a template's connector not on the deployment ->
- * `catalog.not_deployed`; needs_approval without a grant -> a stage deployment request (HTTP 202;
- * dependencies are not approved separately, spec §10). No in-process state.
+ * Organizations see the platform catalog with the plugin scope rules applied (plugin and component
+ * management spec §5): a plugin is `all` (on in every org unless an org admin switched it off,
+ * layering spec §4), `optional` (an org admin switches it on), or `named` (offered to the listed
+ * orgs). Members get the list read-only; org admins switch a plugin on (an install by
+ * {@link PluginInstaller}, with its dependencies; the union of the component actions of the plugins
+ * it brings in is re-checked inside the org row lock) or off (an uninstall, after a preview they
+ * confirm with its hash). Disabled item -> `plugin.disabled`; a
+ * dependency unresolved / disabled / in a cycle -> `catalog.dependency_*`; an extension or a
+ * template's connector not on the deployment -> `catalog.not_deployed`. No in-process state.
  */
 export declare class OrgCatalogService {
     private readonly kdb;
@@ -24,17 +33,23 @@ export declare class OrgCatalogService {
     private readonly orgLock;
     private readonly storage;
     private readonly registry;
-    private readonly requests;
     private readonly pluginInstaller;
-    private readonly pluginUpgrader;
     private readonly log;
     readonly txHost: TransactionHost;
+    /** Why a plugin's extension cannot run (the `unavailable` state's reason). */
+    private readonly availability;
     constructor(kdb: KernelDb, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock: OrgLock, storage: StorageService, registry: ExtensionRegistry, requests: CatalogRequestsService, pluginInstaller: PluginInstaller, pluginUpgrader: PluginUpgrader, log: KernelLogger, txHost: TransactionHost);
+    orgLock: OrgLock, storage: StorageService, registry: ExtensionRegistry, pluginInstaller: PluginInstaller, log: KernelLogger, txHost: TransactionHost, 
+    /** Why a plugin's extension cannot run (the `unavailable` state's reason). */
+    availability: ExtensionAvailability);
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
     private get db();
-    /** The org's view of the items; members (not admins) don't see disabled items. */
+    /**
+     * The org's view of the items: a `named` item without the org on its list is `not_offered` when
+     * shown to other orgs and absent otherwise; disabled ones are shown to admins as `unavailable`
+     * and absent for members. Each item carries the org's pending request for it.
+     */
     list(orgId: string, accountId: string, itemId?: string): Promise<OrgCatalogItem[]>;
     /**
      * Item detail (for the install wizard): the same view as the list (members don't see disabled
@@ -44,10 +59,11 @@ export declare class OrgCatalogService {
      */
     detail(orgId: string, accountId: string, itemId: string): Promise<OrgCatalogDetail>;
     /**
-     * The item's icon; members don't see disabled items (-> `catalog.item_not_found`, decided before
-     * reading storage).
+     * The item's icon; members don't see disabled items, nobody outside its list sees a hidden
+     * `named` item (-> `catalog.item_not_found`, decided before reading storage). Without `orgId`
+     * (the super admin) every item.
      */
-    icon(itemId: string, isAdmin: boolean): Promise<CatalogIcon>;
+    icon(itemId: string, isAdmin: boolean, orgId?: string): Promise<CatalogIcon>;
     /** For the admin item detail: whether the latest version has an icon. */
     hasIcon(itemId: string): Promise<boolean>;
     /**
@@ -57,24 +73,47 @@ export declare class OrgCatalogService {
      * deployed here (the install reads it again).
      */
     private undeployed;
-    /** Installs a plugin in the org (see the class comment). */
-    install(orgId: string, actor: string, itemId: string, body: OrgInstallInput, actorTokenId?: string): Promise<OrgInstallResult>;
     /**
-     * Role and policy under the org row lock; needs_approval without a grant -> a stage deployment
-     * request (its id). Approval follows this plugin's policy only, not its dependencies' (spec §10).
+     * Installs a plugin in the org (the old install route, an alias of switching it on): the role
+     * first, then item errors (a member cannot probe a disabled item through error codes), then the
+     * installer. Records the org's switch as on.
+     */
+    install(orgId: string, actor: string, itemId: string, body: OrgInstallInput, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<OrgInstallResult>;
+    /** The item when the org may see it (scope), else `catalog.item_not_found`. */
+    private visibleItem;
+    /** The org's live plugin install of the item, if any. */
+    private liveInstall;
+    /**
+     * The org admin's switch of a plugin (`PUT catalog/:itemId/switch`). On: installs it (or just
+     * records the switch when it is installed already). Off: refused for builtin items
+     * (`plugin.scope_locked`; an `all` one may go off, layering spec §4); without `confirm` returns
+     * the uninstall preview and its hash, with the hash of the current preview uninstalls (a changed
+     * preview -> `plugin.switch_stale`). The switch row is written after the install / uninstall.
+     */
+    setSwitch(orgId: string, actor: string, itemId: string, body: {
+        enabled: true;
+        inputs?: OrgInstallInput;
+    } | {
+        enabled: false;
+        confirm?: string;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<SwitchResult>;
+    /**
+     * `DELETE plugin-installs/:installId` of a catalog plugin follows the switch-off semantics: builtin
+     * items are refused (`plugin.scope_locked`) unless the install is not live (failed, or
+     * `installing`: the installer cleans up a stale one and refuses a fresh one). Removing a live
+     * install writes the switch row false in the uninstall's transaction (an `all` item then stays
+     * off in the org); removing a failed or stale one writes none.
      */
-    private requestIfNeeded;
-    /** The upgrade preview of an org install (spec §10, see `PluginUpgrader`). */
-    upgradePreview(orgId: string, actor: string, installId: string, version: string): Promise<UpgradePreview>;
+    uninstall(orgId: string, actor: string, installId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<UninstallReport>;
+    private itemOf;
     /**
-     * Upgrades an org install in place (spec §10, Decision 11): the preview's `diffHash` is checked
-     * first (`plugin.upgrade_stale`); the item disabled -> `catalog.item_disabled`; needs_approval
-     * without a grant -> a stage deployment request for the target version (202; after approval the
-     * org admin runs the upgrade again); otherwise the upgrade runs (200, the install view).
+     * Writes the org's switch row of the item under the org row lock. The item row is locked FOR
+     * SHARE first (exclusive with a scope change, an unshare, ruling P3-25, and an owner's delete or
+     * transfer); switching on re-checks that the org may still see it; the install path re-checks the same in `assertItemInstallable`.
      */
-    upgrade(orgId: string, actor: string, installId: string, body: PluginUpgradeInput, actorTokenId?: string): Promise<OrgUpgradeResult>;
-    /** Like {@link requestIfNeeded}, for an upgrade's target version. */
-    private upgradeRequestIfNeeded;
+    private recordSwitch;
     /** The actor can install something in the org (forbidden otherwise), checked before item errors. */
     private assertCanInstall;
 }