@jay-framework/fullstack-component 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -30,6 +30,31 @@ declare function createJayService<ServiceType = unknown>(name?: string): Service
 type ServiceMarkers<T extends any[]> = {
     [K in keyof T]: ServiceMarker<T[K]>;
 };
+/**
+ * Contract metadata passed to dynamic contract components.
+ * Contains the contract name and original YAML definition.
+ */
+interface DynamicContractMetadata {
+    contractName: string;
+    contractYaml: string;
+}
+/**
+ * Built-in service for dynamic contract metadata.
+ * Used by plugin system to pass contract metadata to shared components.
+ *
+ * @example
+ * ```typescript
+ * export const cmsCollection = makeJayStackComponent<DynamicContract>()
+ *   .withServices(DYNAMIC_CONTRACT_SERVICE)
+ *   .withFastRender(async (props, metadata: DynamicContractMetadata) => {
+ *     // metadata.contractName contains the full contract name (e.g., "BlogPostsList")
+ *     const collectionName = deriveCollectionName(metadata.contractName);
+ *     const items = await fetchCollection(collectionName);
+ *     return partialRender({ items }, {});
+ *   });
+ * ```
+ */
+declare const DYNAMIC_CONTRACT_SERVICE: ServiceMarker<DynamicContractMetadata>;
 interface PageProps {
     language: string;
     url: string;
@@ -38,24 +63,43 @@ type UrlParams = Record<string, string>;
 interface ServerError5xx {
     kind: 'ServerError';
     status: number;
+    message?: string;
+    code?: string;
+    details?: Record<string, unknown>;
 }
 interface ClientError4xx {
     kind: 'ClientError';
     status: number;
+    message?: string;
+    code?: string;
+    details?: Record<string, unknown>;
 }
 interface Redirect3xx {
-    kind: 'redirect';
+    kind: 'Redirect';
     status: number;
     location: string;
+    message?: string;
 }
-interface PartialRender<ViewState extends object, CarryForward> {
-    kind: 'PartialRender';
+/**
+ * Successful output of a rendering phase.
+ * Contains the rendered ViewState and data to carry forward to the next phase.
+ */
+interface PhaseOutput<ViewState extends object, CarryForward = {}> {
+    kind: 'PhaseOutput';
     rendered: ViewState;
     carryForward: CarryForward;
 }
-type SlowlyRenderResult<ViewState extends object, CarryForward> = PartialRender<ViewState, CarryForward> | ServerError5xx | ClientError4xx | Redirect3xx;
+/**
+ * @deprecated Use PhaseOutput instead. PartialRender is kept for backwards compatibility.
+ */
+type PartialRender<ViewState extends object, CarryForward> = PhaseOutput<ViewState, CarryForward>;
+/**
+ * Union of all possible render outcomes.
+ */
+type RenderOutcome<ViewState extends object, CarryForward = {}> = PhaseOutput<ViewState, CarryForward> | ServerError5xx | ClientError4xx | Redirect3xx;
+type SlowlyRenderResult<ViewState extends object, CarryForward = {}> = RenderOutcome<ViewState, CarryForward>;
 type AnySlowlyRenderResult = SlowlyRenderResult<object, object>;
-type FastRenderResult<ViewState extends object, CarryForward> = PartialRender<ViewState, CarryForward> | ServerError5xx | ClientError4xx | Redirect3xx;
+type FastRenderResult<ViewState extends object, CarryForward = {}> = RenderOutcome<ViewState, CarryForward>;
 type AnyFastRenderResult = FastRenderResult<object, object>;
 type LoadParams<Services, Params extends UrlParams> = (contexts: Services) => AsyncIterable<Params[]>;
 type RenderSlowly<Services extends Array<object>, PropsT extends object, SlowViewState extends object, SlowlyCarryForward> = (props: PropsT, ...services: Services) => Promise<SlowlyRenderResult<SlowViewState, SlowlyCarryForward>>;
@@ -69,12 +113,51 @@ interface JayStackComponentDefinition<Refs extends object, SlowVS extends object
     comp: ComponentConstructor<PropsT, Refs, InteractiveVS, Contexts, CompCore>;
 }
 type AnyJayStackComponentDefinition = JayStackComponentDefinition<object, object, object, object, object[], object[], object, UrlParams, any>;
+/**
+ * A generated contract definition in YAML string format.
+ *
+ * This avoids dependency on compiler types - generators output contract YAML,
+ * which the compiler parses using its own type system.
+ */
+interface GeneratedContractYaml {
+    name: string;
+    yaml: string;
+    description?: string;
+}
+/**
+ * Function that generates contracts dynamically at build time.
+ * Returns contract definitions as YAML strings to avoid compiler type dependencies.
+ * Services are injected based on the markers provided to withServices().
+ */
+type ContractGeneratorFunction<Services extends any[]> = (...services: Services) => Promise<GeneratedContractYaml[]> | GeneratedContractYaml[];
+/**
+ * Interface for a dynamic contract generator with service dependencies.
+ * Returned by makeContractGenerator() builder.
+ */
+interface DynamicContractGenerator<Services extends any[] = any[]> {
+    services: ServiceMarkers<Services>;
+    generate: ContractGeneratorFunction<Services>;
+}
+/**
+ * Type helper to extract service instances from service markers.
+ */
+type ServiceInstances<Markers extends ServiceMarkers<any[]>> = Markers extends ServiceMarkers<infer Services> ? Services : never;
 
-declare function serverError5xx(status: number): ServerError5xx;
-declare function clientError4xx(status: number): ClientError4xx;
-declare function notFound(): ClientError4xx;
-declare function redirect3xx(status: number, location: string): Redirect3xx;
-declare function partialRender<ViewState extends object, CarryForward>(rendered: ViewState, carryForward: CarryForward): PartialRender<ViewState, CarryForward>;
+declare function serverError5xx(status: number, message?: string, details?: Record<string, unknown>): ServerError5xx;
+declare function clientError4xx(status: number, message?: string, details?: Record<string, unknown>): ClientError4xx;
+declare function notFound(message?: string, details?: Record<string, unknown>): ClientError4xx;
+declare function badRequest(message?: string, details?: Record<string, unknown>): ClientError4xx;
+declare function unauthorized(message?: string, details?: Record<string, unknown>): ClientError4xx;
+declare function forbidden(message?: string, details?: Record<string, unknown>): ClientError4xx;
+declare function redirect3xx(status: number, location: string, message?: string): Redirect3xx;
+/**
+ * Create a successful phase output with rendered ViewState and carry-forward data.
+ */
+declare function phaseOutput<ViewState extends object, CarryForward = {}>(rendered: ViewState, carryForward: CarryForward): PhaseOutput<ViewState, CarryForward>;
+/**
+ * @deprecated Use phaseOutput instead. Kept for backwards compatibility.
+ */
+declare function partialRender<ViewState extends object, CarryForward>(rendered: ViewState, carryForward: CarryForward): PhaseOutput<ViewState, CarryForward>;
 
 type BuilderStates = 'Props' | 'Services' | 'Contexts' | 'UrlLoader' | 'SlowlyRender' | 'FastRender' | 'InteractiveRender' | 'Done';
 type Signals<T extends object> = {
@@ -91,7 +174,8 @@ type Builder<State extends BuilderStates, Refs extends object, SlowVS extends ob
         ...Services
     ], Contexts, PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withFastRender<NewCarryForward extends object>(fastRender: RenderFast<Services, PropsT, FastVS, NewCarryForward>): Builder<'InteractiveRender', Refs, SlowVS, FastVS, InteractiveVS, Services, [
-        Signals<NewCarryForward>,
+        Signals<FastVS>,
+        NewCarryForward,
         ...Contexts
     ], PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withInteractive(comp: ComponentConstructor<PropsT, Refs, InteractiveVS, Contexts, CompCore>): Builder<'Done', Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>;
@@ -103,7 +187,8 @@ type Builder<State extends BuilderStates, Refs extends object, SlowVS extends ob
         ...Services
     ], Contexts, PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withFastRender<NewCarryForward extends object>(fastRender: RenderFast<Services, PropsT, FastVS, NewCarryForward>): Builder<'InteractiveRender', Refs, SlowVS, FastVS, InteractiveVS, Services, [
-        Signals<NewCarryForward>,
+        Signals<FastVS>,
+        NewCarryForward,
         ...Contexts
     ], PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withInteractive(comp: ComponentConstructor<PropsT, Refs, InteractiveVS, Contexts, CompCore>): Builder<'Done', Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>;
