@cosmicdrift/kumiko-types 0.361.0 → 0.363.0

package/dist/config.d.ts

@@ -183,14 +183,64 @@ export type NotificationRecipientFn = (result: import("./hooks.js").SaveContext)
 } | null;
 export type NotificationDataFn = (result: import("./hooks.js").SaveContext) => Record<string, unknown>;
 export type NotificationTemplateFn = (data: Record<string, unknown>) => Record<string, unknown>;
+type TemplateVariableCommon = {
+    readonly label?: string;
+    readonly required?: boolean;
+};
+export type TemplateScalarVariableDef = (TemplateVariableCommon & {
+    readonly type: "text";
+    readonly example?: string;
+}) | (TemplateVariableCommon & {
+    readonly type: "link";
+    readonly example?: string;
+}) | (TemplateVariableCommon & {
+    readonly type: "money";
+    readonly example?: number | {
+        readonly amount: number;
+        readonly currency: string;
+    };
+}) | (TemplateVariableCommon & {
+    readonly type: "date";
+    readonly example?: string;
+});
+export type TemplateListVariableDef = TemplateVariableCommon & {
+    readonly type: "list";
+    readonly item: Readonly<Record<string, TemplateScalarVariableDef>>;
+    readonly example?: readonly Readonly<Record<string, unknown>>[];
+};
+export type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef;
+export type TemplateVariables = Readonly<Record<string, TemplateVariableDef>>;
+export type NotificationTemplateMeta = {
+    readonly subject: string;
+    readonly previewText?: string;
+    readonly layoutSlug?: string;
+    readonly category?: "transactional" | "marketing";
+    readonly sender?: string;
+};
+export type NotificationTemplateBody = {
+    readonly body: string;
+};
+export type NotificationLocalizedTemplate = Readonly<Record<string, {
+    readonly body: string;
+    readonly meta: NotificationTemplateMeta;
+}>>;
+export type NotificationRecordMapping = {
+    readonly entity: string;
+    readonly map: Readonly<Record<string, string>>;
+};
 export type NotificationDefinition = {
     readonly name: string;
-    readonly trigger: {
+    readonly trigger?: {
         readonly on: string;
     };
-    readonly recipient: NotificationRecipientFn;
-    readonly data: NotificationDataFn;
+    readonly recipient?: NotificationRecipientFn;
+    readonly data?: NotificationDataFn;
     readonly templates: Readonly<Record<string, NotificationTemplateFn>> | undefined;
+    readonly variables?: TemplateVariables;
+    readonly record?: NotificationRecordMapping;
+    readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+    readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+    readonly localizedTemplate?: () => NotificationLocalizedTemplate;
 };
 export type PluralForms = {
     readonly zero?: string;
@@ -259,3 +309,4 @@ export type CreateUserSeedOptions = {
     readonly tenantId: string;
     readonly userId: string;
 };
+export {};

package/dist/feature.d.ts

@@ -1,6 +1,6 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
-import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys, TranslationsDef } from "./config.js";
+import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TemplateVariables, TranslationKeys, TranslationsDef } from "./config.js";
 import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { EntityTableMeta } from "./entity-table-meta-types.js";
