@cosmicdrift/kumiko-types 0.387.0 → 0.389.0

package/dist/config.d.ts

@@ -31,6 +31,7 @@ export type ConfigValidateContext = {
     readonly tenantId: TenantId;
     readonly userId: string | null;
     readonly db: TenantDb;
+    readonly readCascade: (qualifiedKey: string) => Promise<ConfigCascade>;
 };
 export type ConfigValidateFn<T extends ConfigKeyType = ConfigKeyType> = (value: ConfigValue<T>, ctx: ConfigValidateContext) => Promise<void>;
 export type ConfigBacking = "config" | "secrets";
@@ -231,6 +232,8 @@ export type NotificationTemplateMeta = {
     readonly layoutSlug?: string;
     readonly category?: "transactional" | "marketing";
     readonly sender?: string;
+    readonly senderName?: string;
+    readonly replyTo?: string;
 };
 export type NotificationTemplateBody = {
     readonly body: string;

package/dist/db-connection.d.ts

@@ -1,4 +1,4 @@
-import type postgres from "postgres";
+import type { SQL, TransactionSQL } from "bun";
 export type RawDbClient = {
     unsafe: (sql: string, params?: readonly unknown[]) => PromiseLike<readonly unknown[]>;
     begin: <T>(fn: (tx: DbTx) => Promise<T>) => Promise<T>;
@@ -6,11 +6,11 @@ export type RawDbClient = {
         timeout?: number;
     }) => Promise<void>;
 };
-export type DbConnection = ReturnType<typeof postgres> | RawDbClient;
-export type DbTx = postgres.TransactionSql<Record<string, unknown>> | RawDbClient;
+export type DbConnection = SQL | RawDbClient;
+export type DbTx = TransactionSQL | RawDbClient;
 export type DbRunner = DbConnection | DbTx;
 export type DbRow = Record<string, unknown>;
-export type PgClient = ReturnType<typeof postgres>;
+export type PgClient = SQL;
 export type PgListenSubscription = {
     unlisten(): Promise<void>;
 };

package/dist/define-handler.d.ts

@@ -14,6 +14,9 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: z.infer<TSchema>) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
@@ -31,6 +34,9 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: z.infer<TSchema>) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;

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

@@ -3,6 +3,7 @@ import type { EntityDefinition } from "./fields.ts";
 import type { SessionUser, WriteResult } from "./handlers.ts";
 import type { DeleteContext, SaveContext } from "./hooks.ts";
 import type { EntityId, TenantId } from "./identifiers.ts";
