@pikku/core 0.11.2 → 0.12.0

package/src/wirings/http/http.types.ts

@@ -1,5 +1,6 @@
 import type { SerializeOptions } from 'cookie'
-import type { PikkuError } from '../../errors/error-handler.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import { PikkuError } from '../../errors/error-handler.js'
 import type {
   CoreServices,
   CoreSingletonServices,
@@ -44,7 +45,7 @@ export type RunHTTPWiringOptions = Partial<{
 
 export type RunHTTPWiringParams = {
   singletonServices: CoreSingletonServices
-  createWireServices: CreateWireServices<
+  createWireServices?: CreateWireServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
     CoreUserSession
@@ -53,7 +54,7 @@ export type RunHTTPWiringParams = {
 
 /**
  * Represents the HTTP methods supported for API HTTP wirings.
-t */
+ */
 export type HTTPMethod =
   | 'post'
   | 'get'
@@ -64,21 +65,41 @@ export type HTTPMethod =
   | 'options'
 
 /**
- * Represents an API HTTP wiring without a function, including metadata such as content type, route, and timeout settings.
+ * Header schema type for request header validation.
+ * Uses Standard Schema interface - works with Zod, Valibot, ArkType, Effect Schema, etc.
+ */
+export type HTTPHeadersSchema = StandardSchemaV1<
+  Record<string, string | string[] | undefined>
+>
+
+/**
+ * Documentation config for OpenAPI generation
+ */
+export type HTTPRouteDocsConfig = {
+  description?: string
+  response?: string
+  errors?: Array<typeof PikkuError>
+  tags?: string[]
+}
+
+/**
+ * Common HTTP route configuration shared between wireHTTP and wireHTTPRoutes
  */
-export type CoreHTTPFunction = {
+export type HTTPRouteBaseConfig = {
   contentType?: 'xml' | 'json'
+  timeout?: number
+  tags?: string[]
+  headers?: HTTPHeadersSchema
+  docs?: HTTPRouteDocsConfig
+}
+
+/**
+ * Represents an API HTTP wiring without a function, including metadata such as content type, route, and timeout settings.
+ */
+export type CoreHTTPFunction = HTTPRouteBaseConfig & {
   route: string
   eventChannel?: false
   returnsJSON?: false
-  timeout?: number
-  tags?: string[]
-  docs?: Partial<{
-    description: string
-    response: string
-    errors: Array<typeof PikkuError>
-    tags: string[]
-  }>
 }
 /**
  * Represents a http wire within Pikku, including a request and response.
@@ -121,12 +142,14 @@ export type CoreHTTPFunctionWiring<
     In,
     Out,
     any,
+    any,
     any
   > = CorePikkuFunction<In, Out>,
   PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
     In,
     Out,
     any,
+    any,
     any
   > = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission extends CorePikkuPermission<
@@ -149,7 +172,6 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      tags?: string[]
       middleware?: PikkuMiddleware[]
       sse?: undefined
     })
@@ -163,7 +185,6 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      tags?: string[]
       middleware?: PikkuMiddleware[]
       sse?: undefined
     })
@@ -177,9 +198,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      sse?: boolean
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      sse?: boolean
     })
   | (CoreHTTPFunction & {
       route: R
@@ -191,9 +211,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      sse?: boolean
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      sse?: boolean
     })
   | (CoreHTTPFunction & {
       route: R
@@ -205,9 +224,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      query?: Array<keyof In>
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      query?: Array<keyof In>
       sse?: undefined
     })
   | (CoreHTTPFunction & {
@@ -220,24 +238,10 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      query?: Array<keyof In>
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      query?: Array<keyof In>
       sse?: undefined
     })
-  | {
-      /** Route triggers a workflow matched by route/method from workflow wires.http */
-      route: R
-      method: HTTPMethod
-      workflow: true
-      func?: undefined
-      permissions?: undefined
-      auth?: undefined
-      tags?: undefined
-      middleware?: undefined
-      returnsJSON?: undefined
-      sse?: boolean
-    }
 
 /**
  * Represents the input types for HTTP wiring metadata, including parameters, query, and body types.
@@ -257,8 +261,9 @@ export type HTTPWiringMeta = CommonWireMeta & {
   params?: string[]
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
+  headersSchemaName?: string
   sse?: true
-  workflow?: true
+  groupBasePath?: string
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
 
@@ -305,3 +310,82 @@ export interface PikkuHTTPResponse<Out = unknown> {
   close?: () => void
   setMode?: (mode: 'stream') => void
 }
+
+/**
+ * Single route configuration - supports all wireHTTP options
+ */
+export type HTTPRouteConfig<
+  PikkuFunction extends
+    | CorePikkuFunction<any, any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any> =
+    | CorePikkuFunction<any, any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any>,
+  PikkuPermission extends CorePikkuPermission<
+    any,
+    any,
+    any
+  > = CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = HTTPRouteBaseConfig & {
+  // Required
+  method: HTTPMethod
+  route: string
+  func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>
+
+  // Auth & permissions
+  auth?: boolean
+  permissions?: CorePermissionGroup<PikkuPermission>
+
+  // Middleware
+  middleware?: PikkuMiddleware[]
+
+  // SSE support
+  sse?: boolean
+}
+
+/**
+ * Group-level configuration applied to all routes
+ */
+export type HTTPRoutesGroupConfig<
+  PikkuPermission extends CorePikkuPermission<
+    any,
+    any,
+    any
+  > = CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = {
+  basePath?: string
+  tags?: string[]
+  auth?: boolean
+  middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+/**
+ * Nested route map - allows hierarchical organization
+ * Can contain individual routes, nested maps, or contracts with config
+ */
+export type HTTPRouteMap = {
+  [key: string]: HTTPRouteConfig | HTTPRouteMap | HTTPRouteContract
+}
+
+/**
+ * A route contract with optional group config (returned by defineRoutes)
+ */
+export type HTTPRouteContract<T extends HTTPRouteMap = HTTPRouteMap> =
+  HTTPRoutesGroupConfig & {
+    routes: T
+  }
+
+/**
+ * Full configuration for wireHTTPRoutes
+ */
+export type WireHTTPRoutesConfig = HTTPRoutesGroupConfig & {
+  routes: HTTPRouteMap | HTTPRouteConfig[]
+}

package/src/wirings/http/index.ts

@@ -1,6 +1,6 @@
-export * from './pikku-fetch-http-request.js'
-export * from './pikku-fetch-http-response.js'
-export * from './log-http-routes.js'
+export { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
+export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
+export { logRoutes } from './log-http-routes.js'
 
 export {
   fetch,
@@ -10,4 +10,16 @@ export {
   addHTTPPermission,
 } from './http-runner.js'
 
-export type * from './http.types.js'
+export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+
+export type {
+  AssertHTTPWiringParams,
+  CoreHTTPFunctionWiring,
+  HTTPMethod,
+  HTTPRouteBaseConfig,
+  HTTPWiringsMeta,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+  PikkuQuery,
+  RunHTTPWiringOptions,
+} from './http.types.js'

package/src/wirings/mcp/index.ts

@@ -1,3 +1,27 @@
-export * from './mcp.types.js'
-export * from './mcp-runner.js'
-export * from './mcp-endpoint-registry.js'
+export { MCPEndpointRegistry } from './mcp-endpoint-registry.js'
+export {
+  MCPError,
+  wireMCPResource,
+  wireMCPPrompt,
+  runMCPResource,
+  runMCPTool,
+  runMCPPrompt,
+} from './mcp-runner.js'
+export {
+  getMCPResourcesMeta,
+  getMCPToolsMeta,
+  getMCPPromptsMeta,
+} from './mcp-runner.js'
+export type {
+  AssertMCPResourceURIParams,
+  CoreMCPPrompt,
+  CoreMCPResource,
+  CoreMCPTool,
+  MCPPromptResponse,
+  MCPResourceMeta,
+  MCPResourceResponse,
+  MCPToolMeta,
+  MCPToolResponse,
+  MCPPromptMeta,
+  PikkuMCP,
+} from './mcp.types.js'

package/src/wirings/mcp/mcp-endpoint-registry.test.ts

@@ -147,7 +147,7 @@ describe('MCPEndpointRegistry', () => {
           uri: 'file://test.txt',
           title: 'Test Resource',
           description: 'Test description',
-          pikkuFuncName: 'testResource',
+          pikkuFuncId: 'testResource',
           inputSchema: null,
           outputSchema: null,
           mimeType: 'text/plain',
@@ -164,7 +164,7 @@ describe('MCPEndpointRegistry', () => {
           name: 'test-tool',
           title: 'Test Tool',
           description: 'Test description',
-          pikkuFuncName: 'testTool',
+          pikkuFuncId: 'testTool',
           inputSchema: null,
           outputSchema: null,
         },
@@ -179,7 +179,7 @@ describe('MCPEndpointRegistry', () => {
         'test-prompt': {
           name: 'test-prompt',
           description: 'Test Prompt',
-          pikkuFuncName: 'testPrompt',
+          pikkuFuncId: 'testPrompt',
           inputSchema: null,
           outputSchema: null,
           arguments: [],

package/src/wirings/mcp/mcp-runner.ts

@@ -7,7 +7,6 @@ import {
 } from '../../types/core.types.js'
 import type {
   CoreMCPResource,
-  CoreMCPTool,
   CoreMCPPrompt,
   JsonRpcRequest,
   JsonRpcResponse,
@@ -22,8 +21,15 @@ import { getErrorResponse } from '../../errors/error-handler.js'
 import { closeWireServices } from '../../utils.js'
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { BadRequestError, NotFoundError } from '../../errors/errors.js'
-import { PikkuSessionService } from '../../services/user-session-service.js'
+import {
+  BadRequestError,
+  NotFoundError,
+  PikkuMissingMetaError,
+} from '../../errors/errors.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
 
 export class MCPError extends Error {
   constructor(public readonly error: JsonRpcErrorResponse) {
@@ -59,9 +65,11 @@ export const wireMCPResource = <
   const resourcesMeta = pikkuState(null, 'mcp', 'resourcesMeta')
   const mcpResourceMeta = resourcesMeta[mcpResource.uri]
   if (!mcpResourceMeta) {
-    throw new Error(`MCP resource metadata not found for '${mcpResource.uri}'`)
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for MCP resource '${mcpResource.uri}'`
+    )
   }
-  addFunction(mcpResourceMeta.pikkuFuncName, mcpResource.func as any)
+  addFunction(mcpResourceMeta.pikkuFuncId, mcpResource.func as any)
   const resources = pikkuState(null, 'mcp', 'resources')
   if (resources.has(mcpResource.uri)) {
     throw new Error(`MCP resource already exists: ${mcpResource.uri}`)
@@ -69,26 +77,6 @@ export const wireMCPResource = <
   resources.set(mcpResource.uri, mcpResource)
 }
 
-export const wireMCPTool = <
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<any, any>
-  > = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>,
->(
-  mcpTool: CoreMCPTool<PikkuFunctionConfig>
-) => {
-  const toolsMeta = pikkuState(null, 'mcp', 'toolsMeta')
-  const mcpToolMeta = toolsMeta[mcpTool.name]
-  if (!mcpToolMeta) {
-    throw new Error(`MCP tool metadata not found for '${mcpTool.name}'`)
-  }
-  addFunction(mcpToolMeta.pikkuFuncName, mcpTool.func as any)
-  const tools = pikkuState(null, 'mcp', 'tools')
-  if (tools.has(mcpTool.name)) {
-    throw new Error(`MCP tool already exists: ${mcpTool.name}`)
-  }
-  tools.set(mcpTool.name, mcpTool)
-}
-
 export const wireMCPPrompt = <
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, any>
@@ -99,9 +87,11 @@ export const wireMCPPrompt = <
   const promptsMeta = pikkuState(null, 'mcp', 'promptsMeta')
   const mcpPromptMeta = promptsMeta[mcpPrompt.name]
   if (!mcpPromptMeta) {
-    throw new Error(`MCP prompt metadata not found for '${mcpPrompt.name}'`)
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for MCP prompt '${mcpPrompt.name}'`
+    )
   }
-  addFunction(mcpPromptMeta.pikkuFuncName, mcpPrompt.func as any)
+  addFunction(mcpPromptMeta.pikkuFuncId, mcpPrompt.func as any)
   const prompts = pikkuState(null, 'mcp', 'prompts')
   if (prompts.has(mcpPrompt.name)) {
     throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`)
@@ -115,7 +105,7 @@ export async function runMCPResource(
   uri: string
 ) {
   let endpoint: CoreMCPResource | undefined
-  let pikkuFuncName: string | undefined
+  let pikkuFuncId: string | undefined
   let extractedParams: Record<string, string> = {}
 
   const metas = pikkuState(null, 'mcp', 'resourcesMeta')
@@ -123,7 +113,7 @@ export async function runMCPResource(
 
   if (endpoints.has(uri)) {
     endpoint = endpoints.get(uri)
-    pikkuFuncName = metas[uri]?.pikkuFuncName
+    pikkuFuncId = metas[uri]?.pikkuFuncId
   } else {
     for (const [uriTemplate, value] of endpoints.entries()) {
       // Extract parameter names from the template
@@ -139,7 +129,7 @@ export async function runMCPResource(
 
       if (match) {
         endpoint = value
-        pikkuFuncName = metas[uriTemplate]?.pikkuFuncName
+        pikkuFuncId = metas[uriTemplate]?.pikkuFuncId
 
         // Extract parameter values and create params object
         for (let i = 0; i < paramNames.length; i++) {
@@ -158,7 +148,7 @@ export async function runMCPResource(
     'resource',
     uri,
     endpoint,
-    pikkuFuncName,
+    pikkuFuncId,
     { ...params, mcp: { ...params.mcp, uri } } as RunMCPEndpointParams<
       keyof CoreMCPResource
     >
@@ -170,14 +160,13 @@ export async function runMCPTool(
   params: RunMCPEndpointParams,
   name: string
 ) {
-  const endpoint = pikkuState(null, 'mcp', 'tools').get(name)
   const meta = pikkuState(null, 'mcp', 'toolsMeta')[name]
   return await runMCPPikkuFunc(
     request,
     'tool',
     name,
-    endpoint,
-    meta?.pikkuFuncName,
+    undefined,
+    meta?.pikkuFuncId,
     params
   )
 }
@@ -194,7 +183,7 @@ export async function runMCPPrompt(
     'prompt',
     name,
     endpoint,
-    meta?.pikkuFuncName,
+    meta?.pikkuFuncId,
     params
   )
 }
@@ -206,27 +195,26 @@ async function runMCPPikkuFunc(
   request: JsonRpcRequest,
   type: 'resource' | 'tool' | 'prompt',
   name: string,
-  mcp: CoreMCPResource | CoreMCPTool | CoreMCPPrompt | undefined,
-  pikkuFuncName: string | undefined,
+  mcp: CoreMCPResource | CoreMCPPrompt | undefined,
+  pikkuFuncId: string | undefined,
   { singletonServices, createWireServices, mcp: mcpWire }: RunMCPEndpointParams
 ): Promise<JsonRpcResponse> {
   let wireServices: any
 
   try {
-    // Validate JSON-RPC request structure
     if (request.jsonrpc !== '2.0') {
       throw new BadRequestError(
         'Invalid JSON-RPC version, only supoorted version is 2.0'
       )
     }
 
-    if (!mcp) {
+    if (mcp === undefined && type !== 'tool') {
       throw new NotFoundError(
         `MCP '${type}' registration not found for '${name}'`
       )
     }
 
-    if (!pikkuFuncName) {
+    if (!pikkuFuncId) {
       throw new NotFoundError(
         `MCP '${type}' PikkuFunction Mapping not found for '${name}'`
       )
@@ -234,12 +222,12 @@ async function runMCPPikkuFunc(
 
     singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
 
+    const mcpSessionService = new PikkuSessionService()
     const wire: PikkuWire = {
       mcp: mcpWire,
-      session: new PikkuSessionService(),
+      ...createMiddlewareSessionWireProps(mcpSessionService),
     }
 
-    // Get metadata for the MCP endpoint to access pre-resolved middleware
     let meta: any
     if (type === 'resource') {
       meta = pikkuState(null, 'mcp', 'resourcesMeta')[name]
@@ -249,18 +237,23 @@ async function runMCPPikkuFunc(
       meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
     }
 
-    const result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncName, {
+    let result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncId, {
       singletonServices,
       createWireServices,
       data: () => request.params,
       inheritedMiddleware: meta?.middleware,
-      wireMiddleware: mcp.middleware,
+      wireMiddleware: mcp?.middleware,
       inheritedPermissions: meta?.permissions,
-      wirePermissions: mcp.permissions,
-      tags: mcp.tags,
+      wirePermissions: mcp?.permissions,
+      tags: mcp?.tags,
       wire,
+      sessionService: mcpSessionService,
     })
 
+    if (type === 'tool' && meta?.outputSchema !== 'MCPToolResponse') {
+      result = [{ type: 'text', text: JSON.stringify(result) }]
+    }
+
     return {
       id: request.id,
       result,
@@ -297,10 +290,6 @@ async function runMCPPikkuFunc(
   }
 }
 
-export const getMCPTools = () => {
-  return pikkuState(null, 'mcp', 'tools')
-}
-
 export const getMCPResources = () => {
   return pikkuState(null, 'mcp', 'resources')
 }

package/src/wirings/mcp/mcp.types.ts

@@ -50,7 +50,7 @@ export type PikkuMCP<Tools extends string = any> = {
 export type MCPResourceMeta = Record<
   string,
   Omit<CoreMCPResource, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string
+    pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
@@ -64,7 +64,7 @@ export type MCPResourceMeta = Record<
 export type MCPToolMeta = Record<
   string,
   Omit<CoreMCPTool, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string
+    pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
@@ -78,7 +78,7 @@ export type MCPToolMeta = Record<
 export type MCPPromptMeta = Record<
   string,
   Omit<CoreMCPPrompt, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string
+    pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     arguments: Array<{

package/src/wirings/node/index.ts

@@ -0,0 +1,2 @@
+export type { CoreNodeConfig, NodeType } from './node.types.js'
+export type { NodesMeta } from './node.types.js'

package/src/wirings/node/node.types.ts

@@ -0,0 +1,23 @@
+export type NodeType = 'trigger' | 'action' | 'end'
+
+export type CoreNodeConfig = {
+  displayName: string
+  category: string
+  type: NodeType
+  errorOutput?: boolean
+}
+
+export type NodeMeta = {
+  name: string
+  displayName: string
+  category: string
+  type: NodeType
+  rpc: string
+  description?: string
+  errorOutput: boolean
+  inputSchemaName: string | null
+  outputSchemaName: string | null
+  tags?: string[]
+}
+
+export type NodesMeta = Record<string, NodeMeta>

package/src/wirings/oauth2/index.ts

@@ -0,0 +1,3 @@
+export { OAuth2Client } from './oauth2-client.js'
+export { wireOAuth2Credential } from './wire-oauth2-credential.js'
+export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js'