@getworkbench/core 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Hono } from 'hono';
 import { Queue, RedisOptions } from 'bullmq';
+import { Hono } from 'hono';
 
 /**
  * Job status types matching BullMQ states
@@ -651,15 +651,175 @@ declare class WorkbenchCore {
     };
 }
 
+interface FetchHandlerResult {
+    /**
+     * Web-standard fetch handler. Accepts a `Request` and returns a `Response`.
+     * Suitable for Elysia's `.mount(path, handler)`, Next.js route handlers,
+     * Bun.serve, and any other web-standards-friendly runtime.
+     */
+    fetch: (req: Request) => Promise<Response>;
+    /**
+     * The underlying `WorkbenchCore` instance. Exposed so adapters can read
+     * config, query state, or wire up custom auth strategies.
+     */
+    core: WorkbenchCore;
+}
+/**
+ * Build a self-contained web-fetch handler for Workbench: API routes,
+ * `/config`, static `/assets/:file`, an `index.html` catch-all with a
+ * correct `<base href>`, CORS on `/api/*`, and optional Basic Auth on
+ * everything.
+ *
+ * This is the engine shared by every fetch-native adapter (Elysia, Next.js).
+ * Express and Fastify adapters use {@link buildRouteTable} directly instead.
+ *
+ * When `options.basePath` is set, the handler rewrites the incoming Request
+ * URL to strip that prefix before routing. This makes the bridge work
+ * uniformly for both fetch hosts:
+ *
+ * - `Elysia.mount()` already strips the prefix before calling us — the
+ *   strip below is a no-op in that case.
+ * - Next.js App Router preserves the full path — the strip is what lets
+ *   our internal routes (`/api/*`, `/config`, …) match.
+ */
+declare function createFetchHandler(options: WorkbenchOptions | Queue[]): FetchHandlerResult;
+
+/**
+ * Framework-agnostic HTTP method.
+ */
+type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
 /**
- * Create API routes for Workbench
+ * Normalized input passed to every handler. Adapters are responsible for
+ * mapping their framework-specific request shape to this.
+ */
+interface HandlerInput {
+    params: Record<string, string>;
+    query: Record<string, string | undefined>;
+    body?: unknown;
+}
+/**
+ * Normalized output returned by every handler. Adapters serialize this
+ * onto their framework-specific response object.
+ */
+interface HandlerResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * A framework-agnostic route handler. Closes over a `WorkbenchCore` and
+ * takes a normalized request envelope.
+ */
+type Handler = (input: HandlerInput) => Promise<HandlerResult>;
+/**
+ * A framework-agnostic route definition.
+ *
+ * `path` uses `:param` syntax compatible with Hono, Express, and Fastify.
+ * Paths are relative to `/api` — adapters mount them under that prefix.
+ */
+interface RouteDef {
+    method: HttpMethod;
+    path: string;
+    handler: Handler;
+}
+/**
+ * Build the framework-agnostic route table for the Workbench API.
+ *
+ * Adapters iterate this list and register each route on their host framework.
+ * Paths are relative to `/api`.
+ */
+declare function buildRouteTable(core: WorkbenchCore): RouteDef[];
+
+/**
+ * Create API routes for Workbench as a Hono app.
+ *
+ * Iterates the framework-agnostic `buildRouteTable(core)` and registers
+ * each route on a fresh Hono instance. Adapters that don't speak Hono can
+ * use `buildRouteTable` directly — see `@getworkbench/express` and
+ * `@getworkbench/fastify`.
  */
 declare function createApiRoutes(core: WorkbenchCore): Hono;
 
