@cosmicdrift/kumiko-types 0.342.0 → 0.343.0

package/dist/handlers.d.ts

@@ -13,7 +13,7 @@ import type { GeoTzProvider } from "./geo-tz.js";
 import type { Logger } from "./logger.js";
 import type { Meter, MetricsHandle, Tracer } from "./observability/index.js";
 import type { SearchAdapter } from "./search-adapter.js";
-import type { TenantDb } from "./tenant-db-types.js";
+import type { CrossTenantReads, TenantDb } from "./tenant-db-types.js";
 import type { TzContext } from "./tz-context.js";
 export type OpenToAllPersonalData = "tenant-members";
 export type OpenToAllDeclaration = {
@@ -140,11 +140,20 @@ export type NotifyOptions = {
     readonly locale?: string;
 };
 export type NotifyDeliveryStatus = "queued" | "sent" | "failed" | "skipped";
+export declare const DELIVERY_FAILURE_CODES: readonly ["timeout", "network_error", "redirect_blocked", "host_not_allowed", "missing_credentials", "invalid_address", "unexpected_response", "render_failed", "send_failed", "channel_error"];
+export declare const DELIVERY_SKIP_REASONS: readonly ["channel_disabled", "preference_disabled", "rate_limited", "no_address", "unsubscribed", "duplicate_idempotency_key"];
+export type DeliveryFailureCode = (typeof DELIVERY_FAILURE_CODES)[number];
+export type DeliverySkipReason = (typeof DELIVERY_SKIP_REASONS)[number];
+export type DeliveryErrorCode = DeliveryFailureCode | DeliverySkipReason | `http_${number}`;
+export type ChatSendFailureCode = `http_${number}` | Exclude<DeliveryFailureCode, "render_failed" | "send_failed" | "channel_error">;
+export declare const HTTP_ERROR_CODE_PATTERN: RegExp;
+export declare function isDeliveryErrorCode(value: unknown): value is DeliveryErrorCode;
 export type NotifyDelivery = {
     readonly channel: string;
     readonly recipientId: string | null;
     readonly status: NotifyDeliveryStatus;
-    readonly error: string | null;
+    readonly error: DeliveryErrorCode | null;
+    readonly confirmed?: false;
     readonly deliveryAttemptId?: string;
 };
 export type NotifyResult = {
@@ -157,7 +166,7 @@ export type NotifyJobDispatcher = {
     }): Promise<unknown>;
 };
 export type NotifyFactory = (user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher) => NotifyFn;