@@ -296,21 +296,31 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
     job(definition: JobDefinition): void;
     notification(name: string, definition: {
-        readonly trigger: {
+        readonly trigger?: {
             readonly on: NameOrRef;
         };
-        readonly recipient: NotificationRecipientFn;
-        readonly data: NotificationDataFn;
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
         readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
     }): void;
     notification(definition: {
         readonly name: string;
-        readonly trigger: {
+        readonly trigger?: {
             readonly on: NameOrRef;
         };
-        readonly recipient: NotificationRecipientFn;
-        readonly data: NotificationDataFn;
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
         readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: {

package/dist/handlers.d.ts

@@ -157,16 +157,26 @@ export type NotifyDelivery = {
     readonly confirmed?: false;
     readonly deliveryAttemptId?: string;
 };
-export type NotifyResult = {
+export type NotifyDispatched = {
+    readonly kind: "dispatched";
     readonly deliveries: readonly NotifyDelivery[];
 };
-export type NotifyFn = (notificationType: string, options: NotifyOptions) => Promise<NotifyResult>;
+export type NotifyDeferred = {
+    readonly kind: "deferred";
+};
+export type NotifyResult = NotifyDispatched | NotifyDeferred;
+export type NotifyFn = {
+    (notificationType: string, options: NotifyOptions & {
+        readonly immediate: true;
+    }): Promise<NotifyDispatched>;
+    (notificationType: string, options: NotifyOptions): Promise<NotifyResult>;
+};
 export type NotifyJobDispatcher = {
     dispatch(jobName: string, payload: Record<string, unknown>, meta?: {
         readonly priority?: number;
     }): Promise<unknown>;
 };
-export type NotifyFactory = (user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher) => NotifyFn;
+export type NotifyFactory = (user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher, deliveryDb?: DbConnection, fileProviderResolver?: FileProviderResolver) => NotifyFn;
 export type EscapeHatchKind = "unsafe-raw" | "acknowledge-cross-tenant" | "global-write" | "identity-switch" | "unsafe-all-tenants" | "cross-tenant-read";
 export type EscapeHatchTarget = {
     readonly id: string;
@@ -221,6 +231,7 @@ type SharedContextFields = {
     readonly entityCache?: EntityCache;
     readonly notify?: NotifyFn;
     readonly _notifyFactory?: NotifyFactory;
+    readonly _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
     readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly secrets?: import("./secrets-types.js").SecretsContext;
     readonly masterKeyProvider?: import("./secrets-types.js").MasterKeyProvider;

package/dist/kms-adapter-types.js

@@ -34,7 +34,7 @@ export function subjectIdFromKey(key) {
     if (key.startsWith("user:"))
         return { kind: "user", userId: key.slice("user:".length) };
     if (key.startsWith("tenant:")) {
-        return { kind: "tenant", tenantId: key.slice("tenant:".length) }; // @cast-boundary parse of a key this module minted
+        return { kind: "tenant", tenantId: key.slice("tenant:".length) };
     }
     if (key.startsWith("record:")) {
         const rest = key.slice("record:".length);

package/dist/nav.d.ts

@@ -18,7 +18,7 @@ export type NavDefinition = {
     readonly workspaces?: readonly string[];
 };
 /** Client editor format for r.contentCollection() — not template body storage formats. */
-export type ContentEditorFormat = "plain" | "rich" | "markdown";
+export type ContentEditorFormat = "plain" | "rich" | "markdown" | "document";
 export type ContentCollectionDefinition = {
     readonly id: string;
     readonly kind: string;

package/dist/screen.d.ts

@@ -411,6 +411,8 @@ export type EntityListScreenDefinition = {
     readonly createScreen?: string;
     /** Set by the role projection when `createScreen` is not reachable for the role: the renderer then shows no create button instead of falling back to the entity's edit screen. Not for app authors. */
     readonly createUnavailable?: boolean;
+    /** `false` hides this list's "+ New" button (and the empty-state create CTA) while the entity's edit screen keeps its create branch for other entry points, e.g. a prefilled action. Default `true`. */
+    readonly allowCreate?: boolean;
     readonly columns: readonly ListColumnSpec[];
     readonly rowRenderer?: PlatformComponent;
     readonly cardRenderer?: PlatformComponent;
@@ -732,7 +734,7 @@ export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate
     /** Formats a numeric value as currency (minor units); 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?: "default" | "positive" | "warn" | "negative";
+    readonly tone?: "default" | "positive" | "ok" | "warn" | "negative";
     /** Record field holding `{ atMs, value | null }[]` (MetricResult.points),
      *  drawn as a sparkline next to the value. */
     readonly sparklineField?: string;

package/dist/type-guards.d.ts

@@ -0,0 +1,8 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Membership test that narrows `candidate` to the element union of a const tuple. */
+export declare function isOneOf<const T extends readonly unknown[]>(values: T, candidate: unknown): candidate is T[number];
+/** Reads a string `code` (e.g. Node `ErrnoException`, Postgres SQLSTATE) off an unknown thrown value. */
+export declare function errorCodeOf(error: unknown): string | undefined;
+/** Reads one property off an unknown value (object or function); undefined for primitives, null and absent keys. */
+export declare function propertyOf(value: unknown, key: PropertyKey): unknown;

package/dist/type-guards.js

@@ -0,0 +1,21 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Membership test that narrows `candidate` to the element union of a const tuple. */
+export function isOneOf(values, candidate) {
+    return values.some((value) => value === candidate);
+}
+/** Reads a string `code` (e.g. Node `ErrnoException`, Postgres SQLSTATE) off an unknown thrown value. */
+export function errorCodeOf(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return undefined;
+    return typeof error.code === "string" ? error.code : undefined;
+}
+/** Reads one property off an unknown value (object or function); undefined for primitives, null and absent keys. */
+export function propertyOf(value, key) {
+    if ((typeof value !== "object" && typeof value !== "function") || value === null) {
+        return undefined;
+    }
+    return Reflect.get(value, key);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.361.0",
+  "version": "0.363.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>",
@@ -26,6 +26,10 @@
       "types": "./dist/identifiers.d.ts",
       "default": "./dist/identifiers.js"
     },
+    "./type-guards": {
+      "types": "./dist/type-guards.d.ts",
+      "default": "./dist/type-guards.js"
+    },
     "./session-cookies": {
       "types": "./dist/session-cookies.d.ts",
       "default": "./dist/session-cookies.js"
@@ -297,6 +301,10 @@
         "types": "./dist/identifiers.d.ts",
         "default": "./dist/identifiers.js"
       },
+      "./type-guards": {
+        "types": "./dist/type-guards.d.ts",
+        "default": "./dist/type-guards.js"
+      },
       "./session-cookies": {
         "types": "./dist/session-cookies.d.ts",
         "default": "./dist/session-cookies.js"

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "EntityListScreenDefinition.allowCreate",
+    "detail": "allowCreate false hides the list's create button and empty-state create action; the entity's edit screen keeps its create branch."
+  },
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "Stat tone \"ok\"",
+    "detail": "DashboardStatPanel.tone accepts \"ok\" for a status-green value."
+  },
   {
     "version": "0.361.0",
     "type": "improvement",