@cosmicdrift/kumiko-types 0.374.0 → 0.377.0

package/dist/feature.d.ts

@@ -116,10 +116,12 @@ export type BootCheckContext = {
 };
 export type BootCheckFn = (ctx: BootCheckContext) => void;
 /** runProdApp options a stack can depend on; runProdApp checks the set at boot. */
-export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "demoMode" | "seeds" | "signals" | "rateLimit";
+export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "demoMode" | "seeds" | "signals" | "rateLimit";
 export type StackBootRequirement = {
     readonly stack: string;
     readonly options: readonly BootOptionName[];
+    /** `"warn"`: a missing option logs a boot warning instead of aborting. Default `"error"`. */
+    readonly severity?: "error" | "warn";
 };
 export type FeatureDefinition = {
     readonly name: string;

package/dist/fields.d.ts

@@ -119,8 +119,9 @@ export type TextFieldDef = {
      *  "high" on the directly-dispatched entry handler; a revert doesn't undo a
      *  run that already read the compromised value. See irreversible-operation-gate. */
     readonly readAsInstruction?: boolean;
-    /** "password" is a pure render hint (masked input) — no storage semantics. */
-    readonly format?: "email" | "url" | "phone" | "password";
+    /** "password" is a pure render hint (masked input) — no storage semantics.
+     *  "month" stores `YYYY-MM`: month picker in the form, format enforced on write. */
+    readonly format?: "email" | "url" | "phone" | "password" | "month";
     readonly default?: string;
     readonly access?: FieldAccess;
     /** Mehrzeiliger Text — DefaultInput rendert dann ein <textarea> statt

package/dist/handlers.d.ts

@@ -230,6 +230,9 @@ type SharedContextFields = {
      * absent for r.systemScope() handlers and without a db.
      */
     readonly forTenant?: (tenantId: TenantId) => TenantWriteTarget;
+    /** Mints the per-request `ctx.config`; set by the boot (`addConfigAccessorFactory`) from the effective `configResolver`, overriding an app-supplied value. */
+    readonly configAccessorFactory?: ConfigAccessorFactory;
+    /** @deprecated Use `configAccessorFactory`; the underscore name is removed in the next major. */
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.ts").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.ts").RateLimitResolver;
@@ -290,7 +293,18 @@ export type AppContext = SharedContextFields & {
 };
 export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedContextFields & {
     readonly db: TenantDb;
+    /**
+     * Same tenant scoping as `db`, but never bound to the handler's tx: writes through it survive
+     * a rollback. `undefined` only in the denial phases (member-resolution, before-transaction)
+     * and in platform-metering tenant mode; narrow with `hasOutsideTransactionDb(ctx)` or take it
+     * via `requireOutsideTransactionDb(ctx)` (`@cosmicdrift/kumiko-framework/db`). For
+     * r.systemScope() handlers it is a fail-closed Proxy; use `systemDb.outsideTransaction`.
+     */
     readonly dbOutsideTransaction: TenantDb | undefined;
+    /**
+     * @deprecated Use `runInOwnTransaction(ctx.dbOutsideTransaction, fn)` from
+     * `@cosmicdrift/kumiko-framework/db`; removed in the next major.
+     */
     readonly outsideTransaction?: <T>(fn: (db: TenantDb) => Promise<T>) => Promise<T>;
     readonly systemDb?: UncheckedSystemDb;
     readonly registry: Registry;
@@ -320,8 +334,21 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
     readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
     readonly hasFeature: (featureName: string) => Promise<boolean>;
+    /**
+     * Default append: a typed domain event on one aggregate stream in the current tx. The runtime
+     * bumps the stream version and fires matching projections in the same transaction. A version
+     * conflict throws and poisons the transaction.
+     */
     readonly appendEvent: AppendEventFn<TMap>;
+    /**
+     * Untyped append (`payload: unknown`) with the same runtime as `appendEvent`. Only for
+     * migrations and upcasters, where the event type is not knowable at compile time.
+     */
     readonly unsafeAppendEvent: UnsafeAppendEventFn;
+    /**
+     * Optimistic append: runs in a savepoint and returns a version conflict as a result instead of
+     * throwing, so the handler can continue after losing a race on the same aggregate stream.
+     */
     readonly tryAppendEvent: TryAppendEventFn;
     readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
     readonly loadAggregate: (aggregateId: string, options?: {
@@ -375,8 +402,13 @@ export type JobContext = SharedContextFields & {
     readonly triggerName?: string;
     readonly triggerEvent?: JobTriggerEvent;
     readonly _tenantId?: TenantId;
-    readonly _userId?: string | undefined;
 };
+/**
+ * What a provider plugin (`build`, `capabilitiesFor`, ...) may read. Both write/query handlers
+ * and jobs can produce one (`providerPluginContextFromHandler`, `providerPluginContextFromJob`),
+ * so a plugin never depends on a request-bound field.
+ */
+export type ProviderPluginContext = Pick<HandlerContext, "db" | "dbOutsideTransaction" | "systemDb" | "registry" | "user" | "log" | "triggeredBy" | "config" | "secrets">;
 export type WriteHandlerFn<TPayload = unknown, TData = unknown> = (event: WriteEvent<TPayload>, context: HandlerContext) => Promise<WriteResult<TData>>;
 export type QueryHandlerFn<TPayload = unknown, TResult = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => Promise<TResult>;
 export type StreamHandlerFn<TPayload = unknown, TChunk = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => AsyncGenerator<TChunk>;

package/dist/nav-icon.js

@@ -4,7 +4,7 @@
 // r.nav()/r.screen()/config-mask/button call site instead of a silent
 // missing-icon at runtime.
 //
-// The renderer-web NAV_ICONS map (packages/renderer-web/src/icons.tsx) is
+// The renderer/web NAV_ICONS map (packages/renderer/src/web/icons.tsx) is
 // checked against this same union via `satisfies`, so the two can't drift —
 // add a key here only together with its lucide-react entry there, and vice
 // versa.

package/dist/screen.d.ts

@@ -200,7 +200,7 @@ export type RowActionWriteHandler = {
     readonly style?: "primary" | "secondary" | "danger";
     /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
-     *  (renderer-web), analogous to EditFieldSpec.icon. */
+     *  (renderer/web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
     /** Inline render form in the row-action column — see `RowActionDisplay`. */
     readonly display?: RowActionDisplay;
@@ -244,7 +244,7 @@ export type RowActionNavigateBase = {
     readonly rowClick?: boolean;
     /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
-     *  (renderer-web), analogous to EditFieldSpec.icon. */
+     *  (renderer/web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
     /** Inline render form in the row-action column — see `RowActionDisplay`. */
     readonly display?: RowActionDisplay;
@@ -282,7 +282,7 @@ export type RowActionDrawer = {
     readonly style?: "primary" | "secondary" | "danger";
     /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
-     *  (renderer-web), analogous to EditFieldSpec.icon. */
+     *  (renderer/web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
     /** Inline render form in the row-action column — see `RowActionDisplay`. */
     readonly display?: RowActionDisplay;
@@ -1056,7 +1056,7 @@ export type EditFieldSpec = string | {
      *  rendering are unchanged. */
     readonly submit?: false;
     /** Prefix icon on the input — closed FieldIconKey vocabulary into
-     *  the FIELD_ICONS registry (renderer-web), analogous to
+     *  the FIELD_ICONS registry (renderer/web), analogous to
      *  `ScreenNavSugar.icon` / NavIconKey. Only takes effect for
      *  single-line `type: "text"` and `"number"` — a `text` field with
      *  `multiline` routes to a textarea (no icon slot), and other input
@@ -1151,7 +1151,7 @@ export type EditFieldsSection = {
         readonly columns?: number;
     }[];
     /** Rendered left of the section title, `text-muted-foreground` — closed
-     *  IconKey vocabulary into the ICONS registry (renderer-web), analogous
+     *  IconKey vocabulary into the ICONS registry (renderer/web), analogous
      *  to EditFieldSpec.icon. No title → no icon, and no heuristic derives
      *  one from the title (titles are free i18n strings). */
     readonly icon?: IconKey;
@@ -1612,6 +1612,10 @@ export type ActionFormScreenDefinition = {
      *  handler's success payload); a link without a string id is hidden.
      *  Mutually exclusive with `redirect`. */
     readonly successLinks?: readonly ActionFormSuccessLink[];
+    /** Key figures from the handler's success payload, shown in the success box
+     *  while the screen stays put (e.g. charged/skipped/failed of a batch run).
+     *  Mutually exclusive with `redirect`. */
+    readonly successFacts?: readonly ActionFormSuccessFact[];
     /** 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`. */
@@ -1677,6 +1681,15 @@ export type ActionFormLoad = {
     /** Payload key carrying the record id (default "id"). */
     readonly idParam?: string;
 };
+/** One key figure of the success box, read from the handler's success payload. */
+export type ActionFormSuccessFact = {
+    /** Flat field name in the handler's success payload. A number or string is
+     *  shown as one value, an array a comma-separated list (numbers, strings and
+     *  `{ label }` objects). A missing field hides the fact. */
+    readonly field: string;
+    /** Label (i18n key). */
+    readonly label: 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

package/dist/target-ref.js

@@ -1,5 +1,5 @@
 // TargetRef — runtime-Repräsentation eines typed buildTarget-Outputs.
-// Wird vom Visual-Tree-Component (renderer-web) an einen Target-Resolver
+// Wird vom Visual-Tree-Component (renderer/web) an einen Target-Resolver
 // dispatcht; der Resolver findet die Editor-Maske via featureId.
 //
 // **Compile-time-Safety:** TargetRef wird niemals hand-getippt. Stattdessen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.374.0",
+  "version": "0.377.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>",

package/src/changes.json

@@ -1,4 +1,24 @@
 [
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "outsideTransaction deprecated, ProviderPluginContext added",
+    "detail": "HandlerContext.outsideTransaction is marked deprecated; use runInOwnTransaction(ctx.dbOutsideTransaction, fn). ProviderPluginContext is a Pick of HandlerContext for provider plugins. SharedContextFields gains configAccessorFactory; _configAccessorFactory stays as a deprecated alias. dbOutsideTransaction stays TenantDb | undefined (undefined only in the member-resolution and before-transaction denial phases and in platform-metering tenant mode); hasOutsideTransactionDb(ctx) narrows it and requireOutsideTransactionDb(ctx) throws when it is missing.",
+    "migration": "Replace ctx.outsideTransaction(fn) with runInOwnTransaction(ctx.dbOutsideTransaction, fn). Read configAccessorFactory instead of _configAccessorFactory."
+  },
+  {
+    "version": "0.377.0",
+    "type": "breaking",
+    "title": "JobContext._userId removed",
+    "detail": "The job runner never set JobContext._userId; only user-data-rights read it, falling back to SYSTEM_USER_ID. Hand-built JobContext objects that still set it fail to type-check, and code that read it must use SYSTEM_USER_ID or the job's system user.",
+    "migration": "Drop _userId from hand-built JobContext objects (tests, job helpers) and replace reads of ctx._userId with SYSTEM_USER_ID. Known hits - money-horse data-export integration test, offlot-app channel-text generate-texts.job.ts."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "StackBootRequirement severity and the featureToggles option name",
+    "detail": "StackBootRequirement takes severity \"warn\" for requirements that only log, and BootOptionName lists featureToggles."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",