@rawnodes/logger 2.7.2 → 2.9.0

package/README.md

@@ -136,16 +136,57 @@ This is useful for sending only critical errors to alerting systems while keepin
 
 #### Level precedence
 
-When deciding whether to emit a log entry, the following order applies — **most specific wins**:
+Each transport decides on its own whether to emit a given log entry. The precedence depends on whether the transport **respects runtime overrides** (see the next section):
 
-1. **Global override** from `setLevelOverride(...)` or the top-level `level.rules` array
+**When respecting overrides** (observability transports — console/file/cloudwatch/relay by default):
+
+1. **Runtime override** from `setLevelOverride(...)` or the top-level `level.rules` array
 2. **Per-transport rule** (a matching entry in `console.rules` / `file.rules` / etc.)
 3. **Per-transport level** (`console.level`, `file.level`, …)
 4. **Global default level** (`level` or `level.default`)
 
-Practically: a matching `setLevelOverride({ userId: 123 }, 'debug')` will surface debug logs to **every** transport, even one whose own `level` is set to `info`. This is intentional — dynamic overrides are for targeted troubleshooting, and they wouldn't be useful if a downstream transport could silently swallow the messages they just enabled.
+**When ignoring overrides** (alert transports — discord/telegram/zohoCliq by default):
+
+1. **Per-transport rule**
+2. **Per-transport level**
+3. **Global default level**
+
+Practically: a matching `setLevelOverride({ userId: 123 }, 'debug')` will surface debug logs to **viewing** transports (console/cloudwatch/file), even if their own `level` is set to `info`. But the same override will **not** leak through notification channels (discord/telegram/zohoCliq) unless you explicitly opt them in via `respectRuntimeOverrides: true`.
+
+#### Transport roles (`respectRuntimeOverrides`)
+
+Every transport config accepts an optional `respectRuntimeOverrides?: boolean` flag. Defaults:
 
