@cosmicdrift/kumiko-types 0.336.1 → 0.338.0

package/dist/config.d.ts

@@ -25,6 +25,14 @@ export type ConfigComputedContext = {
     readonly db: DbConnection | TenantDb;
 };
 export type ConfigComputedFn<T extends ConfigKeyType = ConfigKeyType> = (ctx: ConfigComputedContext) => Promise<ConfigValue<T>>;
+export type ConfigValidateContext = {
+    readonly key: string;
+    readonly scope: ConfigScope;
+    readonly tenantId: TenantId;
+    readonly userId: string | null;
+    readonly db: DbConnection | TenantDb;
+};
+export type ConfigValidateFn<T extends ConfigKeyType = ConfigKeyType> = (value: ConfigValue<T>, ctx: ConfigValidateContext) => Promise<void>;
 export type ConfigBacking = "config" | "secrets";
 export type ConfigSecretsReader = {
     get(tenantId: TenantId, key: string): Promise<{
@@ -60,6 +68,7 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
         readonly flags?: string;
     };
     readonly computed?: ConfigComputedFn<T>;
+    readonly validate?: ConfigValidateFn<T>;
     readonly allowPerRequest?: boolean;
     readonly required?: boolean;
     readonly env?: string;

package/dist/feature.d.ts

@@ -39,8 +39,27 @@ export type SecretKeyDefinition = {
     };
     readonly scope: "tenant";
     readonly required?: boolean;
+    readonly writeRoles?: readonly string[];
 };
 export type SecretOptions = Omit<SecretKeyDefinition, "shortName" | "qualifiedName">;
+export type SecretNamespaceDefinition = {
+    readonly shortName: string;
+    readonly qualifiedPrefix: string;
+    readonly label: {
+        readonly [locale: string]: string;
+    };
+    readonly hint?: {
+        readonly [locale: string]: string;
+    };
+    readonly scope: "tenant";
+    readonly writeRoles?: readonly string[];
+    readonly nameSchema?: ZodType<string>;
+};
+export type SecretNamespaceOptions = Omit<SecretNamespaceDefinition, "shortName" | "qualifiedPrefix">;
+export type SecretNamespaceHandle = {
+    readonly prefix: string;
+    keyFor(name: string): string;
+};
 export type SecretKeyHandle = {
     readonly name: string;
 };
