@sparkelf/dsh-dataops-managed 0.3.20 → 0.3.21

package/lib/types/auth-state.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Whether the stored DataOps credential is still accepted, observed rather than guessed.
+ *
+ * Every DataOps call this plugin makes already knows the answer: a 401 is the server saying the
+ * caller's session has ended. Those answers used to be swallowed at each call site — each one
+ * returned `undefined` and moved on — which turned "your session expired" into "this feature
+ * happens to be empty". That is the failure this module removes: the calls still degrade
+ * gracefully, but the reason is recorded once, in a place the interface can read.
+ *
+ * The state is deliberately tiny and stuck in this process. It is not a token cache and it does
+ * not decide authorization — DataOps remains the only authority. It exists because a person
+ * looking at the workspace cannot see a 401 that was handled three layers down, and "sign in
+ * again" is only actionable if it is shown while it is still true.
+ *
+ * @module auth-state
+ */
+/** What the last DataOps answer said about the stored credential. */
+export type AuthState = 'unknown' | 'valid' | 'expired';
+/**
+ * Record that a DataOps call was accepted.
+ *
+ * Called on any non-401 answer, including ones that carry a refusal for another reason: a 403
+ * says the session is fine and the permission is not, so it must not raise the sign-in prompt.
+ */
+export declare const noteAccepted: () => void;
+/** Record that DataOps refused the credential, which means the session is over. */
+export declare const noteExpired: () => void;
+/**
+ * Read the current observation.
+ *
+ * @returns `unknown` before any call has completed, then what the last one said.
+ */
+export declare const currentAuthState: () => AuthState;
+/**
+ * Test-only reset, so one case cannot leak its observation into the next.
+ */
+export declare const resetAuthState: () => void;

package/lib/types/client/NotificationBell.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { ReviewNotification } from './review-types.ts';
+/** Props accepted by a bell. */
+export interface NotificationBellProps {
+    /** Accessible label; the two plaza headings differ so screen readers can tell them apart. */
+    label: string;
+    /** Called after a row is read, so the plaza can jump to the matching tab or card. */
+    onOpen?: (item: ReviewNotification) => void;
+}
+/**
+ * A bell with an unread badge and the shared inbox.
+ *
+ * The bell is a button rather than a menu so keyboard focus and Escape follow the dialog
+ * conventions the rest of the page already uses. Rows mark themselves read when opened;
+ * "全部已读" is the one bulk action.
+ */
+export declare function NotificationBell({ label, onOpen }: NotificationBellProps): ReactNode;
+/** The automation page's seat: the same inbox under the workflow plaza's heading. */
+export declare function WorkflowPlazaBell(): ReactNode;

package/lib/types/client/PermissionCenterIcon.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+/**
+ * The sidebar glyph for the permission centre.
+ *
+ * The entry is hidden for a caller the Host reports as an ordinary user. This is a navigation
+ * affordance, not the authorization decision: every permission-centre endpoint re-checks the
+ * caller, and the page itself refuses to render without a management role.
+ */
+export declare function PermissionCenterIcon(): ReactNode;

package/lib/types/client/PermissionCenterSection.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import type { en } from './locales.ts';
+/** Props accepted by the page. */
+export interface PermissionCenterSectionProps {
+    t?: (key: keyof typeof en) => string;
+}
+/**
+ * The permission centre.
+ *
+ * Every write goes through `saveRbacSection`; the backend enforces the same role/scope rules
+ * the disabled controls represent. The page keeps target-aware state explicitly (actor role,
+ * actor department) so an ADMIN cannot edit a SUPER_ADMIN row and a DEPT_ADMIN cannot reach
+ * another department, even if a list payload is wider than expected.
+ */
+export declare function PermissionCenterSection({ t }: PermissionCenterSectionProps): ReactNode;

