@spikard/node 0.12.0 → 0.15.1

package/index.d.ts

@@ -1,367 +1,808 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 /**
- * JavaScript-side gRPC message stream for client streaming RPC
+ * Configuration for GraphQL routes
  *
- * Wraps a Rust MessageStream and exposes JavaScript async iterator protocol
- * so JavaScript handlers can consume incoming messages as an async iterable.
+ * Provides a builder pattern for configuring GraphQL route parameters
+ * for the Spikard HTTP server's routing system.
+ *
+ * # Example
+ */
+export declare class GraphQLRouteConfig {
+  /**
+   * Set the HTTP path for the GraphQL endpoint
+   *
+   * # Arguments
+   *
+   * * `path` - The URL path (e.g., "/graphql", "/api/graphql")
+   */
+  path(path: string): GraphQLRouteConfig
+  /**
+   * Set the HTTP method for the GraphQL endpoint
+   *
+   * # Arguments
+   *
+   * * `method` - The HTTP method (typically "POST")
+   */
+  method(method: string): GraphQLRouteConfig
+  /**
+   * Enable or disable the GraphQL Playground UI
+   *
+   * # Arguments
+   *
+   * * `enable` - Whether to enable playground
+   */
+  enablePlayground(enable: boolean): GraphQLRouteConfig
+  /**
+   * Set a custom description for documentation
+   *
+   * # Arguments
+   *
+   * * `description` - Documentation string
+   */
+  description(description: string): GraphQLRouteConfig
+  /** Get the configured path */
+  getPath(): string
+  /** Get the configured method */
+  getMethod(): string
+  /** Check if playground is enabled */
+  isPlaygroundEnabled(): boolean
+  /** Get the description if set */
+  getDescription(): string | null
+  static default(): GraphQLRouteConfig
+}
+export type JsGraphQLRouteConfig = GraphQLRouteConfig
+
+export declare class JsGraphQlErrorInfo {
+  statusCode: number
+  isTransient: boolean
+  errorType: string
+  /** HTTP status code for this error (0 means no associated status). */
+  statusCode(): number
+  /** Returns `true` if the error is transient and a retry may succeed. */
+  isTransient(): boolean
+  /** Machine-readable error category string for matching and logging. */
+  errorType(): string
+}
+export type JsGraphQLErrorInfo = JsGraphQlErrorInfo
+
+/**
+ * Core test client for making HTTP requests to a Spikard application.
+ *
+ * This struct wraps axum-test's TestServer and provides a language-agnostic
+ * interface for making HTTP requests, sending WebSocket connections, and
+ * handling Server-Sent Events. Language bindings wrap this to provide
+ * native API surfaces.
  */