@@ -114,7 +199,8 @@ type Builder<State extends BuilderStates, Refs extends object, SlowVS extends ob
         ...Services
     ], Contexts, PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withFastRender<NewCarryForward extends object>(fastRender: RenderFast<Services, PropsT, FastVS, NewCarryForward>): Builder<'InteractiveRender', Refs, SlowVS, FastVS, InteractiveVS, Services, [
-        Signals<NewCarryForward>,
+        Signals<FastVS>,
+        NewCarryForward,
         ...Contexts
     ], PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withInteractive(comp: ComponentConstructor<PropsT, Refs, InteractiveVS, Contexts, CompCore>): Builder<'Done', Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>;
@@ -124,13 +210,15 @@ type Builder<State extends BuilderStates, Refs extends object, SlowVS extends ob
         ...Services
     ], Contexts, PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withFastRender<NewCarryForward extends object>(fastRender: RenderFast<Services, PropsT, FastVS, NewCarryForward>): Builder<'InteractiveRender', Refs, SlowVS, FastVS, InteractiveVS, Services, [
-        Signals<NewCarryForward>,
+        Signals<FastVS>,
+        NewCarryForward,
         ...Contexts
     ], PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withInteractive(comp: ComponentConstructor<PropsT, Refs, InteractiveVS, Contexts, CompCore>): Builder<'Done', Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>;
 } : State extends 'FastRender' ? JayStackComponentDefinition<Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore> & {
     withFastRender<NewCarryForward extends object>(fastRender: RenderFast<Services, PropsT, FastVS, NewCarryForward>): Builder<'InteractiveRender', Refs, SlowVS, FastVS, InteractiveVS, Services, [
-        Signals<NewCarryForward>,
+        Signals<FastVS>,
+        NewCarryForward,
         ...Contexts
     ], PropsT, Params, JayComponentCore<PropsT, InteractiveVS>>;
     withInteractive(comp: ComponentConstructor<PropsT, Refs, InteractiveVS, Contexts, CompCore>): Builder<'Done', Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>;
@@ -159,4 +247,369 @@ declare function makeJayStackComponent<Render extends JayContract<any, any, any,
 ], [
 ], {}, {}, JayComponentCore<object, ExtractInteractiveViewState<Render>>>;
 