package/lib/types/client/ReloginPrompt.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The "sign in again" prompt shown when this workspace's DataOps session has ended.
+ *
+ * The failure it reports used to be invisible. Every DataOps call handles a 401 by degrading to
+ * an empty result, which is right for one panel but wrong for the operator: settings, shared
+ * models and the skill plaza all render as "nothing here" while the real cause is that nobody is
+ * signed in any more. This prompt names that state once, with the one action that clears it.
+ *
+ * It reports and nothing more. It does not retry, expire, or re-authenticate — the portal owns
+ * the login form and is the only thing that can issue a session. It also cannot navigate the
+ * operator there: the portal is a different origin, so this frame cannot read or drive its
+ * window, and the gateway does not forward the browser's origin to the workspace. Guessing a
+ * URL from inside here would open the wrong page on some deployments, so the dialog tells the
+ * operator which window to switch to instead of pretending it can take them.
+ *
+ * @module ReloginPrompt
+ */
+/** The copy this prompt needs, bound by its host surface. */
+export interface ReloginPromptProps {
+    /** Resolve one of the prompt's own strings. */
+    readonly t: (key: 'reloginTitle' | 'reloginBody' | 'reloginAction' | 'reloginDismiss') => string;
+}
+/**
+ * Watch for an ended DataOps session and say so.
+ *
+ * @param props.t - localized copy resolver.
+ * @returns the dialog while the session is known to have ended, otherwise `null`.
+ */
+export declare function ReloginPrompt(props: ReloginPromptProps): import("react").JSX.Element | null;

package/lib/types/client/ReviewSettingsCard.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import type { en } from './locales.ts';
+/**
+ * The three plaza-review switches.
+ *
+ * The card is independent of the review queue so the settings page owns the switches while the
+ * plaza owns the rows. Defaults are on; a 503 keeps the switches usable and says the API is
+ * waiting rather than pretending the save happened.
+ */
+export declare function ReviewSettingsCard({ t }: {
+    t: (key: keyof typeof en) => string;
+}): ReactNode;

package/lib/types/client/SkillPlazaSection.d.ts

@@ -19,11 +19,9 @@ export type SkillPlazaSectionProps = Partial<InjectFace<SkillPlazaSectionInjecte
 /**
  * Browse, share, and install skills other users published.
  *
- * The section appears only where this plugin is installed: the skill center renders the slot,
- * and an empty slot renders nothing. Every action goes through this plugin's Host route, so a
- * workspace without DataOps never reaches these calls.
- * @param props - Skill center injection values.
- * @returns The plaza section, or nothing before injection.
+ * Review is a permissioned overlay on the same plaza: the tab strip and the audit dialog only
+ * appear when the Host says the caller may review, and the Host additionally narrows the pending
+ * list to the caller's department subtree.
  */
 export declare function SkillPlazaSection(props: SkillPlazaSectionProps): ReactNode;
 /** Re-exported so the registration site reads the route from one place. */

package/lib/types/client/WanxiangBrand.d.ts

