@spfn/core 0.3.0-beta.3 → 0.3.0-beta.30

package/dist/{router-Cy7rAfmj.d.ts → route-builder-DRW-MSCJ.d.ts}

@@ -1,8 +1,8 @@
-import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
 import { Context, MiddlewareHandler } from 'hono';
+import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
 import { TSchema, Static } from '@sinclair/typebox';
 import { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
-import { HttpMethod } from './route/types.js';
+import { HttpMethod, RouteEffect } from './route/types.js';
 
 /**
  * Route Input Types
@@ -296,6 +296,13 @@ type RouteDef<TInput extends RouteInput = RouteInput, TInterceptor extends Route
      * the compatibility gate read it.
      */
     contract?: RouteContract;
+    /**
+     * What invoking this route does. Read by a command surface, which
+     * announces it in its manifest; codegen and the contract ignore it.
+     */
+    effect?: RouteEffect;
+    /** One line a command surface announces beside the route; codegen and the contract ignore it. */
+    summary?: string;
     handler: RouteHandlerFn<TInput, TInterceptor, TResponse>;
     _input: TInput;
     _interceptor: TInterceptor;
@@ -312,6 +319,8 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
     _middlewares?: (MiddlewareHandler | NamedMiddleware<string>)[];
     _skipMiddlewares?: string[] | '*';
     _contract?: RouteContract;
+    _effect?: RouteEffect;
+    _summary?: string;
     /**
      * Create a new RouteBuilder with copied properties and optional overrides
      */
@@ -472,6 +481,45 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
      * ```
      */
     contract(contract: RouteContract): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * Declare what invoking this route does
+     *
+     * Read by a command surface (`@spfn/core/surface`, `@spfn/core/ops`),
+     * which announces it in its manifest so a machine caller can tell a read
+     * from a write before it calls — `spfn ops call` asks for `--yes` before a
+     * `destructive` command. A surface built with `defineSurface` refuses an
+     * app command that does not declare one; on `/_ops` it is optional.
+     *
+     * Nothing else reads it: codegen, the route map, and the contract are
+     * unaffected, and a route outside any surface simply carries it.
+     *
+     * @example
+     * ```ts
+     * export const pageAdd = app.route.post('/pages')
+     *   .input({ body: PageAddBody })
+     *   .effect('write')
+     *   .summary('Add a page to the blueprint')
+     *   .handler(async (c) => { ... });
+     * ```
+     */
+    effect(effect: RouteEffect): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * Describe this route in one line for a command surface's manifest
+     *
+     * A surface announces it beside the command in `spfn ops list` and
+     * `--describe`, and refuses one that is empty or longer than 500
+     * characters. Codegen, the route map, and the contract ignore it. On a
+     * module command the module's own summary wins.
+     *
+     * @example
+     * ```ts
+     * export const pageAdd = app.route.post('/pages')
+     *   .effect('write')
+     *   .summary('Add a page to the blueprint')
+     *   .handler(async (c) => { ... });
+     * ```
+     */
+    summary(summary: string): RouteBuilder<TInput, TInterceptor, TResponse>;
     /**
      * Define handler function
      *
@@ -550,127 +598,4 @@ declare const route: {
     delete: (path: string) => RouteBuilder;
 };
 
-/**
- * Router Definition
- *
- * Provides router composition and middleware management
- */
-
-/**
- * Router definition - holds all routes
- */
-interface Router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>> {
-    routes: TRoutes;
-    _routes: TRoutes;
-    _packageRouters: Router<any>[];
-    _globalMiddlewares: NamedMiddleware<string>[];
-    /** The contract version these routes publish, or null when uncontracted. */
-    _contractVersion: string | null;
-    /**
-     * Register package routers (type-hidden)
-     *
-     * Package routes are:
-     * - Recognized by RPC proxy and backend
-     * - NOT exposed in client types (use package's own API like authApi, cmsApi)
-     *
-     * @example
-     * ```ts
-     * import { authRouter } from '@spfn/auth/server';
-     * import { cmsAppRouter } from '@spfn/cms/server';
-     *
-     * export const appRouter = defineRouter({
-     *     getRoot,
-     *     getStatus,
-     * })
-     * .packages([authRouter, cmsAppRouter]);
-     *
-     * // Client usage:
-     * // api.getRoot.call({})     - app routes
-     * // authApi.login.call({})   - package API
-     * ```
-     */
-    packages(routers: Router<any>[]): Router<TRoutes>;
-    /**
-     * Register global middlewares
-     *
-     * Applied to all routes unless explicitly skipped via .skip()
-     *
-     * @example
-     * ```ts
-     * import { authMiddleware, loggingMiddleware } from './middlewares';
-     *
-     * export const appRouter = defineRouter({
-     *     getRoot,
-     *     getStatus,
-     * })
-     * .packages([authRouter])
-     * .use([authMiddleware, loggingMiddleware]);
-     * ```
-     */
-    use(middlewares: NamedMiddleware<string>[]): Router<TRoutes>;
-    /**
-     * Declare the contract version these routes publish.
-     *
-     * A client compiled against this server — a mobile app in a store — is
-     * generated from one version of the contract and cannot be updated when the
-     * server changes. The server announces this version on every response so
-     * that client can tell whether the two ends still agree.
-     *
-     * This is the version's source. A released snapshot is written to
-     * `contracts/released/<version>.json` from what is declared here, so the
-     * filename follows the code rather than the code having to be told what the
-     * filename said.
-     *
-     * Only a server with contracted routes needs it. Without it the contract
-     * generator still writes `current.json` and still runs the compatibility
-     * gate; what it cannot do is cut a release or announce a version.
-     *
-     * @example
-     * ```ts
-     * export const appRouter = defineRouter({ getRoot, listItems })
-     *     .contractVersion('1.2.0')
-     *     .packages([authRouter]);
-     * ```
-     */
-    contractVersion(version: string): Router<TRoutes>;
-}
-/**
- * Define a router with multiple routes (tRPC-style)
- *
- * Supports chainable API for packages and middlewares:
- *
- * @example
- * ```ts
- * // Basic usage
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getStatus,
- *     listExamples,
- * });
- *
- * // With package routers (type-hidden)
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getStatus,
- * })
- * .packages([authRouter, cmsAppRouter]);
- *
- * // With global middlewares
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getStatus,
- * })
- * .packages([authRouter])
- * .use([authMiddleware, loggingMiddleware]);
- *
- * export type AppRouter = typeof appRouter;
- * ```
- *
- * Package routes:
- * - Recognized by RPC proxy and backend for routing
- * - NOT included in AppRouter type (use authApi, cmsApi instead)
- * - Prevents confusion between app API and package APIs
- */
-declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
-
-export { type MergedInput as M, type PaginatedResult as P, type Router as R, type RouteDef as a, RouteBuilder as b, type RouteAuthProfile as c, type RouteBuilderContext as d, type RouteContract as e, type RouteHandlerFn as f, type RouteInput as g, defineRouter as h, route as r };
+export { type MergedInput as M, type PaginatedResult as P, type RouteDef as R, type RouteAuthProfile as a, type RouteBuilderContext as b, type RouteContract as c, type RouteHandlerFn as d, type RouteInput as e, RouteBuilder as f, route as r };

package/dist/router-C57y-vz1.d.ts

@@ -0,0 +1,184 @@
+import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
+import { R as RouteDef } from './route-builder-DRW-MSCJ.js';
+
+/**
+ * Router Definition
+ *
+ * Provides router composition and middleware management
+ */
+
+/**
+ * Router definition - holds all routes
+ */
+interface Router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>> {
+    routes: TRoutes;
+    _routes: TRoutes;
+    _packageRouters: Router<any>[];
+    _globalMiddlewares: NamedMiddleware<string>[];
+    /** The contract version these routes publish, or null when uncontracted. */
+    _contractVersion: string | null;
+    /**
+     * Whether a client ever addresses these routes by name.
+     *
+     * True for an ordinary router. A mounted package router that is true here
+     * has its routes written into the app's generated route map, which is what
+     * lets the package's own client (`authApi.login`) resolve a name through the
+     * app's RPC proxy. It is also what makes an app route sharing a name with a
+     * package route a defect worth refusing a build over: the map holds one
+     * entry per name, so one of the two paths would become unreachable while the
+     * generated types still describe the app's route.
+     *
+     * False says no client names these routes: they are reached by URL, by
+     * something that was handed the URL, so nothing of them belongs in the map
+     * and a name they share with an app route is only a shared name.
+     * `createOpsRouter` sets it — `spfn ops` invokes an ops command over the URL
+     * the manifest gave it.
+     */
+    _publishesRouteMap: boolean;
+    /**
+     * The namespace of the command surface that built this router, absent on
+     * any other. Set by `defineSurface` (and so by `createOpsRouter`) as a
+     * non-enumerable property, so `.packages()` can refuse two surfaces on one
+     * namespace.
+     */
+    readonly _surfaceNamespace?: string;
+    /**
+     * The manifest of the states that built this router — each state's key
+     * fields and whether it has a write, in declaration order — absent on any
+     * other. Set by `defineStateRouter` on the router it derives as a
+     * non-enumerable property; it is the object the snapshot route answers as
+     * `manifest`, and what `@spfn/core:states` reads to write the app's declared
+     * state ids. Written structurally so the route module does not import state.
+     */
+    readonly _stateManifest?: Readonly<Record<string, {
+        readonly key: readonly string[];
+        readonly write: boolean;
+    }>>;
+    /**
+     * Register package routers (type-hidden)
+     *
+     * Package routes are:
+     * - Recognized by RPC proxy and backend
+     * - NOT exposed in client types (use package's own API like authApi, cmsApi)
+     *
+     * @example
+     * ```ts
+     * import { authRouter } from '@spfn/auth/server';
+     * import { cmsAppRouter } from '@spfn/cms/server';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getStatus,
+     * })
+     * .packages([authRouter, cmsAppRouter]);
+     *
+     * // Client usage:
+     * // api.getRoot.call({})     - app routes
+     * // authApi.login.call({})   - package API
+     * ```
+     */
+    packages(routers: Router<any>[]): Router<TRoutes>;
+    /**
+     * Register global middlewares
+     *
+     * Applied to all routes unless explicitly skipped via .skip()
+     *
+     * @example
+     * ```ts
+     * import { authMiddleware, loggingMiddleware } from './middlewares';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getStatus,
+     * })
+     * .packages([authRouter])
+     * .use([authMiddleware, loggingMiddleware]);
+     * ```
+     */
+    use(middlewares: NamedMiddleware<string>[]): Router<TRoutes>;
+    /**
+     * Declare the contract version these routes publish.
+     *
+     * A client compiled against this server — a mobile app in a store — is
+     * generated from one version of the contract and cannot be updated when the
+     * server changes. The server announces this version on every response so
+     * that client can tell whether the two ends still agree.
+     *
+     * This is the version's source. A released snapshot is written to
+     * `contracts/released/<version>.json` from what is declared here, so the
+     * filename follows the code rather than the code having to be told what the
+     * filename said.
+     *
+     * Only a server with contracted routes needs it. Without it the contract
+     * generator still writes `current.json` and still runs the compatibility
+     * gate; what it cannot do is cut a release or announce a version.
+     *
+     * @example
+     * ```ts
+     * export const appRouter = defineRouter({ getRoot, listItems })
+     *     .contractVersion('1.2.0')
+     *     .packages([authRouter]);
+     * ```
+     */
+    contractVersion(version: string): Router<TRoutes>;
+}
+/**
+ * Define a router with multiple routes (tRPC-style)
+ *
+ * Supports chainable API for packages and middlewares:
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ *     listExamples,
+ * });
+ *
+ * // With package routers (type-hidden)
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ * })
+ * .packages([authRouter, cmsAppRouter]);
+ *
+ * // With global middlewares
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ * })
+ * .packages([authRouter])
+ * .use([authMiddleware, loggingMiddleware]);
+ *
+ * export type AppRouter = typeof appRouter;
+ * ```
+ *
+ * Package routes:
+ * - Recognized by RPC proxy and backend for routing
+ * - NOT included in AppRouter type (use authApi, cmsApi instead)
+ * - Prevents confusion between app API and package APIs
+ */
+declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
+/**
+ * A router no client addresses by name.
+ *
+ * The app's generated route map carries the routes of every package router the
+ * app mounts with `.packages()`, so that a package client calling its own route
+ * by name resolves through the app's RPC proxy. A router built here is left out
+ * of that map: its routes are reached by URL, by a tool that was told the URL,
+ * so no name of theirs has to resolve anywhere and a name shared with an app
+ * route is only a shared name.
+ *
+ * Declared by the package that ships the router, because only it knows whether
+ * any client names these routes: `createOpsRouter` and the tracking routes of
+ * `@spfn/notification` do it, and any package whose surface is reached by URL
+ * may. The obligation is the whole of it — a package whose client *does* name
+ * its routes must use `defineRouter`, or those names land in nobody's map and
+ * resolve nowhere (and a collision that really would take an app route's entry
+ * generates silently). `defineRouter` is the default for exactly that reason: a
+ * package that says nothing is carried and checked.
+ */
+declare function defineUnmappedRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
+
+export { type Router as R, defineUnmappedRouter as a, defineRouter as d };