@zlayer/sdk 0.8.0

package/dist/index.js

@@ -0,0 +1,1227 @@
+/**
+ * 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
+ */
+// =============================================================================
+// Version
+// =============================================================================
+/**
+ * The current version of the ZLayer SDK.
+ */
+export const VERSION = '0.1.0';
+// =============================================================================
+// Error Classes
+// =============================================================================
+/**
+ * Error thrown when configuration operations fail.
+ */
+export class ConfigError extends Error {
+    /** The configuration key that caused the error */
+    key;
+    constructor(key, message) {
+        super(message);
+        this.name = 'ConfigError';
+        this.key = key;
+        Object.setPrototypeOf(this, ConfigError.prototype);
+    }
+}
+/**
+ * Error thrown when key-value storage operations fail.
+ */
+export class KVError extends Error {
+    /** The key that caused the error */
+    key;
+    /** The bucket where the error occurred */
+    bucket;
+    /** The error code from the host */
+    code;
+    constructor(bucket, key, code, message) {
+        super(message);
+        this.name = 'KVError';
+        this.bucket = bucket;
+        this.key = key;
+        this.code = code;
+        Object.setPrototypeOf(this, KVError.prototype);
+    }
+}
+/**
+ * Error codes for key-value operations.
+ */
+export var KVErrorCode;
+(function (KVErrorCode) {
+    /** Key not found */
+    KVErrorCode["NotFound"] = "not_found";
+    /** Value too large */
+    KVErrorCode["ValueTooLarge"] = "value_too_large";
+    /** Storage quota exceeded */
+    KVErrorCode["QuotaExceeded"] = "quota_exceeded";
+    /** Key format invalid */
+    KVErrorCode["InvalidKey"] = "invalid_key";
+    /** Generic storage error */
+    KVErrorCode["Storage"] = "storage";
+})(KVErrorCode || (KVErrorCode = {}));
+/**
+ * Error thrown when secret operations fail.
+ */
+export class SecretError extends Error {
+    /** The secret name that caused the error */
+    secretName;
+    constructor(secretName, message) {
+        super(message);
+        this.name = 'SecretError';
+        this.secretName = secretName;
+        Object.setPrototypeOf(this, SecretError.prototype);
+    }
+}
+/**
+ * Error thrown when a required value is missing.
+ */
+export class NotFoundError extends Error {
+    /** The identifier that was not found */
+    identifier;
+    constructor(identifier, message) {
+        super(message);
+        this.name = 'NotFoundError';
+        this.identifier = identifier;
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+    }
+}
+// =============================================================================
+// Log Level Enum
+// =============================================================================
+/**
+ * Log severity levels matching the WIT interface.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    /** Finest-grained debugging information */
+    LogLevel[LogLevel["Trace"] = 0] = "Trace";
+    /** Debugging information */
+    LogLevel[LogLevel["Debug"] = 1] = "Debug";
+    /** Informational messages */
+    LogLevel[LogLevel["Info"] = 2] = "Info";
+    /** Warning messages */
+    LogLevel[LogLevel["Warn"] = 3] = "Warn";
+    /** Error messages */
+    LogLevel[LogLevel["Error"] = 4] = "Error";
+})(LogLevel || (LogLevel = {}));
+/**
+ * HTTP methods supported by the plugin system.
+ */
+export var HttpMethod;
+(function (HttpMethod) {
+    HttpMethod["Get"] = "GET";
+    HttpMethod["Post"] = "POST";
+    HttpMethod["Put"] = "PUT";
+    HttpMethod["Delete"] = "DELETE";
+    HttpMethod["Patch"] = "PATCH";
+    HttpMethod["Head"] = "HEAD";
+    HttpMethod["Options"] = "OPTIONS";
+    HttpMethod["Connect"] = "CONNECT";
+    HttpMethod["Trace"] = "TRACE";
+})(HttpMethod || (HttpMethod = {}));
+// =============================================================================
+// Host Bindings Stub
+// =============================================================================
+/**
+ * Stub for host bindings. In actual WASM execution, these are replaced
+ * by the generated WIT bindings that call into the host.
+ */
+const hostBindings = {
+    config: {
+        get: (_key) => {
+            throw new Error('Host bindings not available: config.get not implemented');
+        },
+        getRequired: (_key) => {
+            throw new Error('Host bindings not available: config.getRequired not implemented');
+        },
+        getMany: (_keys) => {
+            throw new Error('Host bindings not available: config.getMany not implemented');
+        },
+        getPrefix: (_prefix) => {
+            throw new Error('Host bindings not available: config.getPrefix not implemented');
+        },
+        exists: (_key) => {
+            throw new Error('Host bindings not available: config.exists not implemented');
+        },
+        getBool: (_key) => {
+            throw new Error('Host bindings not available: config.getBool not implemented');
+        },
+        getInt: (_key) => {
+            throw new Error('Host bindings not available: config.getInt not implemented');
+        },
+        getFloat: (_key) => {
+            throw new Error('Host bindings not available: config.getFloat not implemented');
+        },
+    },
+    keyvalue: {
+        get: (_key) => {
+            throw new Error('Host bindings not available: keyvalue.get not implemented');
+        },
+        getString: (_key) => {
+            throw new Error('Host bindings not available: keyvalue.getString not implemented');
+        },
+        set: (_key, _value) => {
+            throw new Error('Host bindings not available: keyvalue.set not implemented');
+        },
+        setString: (_key, _value) => {
+            throw new Error('Host bindings not available: keyvalue.setString not implemented');
+        },
+        setWithTtl: (_key, _value, _ttl) => {
+            throw new Error('Host bindings not available: keyvalue.setWithTtl not implemented');
+        },
+        delete: (_key) => {
+            throw new Error('Host bindings not available: keyvalue.delete not implemented');
+        },
+        exists: (_key) => {
+            throw new Error('Host bindings not available: keyvalue.exists not implemented');
+        },
+        listKeys: (_prefix) => {
+            throw new Error('Host bindings not available: keyvalue.listKeys not implemented');
+        },
+        increment: (_key, _delta) => {
+            throw new Error('Host bindings not available: keyvalue.increment not implemented');
+        },
+        compareAndSwap: (_key, _expected, _newValue) => {
+            throw new Error('Host bindings not available: keyvalue.compareAndSwap not implemented');
+        },
+    },
+    logging: {
+        log: (_level, _message) => {
+            throw new Error('Host bindings not available: logging.log not implemented');
+        },
+        logStructured: (_level, _message, _fields) => {
+            throw new Error('Host bindings not available: logging.logStructured not implemented');
+        },
+        trace: (_message) => {
+            throw new Error('Host bindings not available: logging.trace not implemented');
+        },
+        debug: (_message) => {
+            throw new Error('Host bindings not available: logging.debug not implemented');
+        },
+        info: (_message) => {
+            throw new Error('Host bindings not available: logging.info not implemented');
+        },
+        warn: (_message) => {
+            throw new Error('Host bindings not available: logging.warn not implemented');
+        },
+        error: (_message) => {
+            throw new Error('Host bindings not available: logging.error not implemented');
+        },
+        isEnabled: (_level) => {
+            throw new Error('Host bindings not available: logging.isEnabled not implemented');
+        },
+    },
+    secrets: {
+        get: (_name) => {
+            throw new Error('Host bindings not available: secrets.get not implemented');
+        },
+        getRequired: (_name) => {
+            throw new Error('Host bindings not available: secrets.getRequired not implemented');
+        },
+        exists: (_name) => {
+            throw new Error('Host bindings not available: secrets.exists not implemented');
+        },
+        listNames: () => {
+            throw new Error('Host bindings not available: secrets.listNames not implemented');
+        },
+    },
+    metrics: {
+        counterInc: (_name, _value) => {
+            throw new Error('Host bindings not available: metrics.counterInc not implemented');
+        },
+        counterIncLabeled: (_name, _value, _labels) => {
+            throw new Error('Host bindings not available: metrics.counterIncLabeled not implemented');
+        },
+        gaugeSet: (_name, _value) => {
+            throw new Error('Host bindings not available: metrics.gaugeSet not implemented');
+        },
+        gaugeSetLabeled: (_name, _value, _labels) => {
+            throw new Error('Host bindings not available: metrics.gaugeSetLabeled not implemented');
+        },
+        gaugeAdd: (_name, _delta) => {
+            throw new Error('Host bindings not available: metrics.gaugeAdd not implemented');
+        },
+        histogramObserve: (_name, _value) => {
+            throw new Error('Host bindings not available: metrics.histogramObserve not implemented');
+        },
+        histogramObserveLabeled: (_name, _value, _labels) => {
+            throw new Error('Host bindings not available: metrics.histogramObserveLabeled not implemented');
+        },
+        recordDuration: (_name, _durationNs) => {
+            throw new Error('Host bindings not available: metrics.recordDuration not implemented');
+        },
+        recordDurationLabeled: (_name, _durationNs, _labels) => {
+            throw new Error('Host bindings not available: metrics.recordDurationLabeled not implemented');
+        },
+    },
+};
+// =============================================================================
+// Configuration Helpers
+// =============================================================================
+/**
+ * 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 function getConfig(key) {
+    return hostBindings.config.get(key);
+}
+/**
+ * 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 function getConfigRequired(key) {
+    const value = hostBindings.config.get(key);
+    if (value === undefined) {
+        throw new ConfigError(key, `Required configuration key '${key}' not found`);
+    }
+    return value;
+}
+/**
+ * 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 function getConfigBool(key) {
+    return hostBindings.config.getBool(key);
+}
+/**
+ * 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 function getConfigInt(key) {
+    const value = hostBindings.config.getInt(key);
+    if (value === undefined) {
+        return undefined;
+    }
+    return Number(value);
+}
+/**
+ * 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 function getConfigFloat(key) {
+    return hostBindings.config.getFloat(key);
+}
+/**
+ * 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 function getConfigMany(keys) {
+    const pairs = hostBindings.config.getMany(keys);
+    return new Map(pairs);
+}
+/**
+ * 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 function getConfigPrefix(prefix) {
+    const pairs = hostBindings.config.getPrefix(prefix);
+    return new Map(pairs);
+}
+/**
+ * Check if a configuration key exists.
+ *
+ * @param key - The configuration key to check
+ * @returns true if the key exists, false otherwise
+ */
+export function configExists(key) {
+    return hostBindings.config.exists(key);
+}
+/**
+ * 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 function getAllConfig() {
+    const pairs = hostBindings.config.getPrefix('');
+    const obj = {};
+    for (const [key, value] of pairs) {
+        obj[key] = value;
+    }
+    return JSON.stringify(obj);
+}
+// =============================================================================
+// Key-Value Storage Helpers
+// =============================================================================
+/**
+ * Construct a namespaced key from bucket and key.
+ *
+ * @param bucket - The bucket/namespace
+ * @param key - The key within the bucket
+ * @returns The full namespaced key
+ */
+function makeKey(bucket, key) {
+    return `${bucket}:${key}`;
+}
+/**
+ * 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 function kvGet(bucket, key) {
+    return hostBindings.keyvalue.get(makeKey(bucket, key));
+}
+/**
+ * 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 function kvGetString(bucket, key) {
+    return hostBindings.keyvalue.getString(makeKey(bucket, key));
+}
+/**
+ * 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 function kvGetJson(bucket, key) {
+    const value = kvGetString(bucket, key);
+    if (value === undefined) {
+        return undefined;
+    }
+    return JSON.parse(value);
+}
+/**
+ * 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 function kvSet(bucket, key, value) {
+    hostBindings.keyvalue.set(makeKey(bucket, key), value);
+}
+/**
+ * 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 function kvSetString(bucket, key, value) {
+    hostBindings.keyvalue.setString(makeKey(bucket, key), value);
+}
+/**
+ * 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 function kvSetJson(bucket, key, value) {
+    kvSetString(bucket, key, JSON.stringify(value));
+}
+/**
+ * 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 function kvSetWithTtl(bucket, key, value, ttlMs) {
+    const ttlNs = BigInt(ttlMs) * BigInt(1_000_000);
+    hostBindings.keyvalue.setWithTtl(makeKey(bucket, key), value, ttlNs);
+}
+/**
+ * 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 function kvSetStringWithTtl(bucket, key, value, ttlMs) {
+    const encoder = new TextEncoder();
+    kvSetWithTtl(bucket, key, encoder.encode(value), ttlMs);
+}
+/**
+ * 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 function kvDelete(bucket, key) {
+    return hostBindings.keyvalue.delete(makeKey(bucket, key));
+}
+/**
+ * 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 function kvKeys(bucket, prefix = '') {
+    const fullPrefix = makeKey(bucket, prefix);
+    const keys = hostBindings.keyvalue.listKeys(fullPrefix);
+    // Strip the bucket prefix from returned keys
+    const bucketPrefix = `${bucket}:`;
+    return keys.map((k) => k.startsWith(bucketPrefix) ? k.slice(bucketPrefix.length) : k);
+}
+/**
+ * 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 function kvExists(bucket, key) {
+    return hostBindings.keyvalue.exists(makeKey(bucket, key));
+}
+/**
+ * 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 function kvIncrement(bucket, key, delta = 1) {
+    return hostBindings.keyvalue.increment(makeKey(bucket, key), BigInt(delta));
+}
+/**
+ * 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 function kvCompareAndSwap(bucket, key, expected, newValue) {
+    return hostBindings.keyvalue.compareAndSwap(makeKey(bucket, key), expected, newValue);
+}
+// =============================================================================
+// Logging Helpers
+// =============================================================================
+/**
+ * Logging utilities for emitting structured logs to the host.
+ */
+export const log = {
+    /**
+     * Emit a trace-level log message.
+     * Use for finest-grained debugging information.
+     *
+     * @param msg - The log message
+     */
+    trace: (msg) => {
+        hostBindings.logging.trace(msg);
+    },
+    /**
+     * Emit a debug-level log message.
+     * Use for debugging information.
+     *
+     * @param msg - The log message
+     */
+    debug: (msg) => {
+        hostBindings.logging.debug(msg);
+    },
+    /**
+     * Emit an info-level log message.
+     * Use for informational messages about normal operation.
+     *
+     * @param msg - The log message
+     */
+    info: (msg) => {
+        hostBindings.logging.info(msg);
+    },
+    /**
+     * Emit a warn-level log message.
+     * Use for warning messages about potential issues.
+     *
+     * @param msg - The log message
+     */
+    warn: (msg) => {
+        hostBindings.logging.warn(msg);
+    },
+    /**
+     * Emit an error-level log message.
+     * Use for error messages.
+     *
+     * @param msg - The log message
+     */
+    error: (msg) => {
+        hostBindings.logging.error(msg);
+    },
+    /**
+     * Emit a log message at the specified level.
+     *
+     * @param level - The log level
+     * @param msg - The log message
+     */
+    log: (level, msg) => {
+        hostBindings.logging.log(level, msg);
+    },
+    /**
+     * 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, msg, fields) => {
+        const kvFields = Object.entries(fields).map(([key, value]) => ({
+            key,
+            value,
+        }));
+        hostBindings.logging.logStructured(level, msg, kvFields);
+    },
+    /**
+     * 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) => {
+        return hostBindings.logging.isEnabled(level);
+    },
+};
+// =============================================================================
+// Secrets Helpers
+// =============================================================================
+/**
+ * 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 function getSecret(name) {
+    return hostBindings.secrets.get(name);
+}
+/**
+ * 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 function getSecretRequired(name) {
+    const value = hostBindings.secrets.get(name);
+    if (value === undefined) {
+        throw new SecretError(name, `Required secret '${name}' not found`);
+    }
+    return value;
+}
+/**
+ * Check if a secret exists.
+ *
+ * @param name - The secret name
+ * @returns true if the secret exists, false otherwise
+ */
+export function secretExists(name) {
+    return hostBindings.secrets.exists(name);
+}
+/**
+ * List all available secret names (not values).
+ * Useful for diagnostics without exposing sensitive data.
+ *
+ * @returns Array of secret names
+ */
+export function listSecretNames() {
+    return hostBindings.secrets.listNames();
+}
+// =============================================================================
+// Metrics Helpers
+// =============================================================================
+/**
+ * Metrics utilities for emitting observability data to the host.
+ */
+export 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, value = 1) => {
+        hostBindings.metrics.counterInc(name, BigInt(value));
+    },
+    /**
+     * 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, value, labels) => {
+        const kvLabels = Object.entries(labels).map(([key, val]) => ({
+            key,
+            value: val,
+        }));
+        hostBindings.metrics.counterIncLabeled(name, BigInt(value), kvLabels);
+    },
+    /**
+     * 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, value) => {
+        hostBindings.metrics.gaugeSet(name, value);
+    },
+    /**
+     * Set a gauge metric with labels.
+     *
+     * @param name - The metric name
+     * @param value - The value to set
+     * @param labels - The metric labels
+     */
+    gaugeSetLabeled: (name, value, labels) => {
+        const kvLabels = Object.entries(labels).map(([key, val]) => ({
+            key,
+            value: val,
+        }));
+        hostBindings.metrics.gaugeSetLabeled(name, value, kvLabels);
+    },
+    /**
+     * Add to a gauge value (can be negative).
+     *
+     * @param name - The metric name
+     * @param delta - The amount to add (can be negative)
+     */
+    gaugeAdd: (name, delta) => {
+        hostBindings.metrics.gaugeAdd(name, delta);
+    },
+    /**
+     * 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, value) => {
+        hostBindings.metrics.histogramObserve(name, value);
+    },
+    /**
+     * Record a histogram observation with labels.
+     *
+     * @param name - The metric name
+     * @param value - The observed value
+     * @param labels - The metric labels
+     */
+    histogramObserveLabeled: (name, value, labels) => {
+        const kvLabels = Object.entries(labels).map(([key, val]) => ({
+            key,
+            value: val,
+        }));
+        hostBindings.metrics.histogramObserveLabeled(name, value, kvLabels);
+    },
+    /**
+     * Record request duration in milliseconds.
+     * Convenience method that converts to nanoseconds.
+     *
+     * @param name - The metric name
+     * @param durationMs - Duration in milliseconds
+     */
+    recordDuration: (name, durationMs) => {
+        const durationNs = BigInt(Math.floor(durationMs * 1_000_000));
+        hostBindings.metrics.recordDuration(name, durationNs);
+    },
+    /**
+     * Record request duration with labels.
+     *
+     * @param name - The metric name
+     * @param durationMs - Duration in milliseconds
+     * @param labels - The metric labels
+     */
+    recordDurationLabeled: (name, durationMs, labels) => {
+        const durationNs = BigInt(Math.floor(durationMs * 1_000_000));
+        const kvLabels = Object.entries(labels).map(([key, val]) => ({
+            key,
+            value: val,
+        }));
+        hostBindings.metrics.recordDurationLabeled(name, durationNs, kvLabels);
+    },
+};
+// =============================================================================
+// Response Helpers
+// =============================================================================
+/**
+ * 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 function jsonResponse(data, status = 200, headers = {}) {
+    const body = JSON.stringify(data);
+    const encoder = new TextEncoder();
+    const responseHeaders = [
+        { key: 'Content-Type', value: 'application/json' },
+        ...Object.entries(headers).map(([key, value]) => ({ key, value })),
+    ];
+    return {
+        status,
+        headers: responseHeaders,
+        body: encoder.encode(body),
+    };
+}
+/**
+ * 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 function textResponse(text, status = 200, contentType = 'text/plain') {
+    const encoder = new TextEncoder();
+    return {
+        status,
+        headers: [{ key: 'Content-Type', value: contentType }],
+        body: encoder.encode(text),
+    };
+}
+/**
+ * Create an HTML response.
+ *
+ * @param html - The HTML content
+ * @param status - HTTP status code (default: 200)
+ * @returns A PluginResponse
+ */
+export function htmlResponse(html, status = 200) {
+    return textResponse(html, status, 'text/html; charset=utf-8');
+}
+/**
+ * Create a binary response.
+ *
+ * @param data - The binary data
+ * @param contentType - Content type
+ * @param status - HTTP status code (default: 200)
+ * @returns A PluginResponse
+ */
+export function binaryResponse(data, contentType, status = 200) {
+    return {
+        status,
+        headers: [{ key: 'Content-Type', value: contentType }],
+        body: data,
+    };
+}
+/**
+ * Create an error response.
+ *
+ * @param message - The error message
+ * @param status - HTTP status code (default: 500)
+ * @returns A HandleResult with error response
+ */
+export function errorResponse(message, status = 500) {
+    return {
+        type: 'response',
+        response: jsonResponse({ error: message }, status),
+    };
+}
+/**
+ * Create a redirect response.
+ *
+ * @param location - The URL to redirect to
+ * @param status - HTTP status code (default: 302)
+ * @returns A PluginResponse
+ */
+export function redirectResponse(location, status = 302) {
+    return {
+        status,
+        headers: [{ key: 'Location', value: location }],
+        body: new Uint8Array(0),
+    };
+}
+/**
+ * Create a pass-through result.
+ * Use this when the plugin doesn't want to handle the request.
+ *
+ * @returns A HandleResult indicating pass-through
+ */
+export function passThrough() {
+    return { type: 'passThrough' };
+}
+// =============================================================================
+// Request Helpers
+// =============================================================================
+/**
+ * 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 function getHeader(request, name) {
+    const lowerName = name.toLowerCase();
+    const header = request.headers.find((h) => h.key.toLowerCase() === lowerName);
+    return header?.value;
+}
+/**
+ * Get all values for a header (case-insensitive).
+ *
+ * @param request - The plugin request
+ * @param name - The header name
+ * @returns Array of header values
+ */
+export function getHeaders(request, name) {
+    const lowerName = name.toLowerCase();
+    return request.headers
+        .filter((h) => h.key.toLowerCase() === lowerName)
+        .map((h) => h.value);
+}
+/**
+ * Parse the request body as JSON.
+ *
+ * @param request - The plugin request
+ * @returns The parsed JSON body
+ */
+export function parseJsonBody(request) {
+    const decoder = new TextDecoder();
+    const text = decoder.decode(request.body);
+    return JSON.parse(text);
+}
+/**
+ * Get the request body as a string.
+ *
+ * @param request - The plugin request
+ * @returns The body as a string
+ */
+export function getBodyString(request) {
+    const decoder = new TextDecoder();
+    return decoder.decode(request.body);
+}
+/**
+ * Parse query string into a Map.
+ *
+ * @param request - The plugin request
+ * @returns Map of query parameters
+ */
+export function parseQuery(request) {
+    const params = new Map();
+    if (!request.query) {
+        return params;
+    }
+    const pairs = request.query.split('&');
+    for (const pair of pairs) {
+        const [key, value] = pair.split('=');
+        if (key) {
+            params.set(decodeURIComponent(key), decodeURIComponent(value ?? ''));
+        }
+    }
+    return params;
+}
+/**
+ * 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 function getContext(request, key) {
+    const ctx = request.context.find((c) => c.key === key);
+    return ctx?.value;
+}
+// =============================================================================
+// Timing Helpers
+// =============================================================================
+/**
+ * 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 async function timed(name, fn) {
+    const start = Date.now();
+    try {
+        return await fn();
+    }
+    finally {
+        const duration = Date.now() - start;
+        metrics.recordDuration(name, duration);
+    }
+}
+/**
+ * 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 function timedSync(name, fn) {
+    const start = Date.now();
+    try {
+        return fn();
+    }
+    finally {
+        const duration = Date.now() - start;
+        metrics.recordDuration(name, duration);
+    }
+}
+// =============================================================================
+// Version Helpers
+// =============================================================================
+/**
+ * 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 function parseVersion(semver) {
+    const [versionPart, preRelease] = semver.split('-', 2);
+    const [major, minor, patch] = versionPart.split('.').map(Number);
+    return {
+        major: major ?? 0,
+        minor: minor ?? 0,
+        patch: patch ?? 0,
+        preRelease,
+    };
+}
+/**
+ * Format a Version object as a semver string.
+ *
+ * @param version - The Version object
+ * @returns The semver string
+ */
+export function formatVersion(version) {
+    const base = `${version.major}.${version.minor}.${version.patch}`;
+    return version.preRelease ? `${base}-${version.preRelease}` : base;
+}
+// =============================================================================
+// Plugin Registration Helper
+// =============================================================================
+/**
+ * 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 function registerPlugin(plugin) {
+    return plugin;
+}
+//# sourceMappingURL=index.js.map