+import type { ListAggregatePayload, ListAggregateResult } from "./list-aggregate-types.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { TenantDb } from "./tenant-db-types.ts";
 export type ParentVisibilityOption = {
@@ -21,6 +22,38 @@ export type LockGuardOption = {
     readonly unsafeSkipLockGuard?: boolean;
     readonly writePurpose?: WritePurpose;
 };
+export type ListRuntimeOptions = {
+    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;
+};
+type ListFilterOption = {
+    readonly field: string;
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+    readonly value: unknown;
+};
+export type ListAggregateRequest = {
+    readonly search?: string | undefined;
+    readonly filter?: ListFilterOption | undefined;
+    readonly filters?: readonly ListFilterOption[] | undefined;
+    readonly aggregate: ListAggregatePayload;
+};
 export type EventStoreExecutor<Row extends Record<string, unknown> = Record<string, unknown>> = {
     create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: StreamTenantOption & {
         preSave?: PreSaveRunner;
@@ -70,30 +103,13 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
      *  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<Row>>;
+    runtimeOptions?: ListRuntimeOptions) => Promise<CursorResult<Row>>;
+    /** Groups and measures over the same WHERE as `list` (filters, search, ownership, field-read gates); paging and sort are ignored. */
+    aggregate: (payload: ListAggregateRequest, user: SessionUser, db: TenantDb, runtimeOptions?: ListRuntimeOptions) => Promise<ListAggregateResult>;
     detail: (payload: {
         id: EntityId;
     }, user: SessionUser, db: TenantDb, options?: {
         readonly parentVisibility?: ParentVisibilityOption;
     }) => Promise<Row | null>;
 };
+export {};

package/dist/feature-registrar.d.ts

@@ -0,0 +1,326 @@
+import type * as z from "zod";
+import type { ZodType } from "zod";
+import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, RegistrarExtensionDef, TemplateVariables, TranslationsDef } from "./config.ts";
+import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.ts";
+import type { RegisterEntityCrudOptions } from "./entity-handlers.ts";
+import type { EntityTableMeta } from "./entity-table-meta-types.ts";
+import type { KumikoEventTypeMap } from "./event-type-map.ts";
+import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.ts";
+import type { BootCheckFn, MetricOptions, SecretKeyHandle, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableOptions, UiHints } from "./feature.ts";
+import type { EntityDefinition } from "./fields.ts";
+import type { AccessRule, AuthClaimsFn, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, RateLimitDeclaration, StreamHandlerFn } from "./handlers.ts";
+import type { HookPhase, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
+import type { HttpRouteDefinition } from "./http-route.ts";
+import type { ContentCollectionDefinition, NavDefinition } from "./nav.ts";
+import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection.ts";
+import type { RelationDefinition } from "./relations.ts";
+import type { ScreenDefinition } from "./screen.ts";
+import type { TreeActionDef, TreeActionsHandle } from "./tree-node.ts";
+import type { WebSocketRouteDefinition } from "./websocket-route.ts";
+import type { WorkspaceDefinition } from "./workspace.ts";
+type RefOrRefs = NameOrRef | readonly NameOrRef[];
+type HookTarget = RefOrRefs | {
+    readonly allOf: NameOrRef;
+};
+export type EntityObjectDefinition = {
+    readonly name: string;
+    readonly backingTable?: unknown;
+} & EntityDefinition;
+type HookEscapeHatch = {
+    readonly escapeHatch?: EscapeHatchDeclaration;
+};
+type HookPhaseOption = {
+    readonly phase?: HookPhase;
+};
+export type HookDefinition = {
+    readonly type: "validation";
+    readonly target: RefOrRefs;
+    readonly handler: ValidationHookFn;
+    readonly escapeHatch?: never;
+    readonly phase?: never;
+} | ({
+    readonly type: "preSave";
+    readonly target: RefOrRefs;
+    readonly handler: PreSaveHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch) | ({
+    readonly type: "postSave";
+    readonly target: HookTarget;
+    readonly handler: PostSaveHookFn;
+} & HookEscapeHatch & HookPhaseOption) | ({
+    readonly type: "preDelete";
+    readonly target: HookTarget;
+    readonly handler: PreDeleteHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch) | ({
+    readonly type: "postDelete";
+    readonly target: HookTarget;
+    readonly handler: PostDeleteHookFn;
+} & HookEscapeHatch & HookPhaseOption) | ({
+    readonly type: "preQuery";
+    readonly target: RefOrRefs;
+    readonly handler: PreQueryHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch) | ({
+    readonly type: "postQuery";
+    readonly target: HookTarget;
+    readonly handler: PostQueryHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch);
+/**
+ * `r.requires({ features })` declares the features this one depends on; the
+ * `.projection` extension declares read-side projection tables that this
+ * feature's pipeline steps are allowed to write via
+ * `r.step.unsafeProjectionUpsert` (hard-required for any unsafeProjection-*
+ * step usage, see Q10).
+ *
+ * @example r.requires({ features: ["auth", "tenant"] });
+ */
+export type RequiresApi = ((options: {
+    readonly features: readonly string[];
+}) => void) & {
+    readonly projection: (tableName: string) => void;
+    readonly step: (stepKind: string) => void;
+};
+/**
+ * `TFeature` is the literal feature-name from `defineFeature("foo", ...)` —
+ * default-`string` keeps every existing usage zero-config. Strict-typed
+ * features (apps that opt into the literal-name flavour) get propagated
+ * through to `defineEvent` so the returned `EventDef.name` is a literal
+ * `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`. That literal
+ * threads through `ctx.appendEvent({ type: eventDef.name, ... })`,
+ * keeping strict-mode alive even when handlers route via `eventDef.name`
+ * instead of hand-typed string literals.
+ */
+export type FeatureRegistrar<TFeature extends string = string> = {
+    systemScope(): void;
+    describe(text: string): void;
+    requires: RequiresApi;
+    optionalRequires(...featureNames: string[]): void;
+    optionalRequires(options: {
+        readonly features: readonly string[];
+    }): void;
+    toggleable(options: {
+        default: boolean;
+    }): void;
+    adoptsBundledLists(): void;
+    uiHints(hints: UiHints): void;
+    /**
+     * @example r.entity({ name: "note", fields: { title: createTextField({ required: true }) } });
+     */
+    entity(definition: EntityObjectDefinition): EntityRef;
+    crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
+    /**
+     * @example r.writeHandler({ name: "note:archive", schema, handler, access: { roles: ["User"] } });
+     */
+    writeHandler<TName extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
+    /**
+     * @example r.queryHandler({ name: "note:list", schema, handler, access: { roles: ["User"] } });
+     */
+    queryHandler<TName extends string, TSchema extends ZodType>(def: QueryHandlerDefinition<TName, TSchema>): HandlerRef;
+    streamHandler<TName extends string, TSchema extends ZodType>(def: StreamHandlerDefinition<TName, TSchema>): HandlerRef;
+    streamHandler<TSchema extends ZodType>(name: string, schema: TSchema, handler: StreamHandlerFn<z.infer<TSchema>>, options: {
+        access: AccessRule;
+        rateLimit?: RateLimitDeclaration;
+        escapeHatch?: EscapeHatchDeclaration;
+    }): HandlerRef;
+    relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
+    relation<TDef extends RelationDefinition>(definition: {
+        readonly entity: NameOrRef;
+        readonly name: string;
+    } & TDef): void;
+    /**
+     * @example r.hook({ type: "postSave", target: { allOf: noteRef }, handler: notifyOwner });
+     */
+    hook(definition: HookDefinition): void;
+    searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
+    config<T extends ConfigKeyType>(keyName: string, def: ConfigKeyDefinition<T>): ConfigKeyHandle<T>;
+    config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
+        readonly keys: TKeys;
+        readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
+    }): {
+        readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
+    };
+    job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
+    job(definition: JobDefinition): void;
+    notification(name: string, definition: {
+        readonly trigger?: {
+            readonly on: NameOrRef;
+        };
+        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;
+        readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
+    }): void;
+    notification(definition: {
+        readonly name: string;
+        readonly trigger?: {
+            readonly on: NameOrRef;
+        };
+        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;
+        readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
+    }): void;
+    translations(def: TranslationsDef): void;
+    defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: {
+        readonly version?: number;
+        readonly piiFields: EventPiiStance;
+        readonly migrations?: readonly {
+            readonly fromVersion: number;
+            readonly toVersion: number;
+            readonly transform: EventUpcastFn | DeclarativeEventMigration;
+        }[];
+    }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
+    readsConfig(...qualifiedKeys: string[]): void;
+    readsConfig(options: {
+        readonly keys: readonly string[];
+    }): void;
+    referenceData(entity: NameOrRef, data: readonly Record<string, unknown>[], options?: {
+        upsertKey?: string;
+    }): void;
+    referenceData(definition: {
+        readonly entity: NameOrRef;
+        readonly data: readonly Record<string, unknown>[];
+        readonly upsertKey?: string;
+    }): void;
+    extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
+    useExtension<N extends string>(extensionName: N, entity: NameOrRef, ...options: ExtensionOptionsArgs<N>): void;
+    useExtension<N extends string>(definition: {
+        readonly name: N;
+        readonly entity: NameOrRef;
+    } & ExtensionOptionsFor<N>): void;
+    /**
+     * Declares which config key selects the active provider under an
+     * extension point — called by the point-owning foundation (e.g.
+     * `r.extensionSelector("mailTransport", configKeys.provider)`).
+     * Readiness gating counts a provider-feature's `required` keys and
+     * secrets only while that provider is the selected one. Registry-build
+     * fails on duplicate declarations per extension and on selector keys
+     * that no mounted feature declares. A masked tenant selector key makes the
+     * Settings-Hub render one tenant dashboard for the owner: the selector as a
+     * select of the mounted plugin ids, the selected plugin's config and secrets
+     * as panels, and plugin features lose their own tenant nav. `config:write:set`
+     * rejects unknown plugin ids (`""` clears). `options.panels` adds the owner's own
+     * `custom`/`screen` panels to that dashboard, after the selection and before the
+     * plugin panels (a short `screen` id means a screen of the declaring feature).
+     */
+    extensionSelector(extensionName: string, key: {
+        readonly name: string;
+    } | string, options?: {
+        readonly panels?: readonly ExtensionSelectorPanel[];
+    }): void;
+    /**
+     * Marker declaration: this feature provides a cross-feature API under the
+     * given name. The implementation is registered separately as a query or
+     * write handler under the QN pattern; `r.exposesApi` is only a boot-check
+     * surface.
+     *
+     * The boot validator checks that every `r.usesApi(name)` finds a matching
+     * exposer, that the exposer feature is listed in requires/optionalRequires,
+     * and that no API name is exposed more than once.
+     *
+     * ```ts
+     * defineFeature("compliance-profiles", (r) => {
+     *   r.exposesApi("compliance.forTenant");
+     *   r.queryHandler({
+     *     name: "compliance:query:for-tenant",
+     *     // ... actual implementation
+     *   });
+     * });
+     * ```
+     */
+    exposesApi(apiName: string): void;
+    /**
+     * Declares that this feature calls a cross-feature API. The boot validator
+     * checks that another feature provides `r.exposesApi(apiName)` and that
+     * this feature lists it in `r.requires/optionalRequires`.
+     *
+     * ```ts
+     * defineFeature("user-data-rights", (r) => {
+     *   r.requires({ features: ["compliance-profiles"] });
+     *   r.usesApi("compliance.forTenant");
+     * });
+     * ```
+     */
+    usesApi(apiName: string): void;
+    /**
+     * Declares a boot-time mount-invariant for this feature. `fn` runs once
+     * at boot with a ctx exposing every mounted feature — throw to fail the
+     * boot with a clear message. Multiple calls per feature are allowed.
+     *
+     * Use for cross-feature invariants that `r.requires` can't express
+     * because they're conditional (only fail when the feature has a
+     * specific shape), e.g. "if this feature has PII entities, some
+     * user-data-hook feature must be mounted" (the prompt-store trap —
+     * a UserData feature was written but never mounted, and nothing caught
+     * it at boot):
+     *
+     * ```ts
+     * defineFeature("prompt-store", (r) => {
+     *   const promptFields = { text: createTextField({ personal: "self", find: "none" }) };
+     *   r.entity({ name: "prompt", fields: promptFields });
+     *   r.bootCheck(({ features }) => {
+     *     // Conditional on this feature's own shape (has a pii field) —
+     *     // r.requires({ features: ["user-data-hook"] }) can't express that, it would fail
+     *     // even for a prompt-store variant with no PII fields at all.
+     *     const hasPiiField = Object.values(promptFields).some((f) => f.pii);
+     *     const hasUserDataHook = features.some((f) => f.name === "user-data-hook");
+     *     if (hasPiiField && !hasUserDataHook) {
+     *       throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
+     *     }
+     *   });
+     * });
+     * ```
+     */
+    bootCheck(fn: BootCheckFn): void;
+    metric(shortName: string, options: MetricOptions): void;
+    metric(definition: {
+        readonly name: string;
+    } & MetricOptions): void;
+    secret(shortName: string, options: SecretOptions): SecretKeyHandle;
+    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;
+    authClaims(fn: AuthClaimsFn): void;
+    claimKey<T extends ClaimKeyType>(shortName: string, options: {
+        readonly type: T;
+    }): ClaimKeyHandle<T>;
+    claimKey<T extends ClaimKeyType>(definition: {
+        readonly name: string;
+        readonly type: T;
+    }): ClaimKeyHandle<T>;
+    screen(definition: ScreenDefinition): void;
+    nav(definition: NavDefinition): void;
+    contentCollection(definition: ContentCollectionDefinition): string;
+    workspace(definition: WorkspaceDefinition): void;
+    httpRoute(definition: HttpRouteDefinition): void;
+    webSocketRoute(definition: WebSocketRouteDefinition): void;
+    storeTable(meta: EntityTableMeta, options: StoreTableOptions): void;
+    treeActions<const TActions extends Record<string, TreeActionDef>>(actions: TActions): TreeActionsHandle<TFeature, TActions>;
+    envSchema(schema: z.ZodObject<z.ZodRawShape>): void;
+};
+export {};

package/dist/feature-registrar.js

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