@maravilla-labs/platform 0.2.1 → 0.2.2

package/dist/config.d.ts

@@ -0,0 +1,236 @@
+/**
+ * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.
+ *
+ * Declares your project's auth settings (resources, groups, relations,
+ * registration fields, OAuth providers, security policy, branding) alongside
+ * your code. The Maravilla adapter reads this at build time and reconciles
+ * the settings into delivery on deploy.
+ *
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [
+ *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],
+ *         policy: 'auth.user_id == node.owner' },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * Omitted sections leave the DB alone — partial adoption is explicitly
+ * supported. List-based sections (`resources`, `groups`, `relations`,
+ * `oauth`) are upserted and never auto-delete DB-only entries. Singleton
+ * sections (`registration`, `security`, `branding`) are replaced wholesale
+ * when declared.
+ */
+/**
+ * String value that may either be a literal secret or a reference to an
+ * environment variable on the **tenant** (resolved server-side at
+ * reconcile time, never shipped plaintext in the manifest).
+ *
+ * Accepted forms:
+ *   - `"literal-value"` — inline (not recommended for real secrets)
+ *   - `"${env.VAR_NAME}"` — string-template form
+ *   - `{ env: "VAR_NAME" }` — object form
+ */
+type SecretRef = string | {
+    env: string;
+};
+interface ResourceDefinition {
+    /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */
+    name: string;
+    /** Human-readable title for the admin UI. */
+    title: string;
+    /** Optional longer description. */
+    description?: string;
+    /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */
+    actions: string[];
+    /**
+     * Optional raisin-rel policy expression. Evaluated on every KV/DB/
+     * realtime/media op that targets this resource. Leave empty to skip
+     * Layer 2 for this resource — tenant + owner isolation still applies.
+     */
+    policy?: string;
+}
+interface GroupPermissionDefinition {
+    /** Must match a `ResourceDefinition.name`. */
+    resource_name: string;
+    /** Actions this group is granted on the resource. */
+    actions: string[];
+}
+interface GroupDefinition {
+    /** Unique group name per tenant. */
+    name: string;
+    /** Optional description for the admin UI. */
+    description?: string;
+    /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */
+    permissions?: GroupPermissionDefinition[];
+}
+interface RelationTypeDefinition {
+    /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */
+    relation_name: string;
+    /** Human-readable title. */
+    title: string;
+    description?: string;
+    /** Grouping for the admin UI (e.g. `"family"`, `"work"`). */
+    category?: string;
+    icon?: string;
+    color?: string;
+    /** Name of the inverse relation type, if one exists. */
+    inverse_relation_name?: string;
+    /** When true, membership in this relation implies stewardship rights. */
+    implies_stewardship?: boolean;
+    /** When true, the relation can only target users flagged as minors. */
+    requires_minor?: boolean;
+    /** When true, the relation is symmetric (A→B implies B→A). */
+    bidirectional?: boolean;
+}
+interface RegistrationFieldDefinition {
+    /** Field key used as the form field name + in profile data. */
+    key: string;
+    /** Display label. */
+    label: string;
+    /** One of: text, email, phone, date, number, select, boolean, url, textarea. */
+    field_type: string;
+    required: boolean;
+    show_on_register: boolean;
+    /** Optional validation metadata — passed through to the UI. */
+    validation?: Record<string, unknown>;
+}
+interface RegistrationConfig {
+    /** Ordered list of custom registration fields. Declaring this replaces the full list. */
+    fields: RegistrationFieldDefinition[];
+}
+interface OAuthProviderDefinition {
+    enabled: boolean;
+    client_id: string;
+    /** Prefer `{ env: "VAR_NAME" }` or `"${env.VAR_NAME}"`. */
+    client_secret: SecretRef;
+    scopes: string[];
+    /** Only for `custom_oidc`. */
+    discovery_url?: string;
+}
+interface OAuthProvidersConfig {
+    google?: OAuthProviderDefinition;
+    github?: OAuthProviderDefinition;
+    okta?: OAuthProviderDefinition;
+    custom_oidc?: OAuthProviderDefinition;
+}
+interface PasswordPolicyDefinition {
+    min_length: number;
+    require_uppercase: boolean;
+    require_number: boolean;
+    require_special: boolean;
+}
+interface SessionConfigDefinition {
+    access_token_ttl_secs: number;
+    refresh_token_ttl_secs: number;
+    max_sessions_per_user: number;
+    require_email_verification: boolean;
+}
+interface SecurityConfig {
+    password_policy?: PasswordPolicyDefinition;
+    session?: SessionConfigDefinition;
+}
+interface BrandingConfig {
+    app_name?: string;
+    logo_url?: string;
+    primary_color?: string;
+    secondary_color?: string;
+    welcome_message?: string;
+    welcome_subtitle?: string;
+    /** `"centered"`, `"split-left"`, `"split-right"`, or `"fullscreen"`. */
+    layout?: string;
+    background_image_url?: string;
+    /** 0–100 percentage. */
+    background_focal_point?: {
+        x: number;
+        y: number;
+    };
+    background_gradient?: string;
+    /** `"light"`, `"dark"`, or `"auto"`. */
+    color_mode?: string;
+    font_family?: string;
+    terms_url?: string;
+    privacy_url?: string;
+    /** Raw CSS merged into the hosted auth pages. */
+    custom_css?: string;
+}
+interface AuthConfigBlock {
+    resources?: ResourceDefinition[];
+    groups?: GroupDefinition[];
+    relations?: RelationTypeDefinition[];
+    registration?: RegistrationConfig;
+    oauth?: OAuthProvidersConfig;
+    security?: SecurityConfig;
+    branding?: BrandingConfig;
+}
+interface MaravillaConfig {
+    /** All project-level auth settings. Every field is optional — partial adoption is supported. */
+    auth?: AuthConfigBlock;
+    /** Declarative database indexes (regular + vector). Reconciled upsert-only on deploy. */
+    database?: DatabaseConfigBlock;
+}
+/** MongoDB-style key direction: `1` ascending, `-1` descending. */
+type IndexDirectionConfig = 1 | -1;
+interface DocumentIndexDeclaration {
+    /** Collection the index lives on. */
+    collection: string;
+    /** Optional name; falls back to an auto-derived name. */
+    name?: string;
+    /**
+     * Compound-index key shape. Array of `[field, direction]` tuples
+     * preserves ordering, which matters for compound indexes.
+     */
+    keys: Array<[string, IndexDirectionConfig]> | Record<string, IndexDirectionConfig>;
+    unique?: boolean;
+    sparse?: boolean;
+    /**
+     * Partial-index predicate — restricted to inline-literal operators
+     * (`$eq`, `$ne`, `$gt`/`$gte`/`$lt`/`$lte`, `$in`/`$nin`, `$exists`,
+     * `$and`, `$or`). No `$regex` / `$where` / `$text`.
+     */
+    partial?: Record<string, unknown>;
+    /** TTL in seconds. Requires a single-field index on a unix-seconds field. */
+    expireAfterSeconds?: number;
+}
+/** Distance metric used by a vector index. */
+type VectorMetricConfig = 'cosine' | 'l2' | 'hamming';
+/** Storage precision for a vector index. */
+type VectorStorageConfig = 'float32' | 'int8' | 'bit';
+interface VectorIndexDeclaration {
+    collection: string;
+    field: string;
+    dimensions: number;
+    metric?: VectorMetricConfig;
+    storage?: VectorStorageConfig;
+    matryoshka?: boolean;
+    multiVector?: boolean;
+}
+interface DatabaseConfigBlock {
+    /** MongoDB-style secondary indexes. */
+    indexes?: DocumentIndexDeclaration[];
+    /** sqlite-vec-backed vector indexes. */
+    vectorIndexes?: VectorIndexDeclaration[];
+}
+/**
+ * Identity function that returns the config unchanged — exists purely so the
+ * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense
+ * on every field.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],
+ *   },
+ * });
+ * ```
+ */
+declare function defineConfig(config: MaravillaConfig): MaravillaConfig;
+
+export { type AuthConfigBlock, type BrandingConfig, type DatabaseConfigBlock, type DocumentIndexDeclaration, type GroupDefinition, type GroupPermissionDefinition, type IndexDirectionConfig, type MaravillaConfig, type OAuthProviderDefinition, type OAuthProvidersConfig, type PasswordPolicyDefinition, type RegistrationConfig, type RegistrationFieldDefinition, type RelationTypeDefinition, type ResourceDefinition, type SecretRef, type SecurityConfig, type SessionConfigDefinition, type VectorIndexDeclaration, type VectorMetricConfig, type VectorStorageConfig, defineConfig };

