@jwilleke/ngdpbase-types 5.37.0 → 5.38.0

package/lib/packages/ngdpbase-types/index.d.ts

@@ -15,6 +15,7 @@
  * only, so the published entry carries no JavaScript.
  */
 export type { AddonModule, AddonManifest, AddonListing } from '../../src/managers/AddonsManager.js';
+export type { AddonDashboardCard, AddonCardSurface, AddonCardSummary, AddonCardFigure } from '../../src/managers/AddonsManager.js';
 export type { AddonHost, AddonIceDeclaration, PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export type { WikiEngine } from '../../src/types/WikiEngine.js';
 export type { ApiContext } from '../../src/context/ApiContext.js';

package/lib/src/managers/AddonsManager.d.ts

@@ -289,9 +289,27 @@ export interface AddonStatusDetails {
     message?: string;
     [key: string]: unknown;
 }
+/** The pages an add-on's card can be shown on: `/admin` (the default) and the Executive Hub, `/executive` (#2093). */
+export type AddonCardSurface = 'admin' | 'executive';
+/** One labelled figure on an Executive Hub card (`Funds`, `$12,400.00`). The add-on formats the value. */
+export interface AddonCardFigure {
+    label: string;
+    value: string | number;
+}
+/** What an Executive Hub card shows a viewer: its figures, and an optional line under them. */
+export interface AddonCardSummary {
+    figures?: AddonCardFigure[];
+    message?: string;
+}
 /**
- * Card registered by an add-on for display on the admin dashboard.
- * The card's live stats are sourced from the add-on's existing status() method.
+ * Card registered by an add-on for display on the admin dashboard, or, with
+ * `surface: 'executive'`, on the Executive Hub (#2093). An add-on registers
+ * at most one card per surface.
+ *
+ * An admin card's live stats come from the add-on's existing status() method.
+ * An executive card names the `permission` a viewer must hold to see it, and
+ * its figures come from `summary(ctx)`, called with the viewer's context, so
+ * the add-on's own doors decide what it reads.
  */
 export interface AddonDashboardCard {
     /** Must match the add-on's registered name */
@@ -300,8 +318,25 @@ export interface AddonDashboardCard {
     title: string;
     /** Font Awesome class, e.g. 'fas fa-wpforms' */
     icon: string;
-    /** URL of the add-on's admin page */
+    /** The page the card links to: the add-on's admin page, or for an executive card the page with the detail */
     adminUrl: string;
+    /** Where the card is shown; omitted means `/admin` */
+    surface?: AddonCardSurface;
+    /** Executive cards: the permission a viewer must hold to see the card (the add-on's own read permission). Required there */
+    permission?: string;
+    /** Executive cards: the card's figures for this viewer, read with their context. Throw to say they could not be read */
+    summary?: (ctx: ActorContext) => Promise<AddonCardSummary>;
+}
+/** An executive card as the hub shows it to one viewer: the figures read for them, or that they could not be. */
+export interface ExecutiveCardView {
+    addonName: string;
+    title: string;
+    icon: string;
+    adminUrl: string;
+    figures: AddonCardFigure[];
+    message: string;
+    /** True when the add-on's summary threw; the card says its figures could not be read. */
+    failed: boolean;
 }
 /** #2100: the PDP refused an administrator's add-on Update or Check. */
 export declare class AddonUpdateForbiddenError extends Error {
@@ -823,10 +858,19 @@ declare class AddonsManager extends BaseManager {
      */
     registerDashboardCard(card: AddonDashboardCard): void;
     /**
-     * Return all registered dashboard cards in registration order.
-     * Called by the admin dashboard route to populate the addon cards row.
+     * Return the registered cards for one surface, in registration order.
+     * The admin dashboard route calls it with no argument for the `/admin` cards.
+     */
+    getDashboardCards(surface?: AddonCardSurface): AddonDashboardCard[];
+    /**
+     * The Executive Hub's cards for one viewer (#2093): each card whose
+     * permission the PDP permits `ctx`, asked with that context, with the
+     * figures its add-on's `summary(ctx)` reads for them. A card the viewer may
+     * not see is left out; a summary that throws shows the card with its
+     * figures marked as not read, and is logged by add-on name only. No
+     * context, or no PDP, shows no cards.
      */
-    getDashboardCards(): AddonDashboardCard[];
+    executiveCardsFor(ctx: ActorContext): Promise<ExecutiveCardView[]>;
     /**
      * Get list of all discovered add-on names
      */

package/lib/src/security/permissions.generated.d.ts

@@ -22,6 +22,8 @@ export type CorePermission =
  | 'comment-create'
 /** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
  | 'config-manage'
+/** Open the Executive Hub (/executive): the organization's summary cards and the requests waiting for the board (#2093). Held by the executive role; deciding a request still needs that request's own permission */
+ | 'executive-read'
 /** Create, edit, delete and link identity records, of users and contacts alike, and organizations, and an identity's affiliations, through IdentityManager and OrganizationManager (#1930). Reading them is identity-read. Was contact-manage until #2038; a policy naming that is still read as this for one release. Admins by default; an add-on grants it to its own roles in its own policy */
  | 'identity-manage'
 /** List, search and view identity records, of users and contacts alike, and organizations, and their affiliations, through IdentityManager and OrganizationManager, and the /admin/contacts and /admin/organizations views (#1930). Was contact-read until #2038; a policy naming that is still read as this for one release. Admins and demo admins by default; an add-on grants it to its own roles in its own policy */

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -58,6 +58,8 @@ export declare const AUDIT_EVENT: {
     readonly EMAILCHANGE_CONFIRM: "emailchange-confirm";
     /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
     readonly EMAILCHANGE_REQUEST: "emailchange-request";
+    /** Executive Hub read; not recorded, read volume */
+    readonly EXECUTIVE_READ: "executive-read";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
     /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */

package/lib/src/utils/auditEventNames.generated.js

@@ -65,6 +65,8 @@ export const AUDIT_EVENT = {
     EMAILCHANGE_CONFIRM: 'emailchange-confirm',
     /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
     EMAILCHANGE_REQUEST: 'emailchange-request',
+    /** Executive Hub read; not recorded, read volume */
+    EXECUTIVE_READ: 'executive-read',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
     /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.37.0",
+  "version": "5.38.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",