@worktif/runtime 0.3.0-edge.0

package/out/dist/lib/lib/runtime-web/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime Web Core - Library (Isomorphic/Browser)
+ *
+ * **ARCHITECTURE NOTE**: This module contains browser-safe code that:
+ * - Runs in browser environment (client-side)
+ * - Uses browser APIs (window, document, hydrateRoot)
+ * - Must be isomorphic-safe (no Node.js APIs)
+ * - NEVER runs in Lambda
+ * - Bundled into browser builds
+ *
+ * **Exports**:
+ * - BrowserPipeline: Client-side React hydration and routing
+ */
+export * from './pipelines';
+export * from './types';
+export * from './pureweb';
+//# sourceMappingURL=index.d.ts.map

package/out/dist/lib/lib/runtime-web/pipelines/browser-pipeline.d.ts

@@ -0,0 +1,110 @@
+import type { BrowserMetadata, RuntimeWebConfig } from '../../runtime-web/types';
+/**
+ * Browser execution pipeline for Runtime Target Core.
+ *
+ * @todo: ordinate this class to infra or core cause we have Node.js responsibility
+ *      ---- OR –> REMOVE LOGGER
+ *
+ * **ARCHITECTURE NOTE**: This file is in `src/lib/` because it:
+ * - Uses browser-only APIs (window, document, hydrateRoot)
+ * - Runs ONLY in browser environment
+ * - Must be isomorphic-safe (no Node.js APIs)
+ * - NEVER runs in Lambda
+ *
+ * Handles client-side hydration of React applications with pre-loaded data
+ * from server-side rendering. Sets up client-side routing and HTTP client
+ * for post-hydration API calls to Lambda endpoints.
+ *
+ * **Execution Flow**:
+ * 1. Hydrate React app with existing PurenowRouter
+ * 2. Call config.app({ router }) to get React element
+ * 3. Initialize client-side navigation
+ * 4. Set up HTTP client for Lambda endpoint calls
+ *
+ * **Requirements**: REQ-06, REQ-12
+ */
+export declare class BrowserPipeline {
+    /**
+     * Execute browser pipeline for client-side hydration.
+     *
+     * Hydrates the React application with pre-loaded data from SSR and sets up
+     * client-side routing. Uses React hydration (not render) to match the
+     * server-rendered HTML exactly.
+     *
+     * @param config - Purenow configuration with app factory and router
+     * @param context - Browser environment context with metadata
+     *
+     * @example
+     * ```typescript
+     * const pipeline = new BrowserPipeline();
+     * await pipeline.execute(config, {
+     *   type: 'browser',
+     *   metadata: {
+     *     userAgent: navigator.userAgent,
+     *     url: window.location.href,
+     *     viewport: { width: window.innerWidth, height: window.innerHeight }
+     *   }
+     * });
+     * ```
+     */
+    execute(config: RuntimeWebConfig, context: {
+        type: 'browser';
+        metadata: BrowserMetadata;
+    }): Promise<void>;
+    /**
+     * Create browser router from PurenowRouter configuration.
+     *
+     * Uses the existing PurenowRouter to get routes and creates a React Router
+     * browser router for client-side navigation.
+     *
+     * @param config - Purenow configuration
+     * @returns Browser router instance
+     * @private
+     */
+    private createBrowserRouter;
+    /**
+     * Create React element from app factory function.
+     *
+     * Calls the user's app factory function with the router dependency
+     * to get the root React element for the application.
+     *
+     * @param config - Purenow configuration
+     * @returns Root React element
+     * @private
+     */
+    private createAppElement;
+    /**
+     * Hydrate the React application in the browser.
+     *
+     * Uses React's hydrateRoot to hydrate the server-rendered HTML with
+     * the client-side React application. This ensures the client matches
+     * the server exactly to avoid hydration mismatches.
+     *
+     * @param routerProvider - Router provider element to hydrate
+     * @private
+     */
+    private hydrateApplication;
+    /**
+     * Set up HTTP client for Lambda endpoint calls.
+     *
+     * Configures the HTTP client for making API calls to Lambda endpoints
+     * after hydration. This is used for post-hydration interactions that
+     * require server-side data.
+     *
+     * @param config - Purenow configuration
+     * @private
+     */
+    private setupHttpClient;
+    /**
+     * Get API base URL based on deployment stage.
+     *
+     * Determines the appropriate API base URL for making HTTP requests
+     * to Lambda endpoints based on the deployment stage.
+     *
+     * @param stage - Deployment stage
+     * @returns API base URL
+     * @private
+     */
+    private getApiBaseUrl;
+}
+//# sourceMappingURL=browser-pipeline.d.ts.map