+declare function computeBasePath(pathname: string): string;
+/**
+ * Resolve the dashboard's base path, preferring an explicit override.
+ *
+ * Adapters where the host framework preserves the mount prefix on the
+ * incoming URL (Hono `.route()`, Express `req.originalUrl`, Next.js route
+ * files) can rely on auto-detection. Adapters where the prefix is stripped
+ * before the handler runs (Elysia `.mount()`) require the user to pass
+ * `basePath` so the dashboard's HTML still references assets under the
+ * correct prefix.
+ */
+declare function resolveBasePath(override: string | undefined, pathname: string): string;
+
+/**
+ * Parse a `Basic` Authorization header and check it against the configured
+ * credentials. Uses constant-time comparison to avoid leaking timing info
+ * about which character mismatched.
+ *
+ * Returns `true` when credentials are valid, `false` otherwise. Both inputs
+ * being undefined or empty count as a failed check — adapters should only
+ * call this when `core.requiresAuth()` is true.
+ */
+declare function checkBasicAuth(authHeader: string | undefined, username: string, password: string): boolean;
+/**
+ * Standard 401 response body + header for an unauthenticated Basic auth
+ * request. Adapters use this when `checkBasicAuth` returns false.
+ */
+declare const BASIC_AUTH_CHALLENGE: {
+    status: 401;
+    headers: {
+        "WWW-Authenticate": string;
+    };
+    body: string;
+};
+
+/**
+ * Build a fully-wired Hono app for Workbench:
+ *
+ * - `POST /api/*`, `GET /api/*` etc.   — JSON API
+ * - `GET /config`                       — UI bootstrap config
+ * - `GET /assets/:file`                 — static asset reader
+ * - `GET *`                             — `index.html` with `<base href>`
+ * - CORS on `/api/*`
+ * - Basic auth on everything when `core.requiresAuth()` is true
+ *
+ * Used directly by `@getworkbench/hono` (returned as-is for `.route()`
+ * mounting) and indirectly by `createFetchHandler` for non-Hono adapters.
+ */
+declare function buildWorkbenchApp(core: WorkbenchCore): Hono;
+
+interface StaticAssetResult {
+    status: 200 | 404;
+    body: Buffer | null;
+    contentType: string;
+}
+/**
+ * Read a bundled UI asset from `UI_DIST_PATH/assets/<filename>`.
+ *
+ * Returns a uniform `{ status, body, contentType }` shape so each adapter
+ * can serialize it onto its framework-native response without re-implementing
+ * the file lookup or content-type sniffing.
+ */
+declare function serveStaticAsset(filename: string): StaticAssetResult;
+interface IndexHtmlResult {
+    body: string;
+    contentType: "text/html; charset=utf-8";
+}
+/**
+ * Read the bundled `index.html`, inject a `<base href>` matching the request's
+ * mount path so client-side asset URLs resolve correctly, and return it.
+ *
+ * Falls back to a tiny "UI assets not found" stub when the core package has
+ * not been built yet — useful for `bun run dev` against a fresh checkout.
+ */
+declare function renderIndexHtml(basePath: string, title: string): IndexHtmlResult;
+
 /**
  * Absolute filesystem path to the bundled UI assets (index.html + /assets).
- * Adapters should serve static files from this directory.
+ * Adapters that don't go through {@link createFetchHandler} serve static
+ * files from this directory directly.
  */
 declare const UI_DIST_PATH: string;
 
-export { type ActivityBucket, type ActivityStatsResponse, type CreateFlowChildRequest, type CreateFlowRequest, type DelayedJobInfo, type DelayedSortField, type FailingJobType, type FlowNode, type FlowSummary, type HourlyBucket, type JobInfo, type JobStatus, type JobTags, type MetricsResponse, type OverviewStats, type PaginatedResponse, type QueueInfo, QueueManager, type QueueMetrics, type RepeatableSortField, type RunInfo, type RunInfoList, type RunSortField, type SchedulerInfo, type SearchResult, type SlowestJob, type SortDirection, type SortOptions, type TestJobRequest, UI_DIST_PATH, WorkbenchCore, type WorkbenchOptions, type WorkerInfo, createApiRoutes };
+export { type ActivityBucket, type ActivityStatsResponse, BASIC_AUTH_CHALLENGE, type CreateFlowChildRequest, type CreateFlowRequest, type DelayedJobInfo, type DelayedSortField, type FailingJobType, type FetchHandlerResult, type FlowNode, type FlowSummary, type Handler, type HandlerInput, type HandlerResult, type HourlyBucket, type HttpMethod, type IndexHtmlResult, type JobInfo, type JobStatus, type JobTags, type MetricsResponse, type OverviewStats, type PaginatedResponse, type QueueInfo, QueueManager, type QueueMetrics, type RepeatableSortField, type RouteDef, type RunInfo, type RunInfoList, type RunSortField, type SchedulerInfo, type SearchResult, type SlowestJob, type SortDirection, type SortOptions, type StaticAssetResult, type TestJobRequest, UI_DIST_PATH, WorkbenchCore, type WorkbenchOptions, type WorkerInfo, buildRouteTable, buildWorkbenchApp, checkBasicAuth, computeBasePath, createApiRoutes, createFetchHandler, renderIndexHtml, resolveBasePath, serveStaticAsset };