@eldrin-project/eldrin-app-core 0.0.1 → 0.0.2

package/dist/index.d.cts

@@ -56,20 +56,94 @@ interface MigrationOptions {
     /** Callback for logging */
     onLog?: (message: string, level: 'info' | 'warn' | 'error') => void;
 }
+/**
+ * Permission declaration in app manifest
+ */
+interface ManifestPermission {
+    /** Resource name (e.g., "invoices", "customers") */
+    resource: string;
+    /** Allowed actions on this resource */
+    actions: string[];
+}
+/**
+ * Group/role declaration in app manifest
+ */
+interface ManifestGroup {
+    /** Group identifier (e.g., "admin", "viewer") */
+    id: string;
+    /** Display name for the group */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Permissions granted to this group (e.g., ["invoices:read", "invoices:*"]) */
+    permissions: string[];
+}
 /**
  * App configuration from eldrin-app.manifest.json
  */
 interface AppManifest {
+    /** App identifier (unique within developer namespace) */
     name: string;
+    /** App version (semver) */
     version: string;
+    /** Developer ID (namespace owner) */
+    developerId?: string;
+    /** Display name shown in UI */
     displayName?: string;
+    /** Short description */
     description?: string;
-    permissions?: string[];
+    /** Icon URL or path */
+    icon?: string;
+    /** Webhook hooks configuration */
     hooks?: Record<string, string>;
+    /** Event system configuration */
     events?: {
+        /** Event types this app emits */
         emits?: string[];
+        /** Event types this app subscribes to */
         subscribes?: string[];
     };
+    /**
+     * Permission declarations for this app
+     *
+     * Defines the resources and actions that can be assigned to users.
+     * Full permission format: developer_id:app_id:resource:action
+     *
+     * @example
+     * ```json
+     * {
+     *   "permissions": [
+     *     { "resource": "invoices", "actions": ["read", "write", "delete"] },
+     *     { "resource": "customers", "actions": ["read", "write"] }
+     *   ]
+     * }
+     * ```
+     */
+    permissions?: ManifestPermission[];
+    /**
+     * Group/role definitions for this app
+     *
+     * Groups bundle permissions together for easier assignment.
+     *
+     * @example
+     * ```json
+     * {
+     *   "groups": [
+     *     {
+     *       "id": "admin",
+     *       "name": "App Admin",
+     *       "permissions": ["invoices:*", "customers:*"]
+     *     },
+     *     {
+     *       "id": "viewer",
+     *       "name": "Viewer",
+     *       "permissions": ["invoices:read", "customers:read"]
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    groups?: ManifestGroup[];
 }
 /**
  * Options for createApp factory
@@ -482,4 +556,513 @@ declare function validateMigrationManifest(manifest: MigrationManifest, files: M
     errors: string[];
 }>;
 
-export { type AppLifecycle, type AppManifest, CHECKSUM_PREFIX, type CreateAppOptions, type DatabaseContext, DatabaseProvider, type DatabaseProviderProps, type EldrinContext, type GenerateMigrationManifestOptions, type GenerateMigrationManifestResult, type LifecycleProps, type MigrationFile, type MigrationFiles, type MigrationManifest, type MigrationManifestEntry, type MigrationOptions, type MigrationRecord, type MigrationResult, type RollbackResult, calculateChecksum, calculatePrefixedChecksum, createApp, extractTimestamp, generateMigrationManifest, getMigrationStatus, getRollbackFilename, isValidMigrationFilename, isValidRollbackFilename, parseSQLStatements, rollbackMigrations, runMigrations, useDatabase, useDatabaseContext, useMigrationsComplete, validateMigrationManifest, verifyChecksum };
+/**
+ * Event System Types
+ * Types for server-side inter-app event communication
+ */
+/**
+ * Base event structure
+ */
+interface EldrinEvent<T = unknown> {
+    /** Unique event ID (UUID) */
+    id: string;
+    /** Event type identifier (e.g., "invoice.created") */
+    type: string;
+    /** App ID that emitted the event */
+    source: string;
+    /** Event payload data */
+    payload: T;
+    /** Payload schema version */
+    version: number;
+    /** Unix timestamp (ms) when event was created */
+    timestamp: number;
+    /** Optional idempotency key for deduplication */
+    idempotencyKey?: string;
+}
+/**
+ * Options for emitting events
+ */
+interface EmitOptions {
+    /** Optional key to prevent duplicate events */
+    idempotencyKey?: string;
+    /** Payload schema version (default: 1) */
+    version?: number;
+}
+/**
+ * Result from emitting an event
+ */
+interface EmitResult {
+    /** ID of the created event */
+    eventId: string;
+    /** Event type */
+    type: string;
+    /** True if event was deduplicated (already existed) */
+    deduplicated?: boolean;
+}
+/**
+ * Event delivery record
+ */
+interface EventDelivery<T = unknown> {
+    /** Delivery record ID */
+    id: number;
+    /** The event being delivered */
+    event: EldrinEvent<T>;
+    /** Delivery status */
+    status: 'pending' | 'delivered' | 'failed';
+    /** Number of delivery attempts */
+    attempts: number;
+    /** Timestamp of last attempt */
+    lastAttemptAt?: number;
+}
+/**
+ * Result from polling events
+ */
+interface PollResult<T = unknown> {
+    /** List of pending event deliveries */
+    events: EventDelivery<T>[];
+    /** True if there are more events to fetch */
+    hasMore: boolean;
+}
+/**
+ * Options for polling events
+ */
+interface PollOptions {
+    /** Maximum number of events to fetch (default: 10, max: 100) */
+    limit?: number;
+    /** Only fetch events of these types */
+    types?: string[];
+}
+/**
+ * Configuration for the event client
+ */
+interface EventClientConfig {
+    /** App ID for this client */
+    appId: string;
+    /** Base URL of the Eldrin Core worker */
+    coreApiUrl: string;
+}
+/**
+ * Event handler function type
+ */
+type EventHandler<T = unknown> = (event: EldrinEvent<T>) => Promise<void> | void;
+/**
+ * Subscription info returned from the API
+ */
+interface SubscriptionInfo {
+    /** Subscription ID */
+    id: number;
+    /** Event pattern (e.g., "invoice.*") */
+    pattern: string;
+    /** Delivery mode */
+    deliveryMode: 'poll' | 'push';
+    /** Whether subscription is enabled */
+    enabled: boolean;
+}
+/**
+ * Registered event type info
+ */
+interface RegisteredEventType {
+    /** Event type identifier */
+    type: string;
+    /** App that can emit this event */
+    sourceApp: string;
+    /** Human-readable description */
+    description?: string;
+}
+
+/**
+ * Eldrin Event Client
+ * SDK for app workers to emit and consume events
+ */
+
+/**
+ * Client for interacting with the Eldrin event bus
+ *
+ * @example
+ * ```typescript
+ * const events = new EldrinEventClient({
+ *   appId: 'invoicing',
+ *   coreApiUrl: 'https://your-eldrin-core.workers.dev'
+ * });
+ *
+ * // Emit an event
+ * await events.emit('invoice.created', { invoiceId: 'inv_123', total: 1500 });
+ *
+ * // Poll for events
+ * const pending = await events.poll();
+ * for (const delivery of pending.events) {
+ *   await processEvent(delivery.event);
+ *   await events.ack(delivery.id);
+ * }
+ * ```
+ */
+declare class EldrinEventClient {
+    private readonly appId;
+    private readonly coreApiUrl;
+    constructor(config: EventClientConfig);
+    /**
+     * Emit an event to the event bus
+     *
+     * @param type - Event type (must be declared in app's manifest emits)
+     * @param payload - Event payload data
+     * @param options - Optional emit configuration
+     * @returns Result containing the event ID
+     * @throws Error if app is not authorized to emit this event type
+     */
+    emit<T>(type: string, payload: T, options?: EmitOptions): Promise<EmitResult>;
+    /**
+     * Poll for pending events
+     *
+     * @param options - Optional polling configuration
+     * @returns List of pending event deliveries
+     */
+    poll<T = unknown>(options?: PollOptions): Promise<PollResult<T>>;
+    /**
+     * Acknowledge successful event processing
+     *
+     * @param deliveryId - The delivery record ID to acknowledge
+     */
+    ack(deliveryId: number): Promise<void>;
+    /**
+     * Negative acknowledge - event will be retried later
+     *
+     * @param deliveryId - The delivery record ID
+     * @param error - Optional error message for logging
+     */
+    nack(deliveryId: number, error?: string): Promise<void>;
+    /**
+     * Get all registered event types
+     *
+     * @returns List of all registered event types across all apps
+     */
+    getEventTypes(): Promise<RegisteredEventType[]>;
+    /**
+     * Get subscriptions for this app
+     *
+     * @returns List of active subscriptions
+     */
+    getSubscriptions(): Promise<SubscriptionInfo[]>;
+}
+/**
+ * Environment bindings that may include Eldrin Core URL
+ */
+interface EldrinEnv {
+    ELDRIN_CORE_URL?: string;
+    [key: string]: unknown;
+}
+/**
+ * Create an event client for use in app workers
+ *
+ * @param env - Worker environment bindings (must have optional ELDRIN_CORE_URL)
+ * @param appId - The app's identifier
+ * @returns Configured event client
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const events = createEventClient(env, 'invoicing');
+ *     await events.emit('invoice.created', { invoiceId: 'inv_123' });
+ *   }
+ * };
+ * ```
+ */
+declare function createEventClient(env: EldrinEnv, appId: string): EldrinEventClient;
+
+/**
+ * Auth utilities for Eldrin apps
+ *
+ * Supports two authentication methods:
+ *
+ * 1. JWT Token (Authorization header):
+ *    - Direct API calls with JWT token in Authorization: Bearer <token>
+ *    - JWT is verified using shared secret (JWT_SECRET env var)
+ *    - Permissions extracted from JWT payload
+ *
+ * 2. Proxy Headers (X-Eldrin-User-* headers):
+ *    - Requests proxied through eldrin-core shell
+ *    - Shell verifies JWT and injects user context headers
+ *    - Legacy support for proxied requests
+ *
+ * JWT takes precedence if Authorization header is present.
+ */
+/**
+ * Auth context extracted from JWT or shell-injected headers
+ */
+interface AppAuthContext {
+    /** User ID */
+    userId: string;
+    /** User email */
+    email: string;
+    /** User display name */
+    name: string;
+    /** Platform roles (admin, editor, viewer) */
+    platformRoles: string[];
+    /** App-specific permissions (e.g., ["invoices:read", "invoices:write"]) */
+    permissions: string[];
+}
+/**
+ * JWT payload structure (matches eldrin-core JWT format)
+ */
+interface JWTPayload {
+    /** User ID */
+    sub: string;
+    /** Email */
+    email: string;
+    /** First name */
+    firstName: string;
+    /** Last name */
+    lastName: string;
+    /** Platform role names */
+    platformRoles: string[];
+    /** Platform permission names */
+    platformPermissions: string[];
+    /**
+     * App permissions in compact format
+     * Key: "developer_id:app_id", Value: ["resource:action", ...]
+     */
+    appPermissions: Record<string, string[]>;
+    /** Issued at (timestamp) */
+    iat: number;
+    /** Expiration (timestamp) */
+    exp: number;
+}
+/**
+ * Options for JWT verification
+ */
+interface JWTVerifyOptions {
+    /** JWT secret key (from env.JWT_SECRET) */
+    secret: string;
+    /** App ID for extracting app-specific permissions */
+    appId: string;
+    /** Developer ID (optional, uses wildcard matching if not provided) */
+    developerId?: string;
+}
+/**
+ * Header names used by the shell for auth context injection
+ */
+declare const AUTH_HEADERS: {
+    readonly USER_ID: "x-eldrin-user-id";
+    readonly USER_EMAIL: "x-eldrin-user-email";
+    readonly USER_NAME: "x-eldrin-user-name";
+    readonly USER_ROLES: "x-eldrin-user-roles";
+    readonly USER_PERMISSIONS: "x-eldrin-user-permissions";
+};
+/**
+ * Verify JWT token and extract auth context
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const result = await verifyJWT(request, {
+ *       secret: env.JWT_SECRET,
+ *       appId: 'react-todo',
+ *     });
+ *
+ *     if (!result.success) {
+ *       return new Response(JSON.stringify({ error: result.error }), {
+ *         status: 401,
+ *         headers: { 'Content-Type': 'application/json' },
+ *       });
+ *     }
+ *
+ *     // result.auth contains the AppAuthContext
+ *     console.log('User:', result.auth.email);
+ *   }
+ * }
+ * ```
+ */
+declare function verifyJWT(request: Request, options: JWTVerifyOptions): Promise<{
+    success: true;
+    auth: AppAuthContext;
+} | {
+    success: false;
+    error: string;
+}>;
+/**
+ * Get auth context from JWT token or fall back to proxy headers
+ *
+ * This is the recommended way to get auth context as it supports both:
+ * - Direct API calls with JWT token
+ * - Proxied requests with shell-injected headers
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const auth = await getAuthContextFromJWT(request, {
+ *       secret: env.JWT_SECRET,
+ *       appId: 'react-todo',
+ *     });
+ *
+ *     if (!auth) {
+ *       return new Response('Unauthorized', { status: 401 });
+ *     }
+ *
+ *     console.log('User:', auth.email);
+ *   }
+ * }
+ * ```
+ */
+declare function getAuthContextFromJWT(request: Request, options: JWTVerifyOptions): Promise<AppAuthContext | null>;
+/**
+ * Require JWT authentication - returns auth context or error response
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const auth = await requireJWTAuth(request, {
+ *       secret: env.JWT_SECRET,
+ *       appId: 'react-todo',
+ *     });
+ *
+ *     if (auth instanceof Response) {
+ *       return auth; // 401 Unauthorized
+ *     }
+ *
+ *     console.log('User:', auth.email);
+ *   }
+ * }
+ * ```
+ */
+declare function requireJWTAuth(request: Request, options: JWTVerifyOptions): Promise<AppAuthContext | Response>;
+/**
+ * Require JWT auth with specific permission - returns auth context or error response
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const auth = await requireJWTPermission(request, {
+ *       secret: env.JWT_SECRET,
+ *       appId: 'react-todo',
+ *     }, 'categories', 'create');
+ *
+ *     if (auth instanceof Response) {
+ *       return auth; // 401 or 403
+ *     }
+ *
+ *     // User has categories:create permission
+ *   }
+ * }
+ * ```
+ */
+declare function requireJWTPermission(request: Request, options: JWTVerifyOptions, resource: string, action: string): Promise<AppAuthContext | Response>;
+/**
+ * Extract auth context from request headers (proxy mode)
+ *
+ * Returns null if the user is not authenticated (no user ID header).
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request) {
+ *     const auth = getAuthContext(request);
+ *     if (!auth) {
+ *       return new Response('Unauthorized', { status: 401 });
+ *     }
+ *     console.log('User:', auth.email);
+ *   }
+ * }
+ * ```
+ */
+declare function getAuthContext(request: Request): AppAuthContext | null;
+/**
+ * Require authentication - returns auth context or error response
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request) {
+ *     const auth = requireAuth(request);
+ *     if (auth instanceof Response) {
+ *       return auth; // 401 Unauthorized
+ *     }
+ *     // auth is AppAuthContext
+ *     console.log('User:', auth.email);
+ *   }
+ * }
+ * ```
+ */
+declare function requireAuth(request: Request): AppAuthContext | Response;
+/**
+ * Check if auth context has a specific permission
+ *
+ * Supports wildcard matching:
+ * - "invoices:*" matches any action on invoices
+ * - "*:*" matches all permissions
+ *
+ * @example
+ * ```typescript
+ * const auth = getAuthContext(request);
+ * if (auth && hasPermission(auth, 'invoices', 'write')) {
+ *   // User can write invoices
+ * }
+ * ```
+ */
+declare function hasPermission(auth: AppAuthContext, resource: string, action: string): boolean;
+/**
+ * Check if auth context has a platform role
+ *
+ * @example
+ * ```typescript
+ * const auth = getAuthContext(request);
+ * if (auth && hasPlatformRole(auth, 'admin')) {
+ *   // User is platform admin
+ * }
+ * ```
+ */
+declare function hasPlatformRole(auth: AppAuthContext, role: string): boolean;
+/**
+ * Check if auth context is a platform admin
+ *
+ * Platform admins have full access to all apps and resources.
+ */
+declare function isPlatformAdmin(auth: AppAuthContext): boolean;
+/**
+ * Require a specific permission - returns auth context or error response
+ *
+ * Also grants access if user is a platform admin.
+ *
+ * @example
+ * ```typescript
+ * export default {
+ *   async fetch(request: Request) {
+ *     const auth = requirePermission(request, 'invoices', 'write');
+ *     if (auth instanceof Response) {
+ *       return auth; // 401 or 403
+ *     }
+ *     // User has invoices:write permission
+ *   }
+ * }
+ * ```
+ */
+declare function requirePermission(request: Request, resource: string, action: string): AppAuthContext | Response;
+/**
+ * Require any of the specified permissions - returns auth context or error response
+ *
+ * @example
+ * ```typescript
+ * const auth = requireAnyPermission(request, [
+ *   ['invoices', 'read'],
+ *   ['invoices', 'write'],
+ * ]);
+ * ```
+ */
+declare function requireAnyPermission(request: Request, permissions: Array<[resource: string, action: string]>): AppAuthContext | Response;
+/**
+ * Require all of the specified permissions - returns auth context or error response
+ *
+ * @example
+ * ```typescript
+ * const auth = requireAllPermissions(request, [
+ *   ['invoices', 'read'],
+ *   ['customers', 'read'],
+ * ]);
+ * ```
+ */
+declare function requireAllPermissions(request: Request, permissions: Array<[resource: string, action: string]>): AppAuthContext | Response;
+
+export { AUTH_HEADERS, type AppAuthContext, type AppLifecycle, type AppManifest, CHECKSUM_PREFIX, type CreateAppOptions, type DatabaseContext, DatabaseProvider, type DatabaseProviderProps, type EldrinContext, type EldrinEnv, type EldrinEvent, EldrinEventClient, type EmitOptions, type EmitResult, type EventClientConfig, type EventDelivery, type EventHandler, type GenerateMigrationManifestOptions, type GenerateMigrationManifestResult, type JWTPayload, type JWTVerifyOptions, type LifecycleProps, type ManifestGroup, type ManifestPermission, type MigrationFile, type MigrationFiles, type MigrationManifest, type MigrationManifestEntry, type MigrationOptions, type MigrationRecord, type MigrationResult, type PollOptions, type PollResult, type RegisteredEventType, type RollbackResult, type SubscriptionInfo, calculateChecksum, calculatePrefixedChecksum, createApp, createEventClient, extractTimestamp, generateMigrationManifest, getAuthContext, getAuthContextFromJWT, getMigrationStatus, getRollbackFilename, hasPermission, hasPlatformRole, isPlatformAdmin, isValidMigrationFilename, isValidRollbackFilename, parseSQLStatements, requireAllPermissions, requireAnyPermission, requireAuth, requireJWTAuth, requireJWTPermission, requirePermission, rollbackMigrations, runMigrations, useDatabase, useDatabaseContext, useMigrationsComplete, validateMigrationManifest, verifyChecksum, verifyJWT };