-export declare class GrpcMessageStream {
+export declare class TestClient {
+  /** a GraphQL query/mutation to a custom endpoint */
+  graphqlAt(endpoint: string, query: string, variables?: any | undefined | null, operationName?: string | undefined | null): Promise<ResponseSnapshot>
+  /** a GraphQL query/mutation */
+  graphql(query: string, variables?: any | undefined | null, operationName?: string | undefined | null): Promise<ResponseSnapshot>
+  /**
+   *  a GraphQL subscription (WebSocket) to a custom endpoint.
+   *
+   * Uses the `graphql-transport-ws` protocol and captures the first `next` payload.
+   * After the first payload is received, this client sends `complete` to unsubscribe.
+   */
+  graphqlSubscriptionAt(endpoint: string, query: string, variables?: any | undefined | null, operationName?: string | undefined | null): Promise<GraphQLSubscriptionSnapshot>
   /**
-   * Get the next message from the stream
+   *  a GraphQL subscription (WebSocket).
    *
-   * Returns a Promise that resolves to the next message Buffer or null if stream is done.
-   * Throws an error if the stream encounters an error.
+   * Uses `/graphql` as the default subscription endpoint.
    */
-  next(): Promise<Buffer | null>
+  graphqlSubscription(query: string, variables?: any | undefined | null, operationName?: string | undefined | null): Promise<GraphQLSubscriptionSnapshot>
 }
+export type JsTestClient = TestClient
 
-/** Node.js wrapper for SSE event */
-export declare class SseEvent {
+/** API Key authentication configuration */
+export interface ApiKeyConfig {
+  /** Valid API keys */
+  keys: Array<string>
+  /** Header name to check (e.g., "X-API-Key") */
+  headerName: string
+}
 
+/** AsyncAPI HTTP endpoint configuration */
+export interface AsyncApiConfig {
+  /** Enable AsyncAPI endpoints (default: false) */
+  enabled?: boolean
+  /** Pre-registered AsyncAPI spec to serve from GET /asyncapi.json */
+  spec?: any
 }
 
-/** Node.js wrapper for SSE event */
-export declare class SseEvent {
-  /** Get the data field of the event */
-  getData(): string
-  /** Parse the event data as JSON */
-  asJson(): any
-  /** Get the data field of the event */
-  getData(): string
-  /** Parse the event data as JSON */
-  asJson(): any
+export interface BackgroundJobMetadata {
+  name?: string
+  requestId?: string
 }
 
-/** Node.js wrapper for SSE stream */
-export declare class SseStream {
+export declare function backgroundJobMetadataDefault(): BackgroundJobMetadata
 
+/** Configuration for in-process background task execution. */
+export interface BackgroundTaskConfig {
+  maxQueueSize?: number
+  maxConcurrentTasks?: number
+  drainTimeoutSecs?: number
 }
 
-/** Node.js wrapper for SSE stream */
-export declare class SseStream {
-  /** Get the raw body of the SSE response */
-  body(): string
-  /** Get all events from the stream */
-  events(): Array<SseEvent>
-  /** Get events as JSON values */
-  eventsAsJson(): Array<any>
-  /** Get the raw body of the SSE response */
-  body(): string
-  /** Get all events from the stream */
-  events(): Array<SseEvent>
-  /** Get events as JSON values */
-  eventsAsJson(): Array<any>
+export declare function backgroundTaskConfigDefault(): BackgroundTaskConfig
+
+/** Compression configuration shared across runtimes */
+export interface CompressionConfig {
+  /** Enable gzip compression */
+  gzip?: boolean
+  /** Enable brotli compression */
+  brotli?: boolean
+  /** Minimum response size to compress (bytes) */
+  minSize?: number
+  /** Compression quality (0-11 for brotli, 0-9 for gzip) */
+  quality?: number
 }
 
-/** Test client for making HTTP requests to a Spikard application */
-export declare class TestClient {
-  /** Create a new test client from routes and handlers */
-  constructor(routesJson: string, websocketRoutesJson: string | undefined | null, handlersMap: object, websocketHandlers?: object | undefined | null, dependencies?: object | undefined | null, lifecycleHooks?: object | undefined | null, config?: object | undefined | null)
-  /** Make a GET request. */
-  get(path: string, headers?: any | undefined | null): Promise<TestResponse>
-  /** Make a POST request with an optional JSON body. */
-  post(path: string, headers?: any | undefined | null, json?: any | undefined | null): Promise<TestResponse>
-  /** Make a PUT request with an optional JSON body. */
-  put(path: string, headers?: any | undefined | null, json?: any | undefined | null): Promise<TestResponse>
-  /** Make a DELETE request. */
-  delete(path: string, headers?: any | undefined | null): Promise<TestResponse>
-  /** Make a PATCH request with an optional JSON body. */
-  patch(path: string, headers?: any | undefined | null, json?: any | undefined | null): Promise<TestResponse>
-  /** Make a HEAD request. */
-  head(path: string, headers?: any | undefined | null): Promise<TestResponse>
-  /** Make an OPTIONS request. */
-  options(path: string, headers?: any | undefined | null): Promise<TestResponse>
-  /** Make a TRACE request. */
-  trace(path: string, headers?: any | undefined | null): Promise<TestResponse>
-  /** Connect to a Server-Sent Events endpoint */
-  sse(path: string): Promise<SseStream>
-  /** Connect to a WebSocket endpoint */
-  websocket(path: string): Promise<WebSocketTestConnection>
-}
-
-/** HTTP Response wrapper */
-export declare class TestResponse {
-  /** Get the HTTP status code */
-  get statusCode(): number
-  /** Get response headers as JSON */
-  headers(): any
-  /** Get response body as text */
-  text(): string
-  /** Parse response body as JSON */
-  json(): any
-  /** Get raw response body bytes */
-  bytes(): Buffer
-  /** Extract GraphQL data from response */
-  graphqlData(): any
-  /** Extract GraphQL errors from response */
-  graphqlErrors(): Array<any>
-}
-
-/** Node.js wrapper for WebSocket messages */
-export declare class WebSocketMessage {
-
-}
-
-/** Node.js wrapper for WebSocket messages */
-export declare class WebSocketMessage {
-  /** Get message as text if it's a text message */
-  asText(): string | null
-  /** Get message as JSON if it's a text message containing JSON */
-  asJson(): any | null
-  /** Get message as binary if it's a binary message */
-  asBinary(): Buffer | null
-  /** Check if this is a close message */
-  isClose(): boolean
-  /** Get message as text if it's a text message */
-  asText(): string | null
-  /** Get message as JSON if it's a text message containing JSON */
-  asJson(): any | null
-  /** Get message as binary if it's a binary message */
-  asBinary(): Buffer | null
-  /** Check if this is a close message */
-  isClose(): boolean
-}
-
-/** Node.js wrapper for WebSocket test client */
-export declare class WebSocketTestConnection {
-
-}
-
-/** Node.js wrapper for WebSocket test client */
-export declare class WebSocketTestConnection {
-  /** Send a text message */
-  sendText(text: string): Promise<void>
-  /** Send a JSON message */
-  sendJson(obj: any): Promise<void>
-  /** Receive a text message */
-  receiveText(): Promise<string>
-  /** Receive and parse a JSON message */
-  receiveJson(): Promise<any>
-  /** Receive raw bytes */
-  receiveBytes(): Promise<Buffer>
-  /** Receive a message and return WebSocketMessage */
-  receiveMessage(): Promise<WebSocketMessage>
-  /** Close the WebSocket connection */
-  close(): Promise<void>
-  /** Send a text message */
-  sendText(text: string): Promise<void>
-  /** Send a JSON message */
-  sendJson(obj: any): Promise<void>
-  /** Receive a text message */
-  receiveText(): Promise<string>
-  /** Receive and parse a JSON message */
-  receiveJson(): Promise<any>
-  /** Receive raw bytes */
-  receiveBytes(): Promise<Buffer>
-  /** Receive a message and return WebSocketMessage */
-  receiveMessage(): Promise<WebSocketMessage>
-  /** Close the WebSocket connection */
-  close(): Promise<void>
-}
-
-/** Run an async task on Spikard's background runtime. */
-export declare function backgroundRun(task: () => Promise<undefined>): void
+export declare function compressionConfigDefault(): CompressionConfig
+
+/** Contact information */
+export interface ContactInfo {
+  /** Name of the contact person or organisation. */
+  name?: string
+  /** Contact email address. */
+  email?: string
+  /** URL pointing to the contact information page. */
+  url?: string
+}
+
+/** CORS configuration for a route */
+export interface CorsConfig {
+  allowedOrigins?: Array<string>
+  allowedMethods?: Array<string>
+  allowedHeaders?: Array<string>
+  exposeHeaders?: Array<string>
+  maxAge?: number
+  allowCredentials?: boolean
+}
+
+export declare function corsConfigDefault(): CorsConfig
+
+/** Configuration for fully-featured schemas with Query, Mutation, and Subscription types */
+export interface FullSchemaConfig {
+  /** Enable introspection queries */
+  introspectionEnabled?: boolean
+  /** Maximum query complexity (None = unlimited) */
+  complexityLimit?: number
+  /** Maximum query depth (None = unlimited) */
+  depthLimit?: number
+}
+
+export declare function fullSchemaConfigDefault(): FullSchemaConfig
+
+/** Snapshot of a GraphQL subscription exchange over WebSocket. */
+export interface GraphQLSubscriptionSnapshot {
+  /** Operation id used for the subscription request. */
+  operationId: string
+  /** Whether the server acknowledged the GraphQL WebSocket connection. */
+  acknowledged: boolean
+  /** First `next.payload` received for this subscription, if any. */
+  event?: any
+  /** GraphQL protocol errors emitted by the server. */
+  errors: Array<any>
+  /** Whether a `complete` frame was observed for this operation. */
+  completeReceived: boolean
+}
 
 /**
- * Creates a streaming handle from a JavaScript async iterator.
+ * Configuration for gRPC support
+ *
+ * Controls how the server handles gRPC requests, including compression,
+ * timeouts, and protocol settings.
+ *
+ * # Stream Limits
+ *
+ * This configuration enforces message-level size limits but delegates
+ * concurrent stream limiting to the HTTP/2 transport layer:
+ *
+ * - **Message Size Limits**: The `max_message_size` field is enforced per
+ *   individual message (request or response) in both unary and streaming RPCs.
+ *   When a single message exceeds this limit, the request is rejected with
+ *   `PAYLOAD_TOO_LARGE` (HTTP 413).
  *
- * This function is exposed to JavaScript via napi. It wraps async iterators
- * in a streaming handle structure that can be used to construct HTTP streaming responses.
+ * - **Concurrent Stream Limits**: The `max_concurrent_streams` is an advisory
+ *   configuration passed to the HTTP/2 layer for connection-level stream
+ *   negotiation. The HTTP/2 transport automatically enforces this limit and
+ *   returns GOAWAY frames when exceeded. Applications should not rely on
+ *   custom enforcement of this limit.
  *
- * NOTE: Marked with #[allow(dead_code)] because the #[napi] macro generates
- * FFI bindings that aren't visible to the Rust dead code checker, though the
- * function is actually exported and callable from JavaScript.
+ * - **Stream Response Size Limits**: The `max_stream_response_bytes` field caps the
+ *   total encoded bytes emitted across a server-streaming or bidi-streaming response.
+ *   When the cumulative size exceeds the limit, the stream is terminated with
+ *   `tonic.Status.resource_exhausted`. Defaults to `None` (unbounded).
+ *
+ * # Example
  */
-export declare function createStreamingHandle(iterator: object, init?: StreamingResponseInit | undefined | null): number
+export interface GrpcConfig {
+  /** Enable gRPC support */
+  enabled?: boolean
+  /**
+   * Maximum message size in bytes (for both sending and receiving)
+   *
+   * This limit applies to individual messages in both unary and streaming RPCs.
+   * When a single message exceeds this size, the request is rejected with HTTP 413
+   * (Payload Too Large).
+   *
+   * Default: 4MB (4194304 bytes)
+   *
+   * # Note
+   * This limit does NOT apply to the total response size in streaming RPCs.
+   * For multi-message streams, the total response can exceed this limit as long
+   * as each individual message stays within the limit.
+   */
+  maxMessageSize?: number
+  /** Enable gzip compression for gRPC messages */
+  enableCompression?: boolean
+  /** Timeout for gRPC requests in seconds (None = no timeout) */
+  requestTimeout?: number
+  /**
+   * Maximum number of concurrent streams per connection (HTTP/2 advisory)
+   *
+   * This value is communicated to HTTP/2 clients as the server's flow control limit.
+   * The HTTP/2 transport layer enforces this limit automatically via SETTINGS frames
+   * and GOAWAY responses. Applications should NOT implement custom enforcement.
+   *
+   * Default: 100 streams per connection
+   *
+   * # Stream Limiting Strategy
+   * - **Per Connection**: This limit applies per HTTP/2 connection, not globally
+   * - **Transport Enforcement**: HTTP/2 handles all stream limiting; applications
+   *   need not implement custom checks
+   * - **Streaming Requests**: In server streaming or bidi streaming, each logical
+   *   RPC consumes one stream slot. Message ordering within a stream follows
+   *   HTTP/2 frame ordering.
+   */
+  maxConcurrentStreams?: number
+  /** Enable HTTP/2 keepalive */
+  enableKeepalive?: boolean
+  /** HTTP/2 keepalive interval in seconds */
+  keepaliveInterval?: number
+  /** HTTP/2 keepalive timeout in seconds */
+  keepaliveTimeout?: number
+  /**
+   * Total byte cap across an entire streaming response.
+   *
+   * When `Some(n)`, the streaming adapter aborts the stream with
+   * `tonic::Status::resource_exhausted` once the cumulative encoded message
+   * bytes exceed `n`. The stream yields the error item and then terminates.
+   *
+   * Per-message cap remains `max_message_size`. This limit applies to
+   * server-streaming and bidirectional-streaming RPCs only; unary RPCs are
+   * governed solely by `max_message_size`.
+   *
+   * Default: `None` (unbounded total response size).
+   */
+  maxStreamResponseBytes?: number
+}
+
+export declare function grpcConfigDefault(): GrpcConfig
+
+/** JSON-RPC server configuration */
+export interface JsonRpcConfig {
+  /** Enable JSON-RPC endpoint */
+  enabled?: boolean
+  /** HTTP endpoint path for JSON-RPC requests (default: "/rpc") */
+  endpointPath?: string
+  /** Enable batch request processing (default: true) */
+  enableBatch?: boolean
+  /** Maximum number of requests in a batch (default: 100) */
+  maxBatchSize?: number
+}
+
+export declare function jsonRpcConfigDefault(): JsonRpcConfig
 
 /**
- * Bidirectional streaming request: request with collected input messages
+ * JSON-RPC method metadata for routes that support JSON-RPC
+ *
+ * This struct captures the metadata needed to expose HTTP routes as JSON-RPC methods,
+ * enabling discovery and documentation of RPC-compatible endpoints.
  *
- * Used when calling JavaScript bidirectional streaming handlers.
- * The handler receives all input messages and returns an array of response messages.
+ * # Examples
  */
-export interface GrpcBidiStreamRequest {
-  /** Fully qualified service name (e.g., "mypackage.UserService") */
-  serviceName: string
-  /** Method name (e.g., "GetUser") */
+export interface JsonRpcMethodInfo {
+  /** The JSON-RPC method name (e.g., "user.create") */
   methodName: string
-  /** gRPC metadata as key-value pairs */
-  metadata: Record<string, string>
-  /** Collected stream messages as Buffers */
-  messages: Buffer[]
+  /** Optional description of what the method does */
+  description?: string
+  /** Optional JSON Schema for method parameters */
+  paramsSchema?: any
+  /** Optional JSON Schema for the result */
+  resultSchema?: any
+  /** Whether this method is deprecated */
+  deprecated: boolean
+  /** Tags for categorizing and grouping methods */
+  tags: Array<string>
+}
+
+/** JWT authentication configuration */
+export interface JwtConfig {
+  /** Secret key for JWT verification */
+  secret: string
+  /** Required algorithm (HS256, HS384, HS512, RS256, etc.) */
+  algorithm: string
+  /** Required audience claim */
+  audience?: Array<string>
+  /** Required issuer claim */
+  issuer?: string
+  /** Leeway for expiration checks (seconds) */
+  leeway: number
+}
+
+/** License information */
+export interface LicenseInfo {
+  /** SPDX license identifier or display name (e.g. `"MIT"`). */
+  name: string
+  /** URL to the full license text. */
+  url?: string
+}
+
+/** HTTP method */
+export declare const enum Method {
+  Get = 'Get',
+  Post = 'Post',
+  Put = 'Put',
+  Patch = 'Patch',
+  Delete = 'Delete',
+  Head = 'Head',
+  Options = 'Options',
+  Trace = 'Trace'
+}
+
+/** OpenAPI configuration */
+export interface OpenApiConfig {
+  /** Enable OpenAPI generation (default: false for zero overhead) */
+  enabled?: boolean
+  /** API title */
+  title?: string
+  /** API version */
+  version?: string
+  /** API description (supports markdown) */
+  description?: string
+  /** Path to serve Swagger UI (default: "/docs") */
+  swaggerUiPath?: string
+  /** Path to serve Redoc (default: "/redoc") */
+  redocPath?: string
+  /** Path to serve OpenAPI JSON spec (default: "/openapi.json") */
+  openapiJsonPath?: string
+  /** Contact information */
+  contact?: JsContactInfo
+  /** License information */
+  license?: JsLicenseInfo
+  /** Server definitions */
+  servers?: Array<JsServerInfo>
+  /** Security schemes (auto-detected from middleware if not provided) */
+  securitySchemes?: Record<string, JsSecuritySchemeInfo>
+}
+
+export declare function openApiConfigDefault(): OpenApiConfig
+
+/** A single channel extracted from an AsyncAPI spec */
+export interface ParsedChannel {
+  /** Channel key from the spec (e.g. "chat/messages") */
+  name: string
+  /** Channel address / path */
+  address: string
+  /** Message names declared on this channel */
+  messages: Array<string>
+  /** Bindings (ws / http / amqp / …) as raw JSON for forward-compatibility */
+  bindings?: any
+}
+
+/** A resolved message (name + JSON Schema) */
+export interface ParsedMessage {
+  /** Message name */
+  name: string
+  /** Resolved JSON Schema for the message payload, if available */
+  schema?: any
+}
+
+/** A single operation extracted from an AsyncAPI spec */
+export interface ParsedOperation {
+  /** Operation name */
+  name: string
+  /** Operation action: "send" or "receive" */
+  action: string
+  /** Channel reference (resolved to the channel name) */
+  channel: string
+}
+
+/** Request body for `POST /asyncapi/parse` */
+export interface ParseRequest {
+  spec: any
+}
+
+/** Full parse result returned by `POST /asyncapi/parse` */
+export interface ParseResult {
+  specVersion: string
+  title: string
+  apiVersion: string
+  channels: Array<ParsedChannel>
+  operations: Array<ParsedOperation>
+  messages: Array<ParsedMessage>
 }
 
 /**
- * Bidirectional streaming response: array of response messages
+ * RFC 9457 Problem Details for HTTP APIs
+ *
+ * A machine-readable format for specifying errors in HTTP API responses.
+ * Per RFC 9457, all fields are optional. The `type` field defaults to "about:blank"
+ * if not specified.
  *
- * Returned by JavaScript bidirectional streaming handlers.
- * Each message is converted back to a protobuf message in the response stream.
+ * # Content-Type
+ * Responses using this struct should set:
+ * ```text
+ * Content-Type: application/problem+json
+ * ```
+ *
+ * ```json
+ * {
+ *   "type": "https://spikard.dev/errors/validation-error",
+ *   "title": "Request Validation Failed",
+ *   "status": 422,
+ *   "detail": "2 validation errors in request body",
+ *   "errors": [...]
+ * }
+ * ```
  */
-export interface GrpcBidiStreamResponse {
-  /** Stream response messages as Buffers */
-  messages: Buffer[]
-  /** Optional gRPC metadata to include in response */
-  metadata?: Record<string, string> | undefined
+export interface ProblemDetails {
+  /**
+   * A URI reference that identifies the problem type.
+   * Defaults to "about:blank" when absent.
+   * Should be a stable, human-readable identifier for the problem type.
+   */
+  type: string
+  /**
+   * A short, human-readable summary of the problem type.
+   * Should not change from occurrence to occurrence of the problem.
+   */
+  title: string
+  /**
+   * The HTTP status code generated by the origin server.
+   * This is advisory; the actual HTTP status code takes precedence.
+   */
+  status: number
+  /** A human-readable explanation specific to this occurrence of the problem. */
+  detail?: string
+  /**
+   * A URI reference that identifies the specific occurrence of the problem.
+   * It may or may not yield further information if dereferenced.
+   */
+  instance?: string
+  /**
+   * Extension members - problem-type-specific data.
+   * For validation errors, this typically contains an "errors" array.
+   */
+  extensions: Record<string, any>
+}
+
+/** Create a bad request error */
+export declare function problemDetailsBadRequest(detail: string): ProblemDetails
+
+/** Create an internal server error */
+export declare function problemDetailsInternalServerError(detail: string): ProblemDetails
+
+/** Create a method not allowed error */
+export declare function problemDetailsMethodNotAllowed(detail: string): ProblemDetails
+
+/** Create a not found error */
+export declare function problemDetailsNotFound(detail: string): ProblemDetails
+
+/** Set the detail field */
+export declare function problemDetailsWithDetail(cfg: ProblemDetails, detail: string): ProblemDetails
+
+/** Set the instance field */
+export declare function problemDetailsWithInstance(cfg: ProblemDetails, instance: string): ProblemDetails
+
+/** Configuration for schemas with Query and Mutation types */
+export interface QueryMutationConfig {
+  /** Enable introspection queries */
+  introspectionEnabled?: boolean
+  /** Maximum query complexity (None = unlimited) */
+  complexityLimit?: number
+  /** Maximum query depth (None = unlimited) */
+  depthLimit?: number
+}
+
+export declare function queryMutationConfigDefault(): QueryMutationConfig
+
+/** Configuration for schemas with only Query type */
+export interface QueryOnlyConfig {
+  /** Enable introspection queries */
+  introspectionEnabled?: boolean
+  /** Maximum query complexity (None = unlimited) */
+  complexityLimit?: number
+  /** Maximum query depth (None = unlimited) */
+  depthLimit?: number
+}
+
+export declare function queryOnlyConfigDefault(): QueryOnlyConfig
+
+/** Rate limiting configuration shared across runtimes */
+export interface RateLimitConfig {
+  /** Requests per second */
+  perSecond?: number
+  /** Burst allowance */
+  burst?: number
+  /** Use IP-based rate limiting */
+  ipBased?: boolean
+}
+
+export declare function rateLimitConfigDefault(): RateLimitConfig
+
+/** HTTP Response with custom status code, headers, and content */
+export interface Response {
+  /** Response body content */
+  content?: any
+  /** HTTP status code (defaults to 200) */
+  statusCode?: number
+  /** Response headers */
+  headers?: Record<string, string>
+}
+
+export declare function responseDefault(): Response
+
+/** Snapshot of an Axum response used by higher-level language bindings. */
+export interface ResponseSnapshot {
+  /** HTTP status code. */
+  status: number
+  /** Response headers (lowercase keys for predictable lookups). */
+  headers: Record<string, string>
+  /** Response body bytes (decoded for supported encodings). */
+  body: Uint8Array | Buffer | Array<number>
 }
 
 /**
- * Client streaming request: unary request with collected stream messages
+ * Configuration for GraphQL schema building.
  *
- * Used when calling JavaScript client streaming handlers.
- * The handler receives all collected messages in a single call.
+ * Encapsulates all schema-level configuration options including
+ * introspection control, complexity limits, and depth limits.
  */
-export interface GrpcClientStreamRequest {
-  /** Fully qualified service name (e.g., "mypackage.UserService") */
-  serviceName: string
-  /** Method name (e.g., "GetUser") */
-  methodName: string
-  /** gRPC metadata as key-value pairs */
-  metadata: Record<string, string>
-  /** Collected stream messages as Buffers */
-  messages: Buffer[]
+export interface SchemaConfig {
+  /** Enable introspection queries */
+  introspectionEnabled?: boolean
+  /** Maximum query complexity (None = unlimited) */
+  complexityLimit?: number
+  /** Maximum query depth (None = unlimited) */
+  depthLimit?: number
 }
 
+export declare function schemaConfigDefault(): SchemaConfig
+
 /**
- * gRPC request object passed to JavaScript handlers
+ * Create a schema configuration with all three root types.
+ *
+ * This is a convenience function for fully-featured schemas.
  *
- * Contains the parsed components of a gRPC request with all data
- * converted to JavaScript-friendly types.
+ * # Returns
+ *
+ * A `FullSchemaConfig` with default settings
  */
-export interface GrpcRequest {
-  /** Fully qualified service name (e.g., "mypackage.UserService") */
-  serviceName: string
-  /** Method name (e.g., "GetUser") */
-  methodName: string
-  /** Serialized protobuf message as Buffer */
-  payload: Buffer
-  /** gRPC metadata as key-value pairs */
-  metadata: Record<string, string>
-}
+export declare function schemaFull(): FullSchemaConfig
 
 /**
- * gRPC response object returned by JavaScript handlers
+ * Create a schema configuration with Query and Mutation types.
+ *
+ * This is a convenience function for schemas with queries and mutations but no subscriptions.
  *
- * Contains the serialized protobuf response and optional metadata
- * to include in the response headers.
+ * # Returns
+ *
+ * A `QueryMutationConfig` with default settings
  */
-export interface GrpcResponse {
-  /** Serialized protobuf message as Buffer */
-  payload: Buffer
-  /** Optional gRPC metadata to include in response */
-  metadata?: Record<string, string> | undefined
-}
+export declare function schemaQueryMutation(): QueryMutationConfig
 
 /**
- * Structured handler input passed to JavaScript handlers
+ * Create a simple schema configuration with only Query type.
  *
- * This struct replaces JSON string passing, eliminating serialization overhead.
- * Fields are converted from `RequestData` using a direct `From` impl.
+ * This is a convenience function for schemas that only have queries.
  *
- * PERFORMANCE: `object_from_js = false` skips generating FromNapiValue since
- * HandlerInput only flows Rust→JS, never JS→Rust. This eliminates unnecessary
- * code generation and potential conversion overhead.
+ * # Returns
+ *
+ * A `QueryOnlyConfig` with default settings
  */
-export interface HandlerInput {
-  /** HTTP method (GET, POST, etc.) */
-  method: string
-  /** Request path */
-  path: string
-  /** HTTP headers as a map */
-  headers: Record<string, string>
-  /** HTTP cookies as a map */
-  cookies: Record<string, string>
-  /** Parsed query parameters */
-  queryParams: any
-  /** Validated parameters (query/path/header/cookie combined) */
-  validatedParams?: any
-  /** Parsed request body */
-  body: any
-  /** Extracted path parameters */
-  pathParams: Record<string, string>
+export declare function schemaQueryOnly(): QueryOnlyConfig
+
+/** Security scheme types */
+export interface SecuritySchemeInfo {
+  type: string
+  scheme?: string
+  bearerFormat?: string
+  location?: string
+  name?: string
+}
+
+/** Server configuration */
+export interface ServerConfig {
+  /** Host to bind to */
+  host?: string
+  /** Port to bind to */
+  port?: number
+  /** Number of Tokio runtime worker threads used by binding-managed server runtimes */
+  workers?: number
+  /** Enable request ID generation and propagation */
+  enableRequestId?: boolean
+  /** Maximum request body size in bytes (None = unlimited, not recommended) */
+  maxBodySize?: number
+  /** Request timeout in seconds (None = no timeout) */
+  requestTimeout?: number
+  /** Enable compression middleware */
+  compression?: CompressionConfig
+  /** Enable rate limiting */
+  rateLimit?: RateLimitConfig
+  /** JWT authentication configuration */
+  jwtAuth?: JwtConfig
+  /** API Key authentication configuration */
+  apiKeyAuth?: ApiKeyConfig
+  /** Static file serving configuration */
+  staticFiles?: Array<StaticFilesConfig>
+  /** Enable graceful shutdown on SIGTERM/SIGINT */
+  gracefulShutdown?: boolean
+  /** Graceful shutdown timeout (seconds) */
+  shutdownTimeout?: number
+  /** AsyncAPI HTTP endpoint configuration */
+  asyncapi?: AsyncApiConfig
+  /** OpenAPI documentation configuration */
+  openapi?: OpenApiConfig
+  /** JSON-RPC configuration */
+  jsonrpc?: JsonRpcConfig
+  /** gRPC configuration */
+  grpc?: GrpcConfig
+  /** Background task executor configuration */
+  backgroundTasks?: BackgroundTaskConfig
+  /** Enable per-request HTTP tracing (tower-http `TraceLayer`) */
+  enableHttpTrace?: boolean
+}
+
+export declare function serverConfigDefault(): ServerConfig
+
+/** Server information */
+export interface ServerInfo {
+  /** Base URL of the server (e.g. `"https://api.example.com/v1"`). */
+  url: string
+  /** Optional human-readable description of the server environment. */
+  description?: string
+}
+
+/** Possible errors while converting an Axum response into a snapshot. */
+export declare const enum SnapshotError {
+  /** Response header could not be decoded to UTF-8. */
+  InvalidHeader = 'InvalidHeader',
+  /** Body decompression failed. */
+  Decompression = 'Decompression'
 }
 
 /**
- * Structured handler output returned from JavaScript handlers
+ * An individual SSE event
+ *
+ * Represents a single Server-Sent Event to be sent to a connected client.
+ * Events can have an optional type, ID, and retry timeout for advanced scenarios.
  *
- * This struct is returned directly from handlers without JSON serialization,
- * completing the zero-copy request/response pattern.
+ * # Fields
+ *
+ * * `event_type` - Optional event type string (used for client-side event filtering)
+ * * `data` - JSON data payload to send to the client
+ * * `id` - Optional event ID (clients can use this to resume after disconnect)
+ * * `retry` - Optional retry timeout in milliseconds (tells client when to reconnect)
+ *
+ * # SSE Format
+ *
+ * Events are serialized to the following text format:
+ * ```text
+ * event: event_type
+ * data: {"json":"value"}
+ * id: event-123
+ * retry: 3000
+ * ```
  */
-export interface HandlerOutput {
-  /** HTTP status code (e.g., 200, 404, 500) */
-  status: number
-  /** Response headers as a map */
-  headers?: Record<string, string>
-  /** Response body as JSON value (used when `raw_body` is not set) */
-  body?: any
-  /**
-   * Pre-serialized response body bytes. When set, this is used directly as
-   * the response body, bypassing `serde_json::to_vec` on the `body` field.
-   * JS handlers can pass `Buffer.from(JSON.stringify(obj))` here to avoid
-   * a napi Value → serde_json::Value → bytes round-trip.
-   */
-  rawBody?: Buffer
+export interface SseEvent {
+  /** Event type (optional) */
+  eventType?: string
+  /** Event data (JSON value) */
+  data: any
+  /** Event ID (optional, for client-side reconnection) */
+  id?: string
+  /** Retry timeout in milliseconds (optional) */
+  retry?: number
 }
 
 /**
- * Start the Spikard HTTP server from Node.js
+ * Set the event ID for client-side reconnection support
  *
- * Creates an Axum HTTP server in a dedicated background thread with its own Tokio runtime.
- * This ensures the Node.js event loop remains free to process ThreadsafeFunction calls.
+ * Sets an ID that clients can use to resume from this point if they disconnect.
+ * The client sends this ID back in the `Last-Event-ID` header when reconnecting.
  *
  * # Arguments
+ * * `id` - Unique identifier for this event
  *
- * * `app` - Application object containing routes and handler functions
- * * `config` - Optional ServerConfig with all middleware settings
- *
- * # Returns
- *
- * Returns `Ok(())` after the server thread is spawned. Note that this function
- * returns immediately - the server runs in the background.
+ * # Example
+ */
+export declare function sseEventWithId(cfg: SseEvent, id: string): SseEvent
+
+/**
+ * Set the retry timeout for client reconnection
  *
- * # Errors
+ * Sets the time in milliseconds clients should wait before attempting to reconnect
+ * if the connection is lost. The client browser will automatically handle reconnection.
  *
- * Returns an error if:
- * - Route metadata is invalid or missing required fields
- * - Handler functions cannot be converted to ThreadsafeFunctions
- * - Socket address is invalid
- * - Route creation fails
+ * # Arguments
+ * * `retry_ms` - Retry timeout in milliseconds
  *
  * # Example
- *
- * ```typescript
- * import { Spikard, ServerConfig } from 'spikard';
- *
- * const config: ServerConfig = {
- *   host: '0.0.0.0',
- *   port: 8000,
- *   compression: { quality: 9 },
- *   openapi: {
- *     enabled: true,
- *     title: 'My API',
- *     version: '1.0.0'
- *   }
- * };
- *
- * const app = new Spikard();
- * app.run(config);
- * ```
  */
-export declare function runServer(app: object, config?: object | undefined | null): void
+export declare function sseEventWithRetry(cfg: SseEvent, retryMs: number): SseEvent
+
+/** Static file serving configuration */
+export interface StaticFilesConfig {
+  /** Directory path to serve */
+  directory: string
+  /** URL path prefix (e.g., "/static") */
+  routePrefix: string
+  /** Fallback to index.html for directories */
+  indexFile: boolean
+  /** Cache-Control header value */
+  cacheControl?: string
+}
+
+/** A single Server-Sent Event. */
+export interface TestingSseEvent {
+  /** The data field of the event. */
+  data: string
+}
 
 /**
- * Optional configuration for a streaming response.
+ * Represents an uploaded file from multipart/form-data requests.
  *
- * This struct is exposed to JavaScript via napi and provides configuration
- * options when creating streaming responses from async iterators.
+ * This struct provides efficient access to file content with automatic
+ * base64 decoding and implements standard I/O traits for compatibility.
  *
- * NOTE: Marked with #[allow(dead_code)] because the #[napi(object)] macro
- * generates access patterns that aren't visible to the Rust dead code checker,
- * though the struct is actually exposed to and used by JavaScript code.
+ * # Example
  */
-export interface StreamingResponseInit {
-  /** HTTP status code for the streaming response (default 200). */
-  statusCode?: number
-  /** Headers to attach to the streaming response. */
-  headers?: Record<string, string>
+export interface UploadFile {
+  /** Original filename from the client */
+  filename: string
+  /** MIME type of the uploaded file */
+  contentType?: string
+  /** Size of the file in bytes */
+  size?: number
+  /** File content (may be base64 encoded) */
+  content: Uint8Array | Buffer | Array<number>
+  /** Content encoding type */
+  contentEncoding?: string
+}
+
+/** Request body for `POST /asyncapi/validate` */
+export interface ValidateRequest {
+  spec: any
+  channel: string
+  message: string
+  payload: any
+}
+
+/** Response body for `POST /asyncapi/validate` */
+export interface ValidationResponse {
+  valid: boolean
+  errors: Array<string>
+}
+
+/** A WebSocket message that can be text or binary. */
+export declare const enum WebSocketMessage {
+  /** A text message. */
+  Text = 'Text',
+  /** A binary message. */
+  Binary = 'Binary',
+  /**
+   * A close message with a numeric close code (RFC 6455) and optional reason text.
+   *
+   * Common codes: 1000 Normal Closure, 1001 Going Away, 1005 No Status Received,
+   * 1006 Abnormal Closure.
+   */
+  Close = 'Close',
+  /** A ping message. */
+  Ping = 'Ping',
+  /** A pong message. */
+  Pong = 'Pong'
 }