@zlayer/sdk 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,1005 @@
+/**
+ * ZLayer SDK for building WASM plugins in TypeScript.
+ *
+ * This module provides helper functions that wrap the generated WIT bindings
+ * for easier access to ZLayer host capabilities including configuration,
+ * key-value storage, logging, secrets, and metrics.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The current version of the ZLayer SDK.
+ */
+export declare const VERSION = "0.1.0";
+/**
+ * Error thrown when configuration operations fail.
+ */
+export declare class ConfigError extends Error {
+    /** The configuration key that caused the error */
+    readonly key: string;
+    constructor(key: string, message: string);
+}
+/**
+ * Error thrown when key-value storage operations fail.
+ */
+export declare class KVError extends Error {
+    /** The key that caused the error */
+    readonly key: string;
+    /** The bucket where the error occurred */
+    readonly bucket: string;
+    /** The error code from the host */
+    readonly code: KVErrorCode;
+    constructor(bucket: string, key: string, code: KVErrorCode, message: string);
+}
+/**
+ * Error codes for key-value operations.
+ */
+export declare enum KVErrorCode {
+    /** Key not found */
+    NotFound = "not_found",
+    /** Value too large */
+    ValueTooLarge = "value_too_large",
+    /** Storage quota exceeded */
+    QuotaExceeded = "quota_exceeded",
+    /** Key format invalid */
+    InvalidKey = "invalid_key",
+    /** Generic storage error */
+    Storage = "storage"
+}
+/**
+ * Error thrown when secret operations fail.
+ */
+export declare class SecretError extends Error {
+    /** The secret name that caused the error */
+    readonly secretName: string;
+    constructor(secretName: string, message: string);
+}
+/**
+ * Error thrown when a required value is missing.
+ */
+export declare class NotFoundError extends Error {
+    /** The identifier that was not found */
+    readonly identifier: string;
+    constructor(identifier: string, message: string);
+}
+/**
+ * Log severity levels matching the WIT interface.
+ */
+export declare enum LogLevel {
+    /** Finest-grained debugging information */
+    Trace = 0,
+    /** Debugging information */
+    Debug = 1,
+    /** Informational messages */
+    Info = 2,
+    /** Warning messages */
+    Warn = 3,
+    /** Error messages */
+    Error = 4
+}
+/**
+ * A key-value pair used throughout the SDK.
+ */
+export interface KeyValue {
+    key: string;
+    value: string;
+}
+/**
+ * HTTP methods supported by the plugin system.
+ */
+export declare enum HttpMethod {
+    Get = "GET",
+    Post = "POST",
+    Put = "PUT",
+    Delete = "DELETE",
+    Patch = "PATCH",
+    Head = "HEAD",
+    Options = "OPTIONS",
+    Connect = "CONNECT",
+    Trace = "TRACE"
+}
+/**
+ * Semantic version representation.
+ */
+export interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+    preRelease?: string;
+}
+/**
+ * Plugin information returned by the info() method.
+ */
+export interface PluginInfo {
+    /** Unique plugin identifier (e.g., "zlayer:auth-jwt") */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Plugin version */
+    version: Version;
+    /** Brief description of plugin functionality */
+    description: string;
+    /** Plugin author or organization */
+    author: string;
+    /** License identifier (e.g., "MIT", "Apache-2.0") */
+    license?: string;
+    /** Homepage or repository URL */
+    homepage?: string;
+    /** Additional metadata as key-value pairs */
+    metadata?: KeyValue[];
+}
+/**
+ * Incoming request to be processed by a plugin.
+ */
+export interface PluginRequest {
+    /** Unique request identifier for tracing */
+    requestId: string;
+    /** Request path (e.g., "/api/users/123") */
+    path: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Query string (without leading ?) */
+    query?: string;
+    /** Request headers */
+    headers: KeyValue[];
+    /** Request body as bytes */
+    body: Uint8Array;
+    /** Request timestamp in nanoseconds since Unix epoch */
+    timestamp: bigint;
+    /** Additional context from the host */
+    context: KeyValue[];
+}
+/**
+ * Plugin response returned to the host.
+ */
+export interface PluginResponse {
+    /** HTTP status code (200, 404, 500, etc.) */
+    status: number;
+    /** Response headers */
+    headers: KeyValue[];
+    /** Response body */
+    body: Uint8Array;
+}
+/**
+ * Result of handling a request.
+ */
+export type HandleResult = {
+    type: 'response';
+    response: PluginResponse;
+} | {
+    type: 'passThrough';
+} | {
+    type: 'error';
+    message: string;
+};
+/**
+ * Plugin capabilities that can be requested.
+ */
+export interface Capabilities {
+    config?: boolean;
+    keyvalue?: boolean;
+    logging?: boolean;
+    secrets?: boolean;
+    metrics?: boolean;
+    httpClient?: boolean;
+}
+/**
+ * Plugin initialization error types.
+ */
+export type InitError = {
+    type: 'configMissing';
+    key: string;
+} | {
+    type: 'configInvalid';
+    key: string;
+} | {
+    type: 'capabilityUnavailable';
+    capability: string;
+} | {
+    type: 'failed';
+    message: string;
+};
+/**
+ * Authentication result from an authenticator plugin.
+ */
+export type AuthResult = {
+    type: 'authenticated';
+    claims: KeyValue[];
+} | {
+    type: 'denied';
+    reason: string;
+} | {
+    type: 'challenge';
+    challenge: string;
+} | {
+    type: 'skip';
+};
+/**
+ * Rate limit information.
+ */
+export interface RateLimitInfo {
+    /** Requests remaining in current window */
+    remaining: bigint;
+    /** Total limit for the window */
+    limit: bigint;
+    /** Time until limit resets (nanoseconds) */
+    resetAfter: bigint;
+    /** Retry after this duration if denied (nanoseconds) */
+    retryAfter?: bigint;
+}
+/**
+ * Rate limit decision.
+ */
+export type RateLimitResult = {
+    type: 'allowed';
+    info: RateLimitInfo;
+} | {
+    type: 'denied';
+    info: RateLimitInfo;
+};
+/**
+ * The main plugin handler interface that plugins must export.
+ */
+export interface ZLayerPlugin {
+    /**
+     * Initialize the plugin.
+     * Called once when the plugin is loaded.
+     * @returns Capabilities the plugin requires, or an error
+     */
+    init?(): Capabilities | InitError;
+    /**
+     * Return plugin metadata.
+     * Called after successful initialization.
+     */
+    info(): PluginInfo;
+    /**
+     * Handle an incoming request.
+     * @param request The incoming request to process
+     * @returns The result of handling the request
+     */
+    handle(request: PluginRequest): HandleResult;
+    /**
+     * Graceful shutdown hook.
+     * Called when the plugin is being unloaded.
+     */
+    shutdown?(): void;
+}
+/**
+ * A simpler plugin interface for stateless transformations.
+ */
+export interface TransformerPlugin {
+    /**
+     * Transform request headers before forwarding.
+     */
+    transformRequestHeaders?(headers: KeyValue[]): KeyValue[];
+    /**
+     * Transform response headers before returning.
+     */
+    transformResponseHeaders?(headers: KeyValue[]): KeyValue[];
+    /**
+     * Transform request body before forwarding.
+     */
+    transformRequestBody?(body: Uint8Array): Uint8Array;
+    /**
+     * Transform response body before returning.
+     */
+    transformResponseBody?(body: Uint8Array): Uint8Array;
+}
+/**
+ * Authentication plugin interface.
+ */
+export interface AuthenticatorPlugin {
+    /**
+     * Authenticate an incoming request.
+     * @param request The request to authenticate
+     * @returns Authentication result with identity claims on success
+     */
+    authenticate(request: PluginRequest): AuthResult;
+    /**
+     * Validate a token (e.g., JWT, API key).
+     * @param token The token to validate
+     * @returns Claims if valid
+     * @throws Error if invalid
+     */
+    validateToken?(token: string): KeyValue[];
+}
+/**
+ * Rate limiting plugin interface.
+ */
+export interface RateLimiterPlugin {
+    /**
+     * Check if request should be rate limited.
+     * @param request The request to check
+     * @returns Rate limit decision
+     */
+    check(request: PluginRequest): RateLimitResult;
+    /**
+     * Get current rate limit status for a key.
+     * @param key The rate limit key
+     * @returns Current status or undefined if not found
+     */
+    status?(key: string): RateLimitInfo | undefined;
+}
+/**
+ * Get a configuration value by key.
+ *
+ * @param key - The configuration key to retrieve
+ * @returns The configuration value, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const dbHost = getConfig('database.host');
+ * if (dbHost) {
+ *     console.log(`Database host: ${dbHost}`);
+ * }
+ * ```
+ */
+export declare function getConfig(key: string): string | undefined;
+/**
+ * Get a required configuration value by key.
+ * Throws ConfigError if the key does not exist.
+ *
+ * @param key - The configuration key to retrieve
+ * @returns The configuration value
+ * @throws {ConfigError} If the configuration key does not exist
+ *
+ * @example
+ * ```typescript
+ * try {
+ *     const apiKey = getConfigRequired('api.key');
+ * } catch (e) {
+ *     if (e instanceof ConfigError) {
+ *         log.error(`Missing config: ${e.key}`);
+ *     }
+ * }
+ * ```
+ */
+export declare function getConfigRequired(key: string): string;
+/**
+ * Get a configuration value as a boolean.
+ * Recognizes: "true", "false", "1", "0", "yes", "no" (case-insensitive).
+ *
+ * @param key - The configuration key to retrieve
+ * @returns The boolean value, or undefined if not found or not parseable
+ *
+ * @example
+ * ```typescript
+ * const debugMode = getConfigBool('debug.enabled') ?? false;
+ * ```
+ */
+export declare function getConfigBool(key: string): boolean | undefined;
+/**
+ * Get a configuration value as an integer.
+ *
+ * @param key - The configuration key to retrieve
+ * @returns The integer value, or undefined if not found or not parseable
+ *
+ * @example
+ * ```typescript
+ * const maxRetries = getConfigInt('http.max_retries') ?? 3;
+ * ```
+ */
+export declare function getConfigInt(key: string): number | undefined;
+/**
+ * Get a configuration value as a float.
+ *
+ * @param key - The configuration key to retrieve
+ * @returns The float value, or undefined if not found or not parseable
+ *
+ * @example
+ * ```typescript
+ * const timeout = getConfigFloat('http.timeout_seconds') ?? 30.0;
+ * ```
+ */
+export declare function getConfigFloat(key: string): number | undefined;
+/**
+ * Get multiple configuration values at once.
+ *
+ * @param keys - The configuration keys to retrieve
+ * @returns A Map of key to value for keys that exist
+ *
+ * @example
+ * ```typescript
+ * const config = getConfigMany(['db.host', 'db.port', 'db.name']);
+ * const host = config.get('db.host') ?? 'localhost';
+ * ```
+ */
+export declare function getConfigMany(keys: string[]): Map<string, string>;
+/**
+ * Get all configuration keys with a given prefix.
+ *
+ * @param prefix - The prefix to match (e.g., "database.")
+ * @returns A Map of key to value for matching keys
+ *
+ * @example
+ * ```typescript
+ * const dbConfig = getConfigPrefix('database.');
+ * // Returns: Map { 'database.host' => 'localhost', 'database.port' => '5432' }
+ * ```
+ */
+export declare function getConfigPrefix(prefix: string): Map<string, string>;
+/**
+ * Check if a configuration key exists.
+ *
+ * @param key - The configuration key to check
+ * @returns true if the key exists, false otherwise
+ */
+export declare function configExists(key: string): boolean;
+/**
+ * Get all configuration as a JSON string.
+ * Useful for debugging or serialization.
+ *
+ * @returns JSON string of all configuration
+ *
+ * @example
+ * ```typescript
+ * log.debug(`All config: ${getAllConfig()}`);
+ * ```
+ */
+export declare function getAllConfig(): string;
+/**
+ * Get a value from key-value storage as bytes.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to retrieve
+ * @returns The value as bytes, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const data = kvGet('sessions', sessionId);
+ * if (data) {
+ *     const session = JSON.parse(new TextDecoder().decode(data));
+ * }
+ * ```
+ */
+export declare function kvGet(bucket: string, key: string): Uint8Array | undefined;
+/**
+ * Get a value from key-value storage as a string.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to retrieve
+ * @returns The value as a string, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const username = kvGetString('users', `user:${userId}:name`);
+ * ```
+ */
+export declare function kvGetString(bucket: string, key: string): string | undefined;
+/**
+ * Get a value from key-value storage as JSON.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to retrieve
+ * @returns The parsed JSON value, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * interface User { name: string; email: string; }
+ * const user = kvGetJson<User>('users', userId);
+ * ```
+ */
+export declare function kvGetJson<T>(bucket: string, key: string): T | undefined;
+/**
+ * Set a value in key-value storage as bytes.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to set
+ * @param value - The value as bytes
+ *
+ * @example
+ * ```typescript
+ * const encoder = new TextEncoder();
+ * kvSet('sessions', sessionId, encoder.encode(JSON.stringify(session)));
+ * ```
+ */
+export declare function kvSet(bucket: string, key: string, value: Uint8Array): void;
+/**
+ * Set a value in key-value storage as a string.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to set
+ * @param value - The value as a string
+ *
+ * @example
+ * ```typescript
+ * kvSetString('users', `user:${userId}:name`, 'John Doe');
+ * ```
+ */
+export declare function kvSetString(bucket: string, key: string, value: string): void;
+/**
+ * Set a value in key-value storage as JSON.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to set
+ * @param value - The value to serialize as JSON
+ *
+ * @example
+ * ```typescript
+ * kvSetJson('users', userId, { name: 'John', email: 'john@example.com' });
+ * ```
+ */
+export declare function kvSetJson<T>(bucket: string, key: string, value: T): void;
+/**
+ * Set a value in key-value storage with a TTL (time-to-live).
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to set
+ * @param value - The value as bytes
+ * @param ttlMs - Time-to-live in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Cache for 5 minutes
+ * kvSetWithTtl('cache', cacheKey, data, 5 * 60 * 1000);
+ * ```
+ */
+export declare function kvSetWithTtl(bucket: string, key: string, value: Uint8Array, ttlMs: number): void;
+/**
+ * Set a string value in key-value storage with a TTL.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to set
+ * @param value - The value as a string
+ * @param ttlMs - Time-to-live in milliseconds
+ */
+export declare function kvSetStringWithTtl(bucket: string, key: string, value: string, ttlMs: number): void;
+/**
+ * Delete a key from key-value storage.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to delete
+ * @returns true if the key was deleted, false if it didn't exist
+ *
+ * @example
+ * ```typescript
+ * kvDelete('sessions', sessionId);
+ * ```
+ */
+export declare function kvDelete(bucket: string, key: string): boolean;
+/**
+ * List all keys in a bucket with an optional prefix.
+ *
+ * @param bucket - The bucket/namespace
+ * @param prefix - Optional prefix to filter keys
+ * @returns Array of keys matching the prefix
+ *
+ * @example
+ * ```typescript
+ * const userKeys = kvKeys('users', 'user:');
+ * // Returns: ['user:1', 'user:2', 'user:3']
+ * ```
+ */
+export declare function kvKeys(bucket: string, prefix?: string): string[];
+/**
+ * Check if a key exists in key-value storage.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to check
+ * @returns true if the key exists, false otherwise
+ */
+export declare function kvExists(bucket: string, key: string): boolean;
+/**
+ * Atomically increment a numeric value in key-value storage.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to increment
+ * @param delta - The amount to increment by (default: 1)
+ * @returns The new value after incrementing
+ *
+ * @example
+ * ```typescript
+ * const newCount = kvIncrement('counters', 'page_views', 1);
+ * ```
+ */
+export declare function kvIncrement(bucket: string, key: string, delta?: number): bigint;
+/**
+ * Atomically compare and swap a value in key-value storage.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key to update
+ * @param expected - The expected current value (undefined if key shouldn't exist)
+ * @param newValue - The new value to set if expected matches
+ * @returns true if the swap succeeded, false if current value didn't match
+ *
+ * @example
+ * ```typescript
+ * // Optimistic locking
+ * const current = kvGet('locks', 'resource');
+ * const swapped = kvCompareAndSwap('locks', 'resource', current, newLockValue);
+ * if (!swapped) {
+ *     throw new Error('Resource was modified by another process');
+ * }
+ * ```
+ */
+export declare function kvCompareAndSwap(bucket: string, key: string, expected: Uint8Array | undefined, newValue: Uint8Array): boolean;
+/**
+ * Logging utilities for emitting structured logs to the host.
+ */
+export declare const log: {
+    /**
+     * Emit a trace-level log message.
+     * Use for finest-grained debugging information.
+     *
+     * @param msg - The log message
+     */
+    trace: (msg: string) => void;
+    /**
+     * Emit a debug-level log message.
+     * Use for debugging information.
+     *
+     * @param msg - The log message
+     */
+    debug: (msg: string) => void;
+    /**
+     * Emit an info-level log message.
+     * Use for informational messages about normal operation.
+     *
+     * @param msg - The log message
+     */
+    info: (msg: string) => void;
+    /**
+     * Emit a warn-level log message.
+     * Use for warning messages about potential issues.
+     *
+     * @param msg - The log message
+     */
+    warn: (msg: string) => void;
+    /**
+     * Emit an error-level log message.
+     * Use for error messages.
+     *
+     * @param msg - The log message
+     */
+    error: (msg: string) => void;
+    /**
+     * Emit a log message at the specified level.
+     *
+     * @param level - The log level
+     * @param msg - The log message
+     */
+    log: (level: LogLevel, msg: string) => void;
+    /**
+     * Emit a structured log message with key-value fields.
+     *
+     * @param level - The log level
+     * @param msg - The log message
+     * @param fields - Additional structured fields
+     *
+     * @example
+     * ```typescript
+     * log.structured(LogLevel.Info, 'Request processed', {
+     *     requestId: '123',
+     *     duration: '45ms',
+     *     status: '200',
+     * });
+     * ```
+     */
+    structured: (level: LogLevel, msg: string, fields: Record<string, string>) => void;
+    /**
+     * Check if a log level is enabled.
+     * Useful for avoiding expensive log construction when the level is disabled.
+     *
+     * @param level - The log level to check
+     * @returns true if the level is enabled
+     *
+     * @example
+     * ```typescript
+     * if (log.isEnabled(LogLevel.Debug)) {
+     *     log.debug(`Complex data: ${JSON.stringify(largeObject)}`);
+     * }
+     * ```
+     */
+    isEnabled: (level: LogLevel) => boolean;
+};
+/**
+ * Get a secret by name.
+ *
+ * @param name - The secret name
+ * @returns The secret value, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const apiKey = getSecret('external_api_key');
+ * ```
+ */
+export declare function getSecret(name: string): string | undefined;
+/**
+ * Get a required secret by name.
+ * Throws SecretError if the secret does not exist.
+ *
+ * @param name - The secret name
+ * @returns The secret value
+ * @throws {SecretError} If the secret does not exist
+ *
+ * @example
+ * ```typescript
+ * const dbPassword = getSecretRequired('database_password');
+ * ```
+ */
+export declare function getSecretRequired(name: string): string;
+/**
+ * Check if a secret exists.
+ *
+ * @param name - The secret name
+ * @returns true if the secret exists, false otherwise
+ */
+export declare function secretExists(name: string): boolean;
+/**
+ * List all available secret names (not values).
+ * Useful for diagnostics without exposing sensitive data.
+ *
+ * @returns Array of secret names
+ */
+export declare function listSecretNames(): string[];
+/**
+ * Metrics utilities for emitting observability data to the host.
+ */
+export declare const metrics: {
+    /**
+     * Increment a counter metric.
+     *
+     * @param name - The metric name
+     * @param value - The amount to increment by (default: 1)
+     *
+     * @example
+     * ```typescript
+     * metrics.counterInc('requests_total');
+     * metrics.counterInc('bytes_processed', byteCount);
+     * ```
+     */
+    counterInc: (name: string, value?: number) => void;
+    /**
+     * Increment a counter metric with labels.
+     *
+     * @param name - The metric name
+     * @param value - The amount to increment by
+     * @param labels - The metric labels
+     *
+     * @example
+     * ```typescript
+     * metrics.counterIncLabeled('http_requests_total', 1, {
+     *     method: 'GET',
+     *     path: '/api/users',
+     *     status: '200',
+     * });
+     * ```
+     */
+    counterIncLabeled: (name: string, value: number, labels: Record<string, string>) => void;
+    /**
+     * Set a gauge metric to a value.
+     *
+     * @param name - The metric name
+     * @param value - The value to set
+     *
+     * @example
+     * ```typescript
+     * metrics.gaugeSet('active_connections', connectionCount);
+     * ```
+     */
+    gaugeSet: (name: string, value: number) => void;
+    /**
+     * Set a gauge metric with labels.
+     *
+     * @param name - The metric name
+     * @param value - The value to set
+     * @param labels - The metric labels
+     */
+    gaugeSetLabeled: (name: string, value: number, labels: Record<string, string>) => void;
+    /**
+     * Add to a gauge value (can be negative).
+     *
+     * @param name - The metric name
+     * @param delta - The amount to add (can be negative)
+     */
+    gaugeAdd: (name: string, delta: number) => void;
+    /**
+     * Record a histogram observation.
+     *
+     * @param name - The metric name
+     * @param value - The observed value
+     *
+     * @example
+     * ```typescript
+     * metrics.histogramObserve('request_duration_seconds', 0.045);
+     * ```
+     */
+    histogramObserve: (name: string, value: number) => void;
+    /**
+     * Record a histogram observation with labels.
+     *
+     * @param name - The metric name
+     * @param value - The observed value
+     * @param labels - The metric labels
+     */
+    histogramObserveLabeled: (name: string, value: number, labels: Record<string, string>) => void;
+    /**
+     * Record request duration in milliseconds.
+     * Convenience method that converts to nanoseconds.
+     *
+     * @param name - The metric name
+     * @param durationMs - Duration in milliseconds
+     */
+    recordDuration: (name: string, durationMs: number) => void;
+    /**
+     * Record request duration with labels.
+     *
+     * @param name - The metric name
+     * @param durationMs - Duration in milliseconds
+     * @param labels - The metric labels
+     */
+    recordDurationLabeled: (name: string, durationMs: number, labels: Record<string, string>) => void;
+};
+/**
+ * Create a successful response with JSON body.
+ *
+ * @param data - The data to serialize as JSON
+ * @param status - HTTP status code (default: 200)
+ * @param headers - Additional headers
+ * @returns A PluginResponse
+ *
+ * @example
+ * ```typescript
+ * return jsonResponse({ users: ['alice', 'bob'] });
+ * return jsonResponse({ error: 'Not found' }, 404);
+ * ```
+ */
+export declare function jsonResponse<T>(data: T, status?: number, headers?: Record<string, string>): PluginResponse;
+/**
+ * Create a text response.
+ *
+ * @param text - The response text
+ * @param status - HTTP status code (default: 200)
+ * @param contentType - Content type (default: text/plain)
+ * @returns A PluginResponse
+ */
+export declare function textResponse(text: string, status?: number, contentType?: string): PluginResponse;
+/**
+ * Create an HTML response.
+ *
+ * @param html - The HTML content
+ * @param status - HTTP status code (default: 200)
+ * @returns A PluginResponse
+ */
+export declare function htmlResponse(html: string, status?: number): PluginResponse;
+/**
+ * Create a binary response.
+ *
+ * @param data - The binary data
+ * @param contentType - Content type
+ * @param status - HTTP status code (default: 200)
+ * @returns A PluginResponse
+ */
+export declare function binaryResponse(data: Uint8Array, contentType: string, status?: number): PluginResponse;
+/**
+ * Create an error response.
+ *
+ * @param message - The error message
+ * @param status - HTTP status code (default: 500)
+ * @returns A HandleResult with error response
+ */
+export declare function errorResponse(message: string, status?: number): HandleResult;
+/**
+ * Create a redirect response.
+ *
+ * @param location - The URL to redirect to
+ * @param status - HTTP status code (default: 302)
+ * @returns A PluginResponse
+ */
+export declare function redirectResponse(location: string, status?: number): PluginResponse;
+/**
+ * Create a pass-through result.
+ * Use this when the plugin doesn't want to handle the request.
+ *
+ * @returns A HandleResult indicating pass-through
+ */
+export declare function passThrough(): HandleResult;
+/**
+ * Get a header value from a request (case-insensitive).
+ *
+ * @param request - The plugin request
+ * @param name - The header name
+ * @returns The header value, or undefined if not found
+ */
+export declare function getHeader(request: PluginRequest, name: string): string | undefined;
+/**
+ * Get all values for a header (case-insensitive).
+ *
+ * @param request - The plugin request
+ * @param name - The header name
+ * @returns Array of header values
+ */
+export declare function getHeaders(request: PluginRequest, name: string): string[];
+/**
+ * Parse the request body as JSON.
+ *
+ * @param request - The plugin request
+ * @returns The parsed JSON body
+ */
+export declare function parseJsonBody<T>(request: PluginRequest): T;
+/**
+ * Get the request body as a string.
+ *
+ * @param request - The plugin request
+ * @returns The body as a string
+ */
+export declare function getBodyString(request: PluginRequest): string;
+/**
+ * Parse query string into a Map.
+ *
+ * @param request - The plugin request
+ * @returns Map of query parameters
+ */
+export declare function parseQuery(request: PluginRequest): Map<string, string>;
+/**
+ * Get a context value from a request.
+ *
+ * @param request - The plugin request
+ * @param key - The context key
+ * @returns The context value, or undefined if not found
+ */
+export declare function getContext(request: PluginRequest, key: string): string | undefined;
+/**
+ * Measure the duration of an async operation and record it as a metric.
+ *
+ * @param name - The metric name
+ * @param fn - The async function to measure
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await timed('database_query', async () => {
+ *     return await db.query('SELECT * FROM users');
+ * });
+ * ```
+ */
+export declare function timed<T>(name: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Measure the duration of a sync operation and record it as a metric.
+ *
+ * @param name - The metric name
+ * @param fn - The function to measure
+ * @returns The result of the function
+ */
+export declare function timedSync<T>(name: string, fn: () => T): T;
+/**
+ * Create a Version object from a semver string.
+ *
+ * @param semver - The semver string (e.g., "1.2.3" or "1.2.3-beta.1")
+ * @returns A Version object
+ */
+export declare function parseVersion(semver: string): Version;
+/**
+ * Format a Version object as a semver string.
+ *
+ * @param version - The Version object
+ * @returns The semver string
+ */
+export declare function formatVersion(version: Version): string;
+/**
+ * Register a plugin implementation.
+ * This is a convenience function for setting up plugin exports.
+ *
+ * @param plugin - The plugin implementation
+ * @returns The plugin for export
+ *
+ * @example
+ * ```typescript
+ * export default registerPlugin({
+ *     info() {
+ *         return {
+ *             id: 'my-org:my-plugin',
+ *             name: 'My Plugin',
+ *             version: { major: 1, minor: 0, patch: 0 },
+ *             description: 'A sample plugin',
+ *             author: 'My Org',
+ *         };
+ *     },
+ *     handle(request) {
+ *         return { type: 'response', response: jsonResponse({ hello: 'world' }) };
+ *     },
+ * });
+ * ```
+ */
+export declare function registerPlugin(plugin: ZLayerPlugin): ZLayerPlugin;
+//# sourceMappingURL=index.d.ts.map