@webstir-io/module-contract 0.1.14 → 0.1.16

package/README.md

@@ -9,18 +9,10 @@ TypeScript interfaces, helper utilities, and JSON schema describing Webstir modu
 
 ## Install
 
-```ini
-# .npmrc
-@webstir-io:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GH_PACKAGES_TOKEN}
-```
-
 ```bash
 npm install @webstir-io/module-contract
 ```
 
-Consumers only need `read:packages`; publishers also require `write:packages`.
-
 ## Provided Types
 
 ```ts
@@ -48,6 +40,10 @@ import { fromTsRestRoute, fromTsRestRouter } from '@webstir-io/module-contract/t
 - `RequestContext` and `SSRContext` describe what the orchestrator supplies to route and view handlers.
 - `fromTsRestRoute` converts an `@ts-rest/core` route contract into a Webstir `RouteSpec`, and `fromTsRestRouter` adapts an entire ts-rest router tree at once.
 - Routes and views support optional SSG metadata: `renderMode?: 'ssg' | 'ssr' | 'spa'`, `staticPaths?: string[]`, and a reserved `ssg?: { revalidateSeconds?: number }` bag for future incremental/static revalidation hints.
+- Modules can declare `requestHooks?: { id, phase, order }[]`, and routes can opt into them with `requestHooks?: { id }[]`.
+- Routes can also declare progressive-enhancement metadata with `interaction?: 'navigation' | 'mutation'`, optional `session`/`flash` metadata, optional form-level `session`/`flash` metadata, and an optional `fragment` target for partial updates.
+- Route `output` can describe a single response case or a `responses: [...]` list when native and enhanced flows diverge.
+- Route handlers may now return normal document/json bodies, targeted fragment updates, or redirects through the shared result contract, with `RouteNavigationResult` and `RouteMutationResult` aliases for the common progressive-enhancement patterns.
 
 > Install `@ts-rest/core` to use the adapters; it's published as an optional peer dependency of this package.
 
@@ -78,12 +74,30 @@ const responseSchema = z.object({
   email: z.string().email()
 });
 const viewDataSchema = z.object({ account: responseSchema });
+const updateAccountEmailSchema = z.object({ email: z.string().email() });
+
+function isEnhancedRequest(request: unknown): boolean {
+  if (!request || typeof request !== 'object') {
+    return false;
+  }
+
+  const headers = (request as { headers?: Record<string, string | string[] | undefined> }).headers;
+  const header = headers?.['x-webstir-client-nav'];
+  return header === '1' || (Array.isArray(header) && header.includes('1'));
+}
 
 const getAccount = defineRoute<RequestContext, typeof paramsSchema, undefined, undefined, typeof responseSchema>({
   definition: {
     name: 'getAccount',
     method: 'GET',
     path: '/accounts/:id',
+    requestHooks: [{ id: 'resolve-session' }, { id: 'audit-log' }],
+    session: {
+      mode: 'optional'
+    },
+    flash: {
+      consume: ['account-email-updated']
+    },
     input: {
       params: { kind: 'zod', name: 'AccountRouteParams', source: 'src/backend/server/routes/accounts.ts' }
     },
@@ -102,6 +116,81 @@ const getAccount = defineRoute<RequestContext, typeof paramsSchema, undefined, u
   })
 });
 
+const updateAccountEmail = defineRoute<RequestContext, typeof paramsSchema, undefined, typeof updateAccountEmailSchema, typeof responseSchema>({
+  definition: {
+    name: 'updateAccountEmail',
+    method: 'POST',
+    path: '/accounts/:id/email',
+    interaction: 'mutation',
+    requestHooks: [{ id: 'resolve-session' }, { id: 'audit-log' }],
+    session: {
+      mode: 'required',
+      write: true
+    },
+    form: {
+      contentType: 'application/x-www-form-urlencoded',
+      csrf: true,
+      session: {
+        mode: 'required',
+        write: true
+      },
+      flash: {
+        publish: [{ key: 'account-email-updated', level: 'success', when: 'success' }]
+      }
+    },
+    fragment: {
+      target: 'account-email',
+      mode: 'replace'
+    },
+    input: {
+      params: { kind: 'zod', name: 'AccountRouteParams', source: 'src/backend/server/routes/accounts.ts' },
+      body: { kind: 'zod', name: 'UpdateAccountEmailInput', source: 'src/backend/server/routes/accounts.ts' }
+    },
+    output: {
+      responses: [
+        {
+          status: 200,
+          body: { kind: 'zod', name: 'AccountRouteResponse', source: 'src/backend/server/routes/accounts.ts' },
+          fragment: {
+            target: 'account-email',
+            mode: 'replace'
+          }
+        },
+        {
+          redirect: {
+            status: 303
+          }
+        }
+      ]
+    }
+  },
+  schemas: {
+    params: paramsSchema,
+    body: updateAccountEmailSchema,
+    response: responseSchema
+  },
+  handler: async (ctx) => {
+    const account = await ctx.db.accounts.updateEmail(ctx.params.id, ctx.body.email);
+    if (isEnhancedRequest(ctx.request)) {
+      return {
+        status: 200,
+        fragment: {
+          target: 'account-email',
+          mode: 'replace',
+          body: account
+        }
+      };
+    }
+
+    return {
+      status: 303,
+      redirect: {
+        location: `/accounts/${ctx.params.id}`
+      }
+    };
+  }
+});
+
 const accountView = defineView<SSRContext, typeof paramsSchema, typeof viewDataSchema>({
   definition: {
     name: 'AccountView',
@@ -126,15 +215,64 @@ export const accountsModule = createModule({
     capabilities: ['auth', 'db', 'views'],
     // Optional: pass-through metadata for providers
     assets: [],
-    middlewares: [],
-    routes: [getAccount.definition],
+    requestHooks: [
+      {
+        id: 'resolve-session',
+        phase: 'beforeAuth',
+        order: 10
+      },
+      {
+        id: 'audit-log',
+        phase: 'afterHandler',
+        order: 90
+      }
+    ],
+    routes: [getAccount.definition, updateAccountEmail.definition],
     views: [accountView.definition]
   },
-  routes: [getAccount],
+  routes: [getAccount, updateAccountEmail],
   views: [accountView]
 });
 ```
 
