@spfn/core 0.3.0-beta.1 → 0.3.0-beta.10

package/dist/router-DJdpwuB6.d.ts

@@ -0,0 +1,127 @@
+import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
+import { R as RouteDef } from './route-builder-2ani2jEI.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;
+    /**
+     * 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 Router as R, defineRouter as d };

package/dist/server/index.d.ts

@@ -5,13 +5,18 @@ import { serve } from '@hono/node-server';
 import { NamedMiddleware, Router } from '@spfn/core/route';
 import { OnErrorContext, ProxyGuardConfig, RateLimitOptions } from '@spfn/core/middleware';
 import { SafeFetchPolicy } from '@spfn/core/security';
-import { c as JobRouter, e as BossOptions } from '../boss-D16fO2oG.js';
+import { c as JobRouter, f as BossOptions } from '../boss-BiDCbbAQ.js';
 import { b as EventRouterDef, E as EventDef } from '../token-manager-BT5EnUAR.js';
 import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-ZQODsBft.js';
 import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-2AbaW4Ie.js';
 import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
-import '@sinclair/typebox';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static } from '@sinclair/typebox';
+import { R as RouteDef } from '../route-builder-2ani2jEI.js';
 import 'pg-boss';
+import '../define-middleware-CVKgqo8S.js';
+import 'hono/utils/http-status';
+import '../route/types.js';
 
 /**
  * @deprecated Use `loadEnv` from '@spfn/core/env/loader' instead.
@@ -22,6 +27,33 @@ import 'pg-boss';
  */
 declare function loadEnvFiles(): void;
 
+/** Stable operation identity used by separately deployed clients. */
+declare const CORE_TIME_OPERATION_ID = "core.time";
+/**
+ * Closed response shape for the server-time wire capability.
+ *
+ * Millisecond timestamps use integers throughout SPFN's external contracts.
+ */
+declare const ServerTimeResponseSchema: _sinclair_typebox.TObject<{
+    serverTimeMillis: _sinclair_typebox.TInteger;
+}>;
+type ServerTimeResponse = Static<typeof ServerTimeResponseSchema>;
+/** Injectable source of Unix epoch milliseconds. */
+interface ServerClock {
+    now(): number;
+}
+/**
+ * Build the route from a clock so tests and alternate runtimes can supply the
+ * epoch source without replacing global time.
+ */
+declare function createCoreTimeRoute(clock?: ServerClock): RouteDef<{}, {}, {
+    serverTimeMillis: number;
+}>;
+/** The production route and the public wire-contract source of truth. */
+declare const CORE_TIME_ROUTE: RouteDef<{}, {}, {
+    serverTimeMillis: number;
+}>;
+
 /**
  * Workflow router interface for @spfn/core integration
  *
@@ -202,6 +234,8 @@ interface ServerConfig {
      * Jobs defined with job()...handler() style
      * Uses pg-boss for PostgreSQL-based job queue
      *
+     * Merged across every `.jobs()` call, so this holds all of them.
+     *
      * @example
      * ```typescript
      * import { job, defineJobRouter } from '@spfn/core/job';
@@ -454,7 +488,9 @@ interface ServerConfig {
     };
     /**
      * Health check endpoint configuration
-     * Provides monitoring endpoints for Kubernetes probes and load balancers
+     *
+     * The endpoint answers at `/_core/health`, which no app route can take from
+     * it. Point Kubernetes probes and load balancers there.
      */
     healthCheck?: {
         /**
@@ -464,9 +500,19 @@ interface ServerConfig {
          */
         enabled?: boolean;
         /**
-         * Health check endpoint path
-         * @default '/health'
-         * @env HEALTH_CHECK_PATH
+         * An additional path to answer on, for a deployment whose probe path is
+         * fixed somewhere you cannot change it.
+         *
+         * BREAKING (@spfn/core 0.4): unset, the endpoint answers at
+         * `/_core/health` and nowhere else. It used to default to `/health` and
+         * swallow any app route declared there. `/health` now belongs to your
+         * app; set this to `'/health'` to have the built-in answer there again.
+         *
+         * The path is registered before app routes, so an app route on the same
+         * path will not run and the server says so at boot.
+         *
+         * @default undefined — `/_core/health` only
+         * @example '/health'
          */
         path?: string;
         /**
@@ -477,6 +523,15 @@ interface ServerConfig {
          */
         detailed?: boolean;
     };