package/dist/config.js

@@ -0,0 +1,8 @@
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["/**\n * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.\n *\n * Declares your project's auth settings (resources, groups, relations,\n * registration fields, OAuth providers, security policy, branding) alongside\n * your code. The Maravilla adapter reads this at build time and reconciles\n * the settings into delivery on deploy.\n *\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [\n *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],\n *         policy: 'auth.user_id == node.owner' },\n *     ],\n *   },\n * });\n * ```\n *\n * Omitted sections leave the DB alone — partial adoption is explicitly\n * supported. List-based sections (`resources`, `groups`, `relations`,\n * `oauth`) are upserted and never auto-delete DB-only entries. Singleton\n * sections (`registration`, `security`, `branding`) are replaced wholesale\n * when declared.\n */\n\n/**\n * String value that may either be a literal secret or a reference to an\n * environment variable on the **tenant** (resolved server-side at\n * reconcile time, never shipped plaintext in the manifest).\n *\n * Accepted forms:\n *   - `\"literal-value\"` — inline (not recommended for real secrets)\n *   - `\"${env.VAR_NAME}\"` — string-template form\n *   - `{ env: \"VAR_NAME\" }` — object form\n */\nexport type SecretRef = string | { env: string };\n\n// ── Resources + policies ──\n\nexport interface ResourceDefinition {\n  /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */\n  name: string;\n  /** Human-readable title for the admin UI. */\n  title: string;\n  /** Optional longer description. */\n  description?: string;\n  /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */\n  actions: string[];\n  /**\n   * Optional raisin-rel policy expression. Evaluated on every KV/DB/\n   * realtime/media op that targets this resource. Leave empty to skip\n   * Layer 2 for this resource — tenant + owner isolation still applies.\n   */\n  policy?: string;\n}\n\n// ── Groups ──\n\nexport interface GroupPermissionDefinition {\n  /** Must match a `ResourceDefinition.name`. */\n  resource_name: string;\n  /** Actions this group is granted on the resource. */\n  actions: string[];\n}\n\nexport interface GroupDefinition {\n  /** Unique group name per tenant. */\n  name: string;\n  /** Optional description for the admin UI. */\n  description?: string;\n  /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */\n  permissions?: GroupPermissionDefinition[];\n}\n\n// ── Relations ──\n\nexport interface RelationTypeDefinition {\n  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */\n  relation_name: string;\n  /** Human-readable title. */\n  title: string;\n  description?: string;\n  /** Grouping for the admin UI (e.g. `\"family\"`, `\"work\"`). */\n  category?: string;\n  icon?: string;\n  color?: string;\n  /** Name of the inverse relation type, if one exists. */\n  inverse_relation_name?: string;\n  /** When true, membership in this relation implies stewardship rights. */\n  implies_stewardship?: boolean;\n  /** When true, the relation can only target users flagged as minors. */\n  requires_minor?: boolean;\n  /** When true, the relation is symmetric (A→B implies B→A). */\n  bidirectional?: boolean;\n}\n\n// ── Registration fields ──\n\nexport interface RegistrationFieldDefinition {\n  /** Field key used as the form field name + in profile data. */\n  key: string;\n  /** Display label. */\n  label: string;\n  /** One of: text, email, phone, date, number, select, boolean, url, textarea. */\n  field_type: string;\n  required: boolean;\n  show_on_register: boolean;\n  /** Optional validation metadata — passed through to the UI. */\n  validation?: Record<string, unknown>;\n}\n\nexport interface RegistrationConfig {\n  /** Ordered list of custom registration fields. Declaring this replaces the full list. */\n  fields: RegistrationFieldDefinition[];\n}\n\n// ── OAuth providers ──\n\nexport interface OAuthProviderDefinition {\n  enabled: boolean;\n  client_id: string;\n  /** Prefer `{ env: \"VAR_NAME\" }` or `\"${env.VAR_NAME}\"`. */\n  client_secret: SecretRef;\n  scopes: string[];\n  /** Only for `custom_oidc`. */\n  discovery_url?: string;\n}\n\nexport interface OAuthProvidersConfig {\n  google?: OAuthProviderDefinition;\n  github?: OAuthProviderDefinition;\n  okta?: OAuthProviderDefinition;\n  custom_oidc?: OAuthProviderDefinition;\n}\n\n// ── Security ──\n\nexport interface PasswordPolicyDefinition {\n  min_length: number;\n  require_uppercase: boolean;\n  require_number: boolean;\n  require_special: boolean;\n}\n\nexport interface SessionConfigDefinition {\n  access_token_ttl_secs: number;\n  refresh_token_ttl_secs: number;\n  max_sessions_per_user: number;\n  require_email_verification: boolean;\n}\n\nexport interface SecurityConfig {\n  password_policy?: PasswordPolicyDefinition;\n  session?: SessionConfigDefinition;\n}\n\n// ── Branding ──\n\nexport interface BrandingConfig {\n  app_name?: string;\n  logo_url?: string;\n  primary_color?: string;\n  secondary_color?: string;\n  welcome_message?: string;\n  welcome_subtitle?: string;\n  /** `\"centered\"`, `\"split-left\"`, `\"split-right\"`, or `\"fullscreen\"`. */\n  layout?: string;\n  background_image_url?: string;\n  /** 0–100 percentage. */\n  background_focal_point?: { x: number; y: number };\n  background_gradient?: string;\n  /** `\"light\"`, `\"dark\"`, or `\"auto\"`. */\n  color_mode?: string;\n  font_family?: string;\n  terms_url?: string;\n  privacy_url?: string;\n  /** Raw CSS merged into the hosted auth pages. */\n  custom_css?: string;\n}\n\n// ── Top-level shape ──\n\nexport interface AuthConfigBlock {\n  resources?: ResourceDefinition[];\n  groups?: GroupDefinition[];\n  relations?: RelationTypeDefinition[];\n  registration?: RegistrationConfig;\n  oauth?: OAuthProvidersConfig;\n  security?: SecurityConfig;\n  branding?: BrandingConfig;\n}\n\nexport interface MaravillaConfig {\n  /** All project-level auth settings. Every field is optional — partial adoption is supported. */\n  auth?: AuthConfigBlock;\n  /** Declarative database indexes (regular + vector). Reconciled upsert-only on deploy. */\n  database?: DatabaseConfigBlock;\n}\n\n// ── Database block ──\n//\n// Regular indexes speed up document reads on frequently-queried fields.\n// Vector indexes back hybrid semantic search via sqlite-vec. Both are\n// upsert-only — declaring an index in config creates it if missing,\n// updates metadata when safe, and never auto-deletes DB-only indexes.\n\n/** MongoDB-style key direction: `1` ascending, `-1` descending. */\nexport type IndexDirectionConfig = 1 | -1;\n\nexport interface DocumentIndexDeclaration {\n  /** Collection the index lives on. */\n  collection: string;\n  /** Optional name; falls back to an auto-derived name. */\n  name?: string;\n  /**\n   * Compound-index key shape. Array of `[field, direction]` tuples\n   * preserves ordering, which matters for compound indexes.\n   */\n  keys: Array<[string, IndexDirectionConfig]> | Record<string, IndexDirectionConfig>;\n  unique?: boolean;\n  sparse?: boolean;\n  /**\n   * Partial-index predicate — restricted to inline-literal operators\n   * (`$eq`, `$ne`, `$gt`/`$gte`/`$lt`/`$lte`, `$in`/`$nin`, `$exists`,\n   * `$and`, `$or`). No `$regex` / `$where` / `$text`.\n   */\n  partial?: Record<string, unknown>;\n  /** TTL in seconds. Requires a single-field index on a unix-seconds field. */\n  expireAfterSeconds?: number;\n}\n\n/** Distance metric used by a vector index. */\nexport type VectorMetricConfig = 'cosine' | 'l2' | 'hamming';\n\n/** Storage precision for a vector index. */\nexport type VectorStorageConfig = 'float32' | 'int8' | 'bit';\n\nexport interface VectorIndexDeclaration {\n  collection: string;\n  field: string;\n  dimensions: number;\n  metric?: VectorMetricConfig;\n  storage?: VectorStorageConfig;\n  matryoshka?: boolean;\n  multiVector?: boolean;\n}\n\nexport interface DatabaseConfigBlock {\n  /** MongoDB-style secondary indexes. */\n  indexes?: DocumentIndexDeclaration[];\n  /** sqlite-vec-backed vector indexes. */\n  vectorIndexes?: VectorIndexDeclaration[];\n}\n\n/**\n * Identity function that returns the config unchanged — exists purely so the\n * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense\n * on every field.\n *\n * @example\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],\n *   },\n * });\n * ```\n */\nexport function defineConfig(config: MaravillaConfig): MaravillaConfig {\n  return config;\n}\n"],"mappings":";AAiRO,SAAS,aAAa,QAA0C;AACrE,SAAO;AACT;","names":[]}

