@cosmicdrift/kumiko-types 0.372.0 → 0.374.0

package/dist/handlers.d.ts

@@ -513,7 +513,8 @@ export type EntityRef = {
 export type HandlerRef = {
     readonly name: string;
 };
-export type RateLimitPer = "user" | "tenant" | "ip" | "user+handler" | "tenant+handler" | "ip+handler";
+export declare const RATE_LIMIT_PERS: readonly ["user", "tenant", "ip", "user+handler", "tenant+handler", "ip+handler"];
+export type RateLimitPer = (typeof RATE_LIMIT_PERS)[number];
 export type RateLimitOption = {
     readonly per: RateLimitPer;
     readonly limit: number;
@@ -531,11 +532,14 @@ export type PayloadRateLimitOption = {
     readonly cost?: number;
     readonly normalize?: PayloadBucketNormalization;
 };
+export declare function isRateLimitOption(value: unknown): value is RateLimitOption;
+export type RateLimitOptions = readonly [RateLimitOption, ...RateLimitOption[]];
 export type RateLimitDisabled = {
     readonly disabled: true;
     readonly reason: string;
 };
-export type RateLimitDeclaration = RateLimitOption | RateLimitDisabled;
+export type RateLimitDeclaration = RateLimitOption | RateLimitOptions | RateLimitDisabled;
+export declare function declaredRateLimitOptions(declaration: RateLimitDeclaration | undefined): readonly RateLimitOption[];
 export declare function isRateLimitDisabled(v: RateLimitDeclaration | undefined): v is RateLimitDisabled;
 export type AgentRisk = "low" | "mid" | "high";
 /** Per-handler hints for the AI-agent manifest. `expose` overrides the

package/dist/handlers.js

@@ -1,3 +1,4 @@
+import { isOneOf, propertyOf } from "./type-guards.js";
 export const ESCAPE_HATCH_GRANTS = ["systemIdentity", "globalWrites", "unsafeRaw"];
 export function isEscapeHatchGrant(value) {
     return ESCAPE_HATCH_GRANTS.some((grant) => grant === value);
@@ -98,8 +99,41 @@ export function normalizeEventPiiSubject(spec) {
         return { kind: "self" };
     return { kind: "user", ownerField: spec.personal.of, whenAbsent: spec.personal.whenAbsent };
 }
+// --- Handler Definitions (stored in feature/registry) ---
+// Per-handler rate limit. Bucket key derived from `per`:
+//   "user"            → userId
+//   "tenant"          → tenantId
+//   "ip"              → request IP
+//   "user+handler"    → userId + handlerName
+//   "tenant+handler"  → tenantId + handlerName
+//   "ip+handler"      → IP + handlerName (anonymous endpoints)
+// `cost` is the tokens this handler-call deducts. Default 1 — bump for
+// expensive operations (bulk export, bulk import).
+export const RATE_LIMIT_PERS = [
+    "user",
+    "tenant",
+    "ip",
+    "user+handler",
+    "tenant+handler",
+    "ip+handler",
+];
+export function isRateLimitOption(value) {
+    const cost = propertyOf(value, "cost");
+    return (isOneOf(RATE_LIMIT_PERS, propertyOf(value, "per")) &&
+        typeof propertyOf(value, "limit") === "number" &&
+        typeof propertyOf(value, "windowSeconds") === "number" &&
+        (cost === undefined || typeof cost === "number"));
+}
+export function declaredRateLimitOptions(declaration) {
+    if (declaration === undefined || isRateLimitDisabled(declaration))
+        return [];
+    return isRateLimitOptionList(declaration) ? declaration : [declaration];
+}
+function isRateLimitOptionList(declaration) {
+    return Array.isArray(declaration);
+}
 export function isRateLimitDisabled(v) {
-    return v !== undefined && "disabled" in v && v.disabled === true;
+    return v !== undefined && !Array.isArray(v) && "disabled" in v && v.disabled === true;
 }
 // Marker set by defineEntityQueryHandler on both of its verbs. A string, not
 // a Symbol(), for the same reason as PAGED_QUERY_HANDLER_BRAND: a symlinked

package/dist/rate-limit-types.d.ts

@@ -13,8 +13,13 @@ export type RateLimitConfig = {
     readonly windowSeconds: number;
     readonly cost?: number;
 };
+export type RateLimitBucketRequest = {
+    readonly bucket: string;
+    readonly config: RateLimitConfig;
+};
 export type RateLimitResolver = {
     check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
     enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
+    enforceAll(requests: readonly RateLimitBucketRequest[]): Promise<readonly RateLimitDecision[]>;
     peek(bucket: string, config: Omit<RateLimitConfig, "cost">): Promise<RateLimitDecision>;
 };

package/dist/screen.d.ts

@@ -167,7 +167,7 @@ export type RowActionDisplay = "button" | "link" | "icon" | "responsive";
  *  the rest in a kebab menu — except actions with an explicit `display`, which
  *  stay inline. `"inline"`: every action inline, no kebab. */
 export type RowActionMode = "adaptive" | "inline";
-export type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer;
+export type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
 export type RowActionWriteHandler = {
     /** Default für RowActions ohne explizit gesetzten `kind` —
      *  Backwards-kompatible Form. Kann auch explizit gesetzt werden. */
@@ -293,6 +293,37 @@ export type RowActionDrawer = {
     /** Line under the drawer heading (i18n key or a bare `{name}` template),
      *  resolved like `title`. */
     readonly subtitle?: string;
+    /** Clicking the row opens this drawer with that row's `params`. At most one
+     *  `rowClick` action (navigate or drawer) per list; rejected on
+     *  projectionDetail header actions, like navigate's. */
+    readonly rowClick?: boolean;
+};
+export type RowActionClientAction = {
+    readonly kind: "clientAction";
+    readonly id: string;
+    readonly label: string;
+    /** Registered client handler name, `<feature>:<kebab>`, e.g.
+     *  "auth-email-password:request-password-reset". Resolved when the action is
+     *  triggered; a name no client feature registered shows an error toast. */
+    readonly action: string;
+    /** Payload handed to the handler, picked from the row (or the shown record).
+     *  Default `{ id: row.id }`, like a writeHandler. */
+    readonly payload?: RowFieldExtractor;
+    /** i18n key for the confirm dialog description. */
+    readonly confirm?: string;
+    /** i18n key for the confirm button, default `label`. */
+    readonly confirmLabel?: string;
+    /** Conditional visibility per row. */
+    readonly visible?: FieldCondition;
+    /** Visual style. "danger" forces a confirm dialog, like a writeHandler. */
+    readonly style?: "primary" | "secondary" | "danger";
+    /** Overrides the id-based default icon, see `RowActionWriteHandler.icon`. */
+    readonly icon?: IconKey;
+    /** Inline render form in the row-action column — see `RowActionDisplay`. */
+    readonly display?: RowActionDisplay;
+    /** i18n key of the toast shown after the handler reported `{ ok: true }`
+     *  (default `kumiko.clientAction.success`). */
+    readonly successMessage?: string;
 };
 export type ToolbarAction = {
     readonly kind: "navigate";
@@ -692,18 +723,30 @@ export type DashboardDateParam = {
     readonly kind: "date";
     readonly atMs: number;
 };
+/** Epoch ms, rendered relative to now ("5 minutes ago", "in 30 seconds") in the
+ *  user locale; the text keeps ticking while it is on screen. */
+export type DashboardRelativeTimeParam = {
+    readonly kind: "relativeTime";
+    readonly atMs: number;
+};
 /** Nested DashboardI18nText params resolve first (e.g. a duration "{years} {months}"
  *  with one plural key each); numbers stay raw so plural rules can read `count`. */
-export type DashboardTextParam = string | number | DashboardI18nText | DashboardMoneyParam | DashboardDateParam;
+export type DashboardTextParam = string | number | DashboardI18nText | DashboardMoneyParam | DashboardDateParam | DashboardRelativeTimeParam;
 /** Plain string is displayed as-is; DashboardI18nText is translated by the renderer. */
 export type DashboardText = string | DashboardI18nText;
 /** Chart/stat values are minor units, formatted with the user locale. */
-export type DashboardValueFormat = {
+export type DashboardCurrencyFormat = {
     readonly kind: "currency";
     readonly currency: string;
     /** Defaults to the currency's own decimals. */
     readonly fractionDigits?: number;
 };
+/** The stat value is an epoch ms timestamp, shown relative to now and kept current. */
+export type DashboardRelativeTimeFormat = {
+    readonly kind: "relativeTime";
+};
+/** Stat panels take both formats; chart panels only the currency one. */
+export type DashboardValueFormat = DashboardCurrencyFormat | DashboardRelativeTimeFormat;
 export type DashboardPanelQueryOptions = {
     /** Static, author-set query parameters merged on top of the screen's
      *  dynamic filterParams — lets a panel pin a value (e.g. a status facet)
@@ -737,7 +780,8 @@ export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate
     readonly valueField: string;
     readonly subField?: string;
     readonly toneField?: string;
-    /** Formats a numeric value as currency (minor units); ignored for string values. The sparkline is not formatted. */
+    /** Formats a numeric value as currency (minor units) or, with `relativeTime`, as
+     *  a ticking "5 minutes ago" from epoch ms; ignored for string values. The sparkline is not formatted. */
     readonly valueFormat?: DashboardValueFormat;
     /** Fixed tone when `toneField` is unset or yields none; not applied while the value is 0. */
     readonly tone?: DashboardStatTone;
@@ -802,7 +846,9 @@ export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmp
     readonly seriesColors?: Readonly<Record<string, string>>;
     /** Formats values as currency (minor units): y ticks, legend totals and tooltips on
      *  stacked-bars/segment-bars/stacked-area, only the y ticks on timeseries. */
-    readonly valueFormat?: DashboardValueFormat;
+    readonly valueFormat?: DashboardCurrencyFormat;
+    /** i18n key of a unit label. Only for chart "timeseries": shown once above the y ticks instead of on every tick. */
+    readonly unit?: string;
     /** Only for chart "stacked-area": fixed width per bucket, plot scrolls horizontally. */
     readonly scrollable?: boolean;
     /** Only for chart "stacked-area": marker `kind` -> look. Markers without a
@@ -849,6 +895,7 @@ export type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmpt
     readonly label: string;
     readonly query: string;
 };
+export type DashboardProgressTone = "default" | "danger";
 export type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
     readonly kind: "progress-list";
     readonly id: string;
@@ -860,6 +907,32 @@ export type DashboardCustomPanel = {
     readonly id: string;
     readonly component: PlatformComponent;
 };
+export type DashboardTextBlock = {
+    readonly kind: "heading";
+    readonly text: string;
+} | {
+    readonly kind: "paragraph";
+    readonly text: string;
+    /** Default "muted", like body copy inside panels. */
+    readonly emphasis?: "muted" | "strong";
+} | {
+    readonly kind: "list";
+    readonly items: readonly string[];
+} | {
+    readonly kind: "code";
+    readonly code: string;
+} | {
+    readonly kind: "hint";
+    readonly text: string;
+};
+export type DashboardTextPanel = DashboardPanelGate & {
+    readonly kind: "text";
+    readonly id: string;
+    /** Panel title (i18n key). */
+    readonly label?: string;
+    readonly span?: DashboardPanelSpan;
+    readonly blocks: readonly DashboardTextBlock[];
+};
 export type DashboardPanelVisibility = {
     readonly query: string;
     readonly field: string;
@@ -872,13 +945,17 @@ export type DashboardScreenPanel = {
     readonly screen: string;
     readonly label?: string;
     readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` embedded in this
+     *  panel's place when `visibleWhen` is unmet or its query fails (nothing while it loads).
+     *  Needs `visibleWhen`; the target must not have a `visibleWhen` of its own. */
+    readonly fallback?: string;
     /** Render the embedded form without its own card frame and padding, aligned to
      *  the dashboard's page grid like a standalone settings screen. Default false
      *  (framed card); set for panels whose body is a settings-list form, where a
      *  card inside the page would double the inset. */
     readonly chromeless?: boolean;
 };
-export type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardCustomPanel | DashboardScreenPanel;
+export type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardTextPanel | DashboardCustomPanel | DashboardScreenPanel;
 export type DashboardFilterDefinition = {
     readonly id: string;
     readonly label: string;
@@ -906,6 +983,30 @@ export type DashboardScopeDefinition = {
     readonly badge: string;
     readonly notice?: string;
 };
+/** Minimum polling interval of `DashboardScreenDefinition.refresh`; shorter values are rejected
+ *  at boot (`seconds`) or raised at runtime (`field`). */
+export declare const DASHBOARD_MIN_REFRESH_SECONDS = 5;
+export type DashboardRecordBinding = {
+    /** URL search param carrying the record id. Without it the dashboard shows a
+     *  hint instead of its panels and runs no query. */
+    readonly param: string;
+    /** Key of the id in each panel query payload. Default: `param`. */
+    readonly payloadKey?: string;
+    /** Optional query for the record row (QN). It receives `{ [payloadKey]: id }`
+     *  and returns a flat row; `actions` take that row as their input and
+     *  `refresh.field` and `titleField` read from it. */
+    readonly query?: string;
+    /** Field of the record row shown as the page title. Needs `query`. */
+    readonly titleField?: string;
+};
+/** Polling of the record and all panel queries, never faster than
+ *  DASHBOARD_MIN_REFRESH_SECONDS. `field` reads the seconds from the record row
+ *  (needs `record.query`), so a monitor can be polled at its own check interval. */
+export type DashboardRefresh = {
+    readonly seconds: number;
+} | {
+    readonly field: string;
+};
 export type DashboardScreenDefinition = {
     readonly id: string;
     readonly type: "dashboard";
@@ -921,6 +1022,14 @@ export type DashboardScreenDefinition = {
     /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
     readonly fallback?: string;
     readonly panels: readonly DashboardPanelDefinition[];
+    /** Binds the dashboard to one record via a URL search param, see DashboardRecordBinding. */
+    readonly record?: DashboardRecordBinding;
+    /** Header actions on the bound record (writeHandler, navigate, clientAction).
+     *  The row is the `record.query` row, or `{ id, [payloadKey]: id }` without a
+     *  query. After a success the record and all panels refetch. Needs `record`;
+     *  no drawer, redirect or rowClick. */
+    readonly actions?: readonly RowAction[];
+    readonly refresh?: DashboardRefresh;
     readonly filter?: DashboardFilterDefinition;
     /** Segmented control in the toolbar; the value lives in URL search param
      *  `id` and is merged into EVERY panel query (also ignoreScreenFilter ones). */
@@ -953,6 +1062,21 @@ export type EditFieldSpec = string | {
      *  `multiline` routes to a textarea (no icon slot), and other input
      *  kinds (select, combobox, date, …) silently ignore the key. */
     readonly icon?: FieldIconKey;
+    /** Input placeholder (i18n key, falls back to the literal). Only for
+     *  single-line text, number and textarea inputs; other kinds ignore it. */
+    readonly placeholder?: string;
+    /** Static text shown before the input (i18n key, falls back to the
+     *  literal), or `{ field }` for the current form value of another field
+     *  (a hidden field carrying e.g. a base domain). Only for single-line
+     *  text and number inputs; other kinds ignore it. */
+    readonly prefix?: FieldAffix;
+    /** Same as `prefix`, shown after the input. */
+    readonly suffix?: FieldAffix;
+    /** Button beside the input that runs a query and writes one scalar of
+     *  its result into this field. Also offered on a readOnly field, where
+     *  the value can only come from the suggestion. Only for single-line
+     *  text and number inputs; other kinds ignore it. */
+    readonly fillAction?: FieldFillAction;
     /** Marks this field as a reference lookup instead of a plain value —
      *  for projectionDetail fields, which have no `EntityDefinition` to
      *  carry a real `reference` field type. Same target convention as
@@ -971,6 +1095,20 @@ export type EditFieldSpec = string | {
      *  field `default`, it is not applied server-side. */
     readonly prefill?: EditFieldPrefill;
 };
+export type FieldAffix = string | {
+    readonly field: string;
+};
+export type FieldFillAction = {
+    /** i18n key (falls back to the literal) of the button label. */
+    readonly label: string;
+    /** Qualified query name, run with the current form values picked by `params`. */
+    readonly query: string;
+    /** Key in the query result written into the field; the value must be a
+     *  string or a number, anything else counts as a failed fill. */
+    readonly field: string;
+    /** Form fields sent as the query payload (none: an empty payload). */
+    readonly params?: RowFieldExtractor;
+};
 export type EmbeddedListEditSpec = {
     /** Sub-fields shown as read-only cells; every other cell stays editable. */
     readonly readOnlyCells?: readonly string[];
@@ -1469,6 +1607,20 @@ export type ActionFormScreenDefinition = {
      *  the handler creates a child record but the target screen is the
      *  parent's detail screen (fw#2670). */
     readonly redirect?: string | ActionFormRedirect;
+    /** Links shown in the success box after a successful submit while the
+     *  screen stays put. Targets resolve like `redirect` (the id comes from the
+     *  handler's success payload); a link without a string id is hidden.
+     *  Mutually exclusive with `redirect`. */
+    readonly successLinks?: readonly ActionFormSuccessLink[];
+    /** Reset the form to its initial values after a successful submit (prefill
+     *  kept, typed values cleared). Only applies while the screen stays put,
+     *  i.e. without `redirect`. */
+    readonly resetOnSuccess?: boolean;
+    /** Load the initial values from a query. The record id comes from the route
+     *  (or the drawer row id) and is sent as `{ [idParam]: id }`; the result,
+     *  picked to `fields`, becomes the initial values. Turns URL prefill off:
+     *  search params never reach the form. */
+    readonly load?: ActionFormLoad;
     /** Target of the Cancel button. Default: `redirect` (historical
      *  behavior — Cancel and the submit-redirect then land in the same
      *  place). `false` = no Cancel button; correct for single-action
@@ -1519,6 +1671,21 @@ export type ActionFormRedirect = {
      *  Boot rejects other targets and unknown section ids. */
     readonly tab?: string;
 };
+export type ActionFormLoad = {
+    /** Query QN that returns the record. */
+    readonly query: string;
+    /** Payload key carrying the record id (default "id"). */
+    readonly idParam?: string;
+};
+/** A redirect target rendered as a link in the success box. */
+export type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom"> & {
+    /** Success-payload field carrying the navigation id. Required for a record
+     *  target (`entityEdit`, `projectionDetail`); omit it for a list, dashboard
+     *  or form target, which opens without an id. */
+    readonly idFrom?: string;
+    /** Link text (i18n key). */
+    readonly label: string;
+};
 /** Author-declared field shown once after a mint-form submit — API token,
  *  recovery codes, similar one-time secrets. */
 export type SecretRevealField = {

package/dist/screen.js

@@ -8,6 +8,9 @@ export function metricField(metric) {
 // `visibleWhen` only on a top-level stat; the boot validator rejects it on a
 // stat-group child (gate the whole group instead).
 export const DASHBOARD_STAT_TONES = ["default", "positive", "ok", "warn", "negative"];
+/** Minimum polling interval of `DashboardScreenDefinition.refresh`; shorter values are rejected
+ *  at boot (`seconds`) or raised at runtime (`field`). */
+export const DASHBOARD_MIN_REFRESH_SECONDS = 5;
 /** Group key of a field value; `collapsedWhen` and row values both go through it. */
 export function relatedListGroupKey(value) {
     return value === undefined || value === null ? "" : String(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.372.0",
+  "version": "0.374.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",