@infinitetoken/lumber-kit 0.7.0 → 1.0.0

package/dist/index.d.mts

@@ -22,8 +22,10 @@ declare const LOG_KEY_VERSION = 1;
 /**
  * How a plugin delivers logs: one POST /logs per log, in the order they were logged. A network error or a 5xx is a
  * failed attempt, tried again after `baseDelayMs`, doubling up to `maxDelayMs`, and dropped after `maxAttempts`. Any
- * other 4xx is dropped at once, since sending it again won't help. A 429 (the team's logs for the month are used up)
- * drops what's queued and every new log until its Retry-After, or for `pauseMs` when it has none.
+ * other 4xx (a 413 for a log over MAX_LOG_PAYLOAD_LENGTH among them) is dropped at once, since sending it again won't
+ * help. Any 2xx is sent, including the 200 the API answers when it drops a log below ERROR past the team's monthly
+ * logs (monthlyLogsCap). A 429 (the team is at its hard stop, twice its plan's monthly logs) drops what's queued and
+ * every new log until its Retry-After, or for `pauseMs` when it has none.
  */
 declare const logDelivery: {
     readonly maxAttempts: 5;
@@ -31,6 +33,12 @@ declare const logDelivery: {
     readonly maxDelayMs: 30000;
     readonly pauseMs: number;
 };
+/**
+ * The longest `encrypted.payload` POST /logs takes, in characters: 16 KB of base64, about 12 KB of log as written (its
+ * message, context and metadata). A longer one is refused with a 413, which a plugin drops at once with a warning
+ * (Jay, 2026-11-13). The server can only measure the ciphertext.
+ */
+declare const MAX_LOG_PAYLOAD_LENGTH: number;
 
 /** Log severity level. Numeric values match the existing Lumber-API level field. */
 declare const enum LogLevel {
@@ -49,48 +57,6 @@ declare const logLevelNameToLevel: Record<LogLevelName, LogLevel>;
 /** All valid log levels, ordered from least to most severe. */
 declare const logLevels: readonly LogLevel[];
 
-/** A push threshold one past Fatal, which no log reaches: log pushes are off (the account's, or one app's). */
-declare const PUSH_OFF = 5;
-/** The lowest log level that pushes, or PUSH_OFF. Stored as a notification preference's `minimumLevel`. */
-type PushThreshold = LogLevel | typeof PUSH_OFF;
-/** The threshold a user gets when none is set. */
-declare const DEFAULT_PUSH_THRESHOLD: PushThreshold;
-
-/** User subscription level. Mirrors User.subscriptionLevel in Lumber-API. */
-declare const enum SubscriptionLevel {
-    Hobby = 0,
-    Dev = 1,
-    Pro = 2,
-    Enterprise = 3
-}
-/** String name for each subscription level, suitable for display and Redux state. */
-type SubscriptionLevelName = 'hobby' | 'dev' | 'pro' | 'enterprise';
-/** Maps numeric subscription level to its string level name. */
-declare const subscriptionLevelToName: Record<SubscriptionLevel, SubscriptionLevelName>;
-/** All valid subscription levels, ordered from least to most severe. */
-declare const subscriptionLevels: readonly SubscriptionLevel[];
-type SubscriptionLimits = {
-    apps: number;
-    seats: number;
-    apiKeys: number;
-    logRetentionDays: number;
-    monthlyLogs: number;
-    /** Whether real-time WebSocket log streaming is available. */
-    realtimeLogs: boolean;
-    /** Minimum log level that triggers a push notification. Infinity means push is disabled. */
-    minPushLevel: number;
-};
-/** Per-level resource limits. Use Infinity to mean unlimited or disabled. */
-declare const subscriptionLimits: Record<SubscriptionLevel, SubscriptionLimits>;
-type SubscriptionPlan = {
-    /** Display name, as every surface shows it. */
-    name: string;
-    /** Monthly price in US dollars: 0 for free, null when priced per customer. */
-    monthlyPrice: number | null;
-};
-/** Each level's name and price. Stripe holds the prices themselves; these must match what it charges. */
-declare const subscriptionPlans: Record<SubscriptionLevel, SubscriptionPlan>;
-
 /**
  * An organization that owns apps and pays for member usage.
  * Team subscriptionLevel takes precedence over individual member levels.
@@ -177,8 +143,16 @@ interface AppRecord {
     teamAccess?: AppTeamAccess;
     /** How many days of its logs the app's team's plan keeps, null for no limit (and when missing). */
     retentionDays?: number | null;
-    /** While the team has sent its plan's monthly logs, when new ones are taken again (the next UTC month); else null. */
+    /**
+     * While the team has sent its plan's monthly logs, when every level is taken again (the next UTC month); else null.
+     * Until then only ERROR and FATAL are taken (monthlyLogsCap).
+     */
     logsCappedUntil?: string | null;
+    /**
+     * While the team is at its hard stop (twice its plan's monthly logs, monthlyLogsCap), when any log is taken again
+     * (the next UTC month); else null. Set only alongside logsCappedUntil.
+     */
+    logsStoppedUntil?: string | null;
 }
 /**
  * App creation response.
@@ -588,7 +562,10 @@ interface ResponseMetadata {
     cursor?: string | null;
     hasMore?: boolean;
     count?: number;
-    hiddenCount?: number;
+    /** POST /logs past the team's monthly logs: how many logs it dropped (1), below ERROR (monthlyLogsCap). */
+    dropped?: number;
+    /** With `dropped`: when every level is taken again (the next UTC month), an ISO time. */
+    cappedUntil?: string;
 }
 interface ApiResponse<T> {
     data: T;
@@ -667,6 +644,18 @@ interface LogTimeseriesQuery {
 }
 
 type Appearance = 'system' | 'dark' | 'light';
+/** A 24-hour clock (`19:15:44`) or a 12-hour one (`7:15:44 PM`). */
+type TimeClock = '24h' | '12h';
+/** The device's own time zone, or UTC. */
+type TimeZoneChoice = 'local' | 'utc';
+/**
+ * How a user reads times, on every device: the clock, and the zone that times, days and hours are in (the log list, the
+ * heatmap, pushes).
+ */
+interface TimeFormat {
+    clock: TimeClock;
+    zone: TimeZoneChoice;
+}
 interface PushToken {
     token: string;
     deviceId?: string;
@@ -701,6 +690,8 @@ interface UserRecord {
     appearance?: Appearance;
     color?: string;
     imageUrl?: string;
+    /** Null until the user picks one (DEFAULT_TIME_FORMAT). Missing from an API before it was kept. */
+    timeFormat?: TimeFormat | null;
     agreedToTermsVersion?: string;
     notificationPreferences: NotificationPreferences;
     pushTokens: PushToken[];
@@ -710,6 +701,62 @@ interface UserRecord {
     notesReadAt?: Record<string, string>;
 }
 
+/** A push threshold one past Fatal, which no log reaches: log pushes are off (the account's, or one app's). */
+declare const PUSH_OFF = 5;
+/** The lowest log level that pushes, or PUSH_OFF. Stored as a notification preference's `minimumLevel`. */
+type PushThreshold = LogLevel | typeof PUSH_OFF;
+/** The threshold a user gets when none is set. */
+declare const DEFAULT_PUSH_THRESHOLD: PushThreshold;
+/** The time format a user gets until they pick one: 24-hour, in the device's own time zone. */
+declare const DEFAULT_TIME_FORMAT: TimeFormat;
+
+/** User subscription level. Mirrors User.subscriptionLevel in Lumber-API. */
+declare const enum SubscriptionLevel {
+    Hobby = 0,
+    Dev = 1,
+    Pro = 2,
+    Enterprise = 3
+}
+/** String name for each subscription level, suitable for display and Redux state. */
+type SubscriptionLevelName = 'hobby' | 'dev' | 'pro' | 'enterprise';
+/** Maps numeric subscription level to its string level name. */
+declare const subscriptionLevelToName: Record<SubscriptionLevel, SubscriptionLevelName>;
+/** All valid subscription levels, ordered from least to most severe. */
+declare const subscriptionLevels: readonly SubscriptionLevel[];
+type SubscriptionLimits = {
+    apps: number;
+    seats: number;
+    apiKeys: number;
+    logRetentionDays: number;
+    monthlyLogs: number;
+    /** Whether real-time WebSocket log streaming is available. */
+    realtimeLogs: boolean;
+    /** Minimum log level that triggers a push notification. Infinity means push is disabled. */
+    minPushLevel: number;
+};
+/** Per-level resource limits. Use Infinity to mean unlimited or disabled. */
+declare const subscriptionLimits: Record<SubscriptionLevel, SubscriptionLimits>;
+/**
+ * What happens past a team's monthly logs (Jay, 2026-11-13: errors always get through). Past its plan's monthlyLogs,
+ * POST /logs still takes ERROR and FATAL and drops lower levels, answering a dropped log 200 with `metadata.dropped`
+ * so a plugin carries on, until `hardStopMultiple` times monthlyLogs, when it refuses every log with a 429 until the
+ * next UTC month. Only the logs it takes count in usage, so the hard stop measures what every device holds.
+ */
+declare const monthlyLogsCap: {
+    /** The lowest level still taken past the cap. */
+    readonly minLevelPastCap: LogLevel.Error;
+    /** Where every log is refused, as a multiple of the plan's monthlyLogs. */
+    readonly hardStopMultiple: 2;
+};
+type SubscriptionPlan = {
+    /** Display name, as every surface shows it. */
+    name: string;
+    /** Monthly price in US dollars: 0 for free, null when priced per customer. */
+    monthlyPrice: number | null;
+};
+/** Each level's name and price. Stripe holds the prices themselves; these must match what it charges. */
+declare const subscriptionPlans: Record<SubscriptionLevel, SubscriptionPlan>;
+
 /**
  * The plaintext a plugin encrypts for one log call: its level and message, requestId and traceId when given, the
  * plugin's automatic context (pid, hostname and the like) with the call's context over it, and the call's other keys
@@ -719,14 +766,19 @@ interface UserRecord {
  */
 declare const buildLogPayload: (level: LogLevel, message: string, data?: LogData, autoContext?: Record<string, unknown>) => LogPayload;
 /**
- * What to do with a log once POST /logs answers with `status`, or null for no answer (a network error): sent on a 2xx,
- * pause on a 429, drop on any other 4xx, and retry on anything else.
+ * What to do with a log once POST /logs answers with `status`, or null for no answer (a network error): sent on a 2xx
+ * (the API's 200 for a log it dropped past the monthly cap too), pause on a 429, drop on any other 4xx, and retry on
+ * anything else.
  */
 declare const logDeliveryOutcome: (status: number | null) => LogDeliveryOutcome;
 /** How long to wait before trying a log again after its `failedAttempts`th failure: 1s, 2s, 4s and so on, up to 30s. */
 declare const logRetryDelayMs: (failedAttempts: number) => number;
 
 declare const isValidAppearance: (value: unknown) => value is Appearance;
+/** A time format as sent or stored: an object with a known clock and zone, and nothing else. */
+declare const isValidTimeFormat: (value: unknown) => value is TimeFormat;
+/** A stored or sent time format, each part the default (DEFAULT_TIME_FORMAT) when it's missing or unknown. */
+declare const normalizeTimeFormat: (value: unknown) => TimeFormat;
 /** Accepts 3- and 6-digit hex color strings (#rgb, #rrggbb). */
 declare const isValidColor: (value: string) => boolean;
 /**
@@ -766,4 +818,5 @@ declare const apiErrorCodeOf: (body: unknown) => ApiErrorCode | null;
 /** A push notification's data as PushData, or null for data no Lumber push sends. */
 declare const parsePushData: (data: unknown) => PushData | null;
 
-export { APP_COLORS, type ApiErrorBody, type ApiErrorCode, type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppKeyUpsertBody, type AppPermission, type AppPersonRecord, type AppRecord, type AppTeamAccess, type Appearance, type AppsQuery, type ClaimantKeyCheck, type ClientToServerEvents, DEFAULT_ACCENT, DEFAULT_API_ENDPOINT, DEFAULT_PUSH_THRESHOLD, type DeviceLinkApproveBody, type DeviceLinkCreateBody, type DeviceLinkCreatedRecord, type DeviceLinkPlatform, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, type HolderKeyCheck, type InvitationRecord, type KeyCheckResult, type KeyHolder, type KeyPin, LOG_KEY_VERSION, type LogContext, type LogData, type LogDeliveryOutcome, type LogEncrypted, type LogIngestBody, LogLevel, type LogLevelName, type LogPayload, type LogRecord, type LogTimeseriesQuery, type LogsQuery, type NoteEncrypted, type NoteRecord, type NotesQuery, type NotificationPreference, type NotificationPreferences, PUSH_OFF, type PendingAppKey, type PendingDeviceLink, type PushData, type PushThreshold, type PushToken, type PushType, type ResponseMetadata, type ServerToClientEvents, type SocketAppPayload, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type SubscriptionPlan, type SubscriptionPlanRecord, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, buildLogPayload, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logDelivery, logDeliveryOutcome, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, logRetryDelayMs, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+export { APP_COLORS, DEFAULT_ACCENT, DEFAULT_API_ENDPOINT, DEFAULT_PUSH_THRESHOLD, DEFAULT_TIME_FORMAT, LOG_KEY_VERSION, LogLevel, MAX_LOG_PAYLOAD_LENGTH, PUSH_OFF, SubscriptionLevel, apiErrorCodeOf, apiErrorCodes, buildLogPayload, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, isValidTimeFormat, joinApiKey, logDelivery, logDeliveryOutcome, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, logRetryDelayMs, monthlyLogsCap, nameColor, normalizePushThreshold, normalizeTimeFormat, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+export type { ApiErrorBody, ApiErrorCode, ApiKeyRecord, ApiResponse, AppCreatedRecord, AppEncryptedKey, AppKeyUpsertBody, AppPermission, AppPersonRecord, AppRecord, AppTeamAccess, Appearance, AppsQuery, ClaimantKeyCheck, ClientToServerEvents, DeviceLinkApproveBody, DeviceLinkCreateBody, DeviceLinkCreatedRecord, DeviceLinkPlatform, DeviceLinkRecord, DeviceLinkStatus, FlagRecord, FlagsQuery, GuestRecord, HolderKeyCheck, InvitationRecord, KeyCheckResult, KeyHolder, KeyPin, LogContext, LogData, LogDeliveryOutcome, LogEncrypted, LogIngestBody, LogLevelName, LogPayload, LogRecord, LogTimeseriesQuery, LogsQuery, NoteEncrypted, NoteRecord, NotesQuery, NotificationPreference, NotificationPreferences, PendingAppKey, PendingDeviceLink, PushData, PushThreshold, PushToken, PushType, ResponseMetadata, ServerToClientEvents, SocketAppPayload, SubscriptionLevelName, SubscriptionLimits, SubscriptionPlan, SubscriptionPlanRecord, TeamMemberRecord, TeamRecord, TeamsQuery, TimeClock, TimeFormat, TimeZoneChoice, TimeseriesBucket, TimeseriesResponse, UserRecord };

package/dist/index.d.ts

@@ -22,8 +22,10 @@ declare const LOG_KEY_VERSION = 1;
 /**
  * How a plugin delivers logs: one POST /logs per log, in the order they were logged. A network error or a 5xx is a
  * failed attempt, tried again after `baseDelayMs`, doubling up to `maxDelayMs`, and dropped after `maxAttempts`. Any
- * other 4xx is dropped at once, since sending it again won't help. A 429 (the team's logs for the month are used up)
- * drops what's queued and every new log until its Retry-After, or for `pauseMs` when it has none.
+ * other 4xx (a 413 for a log over MAX_LOG_PAYLOAD_LENGTH among them) is dropped at once, since sending it again won't
+ * help. Any 2xx is sent, including the 200 the API answers when it drops a log below ERROR past the team's monthly
+ * logs (monthlyLogsCap). A 429 (the team is at its hard stop, twice its plan's monthly logs) drops what's queued and
+ * every new log until its Retry-After, or for `pauseMs` when it has none.
  */
 declare const logDelivery: {
     readonly maxAttempts: 5;
@@ -31,6 +33,12 @@ declare const logDelivery: {
     readonly maxDelayMs: 30000;
     readonly pauseMs: number;
 };
+/**
+ * The longest `encrypted.payload` POST /logs takes, in characters: 16 KB of base64, about 12 KB of log as written (its
+ * message, context and metadata). A longer one is refused with a 413, which a plugin drops at once with a warning
+ * (Jay, 2026-11-13). The server can only measure the ciphertext.
+ */
+declare const MAX_LOG_PAYLOAD_LENGTH: number;
 
 /** Log severity level. Numeric values match the existing Lumber-API level field. */
 declare const enum LogLevel {
@@ -49,48 +57,6 @@ declare const logLevelNameToLevel: Record<LogLevelName, LogLevel>;
 /** All valid log levels, ordered from least to most severe. */
 declare const logLevels: readonly LogLevel[];
 
-/** A push threshold one past Fatal, which no log reaches: log pushes are off (the account's, or one app's). */
-declare const PUSH_OFF = 5;
-/** The lowest log level that pushes, or PUSH_OFF. Stored as a notification preference's `minimumLevel`. */
-type PushThreshold = LogLevel | typeof PUSH_OFF;
-/** The threshold a user gets when none is set. */
-declare const DEFAULT_PUSH_THRESHOLD: PushThreshold;
-
-/** User subscription level. Mirrors User.subscriptionLevel in Lumber-API. */
-declare const enum SubscriptionLevel {
-    Hobby = 0,
-    Dev = 1,
-    Pro = 2,
-    Enterprise = 3
-}
-/** String name for each subscription level, suitable for display and Redux state. */
-type SubscriptionLevelName = 'hobby' | 'dev' | 'pro' | 'enterprise';
-/** Maps numeric subscription level to its string level name. */
-declare const subscriptionLevelToName: Record<SubscriptionLevel, SubscriptionLevelName>;
-/** All valid subscription levels, ordered from least to most severe. */
-declare const subscriptionLevels: readonly SubscriptionLevel[];
-type SubscriptionLimits = {
-    apps: number;
-    seats: number;
-    apiKeys: number;
-    logRetentionDays: number;
-    monthlyLogs: number;
-    /** Whether real-time WebSocket log streaming is available. */
-    realtimeLogs: boolean;
-    /** Minimum log level that triggers a push notification. Infinity means push is disabled. */
-    minPushLevel: number;
-};
-/** Per-level resource limits. Use Infinity to mean unlimited or disabled. */
-declare const subscriptionLimits: Record<SubscriptionLevel, SubscriptionLimits>;
-type SubscriptionPlan = {
-    /** Display name, as every surface shows it. */
-    name: string;
-    /** Monthly price in US dollars: 0 for free, null when priced per customer. */
-    monthlyPrice: number | null;
-};
-/** Each level's name and price. Stripe holds the prices themselves; these must match what it charges. */
-declare const subscriptionPlans: Record<SubscriptionLevel, SubscriptionPlan>;
-
 /**
  * An organization that owns apps and pays for member usage.
  * Team subscriptionLevel takes precedence over individual member levels.
@@ -177,8 +143,16 @@ interface AppRecord {
     teamAccess?: AppTeamAccess;
     /** How many days of its logs the app's team's plan keeps, null for no limit (and when missing). */
     retentionDays?: number | null;
-    /** While the team has sent its plan's monthly logs, when new ones are taken again (the next UTC month); else null. */
+    /**
+     * While the team has sent its plan's monthly logs, when every level is taken again (the next UTC month); else null.
+     * Until then only ERROR and FATAL are taken (monthlyLogsCap).
+     */
     logsCappedUntil?: string | null;
+    /**
+     * While the team is at its hard stop (twice its plan's monthly logs, monthlyLogsCap), when any log is taken again
+     * (the next UTC month); else null. Set only alongside logsCappedUntil.
+     */
+    logsStoppedUntil?: string | null;
 }
 /**
  * App creation response.
@@ -588,7 +562,10 @@ interface ResponseMetadata {
     cursor?: string | null;
     hasMore?: boolean;
     count?: number;
-    hiddenCount?: number;
+    /** POST /logs past the team's monthly logs: how many logs it dropped (1), below ERROR (monthlyLogsCap). */
+    dropped?: number;
+    /** With `dropped`: when every level is taken again (the next UTC month), an ISO time. */
+    cappedUntil?: string;
 }
 interface ApiResponse<T> {
     data: T;
@@ -667,6 +644,18 @@ interface LogTimeseriesQuery {
 }
 
 type Appearance = 'system' | 'dark' | 'light';
+/** A 24-hour clock (`19:15:44`) or a 12-hour one (`7:15:44 PM`). */
+type TimeClock = '24h' | '12h';
+/** The device's own time zone, or UTC. */
+type TimeZoneChoice = 'local' | 'utc';
+/**
+ * How a user reads times, on every device: the clock, and the zone that times, days and hours are in (the log list, the
+ * heatmap, pushes).
+ */
+interface TimeFormat {
+    clock: TimeClock;
+    zone: TimeZoneChoice;
+}
 interface PushToken {
     token: string;
     deviceId?: string;
@@ -701,6 +690,8 @@ interface UserRecord {
     appearance?: Appearance;
     color?: string;
     imageUrl?: string;
+    /** Null until the user picks one (DEFAULT_TIME_FORMAT). Missing from an API before it was kept. */
+    timeFormat?: TimeFormat | null;
     agreedToTermsVersion?: string;
     notificationPreferences: NotificationPreferences;
     pushTokens: PushToken[];
@@ -710,6 +701,62 @@ interface UserRecord {
     notesReadAt?: Record<string, string>;
 }
 
+/** A push threshold one past Fatal, which no log reaches: log pushes are off (the account's, or one app's). */
+declare const PUSH_OFF = 5;
+/** The lowest log level that pushes, or PUSH_OFF. Stored as a notification preference's `minimumLevel`. */
+type PushThreshold = LogLevel | typeof PUSH_OFF;
+/** The threshold a user gets when none is set. */
+declare const DEFAULT_PUSH_THRESHOLD: PushThreshold;
+/** The time format a user gets until they pick one: 24-hour, in the device's own time zone. */
+declare const DEFAULT_TIME_FORMAT: TimeFormat;
+
+/** User subscription level. Mirrors User.subscriptionLevel in Lumber-API. */
+declare const enum SubscriptionLevel {
+    Hobby = 0,
+    Dev = 1,
+    Pro = 2,
+    Enterprise = 3
+}
+/** String name for each subscription level, suitable for display and Redux state. */
+type SubscriptionLevelName = 'hobby' | 'dev' | 'pro' | 'enterprise';
+/** Maps numeric subscription level to its string level name. */
+declare const subscriptionLevelToName: Record<SubscriptionLevel, SubscriptionLevelName>;
+/** All valid subscription levels, ordered from least to most severe. */
+declare const subscriptionLevels: readonly SubscriptionLevel[];
+type SubscriptionLimits = {
+    apps: number;
+    seats: number;
+    apiKeys: number;
+    logRetentionDays: number;
+    monthlyLogs: number;
+    /** Whether real-time WebSocket log streaming is available. */
+    realtimeLogs: boolean;
+    /** Minimum log level that triggers a push notification. Infinity means push is disabled. */
+    minPushLevel: number;
+};
+/** Per-level resource limits. Use Infinity to mean unlimited or disabled. */
+declare const subscriptionLimits: Record<SubscriptionLevel, SubscriptionLimits>;
+/**
+ * What happens past a team's monthly logs (Jay, 2026-11-13: errors always get through). Past its plan's monthlyLogs,
+ * POST /logs still takes ERROR and FATAL and drops lower levels, answering a dropped log 200 with `metadata.dropped`
+ * so a plugin carries on, until `hardStopMultiple` times monthlyLogs, when it refuses every log with a 429 until the
+ * next UTC month. Only the logs it takes count in usage, so the hard stop measures what every device holds.
+ */
+declare const monthlyLogsCap: {
+    /** The lowest level still taken past the cap. */
+    readonly minLevelPastCap: LogLevel.Error;
+    /** Where every log is refused, as a multiple of the plan's monthlyLogs. */
+    readonly hardStopMultiple: 2;
+};
+type SubscriptionPlan = {
+    /** Display name, as every surface shows it. */
+    name: string;
+    /** Monthly price in US dollars: 0 for free, null when priced per customer. */
+    monthlyPrice: number | null;
+};
+/** Each level's name and price. Stripe holds the prices themselves; these must match what it charges. */
+declare const subscriptionPlans: Record<SubscriptionLevel, SubscriptionPlan>;
+
 /**
  * The plaintext a plugin encrypts for one log call: its level and message, requestId and traceId when given, the
  * plugin's automatic context (pid, hostname and the like) with the call's context over it, and the call's other keys
@@ -719,14 +766,19 @@ interface UserRecord {
  */
 declare const buildLogPayload: (level: LogLevel, message: string, data?: LogData, autoContext?: Record<string, unknown>) => LogPayload;
 /**
- * What to do with a log once POST /logs answers with `status`, or null for no answer (a network error): sent on a 2xx,
- * pause on a 429, drop on any other 4xx, and retry on anything else.
+ * What to do with a log once POST /logs answers with `status`, or null for no answer (a network error): sent on a 2xx
+ * (the API's 200 for a log it dropped past the monthly cap too), pause on a 429, drop on any other 4xx, and retry on
+ * anything else.
  */
 declare const logDeliveryOutcome: (status: number | null) => LogDeliveryOutcome;
 /** How long to wait before trying a log again after its `failedAttempts`th failure: 1s, 2s, 4s and so on, up to 30s. */
 declare const logRetryDelayMs: (failedAttempts: number) => number;
 
 declare const isValidAppearance: (value: unknown) => value is Appearance;
+/** A time format as sent or stored: an object with a known clock and zone, and nothing else. */
+declare const isValidTimeFormat: (value: unknown) => value is TimeFormat;
+/** A stored or sent time format, each part the default (DEFAULT_TIME_FORMAT) when it's missing or unknown. */
+declare const normalizeTimeFormat: (value: unknown) => TimeFormat;
 /** Accepts 3- and 6-digit hex color strings (#rgb, #rrggbb). */
 declare const isValidColor: (value: string) => boolean;
 /**
@@ -766,4 +818,5 @@ declare const apiErrorCodeOf: (body: unknown) => ApiErrorCode | null;
 /** A push notification's data as PushData, or null for data no Lumber push sends. */
 declare const parsePushData: (data: unknown) => PushData | null;
 
-export { APP_COLORS, type ApiErrorBody, type ApiErrorCode, type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppKeyUpsertBody, type AppPermission, type AppPersonRecord, type AppRecord, type AppTeamAccess, type Appearance, type AppsQuery, type ClaimantKeyCheck, type ClientToServerEvents, DEFAULT_ACCENT, DEFAULT_API_ENDPOINT, DEFAULT_PUSH_THRESHOLD, type DeviceLinkApproveBody, type DeviceLinkCreateBody, type DeviceLinkCreatedRecord, type DeviceLinkPlatform, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, type HolderKeyCheck, type InvitationRecord, type KeyCheckResult, type KeyHolder, type KeyPin, LOG_KEY_VERSION, type LogContext, type LogData, type LogDeliveryOutcome, type LogEncrypted, type LogIngestBody, LogLevel, type LogLevelName, type LogPayload, type LogRecord, type LogTimeseriesQuery, type LogsQuery, type NoteEncrypted, type NoteRecord, type NotesQuery, type NotificationPreference, type NotificationPreferences, PUSH_OFF, type PendingAppKey, type PendingDeviceLink, type PushData, type PushThreshold, type PushToken, type PushType, type ResponseMetadata, type ServerToClientEvents, type SocketAppPayload, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type SubscriptionPlan, type SubscriptionPlanRecord, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, buildLogPayload, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logDelivery, logDeliveryOutcome, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, logRetryDelayMs, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+export { APP_COLORS, DEFAULT_ACCENT, DEFAULT_API_ENDPOINT, DEFAULT_PUSH_THRESHOLD, DEFAULT_TIME_FORMAT, LOG_KEY_VERSION, LogLevel, MAX_LOG_PAYLOAD_LENGTH, PUSH_OFF, SubscriptionLevel, apiErrorCodeOf, apiErrorCodes, buildLogPayload, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, isValidTimeFormat, joinApiKey, logDelivery, logDeliveryOutcome, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, logRetryDelayMs, monthlyLogsCap, nameColor, normalizePushThreshold, normalizeTimeFormat, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+export type { ApiErrorBody, ApiErrorCode, ApiKeyRecord, ApiResponse, AppCreatedRecord, AppEncryptedKey, AppKeyUpsertBody, AppPermission, AppPersonRecord, AppRecord, AppTeamAccess, Appearance, AppsQuery, ClaimantKeyCheck, ClientToServerEvents, DeviceLinkApproveBody, DeviceLinkCreateBody, DeviceLinkCreatedRecord, DeviceLinkPlatform, DeviceLinkRecord, DeviceLinkStatus, FlagRecord, FlagsQuery, GuestRecord, HolderKeyCheck, InvitationRecord, KeyCheckResult, KeyHolder, KeyPin, LogContext, LogData, LogDeliveryOutcome, LogEncrypted, LogIngestBody, LogLevelName, LogPayload, LogRecord, LogTimeseriesQuery, LogsQuery, NoteEncrypted, NoteRecord, NotesQuery, NotificationPreference, NotificationPreferences, PendingAppKey, PendingDeviceLink, PushData, PushThreshold, PushToken, PushType, ResponseMetadata, ServerToClientEvents, SocketAppPayload, SubscriptionLevelName, SubscriptionLimits, SubscriptionPlan, SubscriptionPlanRecord, TeamMemberRecord, TeamRecord, TeamsQuery, TimeClock, TimeFormat, TimeZoneChoice, TimeseriesBucket, TimeseriesResponse, UserRecord };

package/dist/index.js

@@ -24,8 +24,10 @@ __export(index_exports, {
   DEFAULT_ACCENT: () => DEFAULT_ACCENT,
   DEFAULT_API_ENDPOINT: () => DEFAULT_API_ENDPOINT,
   DEFAULT_PUSH_THRESHOLD: () => DEFAULT_PUSH_THRESHOLD,
+  DEFAULT_TIME_FORMAT: () => DEFAULT_TIME_FORMAT,
   LOG_KEY_VERSION: () => LOG_KEY_VERSION,
   LogLevel: () => LogLevel,
+  MAX_LOG_PAYLOAD_LENGTH: () => MAX_LOG_PAYLOAD_LENGTH,
   PUSH_OFF: () => PUSH_OFF,
   SubscriptionLevel: () => SubscriptionLevel,
   apiErrorCodeOf: () => apiErrorCodeOf,
@@ -39,6 +41,7 @@ __export(index_exports, {
   isValidLogLevel: () => isValidLogLevel,
   isValidSubscriptionLevel: () => isValidSubscriptionLevel,
   isValidTeamMemberRole: () => isValidTeamMemberRole,
+  isValidTimeFormat: () => isValidTimeFormat,
   joinApiKey: () => joinApiKey,
   logDelivery: () => logDelivery,
   logDeliveryOutcome: () => logDeliveryOutcome,
@@ -47,8 +50,10 @@ __export(index_exports, {
   logLevelToName: () => logLevelToName,
   logLevels: () => logLevels,
   logRetryDelayMs: () => logRetryDelayMs,
+  monthlyLogsCap: () => monthlyLogsCap,
   nameColor: () => nameColor,
   normalizePushThreshold: () => normalizePushThreshold,
+  normalizeTimeFormat: () => normalizeTimeFormat,
   parsePushData: () => parsePushData,
   personColor: () => personColor,
   resolveAppColor: () => resolveAppColor,
@@ -123,10 +128,12 @@ var logDelivery = {
   maxDelayMs: 3e4,
   pauseMs: 60 * 60 * 1e3
 };
+var MAX_LOG_PAYLOAD_LENGTH = 16 * 1024;
 
 // src/constants/notifications.ts
 var PUSH_OFF = 5;
 var DEFAULT_PUSH_THRESHOLD = 2 /* Warn */;
+var DEFAULT_TIME_FORMAT = { clock: "24h", zone: "local" };
 
 // src/constants/subscription.ts
 var SubscriptionLevel = /* @__PURE__ */ ((SubscriptionLevel3) => {
@@ -144,11 +151,17 @@ var subscriptionLevelToName = {
 };
 var subscriptionLevels = [0 /* Hobby */, 1 /* Dev */, 2 /* Pro */, 3 /* Enterprise */];
 var subscriptionLimits = {
-  [0 /* Hobby */]: { apps: 5, seats: 1, apiKeys: 1, logRetentionDays: 7, monthlyLogs: 1e4, realtimeLogs: false, minPushLevel: Infinity },
-  [1 /* Dev */]: { apps: 10, seats: 5, apiKeys: 5, logRetentionDays: 30, monthlyLogs: 25e4, realtimeLogs: true, minPushLevel: 3 /* Error */ },
+  [0 /* Hobby */]: { apps: 5, seats: 1, apiKeys: 1, logRetentionDays: 7, monthlyLogs: 1e5, realtimeLogs: false, minPushLevel: 4 /* Fatal */ },
+  [1 /* Dev */]: { apps: 10, seats: 5, apiKeys: 5, logRetentionDays: 30, monthlyLogs: 5e5, realtimeLogs: true, minPushLevel: 3 /* Error */ },
   [2 /* Pro */]: { apps: 20, seats: 20, apiKeys: 15, logRetentionDays: 90, monthlyLogs: 2e6, realtimeLogs: true, minPushLevel: 2 /* Warn */ },
   [3 /* Enterprise */]: { apps: Infinity, seats: Infinity, apiKeys: Infinity, logRetentionDays: Infinity, monthlyLogs: Infinity, realtimeLogs: true, minPushLevel: 0 /* Debug */ }
 };
+var monthlyLogsCap = {
+  /** The lowest level still taken past the cap. */
+  minLevelPastCap: 3 /* Error */,
+  /** Where every log is refused, as a multiple of the plan's monthlyLogs. */
+  hardStopMultiple: 2
+};
 var subscriptionPlans = {
   [0 /* Hobby */]: { name: "Hobby", monthlyPrice: 0 },
   [1 /* Dev */]: { name: "Dev", monthlyPrice: 9 },
@@ -185,6 +198,17 @@ var logRetryDelayMs = (failedAttempts) => Math.min(logDelivery.baseDelayMs * 2 *
 // src/utils/index.ts
 var appearanceValues = ["system", "dark", "light"];
 var isValidAppearance = (value) => appearanceValues.includes(value);
+var timeClocks = ["24h", "12h"];
+var timeZoneChoices = ["local", "utc"];
+var isValidTimeFormat = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const { clock, zone, ...rest } = value;
+  return timeClocks.includes(clock) && timeZoneChoices.includes(zone) && Object.keys(rest).length === 0;
+};
+var normalizeTimeFormat = (value) => {
+  const { clock, zone } = value && typeof value === "object" ? value : {};
+  return { clock: timeClocks.includes(clock) ? clock : DEFAULT_TIME_FORMAT.clock, zone: timeZoneChoices.includes(zone) ? zone : DEFAULT_TIME_FORMAT.zone };
+};
 var isValidColor = (value) => /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value);
 var hashName = (name) => {
   let hash = 2166136261;
@@ -259,8 +283,10 @@ var parsePushData = (data) => {
   DEFAULT_ACCENT,
   DEFAULT_API_ENDPOINT,
   DEFAULT_PUSH_THRESHOLD,
+  DEFAULT_TIME_FORMAT,
   LOG_KEY_VERSION,
   LogLevel,
+  MAX_LOG_PAYLOAD_LENGTH,
   PUSH_OFF,
   SubscriptionLevel,
   apiErrorCodeOf,
@@ -274,6 +300,7 @@ var parsePushData = (data) => {
   isValidLogLevel,
   isValidSubscriptionLevel,
   isValidTeamMemberRole,
+  isValidTimeFormat,
   joinApiKey,
   logDelivery,
   logDeliveryOutcome,
@@ -282,8 +309,10 @@ var parsePushData = (data) => {
   logLevelToName,
   logLevels,
   logRetryDelayMs,
+  monthlyLogsCap,
   nameColor,
   normalizePushThreshold,
+  normalizeTimeFormat,
   parsePushData,
   personColor,
   resolveAppColor,

package/dist/index.mjs

@@ -61,10 +61,12 @@ var logDelivery = {
   maxDelayMs: 3e4,
   pauseMs: 60 * 60 * 1e3
 };
+var MAX_LOG_PAYLOAD_LENGTH = 16 * 1024;
 
 // src/constants/notifications.ts
 var PUSH_OFF = 5;
 var DEFAULT_PUSH_THRESHOLD = 2 /* Warn */;
+var DEFAULT_TIME_FORMAT = { clock: "24h", zone: "local" };
 
 // src/constants/subscription.ts
 var SubscriptionLevel = /* @__PURE__ */ ((SubscriptionLevel3) => {
@@ -82,11 +84,17 @@ var subscriptionLevelToName = {
 };
 var subscriptionLevels = [0 /* Hobby */, 1 /* Dev */, 2 /* Pro */, 3 /* Enterprise */];
 var subscriptionLimits = {
-  [0 /* Hobby */]: { apps: 5, seats: 1, apiKeys: 1, logRetentionDays: 7, monthlyLogs: 1e4, realtimeLogs: false, minPushLevel: Infinity },
-  [1 /* Dev */]: { apps: 10, seats: 5, apiKeys: 5, logRetentionDays: 30, monthlyLogs: 25e4, realtimeLogs: true, minPushLevel: 3 /* Error */ },
+  [0 /* Hobby */]: { apps: 5, seats: 1, apiKeys: 1, logRetentionDays: 7, monthlyLogs: 1e5, realtimeLogs: false, minPushLevel: 4 /* Fatal */ },
+  [1 /* Dev */]: { apps: 10, seats: 5, apiKeys: 5, logRetentionDays: 30, monthlyLogs: 5e5, realtimeLogs: true, minPushLevel: 3 /* Error */ },
   [2 /* Pro */]: { apps: 20, seats: 20, apiKeys: 15, logRetentionDays: 90, monthlyLogs: 2e6, realtimeLogs: true, minPushLevel: 2 /* Warn */ },
   [3 /* Enterprise */]: { apps: Infinity, seats: Infinity, apiKeys: Infinity, logRetentionDays: Infinity, monthlyLogs: Infinity, realtimeLogs: true, minPushLevel: 0 /* Debug */ }
 };
+var monthlyLogsCap = {
+  /** The lowest level still taken past the cap. */
+  minLevelPastCap: 3 /* Error */,
+  /** Where every log is refused, as a multiple of the plan's monthlyLogs. */
+  hardStopMultiple: 2
+};
 var subscriptionPlans = {
   [0 /* Hobby */]: { name: "Hobby", monthlyPrice: 0 },
   [1 /* Dev */]: { name: "Dev", monthlyPrice: 9 },
@@ -123,6 +131,17 @@ var logRetryDelayMs = (failedAttempts) => Math.min(logDelivery.baseDelayMs * 2 *
 // src/utils/index.ts
 var appearanceValues = ["system", "dark", "light"];
 var isValidAppearance = (value) => appearanceValues.includes(value);
+var timeClocks = ["24h", "12h"];
+var timeZoneChoices = ["local", "utc"];
+var isValidTimeFormat = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const { clock, zone, ...rest } = value;
+  return timeClocks.includes(clock) && timeZoneChoices.includes(zone) && Object.keys(rest).length === 0;
+};
+var normalizeTimeFormat = (value) => {
+  const { clock, zone } = value && typeof value === "object" ? value : {};
+  return { clock: timeClocks.includes(clock) ? clock : DEFAULT_TIME_FORMAT.clock, zone: timeZoneChoices.includes(zone) ? zone : DEFAULT_TIME_FORMAT.zone };
+};
 var isValidColor = (value) => /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value);
 var hashName = (name) => {
   let hash = 2166136261;
@@ -196,8 +215,10 @@ export {
   DEFAULT_ACCENT,
   DEFAULT_API_ENDPOINT,
   DEFAULT_PUSH_THRESHOLD,
+  DEFAULT_TIME_FORMAT,
   LOG_KEY_VERSION,
   LogLevel,
+  MAX_LOG_PAYLOAD_LENGTH,
   PUSH_OFF,
   SubscriptionLevel,
   apiErrorCodeOf,
@@ -211,6 +232,7 @@ export {
   isValidLogLevel,
   isValidSubscriptionLevel,
   isValidTeamMemberRole,
+  isValidTimeFormat,
   joinApiKey,
   logDelivery,
   logDeliveryOutcome,
@@ -219,8 +241,10 @@ export {
   logLevelToName,
   logLevels,
   logRetryDelayMs,
+  monthlyLogsCap,
   nameColor,
   normalizePushThreshold,
+  normalizeTimeFormat,
   parsePushData,
   personColor,
   resolveAppColor,