-export { type AnyFastRenderResult, type AnyJayStackComponentDefinition, type AnySlowlyRenderResult, type Builder, type ClientError4xx, type FastRenderResult, type JayStackComponentDefinition, type LoadParams, type PageProps, type PartialRender, type Redirect3xx, type RenderFast, type RenderSlowly, type ServerError5xx, type ServiceMarker, type ServiceMarkers, type Signals, type SlowlyRenderResult, type UrlParams, clientError4xx, createJayService, makeJayStackComponent, notFound, partialRender, redirect3xx, serverError5xx };
+/**
+ * Builder interface for contract generators without services
+ */
+interface ContractGeneratorBuilderInitial {
+    /**
+     * Adds service dependencies to the contract generator.
+     * Services will be injected when generateWith() is called.
+     */
+    withServices<Services extends Array<any>>(...serviceMarkers: ServiceMarkers<Services>): ContractGeneratorBuilderWithServices<Services>;
+    /**
+     * Defines the contract generation function without services.
+     */
+    generateWith(fn: () => Promise<GeneratedContractYaml[]> | GeneratedContractYaml[]): DynamicContractGenerator<[]>;
+}
+/**
+ * Builder interface for contract generators with services
+ */
+interface ContractGeneratorBuilderWithServices<Services extends Array<any>> {
+    /**
+     * Defines the contract generation function with service injection.
+     * Services are provided as parameters based on the order specified in withServices().
+     */
+    generateWith(fn: ContractGeneratorFunction<Services>): DynamicContractGenerator<Services>;
+}
+/**
+ * Creates a new contract generator builder.
+ *
+ * @returns A builder for creating dynamic contract generators
+ *
+ * @example
+ * ```typescript
+ * // Without services
+ * export const generator = makeContractGenerator()
+ *   .generateWith(async () => {
+ *     return [
+ *       { name: 'Contract1', yaml: 'name: Contract1\ntags: [...]' },
+ *       { name: 'Contract2', yaml: 'name: Contract2\ntags: [...]' }
+ *     ];
+ *   });
+ *
+ * // With services
+ * export const generator = makeContractGenerator()
+ *   .withServices(CMS_SERVICE, API_SERVICE)
+ *   .generateWith(async (cms, api) => {
+ *     const data = await cms.fetch();
+ *     return data.map(item => ({
+ *       name: item.name,
+ *       yaml: generateYaml(item)
+ *     }));
+ *   });
+ * ```
+ */
+declare function makeContractGenerator(): ContractGeneratorBuilderInitial;
+
+/**
+ * Factory object returned by RenderPipeline.for<VS, CF>().
+ * Provides entry points to create a typed pipeline.
+ */
+interface PipelineFactory<TargetVS extends object, TargetCF extends object> {
+    /** Start with a success value (can be T or Promise<T>) */
+    ok<T>(value: T | Promise<T>): RenderPipeline<T, TargetVS, TargetCF>;
+    /**
+     * Start with a function that returns T or Promise<T>.
+     * Catches errors into the pipeline (accessible via recover()).
+     */
+    try<T>(fn: () => T | Promise<T>): RenderPipeline<T, TargetVS, TargetCF>;
+    /** Start from an existing outcome */
+    from<T extends object>(outcome: RenderOutcome<T, unknown>): RenderPipeline<T, TargetVS, TargetCF>;
+    notFound(message?: string, details?: Record<string, unknown>): RenderPipeline<never, TargetVS, TargetCF>;
+    badRequest(message?: string, details?: Record<string, unknown>): RenderPipeline<never, TargetVS, TargetCF>;
+    unauthorized(message?: string, details?: Record<string, unknown>): RenderPipeline<never, TargetVS, TargetCF>;
+    forbidden(message?: string, details?: Record<string, unknown>): RenderPipeline<never, TargetVS, TargetCF>;
+    serverError(status: number, message?: string, details?: Record<string, unknown>): RenderPipeline<never, TargetVS, TargetCF>;
+    clientError(status: number, message?: string, details?: Record<string, unknown>): RenderPipeline<never, TargetVS, TargetCF>;
+    redirect(status: number, location: string): RenderPipeline<never, TargetVS, TargetCF>;
+}
+/**
+ * A pipeline for composing render operations with automatic error propagation.
+ *
+ * Type Parameters:
+ * - T: The current working value being transformed through the chain
+ * - TargetVS: The expected ViewState output type (set via .for<>())
+ * - TargetCF: The expected CarryForward output type (set via .for<>())
+ *
+ * Usage:
+ * ```typescript
+ * const Pipeline = RenderPipeline.for<SlowViewState, CarryForward>();
+ *
+ * return Pipeline
+ *     .try(() => fetchData())
+ *     .map(data => data ? data : Pipeline.notFound())
+ *     .map(async data => enrichData(data))
+ *     .toPhaseOutput(data => ({
+ *         viewState: { ... },
+ *         carryForward: { ... }
+ *     }));
+ * ```
+ */
+declare class RenderPipeline<T, TargetVS extends object = object, TargetCF extends object = Record<string, never>> {
+    private readonly _value;
+    private readonly _isSuccess;
+    private constructor();
+    /**
+     * Create a typed pipeline factory with target output types declared upfront.
+     * TypeScript validates that .toPhaseOutput() produces these types.
+     */
+    static for<TargetVS extends object, TargetCF extends object = Record<string, never>>(): PipelineFactory<TargetVS, TargetCF>;
+    /**
+     * Transform the working value. Always returns RenderPipeline (sync).
+     *
+     * The mapping function can return:
+     * - U: Plain value
+     * - Promise<U>: Async value (resolved at toPhaseOutput)
+     * - RenderPipeline<U>: For conditional errors/branching
+     *
+     * Errors pass through unchanged.
+     */
+    map<U>(fn: (value: T) => U | Promise<U> | RenderPipeline<U, TargetVS, TargetCF>): RenderPipeline<U, TargetVS, TargetCF>;
+    /**
+     * Handle errors, potentially recovering to a success.
+     * The function receives the caught Error and can return a new pipeline.
+     */
+    recover<U>(fn: (error: Error) => RenderPipeline<U, TargetVS, TargetCF>): RenderPipeline<T | U, TargetVS, TargetCF>;
+    /**
+     * Convert to final PhaseOutput. This is the ONLY async method.
+     * Resolves all pending promises and applies the final mapping.
+     */
+    toPhaseOutput(fn: (value: T) => {
+        viewState: TargetVS;
+        carryForward: TargetCF;
+    }): Promise<RenderOutcome<TargetVS, TargetCF>>;
+    /** Check if this pipeline is in a success state */
+    isOk(): boolean;
+    /** Check if this pipeline is in an error state */
+    isError(): boolean;
+}
+
+/**
+ * Supported HTTP methods for actions and queries.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Cache options for GET requests.
+ */
+interface CacheOptions {
+    /** Cache duration in seconds */
+    maxAge?: number;
+    /** Time in seconds to serve stale content while revalidating */
+    staleWhileRevalidate?: number;
+}
+/**
+ * Error class for action/query failures.
+ * Thrown from action handlers to indicate business logic errors.
+ *
+ * @example
+ * ```typescript
+ * throw new ActionError('NOT_AVAILABLE', 'Only 2 units available');
+ * ```
+ */
+declare class ActionError extends Error {
+    readonly code: string;
+    readonly name = "ActionError";
+    constructor(code: string, message: string);
+}
+/**
+ * A callable action/query that makes an HTTP request to the server.
+ * This is the final type returned by the builder's withHandler() method.
+ */
+interface JayAction<Input, Output> {
+    /** Call the action - makes HTTP request to server */
+    (input: Input): Promise<Output>;
+    /** Unique action name for routing */
+    readonly actionName: string;
+    /** HTTP method (GET, POST, etc.) */
+    readonly method: HttpMethod;
+    /** Internal marker for type identification */
+    readonly _brand: 'JayAction';
+}
+/**
+ * Internal action definition used for server-side registration.
+ * Contains all metadata and the handler function.
+ */
+interface JayActionDefinition<Input, Output, Services extends any[]> {
+    /** Unique action name */
+    actionName: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Cache options (for GET requests) */
+    cacheOptions?: CacheOptions;
+    /** Service markers for dependency injection */
+    services: ServiceMarkers<Services>;
+    /** The handler function */
+    handler: (input: Input, ...services: Services) => Promise<Output>;
+}
+/**
+ * Builder interface for creating type-safe actions/queries.
+ */
+interface JayActionBuilder<Services extends any[], Input, Output, DefaultMethod extends HttpMethod> {
+    /**
+     * Specify services to inject into the handler.
+     */
+    withServices<NewServices extends any[]>(...services: ServiceMarkers<NewServices>): JayActionBuilder<NewServices, Input, Output, DefaultMethod>;
+    /**
+     * Override the HTTP method.
+     */
+    withMethod<M extends HttpMethod>(method: M): JayActionBuilder<Services, Input, Output, M>;
+    /**
+     * Enable caching (typically for GET requests).
+     */
+    withCaching(options?: CacheOptions): JayActionBuilder<Services, Input, Output, DefaultMethod>;
+    /**
+     * Define the handler function. Input and output types are inferred from the handler signature.
+     */
+    withHandler<I, O>(handler: (input: I, ...services: Services) => Promise<O>): JayAction<I, O> & JayActionDefinition<I, O, Services>;
+}
+/**
+ * Create an action (defaults to POST method).
+ * Use for mutations: add to cart, submit form, update profile, etc.
+ *
+ * @param name - Unique action name (e.g., 'cart.addToCart')
+ *
+ * @example
+ * ```typescript
+ * export const addToCart = makeJayAction('cart.addToCart')
+ *     .withServices(CART_SERVICE)
+ *     .withHandler(async (input: { productId: string; quantity: number }, cartService) => {
+ *         const cart = await cartService.addItem(input.productId, input.quantity);
+ *         return { cartItemCount: cart.items.length };
+ *     });
+ * ```
+ */
+declare function makeJayAction(name: string): JayActionBuilder<[], unknown, unknown, 'POST'>;
+/**
+ * Create a query (defaults to GET method).
+ * Use for reads: search, get details, list items, etc.
+ * GET enables browser/CDN caching.
+ *
+ * @param name - Unique query name (e.g., 'products.search')
+ *
+ * @example
+ * ```typescript
+ * export const searchProducts = makeJayQuery('products.search')
+ *     .withServices(PRODUCTS_DATABASE_SERVICE)
+ *     .withCaching({ maxAge: 60 })
+ *     .withHandler(async (input: { query: string }, productsDb) => {
+ *         return productsDb.search(input.query);
+ *     });
+ * ```
+ */
+declare function makeJayQuery(name: string): JayActionBuilder<[], unknown, unknown, 'GET'>;
+/**
+ * Extract the input type from a JayAction.
+ */
+type ActionInput<T> = T extends JayAction<infer I, any> ? I : never;
+/**
+ * Extract the output type from a JayAction.
+ */
+type ActionOutput<T> = T extends JayAction<any, infer O> ? O : never;
+/**
+ * Check if a value is a JayAction.
+ */
+declare function isJayAction(value: unknown): value is JayAction<unknown, unknown>;
+
+/**
+ * Builder for plugin/project initialization with type-safe server-to-client data flow.
+ *
+ * Usage:
+ * ```typescript
+ * export const init = makeJayInit()
+ *     .withServer(async () => {
+ *         registerService(MY_SERVICE, createService());
+ *         return { apiUrl: config.url };
+ *     })
+ *     .withClient((data) => {
+ *         // data is typed from withServer return!
+ *         registerGlobalContext(MY_CONFIG_CONTEXT, data);
+ *     });
+ * ```
+ */
+/**
+ * The compiled init object that contains server and/or client init functions.
+ * The compiler transforms the builder chain into this object.
+ */
+interface JayInit<T = void> {
+    readonly __brand: 'JayInit';
+    /** Key for namespacing (plugin name or 'project'). Filled in by framework. */
+    readonly key: string;
+    /** Server init function. Returns data to pass to client. */
+    readonly _serverInit?: () => T | Promise<T>;
+    /** Client init function. Receives data from server. */
+    readonly _clientInit?: (data: T) => void | Promise<void>;
+}
+/**
+ * Builder interface for constructing a JayInit.
+ */
+interface JayInitBuilder<T = void> {
+    /**
+     * Defines server-side initialization logic.
+     * The return value is passed to the client init function.
+     *
+     * @param callback - Async function that runs on server startup
+     * @returns Builder with client data type set to callback's return type
+     */
+    withServer<R extends Record<string, any>>(callback: () => R | Promise<R>): JayInitBuilderWithServer<R>;
+    /**
+     * Defines client-side initialization logic (when no server data needed).
+     *
+     * @param callback - Function that runs on client before component tree mounts
+     * @returns The final JayInit object
+     */
+    withClient(callback: () => void | Promise<void>): JayInit<void>;
+}
+/**
+ * Builder after withServer has been called.
+ */
+interface JayInitBuilderWithServer<T extends Record<string, any>> extends JayInit<T> {
+    /**
+     * Defines client-side initialization logic with server data.
+     *
+     * @param callback - Function that receives data from server init
+     * @returns The final JayInit object
+     */
+    withClient(callback: (data: T) => void | Promise<void>): JayInit<T>;
+}
+/**
+ * Creates a builder for plugin/project initialization.
+ *
+ * The key parameter is optional:
+ * - For plugins: defaults to plugin name from plugin.yaml (injected by framework)
+ * - For project: defaults to 'project'
+ *
+ * @param key - Optional namespace key (typically omitted)
+ * @returns A builder to define server and client initialization
+ *
+ * @example
+ * ```typescript
+ * // Plugin init (key defaults to plugin name)
+ * export const init = makeJayInit()
+ *     .withServer(async () => {
+ *         registerService(STORES_SERVICE, createService());
+ *         return { currency: 'USD', enableCart: true };
+ *     })
+ *     .withClient((data) => {
+ *         registerGlobalContext(STORES_CONFIG, data);
+ *     });
+ *
+ * // Server-only init
+ * export const init = makeJayInit()
+ *     .withServer(async () => {
+ *         registerService(DB_SERVICE, await connectDb());
+ *     });
+ *
+ * // Client-only init
+ * export const init = makeJayInit()
+ *     .withClient(() => {
+ *         initAnalytics();
+ *     });
+ * ```
+ */
+declare function makeJayInit(key?: string): JayInitBuilder<void>;
+/**
+ * Type guard to check if an object is a JayInit.
+ */
+declare function isJayInit(obj: unknown): obj is JayInit<any>;
+
+export { ActionError, type ActionInput, type ActionOutput, type AnyFastRenderResult, type AnyJayStackComponentDefinition, type AnySlowlyRenderResult, type Builder, type CacheOptions, type ClientError4xx, type ContractGeneratorFunction, DYNAMIC_CONTRACT_SERVICE, type DynamicContractGenerator, type DynamicContractMetadata, type FastRenderResult, type GeneratedContractYaml, type HttpMethod, type JayAction, type JayActionBuilder, type JayActionDefinition, type JayInit, type JayInitBuilder, type JayInitBuilderWithServer, type JayStackComponentDefinition, type LoadParams, type PageProps, type PartialRender, type PhaseOutput, type PipelineFactory, type Redirect3xx, type RenderFast, type RenderOutcome, RenderPipeline, type RenderSlowly, type ServerError5xx, type ServiceInstances, type ServiceMarker, type ServiceMarkers, type Signals, type SlowlyRenderResult, type UrlParams, badRequest, clientError4xx, createJayService, forbidden, isJayAction, isJayInit, makeContractGenerator, makeJayAction, makeJayInit, makeJayQuery, makeJayStackComponent, notFound, partialRender, phaseOutput, redirect3xx, serverError5xx, unauthorized };