-If you need a transport to stay narrow while overrides are active, use `rules` on that transport (level 2), not the plain `level` field.
+| Transport    | Default | Role          |
+|--------------|---------|---------------|
+| `console`    | `true`  | observability |
+| `file`       | `true`  | observability |
+| `cloudwatch` | `true`  | observability |
+| `relay`      | `true`  | observability |
+| `discord`    | `false` | alert         |
+| `telegram`   | `false` | alert         |
+| `zohoCliq`   | `false` | alert         |
+
+The defaults reflect typical usage — console/file/cloudwatch are where operators look for logs during troubleshooting, while discord/telegram/zohoCliq are user-facing notification channels that should not get flooded by ad-hoc debug overrides. Override the default per-transport when needed:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  telegram: {
+    botToken: '...',
+    chatId: '...',
+    level: 'warn',
+    respectRuntimeOverrides: true,   // let overrides through (rare)
+  },
+  cloudwatch: {
+    logGroupName: '...',
+    level: 'info',
+    respectRuntimeOverrides: false,  // strict gate even under troubleshooting (also rare)
+    region: '...', accessKeyId: '...', secretAccessKey: '...',
+  },
+});
+```
 
 ### Per-Transport Rules
 

package/dist/index.d.mts

@@ -20,15 +20,34 @@ interface LevelRule {
     };
     level: LogLevel;
 }
+/**
+ * Controls whether a transport respects runtime level overrides registered via
+ * `setLevelOverride(...)` (or the top-level `level.rules` in the logger config).
+ *
+ * When `true` (the default for observability transports — console/file/cloudwatch/relay):
+ * a matching override bypasses the transport's own `level`/`rules` so that
+ * targeted troubleshooting actually surfaces logs in the viewing channels.
+ *
+ * When `false` (the default for alert-style transports — discord/telegram/zohoCliq):
+ * the transport filters strictly by its own `level`/`rules` and ignores runtime
+ * overrides, which prevents ad-hoc debug overrides from flooding user-facing
+ * notification channels.
+ *
+ * Every transport config accepts this flag; the only time it needs to be set
+ * explicitly is when overriding the default for the transport kind.
+ */
+type RespectRuntimeOverrides = boolean;
 interface ConsoleConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface FileConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     dirname: string;
     filename: string;
     datePattern?: string;
@@ -40,6 +59,7 @@ interface FileConfig {
 interface HttpTransportBaseConfig {
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     batchSize?: number;
     flushInterval?: number;
     maxRetries?: number;
@@ -104,6 +124,35 @@ interface TelegramConfig extends HttpTransportBaseConfig {
     threadId?: number;
     replyToMessageId?: number;
 }
+interface ZohoCliqBotConfig {
+    /** Bot display name (shown in the channel). */
+    name: string;
+    /** Optional bot avatar URL. */
+    image?: string;
+}
+interface ZohoCliqConfig extends HttpTransportBaseConfig {
+    /**
+     * Incoming webhook URL. If provided, `companyId`/`channel`/`region` are
+     * ignored and this URL is used as-is (with `zapikey` appended as query).
+     */
+    webhookUrl?: string;
+    /** Zoho Cliq company/org ID. Required unless `webhookUrl` is set. */
+    companyId?: string;
+    /** Target channel name (the `channelsbyname` API segment). Required unless `webhookUrl` is set. */
+    channel?: string;
+    /** Zoho region/TLD: 'eu' | 'com' | 'in' | etc. Default: 'eu'. */
+    region?: string;
+    /** Zoho API key (zapikey). Required. */
+    apiKey: string;
+    /** If true (default), message is posted as a broadcast so all members are notified. */
+    broadcast?: boolean;
+    /** Post as a custom bot instead of the default user. */
+    bot?: ZohoCliqBotConfig;
+    /** Include ISO timestamp in each formatted message. Default: true. */
+    includeTimestamp?: boolean;
+    /** Include meta as a fenced code block. Default: true. */
+    includeMeta?: boolean;
+}
 type LogStreamPattern = 'hostname' | 'hostname-date' | 'hostname-uuid' | 'date' | 'uuid';
 interface LogStreamPatternConfig {
     pattern: LogStreamPattern;
@@ -126,6 +175,8 @@ interface RelayConfig {
     reconnectDelay?: number;
     /** Max reconnect delay in ms (default: 30000) */
     maxReconnectDelay?: number;
+    /** See RespectRuntimeOverrides. Default: true (relay is an observability transport). */
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface CloudWatchConfig extends HttpTransportBaseConfig {
     logGroupName: string;
@@ -167,6 +218,7 @@ interface LoggerConfig {
     discord?: DiscordConfig | DiscordConfig[];
     telegram?: TelegramConfig | TelegramConfig[];
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[];
+    zohoCliq?: ZohoCliqConfig | ZohoCliqConfig[];
     /** Relay transport config — streams logs to a remote server via WebSocket (runs in worker thread) */
     relay?: RelayConfig;
     /** Enable caller info (file:line) in logs. Pass true for defaults or CallerConfig for options */
@@ -409,6 +461,18 @@ declare class CloudWatchTransport extends BaseHttpTransport {
     private isInvalidSequenceTokenError;
 }
 
+declare class ZohoCliqTransport extends BaseHttpTransport {
+    private config;
+    private endpoint;
+    private requestTimeout;
+    constructor(config: ZohoCliqConfig);
+    private buildEndpoint;
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private formatMessage;
+    private splitContent;
+    private post;
+}
+
 interface TimingResult {
     label: string;
     durationMs: number;
@@ -535,6 +599,36 @@ declare const LogStreamPatternConfigSchema: z.ZodType<LogStreamPatternConfig>;
 declare const LogStreamTemplateConfigSchema: z.ZodType<LogStreamTemplateConfig>;
 declare const LogStreamNameSchema: z.ZodType<LogStreamName>;
 declare const CloudWatchConfigSchema: z.ZodType<CloudWatchConfig>;
+declare const ZohoCliqConfigSchema: z.ZodObject<{
+    level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
+    rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+    respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+    flushInterval: z.ZodOptional<z.ZodNumber>;
+    maxRetries: z.ZodOptional<z.ZodNumber>;
+    retryDelay: z.ZodOptional<z.ZodNumber>;
+    onError: z.ZodType<HttpTransportBaseConfig["onError"]>;
+    onDrop: z.ZodType<HttpTransportBaseConfig["onDrop"]>;
+    maxQueueSize: z.ZodOptional<z.ZodNumber>;
+    dropPolicy: z.ZodOptional<z.ZodEnum<{
+        "drop-oldest": "drop-oldest";
+        "drop-newest": "drop-newest";
+    }>>;
+    requestTimeout: z.ZodOptional<z.ZodNumber>;
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    companyId: z.ZodOptional<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodString;
+    broadcast: z.ZodOptional<z.ZodBoolean>;
+    bot: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    includeTimestamp: z.ZodOptional<z.ZodBoolean>;
+    includeMeta: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const RelayConfigSchema: z.ZodType<RelayConfig>;
 declare const LevelConfigObjectSchema: z.ZodType<LevelConfigObject>;
 declare const LevelConfigSchema: z.ZodType<LevelConfig>;
 declare const CallerConfigSchema: z.ZodType<CallerConfig>;
@@ -546,6 +640,63 @@ declare const LoggerConfigSchema: z.ZodObject<{
     discord: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>, z.ZodArray<z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>>]>>;
     telegram: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>, z.ZodArray<z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>>]>>;
     cloudwatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>, z.ZodArray<z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>>]>>;
+    zohoCliq: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
+        rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+        respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
+        batchSize: z.ZodOptional<z.ZodNumber>;
+        flushInterval: z.ZodOptional<z.ZodNumber>;
+        maxRetries: z.ZodOptional<z.ZodNumber>;
+        retryDelay: z.ZodOptional<z.ZodNumber>;
+        onError: z.ZodType<HttpTransportBaseConfig["onError"]>;
+        onDrop: z.ZodType<HttpTransportBaseConfig["onDrop"]>;
+        maxQueueSize: z.ZodOptional<z.ZodNumber>;
+        dropPolicy: z.ZodOptional<z.ZodEnum<{
+            "drop-oldest": "drop-oldest";
+            "drop-newest": "drop-newest";
+        }>>;
+        requestTimeout: z.ZodOptional<z.ZodNumber>;
+        webhookUrl: z.ZodOptional<z.ZodString>;
+        companyId: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodString;
+        broadcast: z.ZodOptional<z.ZodBoolean>;
+        bot: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        includeTimestamp: z.ZodOptional<z.ZodBoolean>;
+        includeMeta: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+        level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
+        rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+        respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
+        batchSize: z.ZodOptional<z.ZodNumber>;
+        flushInterval: z.ZodOptional<z.ZodNumber>;
+        maxRetries: z.ZodOptional<z.ZodNumber>;
+        retryDelay: z.ZodOptional<z.ZodNumber>;
+        onError: z.ZodType<HttpTransportBaseConfig["onError"]>;
+        onDrop: z.ZodType<HttpTransportBaseConfig["onDrop"]>;
+        maxQueueSize: z.ZodOptional<z.ZodNumber>;
+        dropPolicy: z.ZodOptional<z.ZodEnum<{
+            "drop-oldest": "drop-oldest";
+            "drop-newest": "drop-newest";
+        }>>;
+        requestTimeout: z.ZodOptional<z.ZodNumber>;
+        webhookUrl: z.ZodOptional<z.ZodString>;
+        companyId: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodString;
+        broadcast: z.ZodOptional<z.ZodBoolean>;
+        bot: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        includeTimestamp: z.ZodOptional<z.ZodBoolean>;
+        includeMeta: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>]>>;
     relay: z.ZodOptional<z.ZodType<RelayConfig, unknown, z.core.$ZodTypeInternals<RelayConfig, unknown>>>;
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
@@ -559,10 +710,61 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     discord?: DiscordConfig | DiscordConfig[] | undefined;
     telegram?: TelegramConfig | TelegramConfig[] | undefined;
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[] | undefined;
+    zohoCliq?: {
+        onError: ((error: Error, droppedMessages: unknown[]) => void) | undefined;
+        onDrop: ((droppedMessages: unknown[]) => void) | undefined;
+        apiKey: string;
+        level?: "off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly" | undefined;
+        rules?: LevelRule[] | undefined;
+        respectRuntimeOverrides?: boolean | undefined;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+        maxRetries?: number | undefined;
+        retryDelay?: number | undefined;
+        maxQueueSize?: number | undefined;
+        dropPolicy?: "drop-oldest" | "drop-newest" | undefined;
+        requestTimeout?: number | undefined;
+        webhookUrl?: string | undefined;
+        companyId?: string | undefined;
+        channel?: string | undefined;
+        region?: string | undefined;
+        broadcast?: boolean | undefined;
+        bot?: {
+            name: string;
+            image?: string | undefined;
+        } | undefined;
+        includeTimestamp?: boolean | undefined;
+        includeMeta?: boolean | undefined;
+    } | {
+        onError: ((error: Error, droppedMessages: unknown[]) => void) | undefined;
+        onDrop: ((droppedMessages: unknown[]) => void) | undefined;
+        apiKey: string;
+        level?: "off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly" | undefined;
+        rules?: LevelRule[] | undefined;
+        respectRuntimeOverrides?: boolean | undefined;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+        maxRetries?: number | undefined;
+        retryDelay?: number | undefined;
+        maxQueueSize?: number | undefined;
+        dropPolicy?: "drop-oldest" | "drop-newest" | undefined;
+        requestTimeout?: number | undefined;
+        webhookUrl?: string | undefined;
+        companyId?: string | undefined;
+        channel?: string | undefined;
+        region?: string | undefined;
+        broadcast?: boolean | undefined;
+        bot?: {
+            name: string;
+            image?: string | undefined;
+        } | undefined;
+        includeTimestamp?: boolean | undefined;
+        includeMeta?: boolean | undefined;
+    }[] | undefined;
     relay?: RelayConfig | undefined;
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
     autoShutdown?: boolean | AutoShutdownConfig | undefined;
 }>;
 
-export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };
+export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RelayConfig, RelayConfigSchema, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, type ZohoCliqBotConfig, type ZohoCliqConfig, ZohoCliqConfigSchema, ZohoCliqTransport, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };

package/dist/index.d.ts

@@ -20,15 +20,34 @@ interface LevelRule {
     };
     level: LogLevel;
 }
+/**
+ * Controls whether a transport respects runtime level overrides registered via
+ * `setLevelOverride(...)` (or the top-level `level.rules` in the logger config).
+ *
+ * When `true` (the default for observability transports — console/file/cloudwatch/relay):
+ * a matching override bypasses the transport's own `level`/`rules` so that
+ * targeted troubleshooting actually surfaces logs in the viewing channels.
+ *
+ * When `false` (the default for alert-style transports — discord/telegram/zohoCliq):
+ * the transport filters strictly by its own `level`/`rules` and ignores runtime
+ * overrides, which prevents ad-hoc debug overrides from flooding user-facing
+ * notification channels.
+ *
+ * Every transport config accepts this flag; the only time it needs to be set
+ * explicitly is when overriding the default for the transport kind.
+ */
+type RespectRuntimeOverrides = boolean;
 interface ConsoleConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface FileConfig {
     format: LogFormat;
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     dirname: string;
     filename: string;
     datePattern?: string;
@@ -40,6 +59,7 @@ interface FileConfig {
 interface HttpTransportBaseConfig {
     level?: LogLevel;
     rules?: LevelRule[];
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
     batchSize?: number;
     flushInterval?: number;
     maxRetries?: number;
@@ -104,6 +124,35 @@ interface TelegramConfig extends HttpTransportBaseConfig {
     threadId?: number;
     replyToMessageId?: number;
 }
+interface ZohoCliqBotConfig {
+    /** Bot display name (shown in the channel). */
+    name: string;
+    /** Optional bot avatar URL. */
+    image?: string;
+}
+interface ZohoCliqConfig extends HttpTransportBaseConfig {
+    /**
+     * Incoming webhook URL. If provided, `companyId`/`channel`/`region` are
+     * ignored and this URL is used as-is (with `zapikey` appended as query).
+     */
+    webhookUrl?: string;
+    /** Zoho Cliq company/org ID. Required unless `webhookUrl` is set. */
+    companyId?: string;
+    /** Target channel name (the `channelsbyname` API segment). Required unless `webhookUrl` is set. */
+    channel?: string;
+    /** Zoho region/TLD: 'eu' | 'com' | 'in' | etc. Default: 'eu'. */
+    region?: string;
+    /** Zoho API key (zapikey). Required. */
+    apiKey: string;
+    /** If true (default), message is posted as a broadcast so all members are notified. */
+    broadcast?: boolean;
+    /** Post as a custom bot instead of the default user. */
+    bot?: ZohoCliqBotConfig;
+    /** Include ISO timestamp in each formatted message. Default: true. */
+    includeTimestamp?: boolean;
+    /** Include meta as a fenced code block. Default: true. */
+    includeMeta?: boolean;
+}
 type LogStreamPattern = 'hostname' | 'hostname-date' | 'hostname-uuid' | 'date' | 'uuid';
 interface LogStreamPatternConfig {
     pattern: LogStreamPattern;
@@ -126,6 +175,8 @@ interface RelayConfig {
     reconnectDelay?: number;
     /** Max reconnect delay in ms (default: 30000) */
     maxReconnectDelay?: number;
+    /** See RespectRuntimeOverrides. Default: true (relay is an observability transport). */
+    respectRuntimeOverrides?: RespectRuntimeOverrides;
 }
 interface CloudWatchConfig extends HttpTransportBaseConfig {
     logGroupName: string;
@@ -167,6 +218,7 @@ interface LoggerConfig {
     discord?: DiscordConfig | DiscordConfig[];
     telegram?: TelegramConfig | TelegramConfig[];
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[];
+    zohoCliq?: ZohoCliqConfig | ZohoCliqConfig[];
     /** Relay transport config — streams logs to a remote server via WebSocket (runs in worker thread) */
     relay?: RelayConfig;
     /** Enable caller info (file:line) in logs. Pass true for defaults or CallerConfig for options */
@@ -409,6 +461,18 @@ declare class CloudWatchTransport extends BaseHttpTransport {
     private isInvalidSequenceTokenError;
 }
 
+declare class ZohoCliqTransport extends BaseHttpTransport {
+    private config;
+    private endpoint;
+    private requestTimeout;
+    constructor(config: ZohoCliqConfig);
+    private buildEndpoint;
+    protected sendBatch(messages: BufferedMessage[]): Promise<void>;
+    private formatMessage;
+    private splitContent;
+    private post;
+}
+
 interface TimingResult {
     label: string;
     durationMs: number;
@@ -535,6 +599,36 @@ declare const LogStreamPatternConfigSchema: z.ZodType<LogStreamPatternConfig>;
 declare const LogStreamTemplateConfigSchema: z.ZodType<LogStreamTemplateConfig>;
 declare const LogStreamNameSchema: z.ZodType<LogStreamName>;
 declare const CloudWatchConfigSchema: z.ZodType<CloudWatchConfig>;
+declare const ZohoCliqConfigSchema: z.ZodObject<{
+    level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
+    rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+    respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+    flushInterval: z.ZodOptional<z.ZodNumber>;
+    maxRetries: z.ZodOptional<z.ZodNumber>;
+    retryDelay: z.ZodOptional<z.ZodNumber>;
+    onError: z.ZodType<HttpTransportBaseConfig["onError"]>;
+    onDrop: z.ZodType<HttpTransportBaseConfig["onDrop"]>;
+    maxQueueSize: z.ZodOptional<z.ZodNumber>;
+    dropPolicy: z.ZodOptional<z.ZodEnum<{
+        "drop-oldest": "drop-oldest";
+        "drop-newest": "drop-newest";
+    }>>;
+    requestTimeout: z.ZodOptional<z.ZodNumber>;
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    companyId: z.ZodOptional<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodString;
+    broadcast: z.ZodOptional<z.ZodBoolean>;
+    bot: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    includeTimestamp: z.ZodOptional<z.ZodBoolean>;
+    includeMeta: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const RelayConfigSchema: z.ZodType<RelayConfig>;
 declare const LevelConfigObjectSchema: z.ZodType<LevelConfigObject>;
 declare const LevelConfigSchema: z.ZodType<LevelConfig>;
 declare const CallerConfigSchema: z.ZodType<CallerConfig>;
@@ -546,6 +640,63 @@ declare const LoggerConfigSchema: z.ZodObject<{
     discord: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>, z.ZodArray<z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>>]>>;
     telegram: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>, z.ZodArray<z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>>]>>;
     cloudwatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>, z.ZodArray<z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>>]>>;
+    zohoCliq: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
+        rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+        respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
+        batchSize: z.ZodOptional<z.ZodNumber>;
+        flushInterval: z.ZodOptional<z.ZodNumber>;
+        maxRetries: z.ZodOptional<z.ZodNumber>;
+        retryDelay: z.ZodOptional<z.ZodNumber>;
+        onError: z.ZodType<HttpTransportBaseConfig["onError"]>;
+        onDrop: z.ZodType<HttpTransportBaseConfig["onDrop"]>;
+        maxQueueSize: z.ZodOptional<z.ZodNumber>;
+        dropPolicy: z.ZodOptional<z.ZodEnum<{
+            "drop-oldest": "drop-oldest";
+            "drop-newest": "drop-newest";
+        }>>;
+        requestTimeout: z.ZodOptional<z.ZodNumber>;
+        webhookUrl: z.ZodOptional<z.ZodString>;
+        companyId: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodString;
+        broadcast: z.ZodOptional<z.ZodBoolean>;
+        bot: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        includeTimestamp: z.ZodOptional<z.ZodBoolean>;
+        includeMeta: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+        level: z.ZodOptional<z.ZodType<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown, z.core.$ZodTypeInternals<"off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", unknown>>>;
+        rules: z.ZodOptional<z.ZodArray<z.ZodType<LevelRule, unknown, z.core.$ZodTypeInternals<LevelRule, unknown>>>>;
+        respectRuntimeOverrides: z.ZodOptional<z.ZodBoolean>;
+        batchSize: z.ZodOptional<z.ZodNumber>;
+        flushInterval: z.ZodOptional<z.ZodNumber>;
+        maxRetries: z.ZodOptional<z.ZodNumber>;
+        retryDelay: z.ZodOptional<z.ZodNumber>;
+        onError: z.ZodType<HttpTransportBaseConfig["onError"]>;
+        onDrop: z.ZodType<HttpTransportBaseConfig["onDrop"]>;
+        maxQueueSize: z.ZodOptional<z.ZodNumber>;
+        dropPolicy: z.ZodOptional<z.ZodEnum<{
+            "drop-oldest": "drop-oldest";
+            "drop-newest": "drop-newest";
+        }>>;
+        requestTimeout: z.ZodOptional<z.ZodNumber>;
+        webhookUrl: z.ZodOptional<z.ZodString>;
+        companyId: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodString;
+        broadcast: z.ZodOptional<z.ZodBoolean>;
+        bot: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        includeTimestamp: z.ZodOptional<z.ZodBoolean>;
+        includeMeta: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>]>>;
     relay: z.ZodOptional<z.ZodType<RelayConfig, unknown, z.core.$ZodTypeInternals<RelayConfig, unknown>>>;
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
@@ -559,10 +710,61 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     discord?: DiscordConfig | DiscordConfig[] | undefined;
     telegram?: TelegramConfig | TelegramConfig[] | undefined;
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[] | undefined;
+    zohoCliq?: {
+        onError: ((error: Error, droppedMessages: unknown[]) => void) | undefined;
+        onDrop: ((droppedMessages: unknown[]) => void) | undefined;
+        apiKey: string;
+        level?: "off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly" | undefined;
+        rules?: LevelRule[] | undefined;
+        respectRuntimeOverrides?: boolean | undefined;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+        maxRetries?: number | undefined;
+        retryDelay?: number | undefined;
+        maxQueueSize?: number | undefined;
+        dropPolicy?: "drop-oldest" | "drop-newest" | undefined;
+        requestTimeout?: number | undefined;
+        webhookUrl?: string | undefined;
+        companyId?: string | undefined;
+        channel?: string | undefined;
+        region?: string | undefined;
+        broadcast?: boolean | undefined;
+        bot?: {
+            name: string;
+            image?: string | undefined;
+        } | undefined;
+        includeTimestamp?: boolean | undefined;
+        includeMeta?: boolean | undefined;
+    } | {
+        onError: ((error: Error, droppedMessages: unknown[]) => void) | undefined;
+        onDrop: ((droppedMessages: unknown[]) => void) | undefined;
+        apiKey: string;
+        level?: "off" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly" | undefined;
+        rules?: LevelRule[] | undefined;
+        respectRuntimeOverrides?: boolean | undefined;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+        maxRetries?: number | undefined;
+        retryDelay?: number | undefined;
+        maxQueueSize?: number | undefined;
+        dropPolicy?: "drop-oldest" | "drop-newest" | undefined;
+        requestTimeout?: number | undefined;
+        webhookUrl?: string | undefined;
+        companyId?: string | undefined;
+        channel?: string | undefined;
+        region?: string | undefined;
+        broadcast?: boolean | undefined;
+        bot?: {
+            name: string;
+            image?: string | undefined;
+        } | undefined;
+        includeTimestamp?: boolean | undefined;
+        includeMeta?: boolean | undefined;
+    }[] | undefined;
     relay?: RelayConfig | undefined;
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
     autoShutdown?: boolean | AutoShutdownConfig | undefined;
 }>;
 
-export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };
+export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RelayConfig, RelayConfigSchema, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, type ZohoCliqBotConfig, type ZohoCliqConfig, ZohoCliqConfigSchema, ZohoCliqTransport, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };