@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/dist/event-store-executor-types.d.ts

@@ -0,0 +1,86 @@
+import type { CursorResult } from "./cursor-types.js";
+import type { EntityDefinition } from "./fields.js";
+import type { SessionUser, WriteResult } from "./handlers.js";
+import type { DeleteContext, SaveContext } from "./hooks.js";
+import type { EntityId } from "./identifiers.js";
+import type { SearchAdapter } from "./search-adapter.js";
+import type { TenantDb } from "./tenant-db-types.js";
+export type ParentVisibilityOption = {
+    readonly entities: ReadonlyMap<string, EntityDefinition>;
+};
+export type PreSaveRunner = (changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
+export type EventStoreExecutor = {
+    create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: {
+        preSave?: PreSaveRunner;
+    }) => Promise<WriteResult<SaveContext>>;
+    update: (payload: {
+        id: EntityId;
+        version?: number | undefined;
+        changes: Record<string, unknown>;
+    }, user: SessionUser, db: TenantDb, options?: {
+        skipOptimisticLock?: boolean;
+        skipUnchanged?: boolean;
+        preSave?: PreSaveRunner;
+        expect?: Readonly<Record<string, string | number | boolean | null>>;
+    }) => Promise<WriteResult<SaveContext>>;
+    delete: (payload: {
+        id: EntityId;
+    }, user: SessionUser, db: TenantDb) => Promise<WriteResult<DeleteContext>>;
+    forget: (payload: {
+        id: EntityId;
+    }, user: SessionUser, db: TenantDb) => Promise<WriteResult<DeleteContext>>;
+    restore: (payload: {
+        id: EntityId;
+    }, user: SessionUser, db: TenantDb) => Promise<WriteResult<SaveContext>>;
+    list: (payload: {
+        cursor?: string | undefined;
+        limit?: number | undefined;
+        search?: string | undefined;
+        sort?: string | undefined;
+        sortDirection?: "asc" | "desc" | undefined;
+        offset?: number | undefined;
+        totalCount?: boolean | undefined;
+        filter?: {
+            readonly field: string;
+            readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+            readonly value: unknown;
+        } | undefined;
+        filters?: ReadonlyArray<{
+            readonly field: string;
+            readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+            readonly value: unknown;
+        }> | undefined;
+    }, user: SessionUser, db: TenantDb, 
+    /** Tier 2.7e audit fix: per-call SearchAdapter override. When the
+     *  executor didn't get a SearchAdapter via Options at build time
+     *  (defaultEntityQueryHandler path), the caller (handler) can pass
+     *  one from ctx.searchAdapter here at runtime.
+     *  options.searchAdapter (build-time) wins — the runtime override
+     *  is the fallback for the default wrapper. */
+    runtimeOptions?: {
+        readonly searchAdapter?: SearchAdapter;
+        readonly includeDeleted?: boolean;
+        readonly referenceSearch?: {
+            readonly fields: ReadonlyArray<{
+                readonly fieldName: string;
+                readonly targetEntityName: string;
+                readonly labelField: string;
+            }>;
+            readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+        };
+        readonly referenceSort?: {
+            readonly fields: ReadonlyArray<{
+                readonly fieldName: string;
+                readonly targetEntityName: string;
+                readonly labelField: string;
+            }>;
+            readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+        };
+        readonly parentVisibility?: ParentVisibilityOption;
+    }) => Promise<CursorResult<Record<string, unknown>>>;
+    detail: (payload: {
+        id: EntityId;
+    }, user: SessionUser, db: TenantDb, options?: {
+        readonly parentVisibility?: ParentVisibilityOption;
+    }) => Promise<Record<string, unknown> | null>;
+};

package/dist/event-store-executor-types.js

@@ -0,0 +1 @@
+export {};

package/dist/event-store-types.d.ts