@@ -150,6 +169,7 @@ export type FeatureDefinition = {
     readonly handlerEntityMappings: Readonly<Record<string, string>>;
     readonly metrics: Readonly<Record<string, FeatureMetricDef>>;
     readonly secretKeys: Readonly<Record<string, SecretKeyDefinition>>;
+    readonly secretNamespaces: Readonly<Record<string, SecretNamespaceDefinition>>;
     readonly projections: Readonly<Record<string, ProjectionDefinition>>;
     readonly entityProjectionExtensions?: Readonly<Record<string, readonly EntityProjectionExtension[]>>;
     readonly multiStreamProjections: Readonly<Record<string, MultiStreamProjectionDefinition>>;
@@ -409,6 +429,10 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     secret(definition: {
         readonly name: string;
     } & SecretOptions): SecretKeyHandle;
+    secretNamespace(shortName: string, options: SecretNamespaceOptions): SecretNamespaceHandle;
+    secretNamespace(definition: {
+        readonly name: string;
+    } & SecretNamespaceOptions): SecretNamespaceHandle;
     projection(definition: ProjectionDefinition): void;
     multiStreamProjection(definition: MultiStreamProjectionDefinition): void;
     extendEntityProjection(entityName: string, extension: EntityProjectionExtension): void;
@@ -485,6 +509,7 @@ export type Registry = {
     getAllConfigSeeds(): readonly ConfigSeedDef[];
     getAllSecretKeys(): ReadonlyMap<string, SecretKeyDefinition>;
     getSecretKey(qualifiedName: string): SecretKeyDefinition | undefined;
+    findSecretNamespace(key: string): SecretNamespaceDefinition | undefined;
     getJob(qualifiedName: string): JobDefinition | undefined;
     getAllJobs(): ReadonlyMap<string, JobDefinition>;
     getEvent(qualifiedName: string): EventDef | undefined;

package/dist/handlers.d.ts

@@ -28,9 +28,18 @@ export type RoleAccessRule = {
     readonly personalData?: RoleAccessPersonalData;
 };
 export type AccessRule = RoleAccessRule | OpenToAllAccessRule;
+export declare const ESCAPE_HATCH_GRANTS: readonly ["systemIdentity", "globalWrites", "unsafeRaw"];
+export type EscapeHatchGrant = (typeof ESCAPE_HATCH_GRANTS)[number];
 export type EscapeHatchDeclaration = {
     readonly reason: string;
-};
+    readonly grants?: readonly EscapeHatchGrant[];
+};
+export declare function isEscapeHatchGrant(value: unknown): value is EscapeHatchGrant;
+export declare function escapeHatchAllows(declaration: EscapeHatchDeclaration | undefined, grant: EscapeHatchGrant): boolean;
+export declare function escapeHatchFor(declaration: EscapeHatchDeclaration | undefined, grant: EscapeHatchGrant): EscapeHatchDeclaration | undefined;
+export declare function escapeHatchGrantsProblem(declaration: {
+    readonly grants?: unknown;
+}): string | undefined;
 export declare function isOpenToAllGranted(rule: AccessRule): boolean;
 export declare function isUiAccessGranted(access: AccessRule | undefined, userRoles: readonly string[] | undefined): boolean;
 export type SessionUserOrigin = "member-resolution";
@@ -149,6 +158,14 @@ type SharedContextFields = {
     readonly jobRunner?: JobRunnerRef;
     readonly configResolver?: ConfigResolver;
     readonly config?: ConfigAccessor;
+    /**
+     * Config accessor resolved for ANOTHER tenant, identity = that tenant's system
+     * user (the caller's user-scope config never leaks in). Cross-tenant calls
+     * throw AccessDeniedError unless the caller is a system identity or has the
+     * SystemAdmin role; the caller's own tenant needs no privilege. Present when
+     * the config feature wired its accessor factory.
+     */
+    readonly configFor?: (tenantId: TenantId) => ConfigAccessor;
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.js").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.js").RateLimitResolver;

package/dist/handlers.js

@@ -1,3 +1,31 @@
+export const ESCAPE_HATCH_GRANTS = ["systemIdentity", "globalWrites", "unsafeRaw"];
+export function isEscapeHatchGrant(value) {
+    return ESCAPE_HATCH_GRANTS.some((grant) => grant === value);
+}
+export function escapeHatchAllows(declaration, grant) {
+    if (declaration === undefined)
+        return false;
+    return declaration.grants === undefined || declaration.grants.includes(grant);
+}
+// Returns the declaration only when it unlocks `grant`, so call sites keep passing
+// "a declaration or nothing" into grant-gated code.
+export function escapeHatchFor(declaration, grant) {
+    return escapeHatchAllows(declaration, grant) ? declaration : undefined;
+}
+// Boot-time check of `grants` (untyped sources can carry anything): must be a non-empty list of known grants.
+export function escapeHatchGrantsProblem(declaration) {
+    const { grants } = declaration;
+    if (grants === undefined)
+        return undefined;
+    if (!Array.isArray(grants) || grants.length === 0) {
+        return `grants must be a non-empty list of: ${ESCAPE_HATCH_GRANTS.join(", ")}`;
+    }
+    const unknownGrant = grants.find((grant) => !isEscapeHatchGrant(grant));
+    if (unknownGrant !== undefined) {
+        return `unknown grant ${JSON.stringify(unknownGrant)} — allowed: ${ESCAPE_HATCH_GRANTS.join(", ")}`;
+    }
+    return undefined;
+}
 // AccessRule can arrive from untyped sources (pattern-library JSON, Designer)
 // where `openToAll` doesn't actually match the declared union — narrow via
 // `unknown` instead of trusting the static type, deny on anything malformed.

package/dist/screen.d.ts

@@ -920,13 +920,17 @@ export type RelatedListGroupBy = {
     readonly collapsedWhen?: string | number | boolean | null;
     /** i18n key of the group header. Placeholders: `{count}` rows in the group,
      *  `{value}` the group's field value, `{lastDate}` the group's latest
-     *  `dateField` value as a locale date. */
-    readonly label: string;
+     *  `dateField` value as a locale date. A group with neither `label` nor an
+     *  entry in `labels` renders its rows without a header and never collapses. */
+    readonly label?: string;
     /** Header i18n key per group value (as string), overriding `label`. */
     readonly labels?: Readonly<Record<string, string>>;
     /** Row field (ISO date or timestamp) behind `{lastDate}`. */
     readonly dateField?: string;
 };
+/** Group key of a field value; `collapsedWhen` and row values both go through it. */
+export declare function relatedListGroupKey(value: unknown): string;
+export declare function relatedListGroupHeaderLabel(groupBy: RelatedListGroupBy, groupKey: string): string | undefined;
 /** Row tint rule: rows where the `FieldCondition` (`{ field, eq }`, `{ field,
  *  in }` …) holds get the tone. `bad` renders red. */
 export type RelatedListRowTone = Exclude<FieldCondition, boolean> & {
@@ -1482,6 +1486,10 @@ export type SecretsEditScreenDefinition = {
     readonly fieldHints?: Readonly<Record<string, string>>;
     /** field ids whose declaration set `required: true`. */
     readonly requiredFields?: readonly string[];
+    /** field id -> write access derived from the key's `writeRoles`. The screen
+     *  hides fields the viewer fails; UI only, the secrets write gate stays
+     *  authoritative. */
+    readonly fieldAccess?: Readonly<Record<string, AccessRule>>;
     readonly sections: readonly SecretsEditSection[];
     readonly access?: AccessRule;
 };

package/dist/screen.js

@@ -1,3 +1,11 @@
 export function metricField(metric) {
     return typeof metric === "string" ? metric : metric.field;
 }
+/** 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);
+}
+export function relatedListGroupHeaderLabel(groupBy, groupKey) {
+    const labels = groupBy.labels;
+    return labels !== undefined && Object.hasOwn(labels, groupKey) ? labels[groupKey] : groupBy.label;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.336.1",
+  "version": "0.338.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,18 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "ctx.configFor on the handler context types",
+    "detail": "`configFor?: (tenantId: TenantId) => ConfigAccessor` is part of the shared handler context fields, optional like `config`.",
+    "migration": "No code change needed."
+  },
+  {
+    "version": "0.337.0",
+    "type": "improvement",
+    "title": "relatedList groupBy.label is optional; groups without a header show their rows directly",
+    "detail": "`RelatedListGroupBy.label` is optional. The header key of a group is `labels[value] ?? label`; a group without one renders its rows without a header row and never collapses. `relatedListGroupKey` and `relatedListGroupHeaderLabel` resolve the group key and its header key; `collapsedWhen: null` now matches rows whose field is empty.",
+    "migration": "No code change needed. To hide a header, drop `label` and name only the groups that keep one in `labels`, for example `{ field: \"status\", collapsedWhen: \"done\", labels: { done: \"<key>\" } }`."
+  },
   {
     "version": "0.336.0",
     "type": "improvement",