package/dist/events.d.ts

@@ -0,0 +1,167 @@
+import { R as RenEvent } from './ren-D0DCQ0Fs.js';
+
+/**
+ * @fileoverview Event handler registration helpers for Maravilla.
+ *
+ * User apps declare event handlers in `events.ts` or `events/*.ts`:
+ *
+ * ```ts
+ * import { onKvChange, defineEvent } from '@maravilla-labs/platform/events';
+ *
+ * export const invalidateCache = onKvChange(
+ *   { namespace: 'config', keyPattern: 'feature:*' },
+ *   async (event, ctx) => { await ctx.kv.delete('cache', event.key!); },
+ * );
+ * ```
+ *
+ * These helpers are pure factories. They produce a `RegisteredHandler`
+ * marker object that the build pipeline (`@maravilla-labs/functions`
+ * `discoverEvents`) detects by its `__maravilla_trigger` property.
+ * The Rust event dispatcher uses the trigger config from the manifest
+ * and invokes the bundled handler via `globalThis.handleEvent(id, event)`.
+ */
+
+type EventTrigger = EventTriggerKv | EventTriggerDb | EventTriggerAuth | EventTriggerSchedule | EventTriggerQueue | EventTriggerChannel | EventTriggerDeploy | EventTriggerRen;
+interface EventTriggerKv {
+    kind: 'kv';
+    namespace?: string;
+    keyPattern?: string;
+    op?: 'put' | 'delete' | 'expired';
+}
+interface EventTriggerDb {
+    kind: 'db';
+    collection: string;
+    op?: 'insert' | 'update' | 'delete';
+}
+type AuthOp = 'registered' | 'logged_in' | 'logged_out' | 'logged_out_all' | 'deleted' | 'updated';
+interface EventTriggerAuth {
+    kind: 'auth';
+    op?: AuthOp;
+}
+interface EventTriggerSchedule {
+    kind: 'schedule';
+    cron: string;
+}
+interface EventTriggerQueue {
+    kind: 'queue';
+    name: string;
+    batch?: number;
+    maxAttempts?: number;
+}
+interface EventTriggerChannel {
+    kind: 'channel';
+    channel: string;
+    type?: string;
+}
+interface EventTriggerDeploy {
+    kind: 'deploy';
+    phase: 'ready' | 'draining' | 'stopped';
+}
+interface EventTriggerRen {
+    kind: 'ren';
+    match: {
+        r?: string;
+        t?: string;
+        ns?: string;
+    };
+}
+interface KvChangeEvent {
+    op: 'put' | 'delete' | 'expired';
+    namespace: string;
+    key: string;
+    /** Present on `put`. */
+    value?: unknown;
+    ts: number;
+}
+interface DbChangeEvent {
+    op: 'insert' | 'update' | 'delete';
+    collection: string;
+    id: string;
+    doc?: unknown;
+    before?: unknown;
+    after?: unknown;
+    ts: number;
+}
+interface AuthEvent {
+    op: AuthOp;
+    userId: string;
+    /**
+     * Op-specific payload:
+     * - `registered` → `{ email, provider, profile }` where `profile` is the
+     *   app's custom fields passed to `platform.auth.register({ profile: {...} })`.
+     * - `logged_in` → `{ email }`
+     * - `logged_out` → `{ sessionId }`
+     * - `logged_out_all` / `deleted` / `updated` → null or empty.
+     */
+    data?: {
+        email?: string;
+        provider?: string;
+        profile?: Record<string, unknown> | null;
+        sessionId?: string;
+        [k: string]: unknown;
+    };
+    ts: number;
+}
+interface ScheduleEvent {
+    cron: string;
+    scheduledAt: number;
+    firedAt: number;
+}
+interface QueueMessage<T = unknown> {
+    id: string;
+    payload: T;
+    attempt: number;
+    enqueuedAt: number;
+}
+interface ChannelEvent<T = unknown> {
+    channel: string;
+    type: string;
+    data?: T;
+    uid?: string;
+    ts: number;
+}
+interface DeployEvent {
+    phase: 'ready' | 'draining' | 'stopped';
+    ts: number;
+}
+interface EventCtx {
+    /** Per-tenant env vars. */
+    env: Record<string, string>;
+    /** Trace correlation id — propagate through logs. */
+    traceId: string;
+    tenant: string;
+    handlerId: string;
+    [extra: string]: unknown;
+}
+declare const TRIGGER_SYMBOL: "__maravilla_trigger";
+interface RegisteredHandler<Event = unknown, Ctx = EventCtx> {
+    readonly [TRIGGER_SYMBOL]: EventTrigger;
+    readonly handler: (event: Event, ctx: Ctx) => unknown | Promise<unknown>;
+}
+declare function onKvChange(config: Omit<EventTriggerKv, 'kind'>, handler: (event: KvChangeEvent, ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<KvChangeEvent>;
+declare function onDbChange(config: Omit<EventTriggerDb, 'kind'>, handler: (event: DbChangeEvent, ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<DbChangeEvent>;
+/**
+ * React to user authentication events: registration, login, logout,
+ * deletion, update. Omit `op` to match all auth events; set it to
+ * narrow to a specific lifecycle transition.
+ *
+ * ```ts
+ * export const welcomeEmail = onAuth(
+ *   { op: 'registered' },
+ *   async (event, ctx) => {
+ *     await sendWelcomeEmail(event.data?.email);
+ *   },
+ * );
+ * ```
+ */
+declare function onAuth(config: Omit<EventTriggerAuth, 'kind'>, handler: (event: AuthEvent, ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<AuthEvent>;
+declare function onSchedule(cron: string, handler: (event: ScheduleEvent, ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<ScheduleEvent>;
+declare function onQueue<T = unknown>(name: string, config: Omit<EventTriggerQueue, 'kind' | 'name'>, handler: (messages: QueueMessage<T>[], ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<QueueMessage<T>[]>;
+declare function onChannel<T = unknown>(config: Omit<EventTriggerChannel, 'kind'>, handler: (event: ChannelEvent<T>, ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<ChannelEvent<T>>;
+declare function onDeploy(phase: EventTriggerDeploy['phase'], handler: (event: DeployEvent, ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<DeployEvent>;
+/** Escape hatch for arbitrary `RenEvent` matches. */
+declare function defineEvent(config: Omit<EventTriggerRen, 'kind'>, handler: (event: RenEvent, ctx: EventCtx) => unknown | Promise<unknown>): RegisteredHandler<RenEvent>;
+/** Type guard used by the build-time discoverer and the runtime registry. */
+declare function isRegisteredHandler(value: unknown): value is RegisteredHandler;
+
+export { type AuthEvent, type AuthOp, type ChannelEvent, type DbChangeEvent, type DeployEvent, type EventCtx, type EventTrigger, type EventTriggerAuth, type EventTriggerChannel, type EventTriggerDb, type EventTriggerDeploy, type EventTriggerKv, type EventTriggerQueue, type EventTriggerRen, type EventTriggerSchedule, type KvChangeEvent, type QueueMessage, type RegisteredHandler, type ScheduleEvent, TRIGGER_SYMBOL, defineEvent, isRegisteredHandler, onAuth, onChannel, onDbChange, onDeploy, onKvChange, onQueue, onSchedule };

package/dist/events.js

@@ -0,0 +1,45 @@
+// src/events.ts
+var TRIGGER_SYMBOL = "__maravilla_trigger";
+function register(trigger, handler) {
+  return { [TRIGGER_SYMBOL]: trigger, handler };
+}
+function onKvChange(config, handler) {
+  return register({ kind: "kv", ...config }, handler);
+}
+function onDbChange(config, handler) {
+  return register({ kind: "db", ...config }, handler);
+}
+function onAuth(config, handler) {
+  return register({ kind: "auth", ...config }, handler);
+}
+function onSchedule(cron, handler) {
+  return register({ kind: "schedule", cron }, handler);
+}
+function onQueue(name, config, handler) {
+  return register({ kind: "queue", name, ...config }, handler);
+}
+function onChannel(config, handler) {
+  return register({ kind: "channel", ...config }, handler);
+}
+function onDeploy(phase, handler) {
+  return register({ kind: "deploy", phase }, handler);
+}
+function defineEvent(config, handler) {
+  return register({ kind: "ren", ...config }, handler);
+}
+function isRegisteredHandler(value) {
+  return typeof value === "object" && value !== null && TRIGGER_SYMBOL in value && typeof value.handler === "function";
+}
+export {
+  TRIGGER_SYMBOL,
+  defineEvent,
+  isRegisteredHandler,
+  onAuth,
+  onChannel,
+  onDbChange,
+  onDeploy,
+  onKvChange,
+  onQueue,
+  onSchedule
+};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/events.ts"],"sourcesContent":["/**\n * @fileoverview Event handler registration helpers for Maravilla.\n *\n * User apps declare event handlers in `events.ts` or `events/*.ts`:\n *\n * ```ts\n * import { onKvChange, defineEvent } from '@maravilla-labs/platform/events';\n *\n * export const invalidateCache = onKvChange(\n *   { namespace: 'config', keyPattern: 'feature:*' },\n *   async (event, ctx) => { await ctx.kv.delete('cache', event.key!); },\n * );\n * ```\n *\n * These helpers are pure factories. They produce a `RegisteredHandler`\n * marker object that the build pipeline (`@maravilla-labs/functions`\n * `discoverEvents`) detects by its `__maravilla_trigger` property.\n * The Rust event dispatcher uses the trigger config from the manifest\n * and invokes the bundled handler via `globalThis.handleEvent(id, event)`.\n */\n\nimport type { RenEvent } from './ren.js';\n\n// ============ Trigger descriptors ============\n// Kept structurally identical to adapter-core's `EventTrigger` — duplicated\n// here so the runtime SDK has no build-time dep on adapter-core. Keep in sync.\n\nexport type EventTrigger =\n  | EventTriggerKv\n  | EventTriggerDb\n  | EventTriggerAuth\n  | EventTriggerSchedule\n  | EventTriggerQueue\n  | EventTriggerChannel\n  | EventTriggerDeploy\n  | EventTriggerRen;\n\nexport interface EventTriggerKv {\n  kind: 'kv';\n  namespace?: string;\n  keyPattern?: string;\n  op?: 'put' | 'delete' | 'expired';\n}\n\nexport interface EventTriggerDb {\n  kind: 'db';\n  collection: string;\n  op?: 'insert' | 'update' | 'delete';\n}\n\nexport type AuthOp =\n  | 'registered'\n  | 'logged_in'\n  | 'logged_out'\n  | 'logged_out_all'\n  | 'deleted'\n  | 'updated';\n\nexport interface EventTriggerAuth {\n  kind: 'auth';\n  op?: AuthOp;\n}\n\nexport interface EventTriggerSchedule {\n  kind: 'schedule';\n  cron: string;\n}\n\nexport interface EventTriggerQueue {\n  kind: 'queue';\n  name: string;\n  batch?: number;\n  maxAttempts?: number;\n}\n\nexport interface EventTriggerChannel {\n  kind: 'channel';\n  channel: string;\n  type?: string;\n}\n\nexport interface EventTriggerDeploy {\n  kind: 'deploy';\n  phase: 'ready' | 'draining' | 'stopped';\n}\n\nexport interface EventTriggerRen {\n  kind: 'ren';\n  match: { r?: string; t?: string; ns?: string };\n}\n\n// ============ Event payload shapes ============\n\nexport interface KvChangeEvent {\n  op: 'put' | 'delete' | 'expired';\n  namespace: string;\n  key: string;\n  /** Present on `put`. */\n  value?: unknown;\n  ts: number;\n}\n\nexport interface DbChangeEvent {\n  op: 'insert' | 'update' | 'delete';\n  collection: string;\n  id: string;\n  doc?: unknown;\n  before?: unknown;\n  after?: unknown;\n  ts: number;\n}\n\nexport interface AuthEvent {\n  op: AuthOp;\n  userId: string;\n  /**\n   * Op-specific payload:\n   * - `registered` → `{ email, provider, profile }` where `profile` is the\n   *   app's custom fields passed to `platform.auth.register({ profile: {...} })`.\n   * - `logged_in` → `{ email }`\n   * - `logged_out` → `{ sessionId }`\n   * - `logged_out_all` / `deleted` / `updated` → null or empty.\n   */\n  data?: {\n    email?: string;\n    provider?: string;\n    profile?: Record<string, unknown> | null;\n    sessionId?: string;\n    [k: string]: unknown;\n  };\n  ts: number;\n}\n\nexport interface ScheduleEvent {\n  cron: string;\n  scheduledAt: number;\n  firedAt: number;\n}\n\nexport interface QueueMessage<T = unknown> {\n  id: string;\n  payload: T;\n  attempt: number;\n  enqueuedAt: number;\n}\n\nexport interface ChannelEvent<T = unknown> {\n  channel: string;\n  type: string;\n  data?: T;\n  uid?: string;\n  ts: number;\n}\n\nexport interface DeployEvent {\n  phase: 'ready' | 'draining' | 'stopped';\n  ts: number;\n}\n\n// ============ Handler context ============\n\nexport interface EventCtx {\n  /** Per-tenant env vars. */\n  env: Record<string, string>;\n  /** Trace correlation id — propagate through logs. */\n  traceId: string;\n  tenant: string;\n  handlerId: string;\n  // Platform services are attached by the runtime at invoke time.\n  [extra: string]: unknown;\n}\n\n// ============ Registered handler marker ============\n\nexport const TRIGGER_SYMBOL = '__maravilla_trigger' as const;\n\nexport interface RegisteredHandler<Event = unknown, Ctx = EventCtx> {\n  readonly [TRIGGER_SYMBOL]: EventTrigger;\n  readonly handler: (event: Event, ctx: Ctx) => unknown | Promise<unknown>;\n}\n\nfunction register<Event, Ctx = EventCtx>(\n  trigger: EventTrigger,\n  handler: (event: Event, ctx: Ctx) => unknown | Promise<unknown>,\n): RegisteredHandler<Event, Ctx> {\n  return { [TRIGGER_SYMBOL]: trigger, handler };\n}\n\n// ============ Public factory helpers ============\n\nexport function onKvChange(\n  config: Omit<EventTriggerKv, 'kind'>,\n  handler: (event: KvChangeEvent, ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<KvChangeEvent> {\n  return register({ kind: 'kv', ...config }, handler);\n}\n\nexport function onDbChange(\n  config: Omit<EventTriggerDb, 'kind'>,\n  handler: (event: DbChangeEvent, ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<DbChangeEvent> {\n  return register({ kind: 'db', ...config }, handler);\n}\n\n/**\n * React to user authentication events: registration, login, logout,\n * deletion, update. Omit `op` to match all auth events; set it to\n * narrow to a specific lifecycle transition.\n *\n * ```ts\n * export const welcomeEmail = onAuth(\n *   { op: 'registered' },\n *   async (event, ctx) => {\n *     await sendWelcomeEmail(event.data?.email);\n *   },\n * );\n * ```\n */\nexport function onAuth(\n  config: Omit<EventTriggerAuth, 'kind'>,\n  handler: (event: AuthEvent, ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<AuthEvent> {\n  return register({ kind: 'auth', ...config }, handler);\n}\n\nexport function onSchedule(\n  cron: string,\n  handler: (event: ScheduleEvent, ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<ScheduleEvent> {\n  return register({ kind: 'schedule', cron }, handler);\n}\n\nexport function onQueue<T = unknown>(\n  name: string,\n  config: Omit<EventTriggerQueue, 'kind' | 'name'>,\n  handler: (messages: QueueMessage<T>[], ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<QueueMessage<T>[]> {\n  return register({ kind: 'queue', name, ...config }, handler);\n}\n\nexport function onChannel<T = unknown>(\n  config: Omit<EventTriggerChannel, 'kind'>,\n  handler: (event: ChannelEvent<T>, ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<ChannelEvent<T>> {\n  return register({ kind: 'channel', ...config }, handler);\n}\n\nexport function onDeploy(\n  phase: EventTriggerDeploy['phase'],\n  handler: (event: DeployEvent, ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<DeployEvent> {\n  return register({ kind: 'deploy', phase }, handler);\n}\n\n/** Escape hatch for arbitrary `RenEvent` matches. */\nexport function defineEvent(\n  config: Omit<EventTriggerRen, 'kind'>,\n  handler: (event: RenEvent, ctx: EventCtx) => unknown | Promise<unknown>,\n): RegisteredHandler<RenEvent> {\n  return register({ kind: 'ren', ...config }, handler);\n}\n\n/** Type guard used by the build-time discoverer and the runtime registry. */\nexport function isRegisteredHandler(value: unknown): value is RegisteredHandler {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    TRIGGER_SYMBOL in value &&\n    typeof (value as Record<string, unknown>).handler === 'function'\n  );\n}\n"],"mappings":";AA8KO,IAAM,iBAAiB;AAO9B,SAAS,SACP,SACA,SAC+B;AAC/B,SAAO,EAAE,CAAC,cAAc,GAAG,SAAS,QAAQ;AAC9C;AAIO,SAAS,WACd,QACA,SACkC;AAClC,SAAO,SAAS,EAAE,MAAM,MAAM,GAAG,OAAO,GAAG,OAAO;AACpD;AAEO,SAAS,WACd,QACA,SACkC;AAClC,SAAO,SAAS,EAAE,MAAM,MAAM,GAAG,OAAO,GAAG,OAAO;AACpD;AAgBO,SAAS,OACd,QACA,SAC8B;AAC9B,SAAO,SAAS,EAAE,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO;AACtD;AAEO,SAAS,WACd,MACA,SACkC;AAClC,SAAO,SAAS,EAAE,MAAM,YAAY,KAAK,GAAG,OAAO;AACrD;AAEO,SAAS,QACd,MACA,QACA,SACsC;AACtC,SAAO,SAAS,EAAE,MAAM,SAAS,MAAM,GAAG,OAAO,GAAG,OAAO;AAC7D;AAEO,SAAS,UACd,QACA,SACoC;AACpC,SAAO,SAAS,EAAE,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO;AACzD;AAEO,SAAS,SACd,OACA,SACgC;AAChC,SAAO,SAAS,EAAE,MAAM,UAAU,MAAM,GAAG,OAAO;AACpD;AAGO,SAAS,YACd,QACA,SAC6B;AAC7B,SAAO,SAAS,EAAE,MAAM,OAAO,GAAG,OAAO,GAAG,OAAO;AACrD;AAGO,SAAS,oBAAoB,OAA4C;AAC9E,SACE,OAAO,UAAU,YACjB,UAAU,QACV,kBAAkB,SAClB,OAAQ,MAAkC,YAAY;AAE1D;","names":[]}