@@ -0,0 +1,37 @@
+import type { TenantId } from "./identifiers.js";
+export interface VersionConflict extends Error {
+    readonly aggregateId: string;
+    readonly expectedVersion: number;
+}
+export type EventMetadata = {
+    readonly userId: string;
+    readonly requestId?: string;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+    readonly idempotencyKey?: string;
+    readonly headers?: Readonly<Record<string, string | number | boolean>>;
+    readonly feature?: string;
+    readonly handler?: string;
+    readonly writeOrigin?: WriteOrigin;
+};
+export type WriteOrigin = {
+    readonly rootHandler: string;
+    readonly anonymousRoot: boolean;
+    readonly publicIntake: boolean;
+    readonly viaJob?: string;
+};
+export declare function isPersonalDataGated(origin: WriteOrigin): boolean;
+export declare const UNATTRIBUTED_ORIGIN = "unknown";
+export type StoredEvent<TPayload = Record<string, unknown>> = {
+    readonly id: string;
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly tenantId: TenantId;
+    readonly version: number;
+    readonly type: string;
+    readonly eventVersion: number;
+    readonly payload: TPayload;
+    readonly metadata: EventMetadata;
+    readonly createdAt: Temporal.Instant;
+    readonly createdBy: string;
+};

package/dist/event-store-types.js

@@ -0,0 +1,7 @@
+export function isPersonalDataGated(origin) {
+    return origin.anonymousRoot && !origin.publicIntake;
+}
+// Stamped when an append runs outside any attributed scope (seed scripts,
+// tests, direct event-store use). A distinct value, not an omission —
+// omitted would be indistinguishable from a pre-#3043 row.
+export const UNATTRIBUTED_ORIGIN = "unknown";

package/dist/event-type-map.d.ts

@@ -0,0 +1,8 @@
+export interface KumikoEventTypeMap {
+}
+export interface KumikoEntityTypeMap {
+}
+export interface KumikoHandlerPayloadMap {
+}
+export interface KumikoHandlerResultMap {
+}

package/{src/event-type-map.ts → dist/event-type-map.js}

@@ -19,19 +19,4 @@
 //       "users:user.created": z.infer<typeof userCreatedSchema>;
 //     }
 //   }
-
-// MUST be `interface` (not `type`): only interfaces support TS declaration-
-// merging. Apps/features extend these via `declare module "@cosmicdrift/kumiko-framework/engine"`
-// blocks. A `type X = {}` alias would silently break that augmentation channel.
-
-// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker — augmented per feature
-export interface KumikoEventTypeMap {}
-
-// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker
-export interface KumikoEntityTypeMap {}
-
-// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker
-export interface KumikoHandlerPayloadMap {}
-
-// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker
-export interface KumikoHandlerResultMap {}
+export {};

package/dist/executor-brand.d.ts

@@ -0,0 +1,8 @@
+declare const EXECUTOR_ONLY: unique symbol;
+export interface ExecutorOnly {
+    readonly [EXECUTOR_ONLY]: true;
+}
+export type NotExecutorOnly = {
+    readonly [EXECUTOR_ONLY]?: never;
+};
+export {};

package/dist/executor-brand.js

@@ -0,0 +1 @@
+export {};

package/dist/extension-options-map.d.ts

@@ -0,0 +1,9 @@
+import type { EscapeHatchDeclaration } from "./handlers.js";
+export interface KumikoExtensionOptionsMap {
+}
+/** Options shape for an extension name: the augmented hook shape plus `escapeHatch`, or an untyped bag if unaugmented. */
+export type ExtensionOptionsFor<N extends string> = N extends keyof KumikoExtensionOptionsMap ? KumikoExtensionOptionsMap[N] & {
+    readonly escapeHatch?: EscapeHatchDeclaration;
+} : Record<string, unknown>;
+/** Rest-tuple for useExtension's positional options arg: required for an augmented name, optional otherwise. */
+export type ExtensionOptionsArgs<N extends string> = N extends keyof KumikoExtensionOptionsMap ? [options: ExtensionOptionsFor<N>] : [options?: Record<string, unknown>];

package/dist/extension-options-map.js

@@ -0,0 +1,4 @@
+// Cross-Feature Compile-Time-Type-Map for `r.useExtension(name, entity, options)`.
+// Augmented per extension point via `declare module "@cosmicdrift/kumiko-framework/engine"`,
+// mirroring event-type-map.ts; names without augmentation stay untyped.
+export {};