+Use `output.responses` when a route may return different enhanced and baseline shapes from the same handler:
+
+```ts
+output: {
+  responses: [
+    {
+      status: 200,
+      body: { kind: 'zod', name: 'AccountRouteResponse' },
+      fragment: {
+        target: 'account-email',
+        mode: 'replace'
+      }
+    },
+    {
+      redirect: {
+        status: 303
+      }
+    }
+  ]
+};
+```
+
+Fragment-capable handlers can still return partial updates directly:
+
+```ts
+return {
+  status: 200,
+  fragment: {
+    target: 'account-email',
+    mode: 'replace',
+    body: {
+      id: ctx.params.id,
+      email: 'updated@example.com'
+    }
+  }
+};
+```
+
 ### ts-rest Router Example
 
 ```ts
@@ -204,16 +342,16 @@ When authoring a provider:
 ## Maintainer Workflow
 
 ```bash
-npm install
-npm run clean          # remove dist/schema artifacts
-npm run build          # compiles TypeScript, regenerates schema/*.schema.json
-npm run test           # type-checks the Accounts example module
-# Release helper (bumps version, pushes tags to trigger release workflow)
-npm run release -- patch
+bun install
+bun run clean          # remove dist/schema artifacts
+bun run build          # compiles TypeScript, regenerates schema/*.schema.json
+bun run test           # type-checks the Accounts example module
+# Release helper (bumps version and pushes a package-scoped release tag)
+bun run release -- patch
 ```
 
 - The `schema/` folder contains `*-definition.schema.json` files derived from the exported Zod schemas. Commit them with contract changes.
-- Ensure CI runs `npm ci`, `npm run clean`, `npm run build`, `npm run test`, and `npm run smoke` before publish.
+- Ensure CI runs `bun install --frozen-lockfile`, `bun run clean`, `bun run build`, and `bun run test` before publish.
 
 ## License
 

package/dist/adapters/ts-rest.d.ts

@@ -1,6 +1,6 @@
 import type { AppRoute, AppRouter } from '@ts-rest/core';
 import { z } from 'zod';
-import type { ModuleError, RequestContext, RouteHandler, RouteSpec } from '../index.js';
+import type { LooseRouteSpec, ModuleError, RequestContext, RouteHandler, RouteSpec } from '../index.js';
 interface BaseFromTsRestRouteOptions {
     readonly name: string;
     readonly appRoute: AppRoute;
@@ -34,5 +34,5 @@ export interface FromTsRestRouterOptions<TContext extends RequestContext> {
     }) => RouterRouteConfig<TContext>;
 }
 export declare function fromTsRestRoute<TContext extends RequestContext, TParams extends z.ZodTypeAny | undefined = undefined, TQuery extends z.ZodTypeAny | undefined = undefined, TBody extends z.ZodTypeAny | undefined = undefined, TResponse extends z.ZodTypeAny = z.ZodTypeAny>(options: FromTsRestRouteOptions<TContext, TParams, TQuery, TBody, TResponse>): RouteSpec<TContext, TParams, TQuery, TBody, TResponse>;
-export declare function fromTsRestRouter<TContext extends RequestContext>(options: FromTsRestRouterOptions<TContext>): RouteSpec<TContext, any, any, any, any>[];
+export declare function fromTsRestRouter<TContext extends RequestContext>(options: FromTsRestRouterOptions<TContext>): LooseRouteSpec<TContext>[];
 export {};

package/dist/adapters/ts-rest.js

@@ -1,4 +1,4 @@
-import { ContractNoBody, isAppRoute, isAppRouteMutation, isAppRouteNoBody, isAppRouteOtherResponse, isZodType } from '@ts-rest/core';
+import { ContractNoBody, isAppRoute, isAppRouteMutation, isAppRouteNoBody, isAppRouteOtherResponse, isZodType, } from '@ts-rest/core';
 import { z } from 'zod';
 const DEFAULT_SUCCESS_CODES = [200, 201, 202, 204];
 const noopResponseSchema = z.void();
@@ -63,7 +63,7 @@ const extractResponseSchema = (response) => {
     return toZod(response);
 };
 export function fromTsRestRoute(options) {
-    const { appRoute, name, summary, description, tags, schemaBaseName, successStatus, paramsSchema, querySchema, bodySchema, headersSchema, responseSchema, handler, errors, errorSchemas } = options;
+    const { appRoute, name, summary, description, tags, schemaBaseName, successStatus, paramsSchema, querySchema, bodySchema, headersSchema, responseSchema, handler, errors, errorSchemas, } = options;
     const resolvedParamsSchema = (paramsSchema ?? toZod(appRoute.pathParams));
     const resolvedQuerySchema = (querySchema ?? toZod(appRoute.query));
     const resolvedHeadersSchema = headersSchema ?? toZod(appRoute.headers);
@@ -71,19 +71,21 @@ export function fromTsRestRoute(options) {
     const resolvedBodySchema = (bodySchema ?? mutationBodySchema);
     const { status: derivedStatus, response: routeResponse } = selectResponse(appRoute, successStatus);
     const baseResponseSchema = extractResponseSchema(routeResponse);
-    const resolvedResponseSchema = (responseSchema ?? baseResponseSchema ?? noopResponseSchema);
+    const resolvedResponseSchema = (responseSchema ??
+        baseResponseSchema ??
+        noopResponseSchema);
     const schemaNames = buildSchemaNames(schemaBaseName ?? name, {
         params: resolvedParamsSchema,
         query: resolvedQuerySchema,
         body: resolvedBodySchema,
         headers: resolvedHeadersSchema,
-        response: resolvedResponseSchema
+        response: resolvedResponseSchema,
     });
     const definitionInput = {
         params: schemaNames.params,
         query: schemaNames.query,
         body: schemaNames.body,
-        headers: schemaNames.headers
+        headers: schemaNames.headers,
     };
     const hasInput = Object.values(definitionInput).some((value) => value !== undefined);
     return {
@@ -99,16 +101,16 @@ export function fromTsRestRoute(options) {
                     params: schemaNames.params,
                     query: schemaNames.query,
                     body: schemaNames.body,
-                    headers: schemaNames.headers
+                    headers: schemaNames.headers,
                 }
                 : undefined,
             output: schemaNames.response
                 ? {
                     body: schemaNames.response,
-                    status: derivedStatus
+                    status: derivedStatus,
                 }
                 : undefined,
-            errors: isNonEmpty(errors) ? [...errors] : undefined
+            errors: isNonEmpty(errors) ? [...errors] : undefined,
         },
         schemas: {
             params: resolvedParamsSchema,
@@ -116,9 +118,9 @@ export function fromTsRestRoute(options) {
             body: resolvedBodySchema,
             headers: resolvedHeadersSchema,
             response: resolvedResponseSchema,
-            errors: errorSchemas
+            errors: errorSchemas,
         },
-        handler
+        handler,
     };
 }
 export function fromTsRestRouter(options) {
@@ -134,7 +136,7 @@ export function fromTsRestRouter(options) {
                 specs.push(fromTsRestRoute({
                     appRoute: value,
                     name: routeName,
-                    ...routeConfig
+                    ...routeConfig,
                 }));
             }
             else {