-export type EscapeHatchKind = "unsafe-raw" | "acknowledge-cross-tenant" | "global-write" | "identity-switch" | "unsafe-all-tenants";
+export type EscapeHatchKind = "unsafe-raw" | "acknowledge-cross-tenant" | "global-write" | "identity-switch" | "unsafe-all-tenants" | "cross-tenant-read";
 export type EscapeHatchTarget = {
     readonly id: string;
     readonly tenantId: TenantId;
@@ -315,6 +324,7 @@ export type JobContext = SharedContextFields & {
     readonly attempt: number;
     readonly finalAttempt: boolean;
     readonly systemDb?: UncheckedSystemDb;
+    readonly crossTenantReads?: CrossTenantReads;
     readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
     readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
     readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;

package/dist/handlers.js

@@ -57,6 +57,37 @@ export function isUiAccessGranted(access, userRoles) {
         return false;
     return access.roles.some((role) => userRoles.includes(role));
 }
+// Closed vocabulary for delivery failures and skips. Only these values (plus
+// `http_<status>`) are ever stored or returned as a delivery error, never a raw
+// error message: provider errors can carry URLs, tokens and addresses.
+export const DELIVERY_FAILURE_CODES = [
+    "timeout",
+    "network_error",
+    "redirect_blocked",
+    "host_not_allowed",
+    "missing_credentials",
+    "invalid_address",
+    "unexpected_response",
+    "render_failed",
+    "send_failed",
+    "channel_error",
+];
+export const DELIVERY_SKIP_REASONS = [
+    "channel_disabled",
+    "preference_disabled",
+    "rate_limited",
+    "no_address",
+    "unsubscribed",
+    "duplicate_idempotency_key",
+];
+export const HTTP_ERROR_CODE_PATTERN = /^http_(\d{3})$/;
+export function isDeliveryErrorCode(value) {
+    if (typeof value !== "string")
+        return false;
+    return (HTTP_ERROR_CODE_PATTERN.test(value) ||
+        DELIVERY_FAILURE_CODES.some((code) => code === value) ||
+        DELIVERY_SKIP_REASONS.some((reason) => reason === value));
+}
 export function normalizeEventPiiSubject(spec) {
     if ("subjectField" in spec) {
         return { kind: "user", ownerField: spec.subjectField, whenAbsent: undefined };

package/dist/screen.d.ts

@@ -396,6 +396,10 @@ export type EntityListScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     readonly entity: string;
     /** Short screen id (same feature) the create button opens instead of the entity's default edit screen. */
     readonly createScreen?: string;
@@ -501,6 +505,10 @@ export type ProjectionListScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     readonly query: string;
     readonly columns: readonly ListColumnSpec[];
     readonly rowRenderer?: PlatformComponent;
@@ -591,6 +599,10 @@ export type ProjectionDetailScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     readonly query: string;
     /** Query output field whose value titles the page header (breadcrumb) when no `header` is set. */
     readonly recordTitleField?: string;
@@ -789,6 +801,10 @@ export type DashboardScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** 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[];
     readonly filter?: DashboardFilterDefinition;
     /** Segmented control in the toolbar; the value lives in URL search param
@@ -1119,6 +1135,10 @@ export type EntityEditScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     /** Derived by buildAppSchema from the navigate `params` targeting this
      *  screen — the only URL query keys the create form prefills. An authored
      *  value is overwritten. */
@@ -1211,6 +1231,10 @@ export type ActionFormScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     /** Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields. */
     readonly urlPrefillFields?: readonly string[];
     /** Write-Handler-QN der bei Submit gerufen wird. Form-Object landet
@@ -1369,6 +1393,10 @@ export type SecretMintScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     /** Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields. */
     readonly urlPrefillFields?: readonly string[];
     /** Write-handler QN dispatched on submit. */
@@ -1418,6 +1446,10 @@ export type CustomScreenDefinition = {
      *  triggering the diagnostic if it's missing. Also gates the
      *  boot-validator's nav-area check, same as `dormant` on other screens. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
 };
 export type ConfigEditScreenDefinition = {
     readonly id: string;
@@ -1432,6 +1464,10 @@ export type ConfigEditScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     /** scope für config:write:set Calls. Muss zur Scope-Deklaration der
      *  in `configKeys` referenzierten Keys passen — Boot-Validator
      *  prüft das gegen die Registry. */
@@ -1478,6 +1514,10 @@ export type SecretsEditScreenDefinition = {
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
+    /** UI-only gate, also on direct URL access; handlers still enforce access. Unmet or failed renders `fallback`. */
+    readonly visibleWhen?: DashboardPanelVisibility;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice). */
+    readonly fallback?: string;
     /** field id -> qualified secret name (`<feature>:secret:<kebab>`). */
     readonly secretKeys: Readonly<Record<string, string>>;
     /** field id -> i18n key for the label. */

package/dist/tenant-db-types.d.ts

@@ -29,6 +29,7 @@ export type GlobalTableDb<TTable> = GlobalReads & (TTable extends ExecutorOnly ?
  * Tables without a tenantId column are always unfiltered regardless of mode.
  */
 export type TenantDbMode = "tenant" | "system";
+export type CrossTenantReads = Pick<TenantDb, "selectMany" | "fetchOne" | "count">;
 export type TenantDb = {
     readonly tenantId: TenantId;
     readonly mode: TenantDbMode;

package/package.json

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