@@ -6,7 +6,13 @@ interface MarkProps {
 export declare function WanxiangMark({ size, className, animated }: MarkProps & {
     animated?: boolean;
 }): import("react").JSX.Element;
-/** Approved rounded-Heiti artwork, stored as paths with no runtime font dependency. */
+/**
+ * Platform wordmark rendered as text.
+ *
+ * It used to be glyph artwork for the previous platform name, which cannot express the new
+ * name without redrawing every path. Text keeps the visible header, the accessible name, and
+ * the browser title on one string, and inherits the host's CJK font stack through `font-family`.
+ */
 export declare function WanxiangWordmark({ height, accessible, className }: {
     height: number;
     accessible?: boolean;

package/lib/types/client/WorkspaceUpgradePrompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Workspace image upgrade banner and confirmation dialog.
+ *
+ * The banner is deliberately quiet: it tells the user a newer workspace image exists and
+ * leaves the current session usable. Only the explicit upgrade action opens the dialog
+ * that can interrupt running sessions.
+ *
+ * @module WorkspaceUpgradePrompt
+ */
+import type { en } from './locales.ts';
+/** The copy resolver bound by the client plugin. */
+export interface WorkspaceUpgradePromptProps {
+    /** Resolve one managed DataOps message key. */
+    readonly t: (key: keyof typeof en) => string;
+}
+/**
+ * Render the banner and its upgrade dialog.
+ * @param props.t - localized copy resolver.
+ * @returns the banner while an image update is available, otherwise null.
+ */
+export declare function WorkspaceUpgradePrompt(props: WorkspaceUpgradePromptProps): import("react").JSX.Element | null;

package/lib/types/client/combobox.d.ts

@@ -0,0 +1,17 @@
+/** Pure helpers shared by the permission-centre combobox and resource details. */
+/** One selectable option. */
+export interface ComboboxOption {
+    readonly value: string;
+    readonly label: string;
+    readonly hint?: string;
+}
+/**
+ * Filter options by display label or code hint, case-insensitively.
+ * @param options - all options.
+ * @param query - typed search text.
+ */
+export declare function filterComboboxOptions(options: readonly ComboboxOption[], query: string): ComboboxOption[];
+/** Keep an active index inside a possibly empty result list. */
+export declare function clampActiveIndex(index: number, length: number): number;
+/** Owner cell face: a real display name, or a dash; never the raw id. */
+export declare function ownerDisplay(ownerName: string | undefined | null): string;

package/lib/types/client/index.d.ts

@@ -1,6 +1,15 @@
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 import { type ManagedDataOpsKey } from './locales.ts';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /** Header actions declared by the knowledge-base workflow plaza. */
+        'workflow-plaza.actions': {
+            kind: 'single';
+            scope: 'root';
+            owner: Record<string, never>;
+            hookContext: unknown;
+        };
+    }
     interface LocaleNamespaceMap {
         'settings.dataops-managed': ManagedDataOpsKey;
     }
@@ -8,7 +17,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 /** Required client services for the managed DataOps Settings section. */
 export declare const inject: string[];
 /**
- * Register localized managed DataOps Settings navigation and content.
- * @param ctx - DSH client context with locale and settings slots.
+ * Register the managed DataOps surfaces and the sign-in prompt.
+ *
+ * The prompt rides a sidebar seat because the client needs *some* always-mounted surface for a
+ * dialog that is about the whole workspace rather than one panel. The seat is a container: the
+ * dialog itself portals to `document.body`, so this contributes no visible element to the
+ * sidebar at rest and cannot disturb the regions that already live there.
+ *
+ * @param ctx - DSH client context with locale, slots and the sidebar foot.
  */
 export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -38,6 +38,109 @@ export declare const en: {
     readonly plazaLoadFailed: "The skill plaza could not be loaded. Try again.";
     readonly plazaActionFailed: "The action could not be completed. Try again.";
     readonly plazaRetry: "Try again";
+    readonly plazaRefresh: "Refresh";
+    readonly plazaTabApproved: "Approved";
+    readonly plazaTabPending: "Pending";
+    readonly plazaTabAll: "All";
+    readonly plazaSharedTag: "Shared";
+    readonly plazaReview: "Review";
+    readonly plazaPendingEmpty: "No skills are waiting for review.";
+    readonly plazaAuditTitle: "Review skill";
+    readonly plazaAuditSource: "Source";
+    readonly plazaAuditVisibility: "Visibility";
+    readonly plazaRiskTitle: "AI risk report";
+    readonly plazaRiskScan: "Run AI scan";
+    readonly plazaRiskScanning: "Scanning…";
+    readonly plazaRiskNone: "No AI risk report yet.";
+    readonly plazaRiskScore: "Risk score";
+    readonly plazaRiskFindings: "Findings";
+    readonly plazaRiskFailed: "The AI scan failed; review manually.";
+    readonly plazaApprove: "Approve";
+    readonly plazaReject: "Reject";
+    readonly plazaReviewNote: "Review note (required to reject)";
+    readonly plazaReviewNotePlaceholder: "Explain the reason or what to change…";
+    readonly plazaReviewDone: "Review saved.";
+    readonly plazaReviewFailed: "The review could not be saved. Try again.";
+    readonly plazaDemo: "Demo data";
+    readonly plazaGlobal: "Global";
+    readonly plazaPrivate: "Private";
+    readonly plazaDeptSuffix: " department";
+    readonly reviewSettingsTitle: "Review settings";
+    readonly reviewSettingsSkill: "Skill plaza review";
+    readonly reviewSettingsWorkflow: "Workflow plaza review";
+    readonly reviewSettingsKb: "Knowledge base review";
+    readonly reviewSettingsHint: "When on, submitted content stays private until an administrator approves it.";
+    readonly reviewSettingsSave: "Save";
+    readonly reviewSettingsSaved: "Review settings saved.";
+    readonly reviewSettingsFailed: "Could not save. Try again.";
+    readonly reviewSettingsWaiting: "Review settings API is waiting for the backend (task-39).";
+    readonly permNav: "Permissions";
+    readonly permTitle: "Permission centre";
+    readonly permTabRoles: "Role permissions";
+    readonly permTabMembers: "Member roles";
+    readonly permTabDepartments: "Departments";
+    readonly permTabResources: "Resource scope";
+    readonly permRoleMatrix: "Role permission matrix";
+    readonly permPermissionModule: "Module";
+    readonly permPermissionPoint: "Permission";
+    readonly permReadOnly: "Read only";
+    readonly permSave: "Save";
+    readonly permSaved: "Saved.";
+    readonly permSaveFailed: "Could not save. Try again.";
+    readonly permSuperAdminOnly: "Only a super administrator can change this.";
+    readonly permMember: "Member";
+    readonly permDepartment: "Department";
+    readonly permRole: "Role";
+    readonly permDeptAdmin: "Department administrator";
+    readonly permScope: "Visibility";
+    readonly permGlobal: "Global";
+    readonly permDepartmentScope: "Department";
+    readonly permPrivate: "Private";
+    readonly permNoAccess: "You do not have access to the permission centre.";
+    readonly permWaiting: "The permission-centre API is waiting for the backend (task-37).";
+    readonly permResourceSkill: "Skill";
+    readonly permResourceWorkflow: "Workflow";
+    readonly permResourceKb: "Knowledge base";
+    readonly permType: "Type";
+    readonly permName: "Name";
+    readonly permOwner: "Owner";
+    readonly permOperations: "Actions";
+    readonly permViewDetails: "View details";
+    readonly permDetailTitle: "Resource details";
+    readonly permDetailType: "Type";
+    readonly permDetailName: "Name";
+    readonly permDetailOwner: "Owner";
+    readonly permDetailScope: "Visibility";
+    readonly permDetailDepartment: "Department";
+    readonly permDetailStatus: "Review status";
+    readonly permDetailUpdated: "Updated";
+    readonly permNone: "None";
+    readonly permSearch: "Search…";
+    readonly permNoMatches: "No matches";
+    readonly permClose: "Close";
+    readonly permSelect: "Select…";
+    readonly permStatusPending: "Pending review";
+    readonly permStatusApproved: "Approved";
+    readonly permStatusRejected: "Rejected";
+    readonly permDemo: "Demo data";
+    readonly reloginTitle: "Sign in to DataOps again";
+    readonly reloginBody: "This workspace can no longer reach DataOps: the sign-in for this session has ended, so settings, shared models and the skill plaza cannot load. Sign in again in the DataOps window, then reload this page.";
+    readonly reloginAction: "Reload";
+    readonly reloginDismiss: "Later";
+    readonly upgradeAvailableTitle: "A new workspace version is available";
+    readonly upgradeAvailableBody: "Restart the workspace to apply it.";
+    readonly upgradeAction: "Upgrade";
+    readonly upgradeLater: "Later";
+    readonly upgradeDialogTitle: "Upgrade workspace";
+    readonly upgradeDialogBody: "The workspace will restart and briefly disconnect. Your files and sessions are kept.";
+    readonly upgradeNoSessions: "No sessions are running. The workspace will restart now.";
+    readonly upgradeSessionsWarning: "{count} running session(s) will be interrupted. After the upgrade, each one is resumed and sent “继续”.";
+    readonly upgradeCancel: "Cancel";
+    readonly upgradeConfirm: "Stop tasks and upgrade";
+    readonly upgradeBusy: "Upgrading workspace…";
+    readonly upgradeStarted: "Upgrade started. Reload this page when the workspace reconnects.";
+    readonly upgradeFailed: "The workspace upgrade could not be started. Try again.";
+    readonly upgradeRetry: "Retry";
 };
 /** Stable key set shared by every managed DataOps locale. */
 export type ManagedDataOpsKey = keyof typeof en;

package/lib/types/client/review-client.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Browser calls for review, notifications, the permission centre, and review settings.
+ *
+ * Every request goes through this plugin's same-origin bridge, which holds the DataOps JWT.
+ * A 503/404 means the Host or DataOps has not shipped that endpoint yet; callers render their
+ * "waiting for the backend" state instead of treating an unfinished feature as a failure.
+ */
+import type { ReviewContext, ReviewNotification, RiskReport, ReviewStatus, ResourceVisibility } from './review-types.ts';
+/** Caller identity and review capability. */
+export declare const REVIEW_CONTEXT_PATH = "/integrations/dataops/review-context";
+/** Notification list and read receipts. */
+export declare const NOTIFICATIONS_PATH = "/integrations/dataops/review-notifications";
+/** AI scan and the human decision. */
+export declare const REVIEW_ACTION_PATH = "/integrations/dataops/review";
+/** Role matrix, members, departments, and resource scopes. */
+export declare const RBAC_PATH = "/integrations/dataops/rbac";
+/** The three plaza-review switches in the DataOps settings panel. */
+export declare const REVIEW_SETTINGS_PATH = "/integrations/dataops/review-settings";
+/** Department CRUD bridge (task-67). */
+export declare const DEPARTMENTS_PATH = "/integrations/dataops/departments";
+/** One permission point in the role matrix. */
+export interface PermissionPoint {
+    key: string;
+    name: string;
+    group: string;
+    /** Backend scope metadata for the DSH capability catalogue (task-70). */
+    scope?: 'department' | 'global' | string;
+    /** Chinese presentation note (task-76). */
+    description?: string;
+}
+/** One role row in the matrix. */
+export interface RoleMatrixRow {
+    code: string;
+    name: string;
+    systemKey?: string;
+    dataScope: 'ALL' | 'DEPARTMENT' | 'SELF' | 'CUSTOM_DEPARTMENTS' | 'DEPARTMENT_TREE';
+    permissions: readonly string[];
+}
+/** One member and their role assignment. */
+export interface MemberRow {
+    userId: string;
+    username: string;
+    displayName: string;
+    roleCodes: readonly string[];
+    departmentCode?: string;
+    departmentPath?: readonly {
+        code: string;
+        name: string;
+    }[];
+    dataScope?: string;
+}
+/** One department in the tree. */
+export interface DepartmentRow {
+    code: string;
+    name: string;
+    parentCode?: string;
+    path?: readonly {
+        code: string;
+        name: string;
+    }[];
+    memberCount?: number;
+    deptAdmins?: readonly {
+        userId: string;
+        username: string;
+        displayName: string;
+    }[];
+    description?: string;
+    owner?: string;
+    enabled?: boolean;
+    updatedAt?: string;
+}
+/** One skill/workflow resource and its visibility scope. */
+export interface ResourceScopeRow {
+    kind: 'skill' | 'workflow';
+    id: string | number;
+    name: string;
+    ownerId?: string;
+    ownerName?: string;
+    departmentCode?: string | null;
+    visibility: ResourceVisibility;
+    reviewStatus?: ReviewStatus;
+    updatedAt?: string;
+}
+/** Everything the permission centre renders in one read. */
+export interface RbacOverview {
+    matrix: {
+        roles: readonly RoleMatrixRow[];
+        permissions: readonly PermissionPoint[];
+    };
+    members: readonly MemberRow[];
+    departments: readonly DepartmentRow[];
+    resources: readonly ResourceScopeRow[];
+}
+/** One plaza review switch. */
+export interface ReviewSettings {
+    skillPlaza: boolean;
+    workflowPlaza: boolean;
+    knowledgeBase: boolean;
+}
+/** The product defaults, used until DataOps returns its own value. */
+export declare const DEFAULT_REVIEW_SETTINGS: ReviewSettings;
+/**
+ * Whether the page was opened with the demo fixture.
+ *
+ * The fixture exists so the review dialog and the permission matrix can be reviewed before the
+ * backend contract is deployed; every fixture row is labelled and the mode is never the default.
+ */
+export declare function reviewDemoMode(): boolean;
+/** Read the caller's role and review capability. */
+export declare function fetchReviewContext(): Promise<ReviewContext | null>;
+/** Read the current user's notifications. */
+export declare function fetchNotifications(): Promise<{
+    items: readonly ReviewNotification[];
+    unread: number;
+} | null>;
+/** Mark some notifications, or every one, as read. */
+export declare function markNotificationsRead(ids: 'all' | readonly string[]): Promise<boolean>;
+/** Run the AI review for one or more resources. */
+export declare function scanReview(kind: 'skill' | 'workflow', ids: readonly (string | number)[]): Promise<RiskReport | null>;
+/** Record the administrator's decision. The backend enforces the authorization flag too. */
+export declare function decideReview(kind: 'skill' | 'workflow', ids: readonly (string | number)[], decision: 'approve' | 'reject', note: string): Promise<boolean>;
+/** Read the permission centre. */
+export declare function fetchRbacOverview(): Promise<RbacOverview | null>;
+/** What a permission-centre write returned, including the backend's readable refusal. */
+export interface RbacSaveResult {
+    ok: boolean;
+    reason?: string;
+}
+/** Persist one permission-centre section. */
+export declare function saveRbacSection(section: 'roles' | 'members' | 'departments' | 'resources', value: unknown): Promise<RbacSaveResult>;
+/** Read the three plaza-review switches. */
+export declare function fetchReviewSettings(): Promise<ReviewSettings | null>;
+/** Persist the three plaza-review switches. */
+export declare function saveReviewSettings(settings: ReviewSettings): Promise<boolean>;
+/** Create one department through the same-origin bridge. */
+export declare function createDepartment(input: {
+    code: string;
+    name: string;
+    parentCode?: string | null;
+    description?: string;
+    owner?: string;
+    enabled?: boolean;
+}): Promise<RbacSaveResult>;
+/** Update one department; the Host fills `updatedAt` from the current row when omitted. */
+export declare function updateDepartment(input: {
+    code: string;
+    name?: string;
+    parentCode?: string | null;
+    description?: string;
+    owner?: string;
+    enabled?: boolean;
+    updatedAt?: string;
+}): Promise<RbacSaveResult>;
+/** Delete one department after the confirmation dialog. */
+export declare function deleteDepartment(code: string): Promise<RbacSaveResult>;

package/lib/types/client/review-demo.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Labeled fixtures for reviewing the new surfaces before the backend contract is deployed.
+ *
+ * They are only reachable through `?dataopsReviewDemo=1`; production never merges them into a
+ * listing. Keeping them in one module means the plaza, the audit dialog and the permission
+ * centre tell the same story instead of each inventing a different sample.
+ */
+import type { PlazaSkill } from './skill-plaza-client.ts';
+import type { RbacOverview } from './review-client.ts';
+/** A pending skill with an AI report, an approved global skill, and a rejected private one. */
+export declare function demoPlazaSkills(): PlazaSkill[];
+/** Four roles, the permission catalog, three members, two departments, and three resources. */
+export declare function demoRbacOverview(): RbacOverview;

package/lib/types/client/review-notification-store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One process-wide notification store shared by every bell.
+ *
+ * The skill plaza and the workflow plaza are separate React trees, but they show the same
+ * inbox; keeping the read state in one store is what stops a badge in one place from staying
+ * unread after the other opened the row.
+ */
+import type { ReviewNotification } from './review-types.ts';
+interface NotificationState {
+    status: 'idle' | 'loading' | 'ready' | 'unavailable';
+    items: readonly ReviewNotification[];
+    unread: number;
+}
+/** Current snapshot for `useSyncExternalStore`. */
+export declare function notificationSnapshot(): NotificationState;
+/** Subscribe to store changes. */
+export declare function subscribeNotifications(listener: () => void): () => void;
+export declare function loadNotifications(): Promise<void>;
+/** Mark one row or the whole inbox read, optimistically. */
+export declare function markRead(ids: 'all' | readonly string[]): Promise<void>;
+/** Load the inbox when a bell first mounts. */
+export declare function useNotifications(): NotificationState;
+export {};

package/lib/types/client/review-types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared vocabulary for the review, permission and notification surfaces.
+ *
+ * The backend contract is landing in parallel; every field that a legacy row cannot carry
+ * yet is optional here and normalized to the product default (approved/global) rather than
+ * guessed per component. Keeping the rules in one place is what lets the skill plaza, the
+ * permission centre and the notification bell agree on what "pending" means.
+ */
+/** Review state of a shared skill or workflow. */
+export type ReviewStatus = 'pending' | 'approved' | 'rejected';
+/** Who may see a shared resource outside its owner. */
+export type ResourceVisibility = 'global' | 'department' | 'private';
+/** The skill-plaza filter tabs, in display order. */
+export type ReviewTab = 'approved' | 'pending' | 'all';
+/** The four DataOps roles the permission centre knows. */
+export type PortalRole = 'SUPER_ADMIN' | 'ADMIN' | 'DEPT_ADMIN' | 'APP_USER';
+/** One node of a department ancestry path. */
+export interface DepartmentPathEntry {
+    code: string;
+    name: string;
+}
+/** A department as a card tag needs it: code, label, and the ancestry for the tooltip. */
+export interface DepartmentSummary {
+    code: string;
+    name: string;
+    /** Root-first path, in either the legacy string form or the backend object form. */
+    path?: readonly (string | DepartmentPathEntry)[];
+}
+/** One AI risk finding. */
+export interface RiskFinding {
+    category: string;
+    severity: 'low' | 'medium' | 'high';
+    evidence?: string;
+    recommendation?: string;
+}
+/** The AI report attached to a pending resource. */
+export interface RiskReport {
+    score?: number;
+    /** Overall severity, which is wider than a single finding's severity. */
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    summary?: string;
+    findings: readonly RiskFinding[];
+    scannedAt?: string;
+}
+/** The caller's review permissions, as the Host reports them. */
+export interface ReviewContext {
+    userId?: string;
+    role: PortalRole;
+    departmentCode?: string;
+    departmentPath?: readonly string[];
+    canReview: boolean;
+    canManagePermissions: boolean;
+}
+/** One notification row. */
+export interface ReviewNotification {
+    id: string;
+    type: string;
+    title: string;
+    body?: string;
+    resourceKind?: string;
+    resourceId?: string | number;
+    read: boolean;
+    createdAt: string;
+}
+/** A reviewable row as the cards read it. */
+export interface ReviewableSummary {
+    reviewStatus?: ReviewStatus;
+    visibility?: ResourceVisibility;
+    departmentCode?: string | null;
+    departmentName?: string;
+    departmentPath?: readonly (string | DepartmentPathEntry)[];
+    riskReport?: RiskReport | null;
+    reviewNote?: string | null;
+    submittedAt?: string;
+}
+/** Treat a missing status as approved: rows written before the review state existed were live. */
+export declare function normalizeReviewStatus(value: unknown): ReviewStatus;
+/** Treat a missing visibility as global: a shared row with no scope was visible to everyone. */
+export declare function normalizeVisibility(value: unknown): ResourceVisibility;
+/** Whether the caller may see and act on the review queue. */
+export declare function canReview(context: ReviewContext | null | undefined): boolean;
+/** Whether the caller may open the permission centre's write controls. */
+export declare function canManagePermissions(context: ReviewContext | null | undefined): boolean;
+/**
+ * The tabs this caller may see.
+ *
+ * A department administrator sees the queue too, but the Host narrows it to their subtree;
+ * an ordinary user gets only the approved list, and no tab strip at all when there is one tab.
+ */
+export declare function reviewTabsFor(context: ReviewContext | null | undefined): readonly ReviewTab[];
+/** Filter rows by the selected review tab. */
+export declare function filterByReview<T extends ReviewableSummary>(rows: readonly T[], tab: ReviewTab): readonly T[];
+/** Counts for the tab labels. */
+export declare function reviewCounts(rows: readonly ReviewableSummary[]): Record<ReviewTab, number>;
+/** The status badge shown on a local skill card. */
+export declare function reviewStatusLabel(status: ReviewStatus): string;
+/**
+ * The visibility tag in a card's top-right corner.
+ *
+ * A department tag names the department and keeps the full path in the tooltip; a global tag
+ * is one word because it is the default and should not compete with the skill name.
+ */
+/** Read a department path from either the legacy string form or the backend object form. */
+export declare function departmentPathNames(path: ReviewableSummary['departmentPath']): string[];
+export declare function visibilityTag(row: ReviewableSummary): {
+    label: string;
+    detail: string;
+};
+/** Unread count for a bell badge. */
+export declare function unreadCount(items: readonly ReviewNotification[]): number;
+/** Newest first. Read state never reorders rows, so marking one read cannot move it to another page. */
+export declare function sortNotifications(items: readonly ReviewNotification[]): readonly ReviewNotification[];
+/** The tab a notification should open, when its resource has one. */
+export declare function notificationTab(item: ReviewNotification): ReviewTab | undefined;