package/out/dist/lib/lib/runtime-web/pipelines/index.d.ts

@@ -0,0 +1,2 @@
+export { BrowserPipeline } from './browser-pipeline';
+//# sourceMappingURL=index.d.ts.map

package/out/dist/lib/lib/runtime-web/pureweb.d.ts

@@ -0,0 +1,65 @@
+import type { RuntimeWebConfig } from './types';
+/**
+ * Error thrown when configuration validation fails.
+ * Follows purenow error patterns without emoji.
+ */
+export declare class ConfigValidationError extends Error {
+    /** Array of validation error messages */
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Error thrown when environment detection fails.
+ * Follows purenow error patterns without emoji.
+ */
+export declare class EnvironmentDetectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Unified entry point for Runtime Target Core.
+ *
+ * This function provides a single API that works across all execution contexts:
+ * - **Browser**: Hydrates React application with client-side routing
+ * - **Lambda**: Executes server-side rendering and business logic with DI
+ * - **CDK**: Synthesizes CloudFormation infrastructure templates
+ *
+ * The function automatically detects the runtime environment and routes
+ * execution to the appropriate pipeline without user intervention.
+ *
+ * **Note**: For Lambda and CDK contexts, use the server-side entry point
+ * from `@core/runtime-web` instead. This browser-compatible version
+ * only supports browser hydration.
+ *
+ * @param config - Unified configuration for all contexts
+ * @returns Promise that resolves when execution completes
+ * @throws ConfigValidationError if configuration is invalid
+ * @throws EnvironmentDetectionError if environment cannot be detected
+ * @throws Error if execution fails
+ *
+ * @example
+ * ```typescript
+ * import { purenow } from '@worktif/purenow/runtime-web';
+ * import { PurenowRouter } from '@worktif/purenow';
+ *
+ * purenow({
+ *   app: ({ router }) => <App router={router} />,
+ *   router: new PurenowRouter({ routes, defaults: {} }),
+ *   serviceName: 'my-app',
+ *   stage: 'dev',
+ *   register: {
+ *     payments: {
+ *       ties: [PaymentsTies],
+ *       lambdas: [chargeHandler, refundHandler]
+ *     }
+ *   },
+ *   infra: {
+ *     env: { account: '123456789012', region: 'us-east-1' },
+ *     stage: 'dev',
+ *     reactEntry: './src/index.tsx',
+ *     apiMode: 'apiGateway'
+ *   }
+ * });
+ * ```
+ */
+export declare function pureweb(config: RuntimeWebConfig): void;
+//# sourceMappingURL=pureweb.d.ts.map

package/out/dist/lib/lib/runtime-web/types/config.types.d.ts

@@ -0,0 +1,301 @@
+import * as React from 'react';
+import type { InfraOptions } from './infra.types';
+import type { MicroserviceDefinition } from './microservice.types';
+/**
+ * PurenowRouter interface for runtime-web integration.
+ *
+ * Defines the essential methods needed by the runtime-web pipelines.
+ * This interface matches the actual PurenowRouter class from @lib/react/purenow.router.
+ */
+interface PurenowRouter {
+    /**
+     * Get all route objects as an array.
+     * Used for creating browser routers and SSR static handlers.
+     */
+    getRoutes(): Array<{
+        path?: string;
+        element?: unknown;
+        loader?: unknown;
+        children?: unknown;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Find a route by its ID.
+     */
+    getRouteById?(id: string): unknown;
+    /**
+     * Find a route by its path.
+     */
+    getRouteByPath?(path: string): unknown;
+    /**
+     * Get the routes array (getter).
+     */
+    routes?: Array<unknown>;
+    /**
+     * Get the default configuration.
+     */
+    defaults?: unknown;
+}
+/**
+ * Stage environment for deployment.
+ *
+ * - `dev`: Development environment
+ * - `staging`: Staging/pre-production environment
+ * - `prod`: Production environment
+ */
+export type Stage = 'dev' | 'staging' | 'prod';
+/**
+ * Utility type to extract service names from register configuration.
+ *
+ * This enables compile-time validation of service names and provides
+ * type-safe access to service identifiers throughout the framework.
+ *
+ * @template T - The register configuration object type
+ */
+export type ServiceNames<T extends Record<string, MicroserviceDefinition>> = keyof T;
+/**
+ * Utility type to generate Lambda IDs from service configuration.
+ *
+ * Combines service names with Lambda IDs to create fully qualified
+ * Lambda identifiers for type-safe Lambda resolution.
+ *
+ * @template T - The register configuration object type
+ */
+export type LambdaIds<T extends Record<string, MicroserviceDefinition>> = {
+    [K in keyof T]: T[K]['lambdas'][number] extends {
+        id: infer I;
+    } ? I extends string ? `${K & string}.${I}` : never : never;
+}[keyof T];
+/**
+ * Type constraint for valid service names.
+ *
+ * Ensures service names follow the validation pattern:
+ * - Must start with a letter (a-z, A-Z)
+ * - Can contain letters, numbers, and hyphens
+ * - Maximum length: 128 characters
+ *
+ * This is a branded type that provides compile-time validation.
+ */
+export type ValidServiceName = string & {
+    readonly __brand: 'ValidServiceName';
+};
+/**
+ * Type guard to validate service name format.
+ *
+ * @param serviceName - The service name to validate
+ * @returns Type predicate indicating if the service name is valid
+ */
+export declare function isValidServiceName(serviceName: string): serviceName is ValidServiceName;
+/**
+ * Main configuration interface for Runtime Target Core.
+ *
+ * This interface provides a unified configuration that works across all execution contexts:
+ * - Browser: Hydrates React application with client-side routing
+ * - Lambda: Executes server-side rendering and business logic
+ * - CDK: Synthesizes CloudFormation infrastructure
+ *
+ * @template TRegister - The register configuration type for type-safe service names
+ *
+ * @example
+ * ```typescript
+ * import { purenow } from '@worktif/purenow/runtime-web';
+ * import { PurenowRouter } from '@worktif/purenow';
+ *
+ * const config = {
+ *   app: ({ router }) => <App router={router} />,
+ *   router: new PurenowRouter({ router: routes, defaults: {} }),
+ *   serviceName: 'my-app',
+ *   stage: 'dev',
+ *   register: {
+ *     payments: {
+ *       ties: [PaymentsTies],
+ *       lambdas: [chargeHandler, refundHandler]
+ *     },
+ *     users: {
+ *       ties: [UsersTies],
+ *       lambdas: [createUserHandler, getUserHandler]
+ *     }
+ *   } as const,  // Use 'as const' for better type inference
+ *   infra: {
+ *     env: { account: '123456789012', region: 'us-east-1' },
+ *     stage: 'dev',
+ *     reactEntry: './src/index.tsx',
+ *     apiMode: 'apiGateway'
+ *   }
+ * } satisfies PurenowConfig;
+ *
+ * purenow(config);
+ * ```
+ *
+ * @todo: after RuntimeWeb repo will be resolved, RuntimeWebConfig MUST extend PurenowConfig Core
+ */
+export interface RuntimeWebConfig<TRegister extends Record<string, MicroserviceDefinition> = Record<string, MicroserviceDefinition>> {
+    /**
+     * React application component factory function.
+     *
+     * Receives the router instance as a dependency and returns the root React element.
+     * This pattern enables dependency injection of the router into your application.
+     *
+     * @param deps - Dependencies object containing the router
+     * @param deps.router - PurenowRouter instance for navigation and routing
+     * @returns Root React element (React.ReactElement)
+     *
+     * @example
+     * ```typescript
+     * app: ({ router }) => <App router={router} />
+     * ```
+     */
+    app: (deps: {
+        router: PurenowRouter;
+    }) => React.ReactElement;
+    /**
+     * PurenowRouter instance for application routing.
+     *
+     * Defines all routes, loaders, and navigation configuration.
+     * The router is used in both server-side rendering (Lambda) and client-side hydration (browser).
+     *
+     * @see {@link PurenowRouter} for router configuration
+     *
+     * @example
+     * ```typescript
+     * router: new PurenowRouter({
+     *   router: [
+     *     { path: '/', element: <Home /> },
+     *     { path: '/about', element: <About /> }
+     *   ],
+     *   defaults: {}
+     * })
+     * ```
+     */
+    router: PurenowRouter;
+    /**
+     * Service name identifier for the application.
+     *
+     * Used as a prefix for all AWS resources (Lambda functions, API Gateway, S3 buckets, etc.).
+     * Must be unique within your AWS account and region.
+     *
+     * **Validation Rules**:
+     * - Must start with a letter (a-z, A-Z)
+     * - Can contain letters, numbers, and hyphens
+     * - Maximum length: 128 characters
+     * - Pattern: `/^[a-zA-Z][a-zA-Z0-9-]{0,127}$/`
+     *
+     * **Examples**:
+     * - Valid: `my-app`, `MyApp`, `app123`, `my-app-v2`
+     * - Invalid: `123app` (starts with number), `my_app` (underscore), `my app` (space)
+     *
+     * @example
+     * ```typescript
+     * serviceName: 'my-application'
+     * ```
+     */
+    serviceName: string;
+    /**
+     * Deployment stage/environment.
+     *
+     * Determines the environment-specific configuration and resource naming.
+     * Used to create separate infrastructure stacks for different environments.
+     *
+     * **Values**:
+     * - `dev`: Development environment (local testing, rapid iteration)
+     * - `staging`: Staging/pre-production environment (QA, integration testing)
+     * - `prod`: Production environment (live users)
+     *
+     * **Impact**:
+     * - Resource naming: `{serviceName}-{resource}-{stage}`
+     * - Environment variables: Different configs per stage
+     * - Cache TTL: Shorter in dev, longer in prod
+     * - Logging: More verbose in dev, structured in prod
+     *
+     * @example
+     * ```typescript
+     * stage: 'dev'
+     * ```
+     */
+    stage: Stage;
+    /**
+     * Microservice registry (runtime-level configuration).
+     *
+     * **Required**: Defines all microservices, their DI containers, and Lambda endpoints.
+     * **Used in all contexts**: Browser (for type generation), Lambda (for DI), CDK (for infrastructure).
+     * **Architecture**: This is runtime configuration, separate from infrastructure concerns.
+     *
+     * Each microservice gets its own PureContainer instance built from the Ties classes.
+     * Lambda functions are automatically created and wired with dependency injection.
+     *
+     * **Type Safety**: Service names are derived from object keys, ensuring compile-time validation.
+     * **No Magic Strings**: All service identifiers are type-safe and auto-generated.
+     *
+     * @see {@link MicroserviceDefinition} for microservice structure
+     *
+     * @example
+     * ```typescript
+     * register: {
+     *   payments: {
+     *     ties: [PaymentsTies, BillingTies],
+     *     lambdas: [chargeHandler, refundHandler, webhookHandler]
+     *   },
+     *   users: {
+     *     ties: [UsersTies, AuthTies],
+     *     lambdas: [createUserHandler, getUserHandler, loginHandler]
+     *   }
+     * } as const  // Use 'as const' for better type inference
+     * ```
+     */
+    register: TRegister;
+    /**
+     * Infrastructure configuration for CDK deployment.
+     *
+     * **Optional**: Only required when running in CDK context (synthesizing CloudFormation templates).
+     * **Not used**: In browser and Lambda contexts (runtime configuration is in register).
+     * **Pure infrastructure**: Contains only AWS resource configuration, no business logic.
+     *
+     * Defines:
+     * - AWS account and region
+     * - Lambda configuration (memory, timeout, VPC)
+     * - API Gateway or Lambda URL mode
+     * - Custom domain configuration
+     * - React entry point for SSR Lambda
+     *
+     * @see {@link InfraOptions} for detailed configuration options
+     *
+     * @example
+     * ```typescript
+     * infra: {
+     *   env: { account: '123456789012', region: 'us-east-1' },
+     *   stage: 'dev',
+     *   reactEntry: './src/index.tsx',
+     *   apiMode: 'apiGateway',
+     *   lambdaMemorySize: 1024,
+     *   lambdaTimeout: 30,
+     *   domain: {
+     *     rootDomain: 'myapp.com',
+     *     subdomain: 'api'
+     *   }
+     * }
+     * ```
+     */
+    infra?: InfraOptions;
+}
+/**
+ * Type-safe Purenow configuration with inferred service names.
+ *
+ * This type provides Runtime Core type safety by inferring service names from the register
+ * configuration, enabling compile-time validation of service references.
+ *
+ * @template TRegister - The register configuration type
+ */
+export type TypeSafePurenowConfig<TRegister extends Record<string, MicroserviceDefinition>> = RuntimeWebConfig<TRegister> & {
+    /**
+     * Type-safe service names derived from register keys.
+     * Available at compile-time for type checking and IDE autocomplete.
+     */
+    readonly serviceNames?: ServiceNames<TRegister>;
+    /**
+     * Type-safe Lambda IDs derived from register configuration.
+     * Available at compile-time for type checking and IDE autocomplete.
+     */
+    readonly lambdaIds?: LambdaIds<TRegister>;
+};
+export {};
+//# sourceMappingURL=config.types.d.ts.map

package/out/dist/lib/lib/runtime-web/types/http.types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * HTTP methods supported by API Gateway integration.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+/**
+ * Authentication types for HTTP endpoints.
+ *
+ * Maps to appropriate CDK authorizer configurations:
+ * - `none`: No authentication required
+ * - `jwt`: JWT token validation (Cognito User Pools or custom)
+ * - `iam`: AWS IAM signature validation
+ * - `cognito`: Cognito User Pool authorizer
+ * - `custom`: Custom Lambda authorizer
+ */
+export type AuthType = 'none' | 'jwt' | 'iam' | 'cognito' | 'custom';
+/**
+ * CORS configuration for HTTP endpoints.
+ *
+ * Provides fine-grained control over Cross-Origin Resource Sharing settings.
+ * Used when cors: true and corsConfig is provided in HttpIntegration.
+ */
+export interface CorsConfig {
+    /**
+     * Allowed origins for CORS requests.
+     *
+     * **Examples**:
+     * - `['*']`: Allow all origins (development only)
+     * - `['https://myapp.com']`: Specific domain
+     * - `['https://myapp.com', 'https://staging.myapp.com']`: Multiple domains
+     *
+     * @default ['*'] in dev, specific domains in staging/prod
+     */
+    allowOrigins?: string[];
+    /**
+     * Allowed HTTP methods for CORS requests.
+     *
+     * **Examples**:
+     * - `['GET', 'POST']`: Specific methods
+     * - `['*']`: All methods
+     *
+     * @default All methods used by registered Lambda endpoints
+     */
+    allowMethods?: HttpMethod[] | ['*'];
+    /**
+     * Allowed headers for CORS requests.
+     *
+     * **Common headers**:
+     * - `Content-Type`: For JSON/form data
+     * - `Authorization`: For auth tokens
+     * - `X-Requested-With`: For AJAX requests
+     *
+     * @default ['Content-Type', 'Authorization', 'X-Requested-With']
+     */
+    allowHeaders?: string[];
+    /**
+     * Whether to allow credentials (cookies, auth headers) in CORS requests.
+     *
+     * **Important**: Cannot be true when allowOrigins includes '*'
+     *
+     * @default false
+     */
+    allowCredentials?: boolean;
+    /**
+     * Maximum age (seconds) for CORS preflight cache.
+     *
+     * How long browsers can cache the CORS preflight response.
+     *
+     * @default 86400 (24 hours)
+     */
+    maxAge?: number;
+    /**
+     * Headers exposed to the client in CORS responses.
+     *
+     * **Common exposed headers**:
+     * - `X-Request-ID`: For request tracking
+     * - `X-RateLimit-*`: For rate limiting info
+     *
+     * @default []
+     */
+    exposeHeaders?: string[];
+}
+/**
+ * HTTP integration configuration for Lambda endpoints.
+ *
+ * Defines how a Lambda function is exposed as an HTTP endpoint through
+ * API Gateway. Provides high-level configuration that maps to CDK constructs.
+ */
+export interface HttpIntegration {
+    /**
+     * HTTP method for the endpoint.
+     *
+     * @example
+     * ```typescript
+     * method: 'POST'  // For creating resources
+     * method: 'GET'   // For retrieving data
+     * method: 'PUT'   // For updating resources
+     * ```
+     */
+    method: HttpMethod;
+    /**
+     * URL path for the endpoint.
+     *
+     * **Path Parameters**: Use `{param}` syntax for dynamic segments
+     * **Examples**:
+     * - `/api/users`: Static path
+     * - `/api/users/{id}`: Path with parameter
+     * - `/api/users/{id}/orders/{orderId}`: Multiple parameters
+     *
+     * @example
+     * ```typescript
+     * path: '/api/payments/charge'
+     * path: '/api/users/{userId}/payments'
+     * ```
+     */
+    path: string;
+    /**
+     * Authentication type for the endpoint.
+     *
+     * The framework automatically maps these to appropriate CDK authorizer configurations:
+     * - `none`: Public endpoint, no authentication
+     * - `jwt`: JWT token validation (requires token in Authorization header)
+     * - `iam`: AWS IAM signature validation (for service-to-service calls)
+     * - `cognito`: Cognito User Pool authorizer
+     * - `custom`: Custom Lambda authorizer function
+     *
+     * @default 'none'
+     *
+     * @example
+     * ```typescript
+     * auth: 'jwt'     // Requires valid JWT token
+     * auth: 'none'    // Public endpoint
+     * auth: 'iam'     // AWS service calls
+     * ```
+     */
+    auth?: AuthType;
+    /**
+     * Enable CORS for the endpoint.
+     *
+     * **Simple CORS**: Set to `true` for default CORS configuration
+     * **Custom CORS**: Set to `true` and provide `corsConfig` for fine-grained control
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * cors: true  // Enable with defaults
+     * ```
+     */
+    cors?: boolean;
+    /**
+     * Detailed CORS configuration.
+     *
+     * **Required**: `cors` must be `true` for this to take effect
+     * **Optional**: If omitted, uses sensible defaults based on stage
+     *
+     * @see {@link CorsConfig}
+     *
+     * @example
+     * ```typescript
+     * corsConfig: {
+     *   allowOrigins: ['https://myapp.com'],
+     *   allowMethods: ['GET', 'POST'],
+     *   allowHeaders: ['Content-Type', 'Authorization'],
+     *   allowCredentials: true,
+     *   maxAge: 3600
+     * }
+     * ```
+     */
+    corsConfig?: CorsConfig;
+}
+//# sourceMappingURL=http.types.d.ts.map

package/out/dist/lib/lib/runtime-web/types/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime Web Core Types
+ *
+ * Barrel export for all Runtime Web Core type definitions.
+ * Organized by functional area for clean imports.
+ */
+export type { RuntimeWebConfig, TypeSafePurenowConfig, Stage, ServiceNames, LambdaIds, ValidServiceName, } from './config.types';
+export { isValidServiceName } from './config.types';
+export type { InfraOptions, AwsEnvironment, DomainConfig, VpcConfig } from './infra.types';
+export type { MicroserviceDefinition, TiesInstance } from './microservice.types';
+export type { LambdaDefinition, LambdaHandlerFactory, LambdaConfig } from './lambda.types';
+export type { HttpIntegration, HttpMethod, AuthType, CorsConfig } from './http.types';
+export type { EnvironmentContext, BrowserMetadata, LambdaMetadata, CDKMetadata, } from './runtime.types';
+//# sourceMappingURL=index.d.ts.map