+    /**
+     * Server-time capability dependencies.
+     *
+     * The endpoint is always enabled at `GET /_core/time`. Supplying a clock is
+     * primarily a deterministic test seam; production defaults to `Date.now()`.
+     */
+    serverTime?: {
+        clock?: ServerClock;
+    };
     /**
      * Migration boot gate
      *
@@ -501,17 +556,23 @@ interface ServerConfig {
     /**
      * Infrastructure initialization control
      * Controls automatic initialization of database and Redis
-     * @default Both enabled if credentials exist
+     *
+     * Both are initialized unless set to `false` — the credentials are not
+     * sniffed. A server that needs no database must say so, otherwise boot
+     * fails with `No database configuration found`. A component set to `false`
+     * is reported as `disabled` by the health endpoint and never degrades it.
+     *
+     * @default Both enabled
      */
     infrastructure?: {
         /**
          * Enable/disable automatic database initialization
-         * @default true if DATABASE_URL exists
+         * @default true
          */
         database?: boolean;
         /**
          * Enable/disable automatic Redis initialization
-         * @default true if REDIS_URL exists
+         * @default true
          */
         redis?: boolean;
     };
@@ -710,6 +771,43 @@ declare module 'hono' {
  */
 declare function createServer(config?: ServerConfig): Promise<Hono>;
 
+/**
+ * The paths `@spfn/core` registers for itself.
+ *
+ * Its own module because both `create-server.ts` (which registers them) and
+ * `helpers.ts` (which reports them in the startup banner) need them, and
+ * `create-server.ts` already imports `helpers.ts` — putting them in either file
+ * would close a cycle, which `pnpm check:circular` fails the build on.
+ *
+ * @module server/namespace
+ */
+/**
+ * The path prefix `@spfn/core` registers its own endpoints under.
+ *
+ * An app declaring a route in here is declaring something it does not own, and
+ * the route will not run — core's endpoints are registered before app routes.
+ * `@spfn/auth` (`/_auth/`) and ops routes (`/_ops/`) follow the same convention,
+ * and neither has ever had a shadowing defect.
+ */
+declare const CORE_NAMESPACE = "/_core";
+/**
+ * Where the built-in health endpoint always answers.
+ *
+ * Point a readiness probe, a Dockerfile `HEALTHCHECK` or an uptime monitor here
+ * rather than at `/health`: no app route can claim this path, so the answer does
+ * not depend on what the app happens to declare. A probe's path is fixed in
+ * places this repository cannot change — a GitOps manifest, a Dockerfile, a load
+ * balancer console — and a version bump migrates none of them.
+ */
+declare const CORE_HEALTH_PATH = "/_core/health";
+/**
+ * Where clients obtain the server's current Unix epoch in milliseconds.
+ *
+ * This endpoint is registered before application routes and application auth
+ * middleware so a client can call it before it has a proof or session.
+ */
+declare const CORE_TIME_PATH = "/_core/time";
+
 /**
  * Start SPFN Server
  *
@@ -1049,6 +1147,20 @@ declare class ServerConfigBuilder {
     /**
      * Register background jobs router
      *
+     * May be called once per domain router: repeated calls **merge** into one
+     * router, the way `.routes()` composes. Calling it several times used to
+     * keep only the last router and register nothing else, without warning.
+     *
+     * The pg-boss `config` is per server, so pass it on one call only.
+     *
+     * Two names can collide, and both fail loudly:
+     * - a router **key** present in two calls throws here, at config time;
+     * - two jobs sharing a **`job.name`** (the pg-boss queue name) throw in
+     *   `registerJobs()` at boot, before any queue or worker is created.
+     *
+     * @throws if a router key was already registered by an earlier call
+     * @throws if `config` is given when an earlier call already gave one
+     *
      * @example
      * ```typescript
      * import { job, defineJobRouter } from '@spfn/core/job';
@@ -1061,7 +1173,8 @@ declare class ServerConfigBuilder {
      *
      * export default defineServerConfig()
      *   .routes(appRouter)
-     *   .jobs(jobRouter)
+     *   .jobs(jobRouter, { clearOnStart: isDev })   // config on one call only
+     *   .jobs(billingJobRouter)                     // merged, not replaced
      *   .build();
      * ```
      */
@@ -1149,6 +1262,12 @@ declare class ServerConfigBuilder {
      * Configure health check endpoint
      */
     healthCheck(healthCheck: ServerConfig['healthCheck']): this;
+    /**
+     * Supply the clock used by the built-in `GET /_core/time` capability.
+     * Production servers normally keep the default `Date.now()` clock; this is
+     * exposed so tests can assert an exact wire value without replacing globals.
+     */
+    serverTime(serverTime: ServerConfig['serverTime']): this;
     /**
      * Configure infrastructure initialization
      */
@@ -1225,4 +1344,4 @@ declare class ServerConfigBuilder {
  */
 declare function defineServerConfig(): ServerConfigBuilder;
 
-export { type AppFactory, type MigrationSnapshot, PendingMigrationsError, type ServerConfig, type ServerInstance, type ShutdownHookOptions, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
+export { type AppFactory, CORE_HEALTH_PATH, CORE_NAMESPACE, CORE_TIME_OPERATION_ID, CORE_TIME_PATH, CORE_TIME_ROUTE, type MigrationSnapshot, PendingMigrationsError, type ServerClock, type ServerConfig, type ServerInstance, type ServerTimeResponse, ServerTimeResponseSchema, type ShutdownHookOptions, createCoreTimeRoute, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };