@infinitetoken/lumber-kit 0.6.0 → 0.8.0

package/contract/vectors.json

@@ -0,0 +1,180 @@
+{
+  "$comment": "Known answers every Lumber plugin is tested against, whatever its language. Lumber-Kit's own tests check each one against its TypeScript (buildLogPayload, splitApiKey, logDeliveryOutcome, logRetryDelayMs, the constants) and Node's crypto, so these can't drift from the kit. An absent key means absent: JSON has no undefined, and null data values are left out like missing ones.",
+  "constants": {
+    "defaultEndpoint": "https://api.lumber.infinitetoken.com",
+    "ingestPath": "/logs",
+    "keyVersion": 1,
+    "keyBytes": 32,
+    "nonceBytes": 12,
+    "tagBytes": 16,
+    "levels": { "debug": 0, "info": 1, "warn": 2, "error": 3, "fatal": 4 },
+    "delivery": { "maxAttempts": 5, "baseDelayMs": 1000, "maxDelayMs": 30000, "pauseMs": 3600000 }
+  },
+  "apiKeys": [
+    {
+      "name": "token and encryption key",
+      "apiKey": "3f9c0e7a1b2d4c6e8f0a1b2c3d4e5f60.AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=",
+      "token": "3f9c0e7a1b2d4c6e8f0a1b2c3d4e5f60",
+      "encryptionKey": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
+    },
+    {
+      "name": "surrounding whitespace, as pasted from a terminal",
+      "apiKey": "  3f9c0e7a1b2d4c6e8f0a1b2c3d4e5f60.AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\n",
+      "token": "3f9c0e7a1b2d4c6e8f0a1b2c3d4e5f60",
+      "encryptionKey": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
+    },
+    {
+      "name": "a bare token carries no encryption key",
+      "apiKey": "3f9c0e7a1b2d4c6e8f0a1b2c3d4e5f60",
+      "token": "3f9c0e7a1b2d4c6e8f0a1b2c3d4e5f60",
+      "encryptionKey": null
+    },
+    {
+      "name": "empty",
+      "apiKey": "",
+      "token": "",
+      "encryptionKey": null
+    }
+  ],
+  "encryption": [
+    {
+      "name": "ascii",
+      "key": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=",
+      "nonce": "oKGio6Slpqeoqaqr",
+      "plaintext": "{\"level\":1,\"message\":\"Server started\",\"metadata\":{\"port\":3000}}",
+      "payload": "GJU0Lu4J1IGhob9mA32TqJ06EEgzrm6dWFSr8Wofs60RyzwyqJURCe54Q/Rf2AFgoAIim40OcVA66GWsaA7i231gZDgNom5ce207bpQN+A=="
+    },
+    {
+      "name": "non-ascii, encoded as utf-8",
+      "key": "QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkI=",
+      "nonce": "BwcHBwcHBwcHBwcH",
+      "plaintext": "{\"level\":3,\"message\":\"Paiement échoué ☕ 🚨\",\"context\":{\"pid\":4242,\"hostname\":\"web-1\"},\"metadata\":{\"user\":\"Zoë\"}}",
+      "payload": "bG1l/6IGl9vfE0wA1rhuEAPAMcnDlB7ZGWfAErA+VQ+UPWofx/cYJAkRUjZ0WTi3hotyvwFw3G2lbtCoKgD6/aRDnUpDt4kk+HF3FGk6VaEEt5fqiu28C5u9EifuYjd4Qh8KcSMdO9eeVWLqsg2eIpbV9qQQOtD1fMXktGfQmxTjmMtMZuKm"
+    },
+    {
+      "name": "empty message",
+      "key": "7qi7Ixae6epI48zxshkBw43xktBTaE/pwLxUoUhZ6e0=",
+      "nonce": "eDd7UldXtJRCf4kB",
+      "plaintext": "{\"level\":0,\"message\":\"\"}",
+      "payload": "M2E8vR0ITv6RfAwC3fDiMVIfWt3N9U6DEveRBpqxc/K49Py/HVQpMw=="
+    }
+  ],
+  "payloads": [
+    {
+      "name": "message alone",
+      "level": 1,
+      "message": "Server started",
+      "payload": { "level": 1, "message": "Server started" }
+    },
+    {
+      "name": "request and trace ids",
+      "level": 3,
+      "message": "Payment failed",
+      "data": { "requestId": "req-123", "traceId": "trace-abc" },
+      "payload": { "level": 3, "message": "Payment failed", "requestId": "req-123", "traceId": "trace-abc" }
+    },
+    {
+      "name": "other keys become metadata",
+      "level": 1,
+      "message": "User action",
+      "data": { "userId": "123", "action": "login", "order": { "id": 7, "total": 12.5, "items": ["a", "b"] } },
+      "payload": { "level": 1, "message": "User action", "metadata": { "userId": "123", "action": "login", "order": { "id": 7, "total": 12.5, "items": ["a", "b"] } } }
+    },
+    {
+      "name": "explicit metadata wins over other keys",
+      "level": 2,
+      "message": "Rate limit approaching",
+      "data": { "version": 1, "region": "us", "metadata": { "version": 2, "build": "b7" } },
+      "payload": { "level": 2, "message": "Rate limit approaching", "metadata": { "version": 2, "region": "us", "build": "b7" } }
+    },
+    {
+      "name": "metadata alone",
+      "level": 1,
+      "message": "Cache warmed",
+      "data": { "metadata": { "entries": 512 } },
+      "payload": { "level": 1, "message": "Cache warmed", "metadata": { "entries": 512 } }
+    },
+    {
+      "name": "automatic context alone",
+      "level": 0,
+      "message": "Cache miss",
+      "autoContext": { "pid": 4242, "hostname": "web-1" },
+      "payload": { "level": 0, "message": "Cache miss", "context": { "pid": 4242, "hostname": "web-1" } }
+    },
+    {
+      "name": "the call's context over the automatic context",
+      "level": 1,
+      "message": "Job done",
+      "autoContext": { "pid": 4242, "hostname": "web-1", "env": "production" },
+      "data": { "context": { "hostname": "worker-3", "code": "jobs/billing.py", "line": 42 } },
+      "payload": { "level": 1, "message": "Job done", "context": { "pid": 4242, "hostname": "worker-3", "env": "production", "code": "jobs/billing.py", "line": 42 } }
+    },
+    {
+      "name": "context with no automatic context",
+      "level": 1,
+      "message": "Job done",
+      "autoContext": {},
+      "data": { "context": { "code": "app.ts" } },
+      "payload": { "level": 1, "message": "Job done", "context": { "code": "app.ts" } }
+    },
+    {
+      "name": "a context that isn't an object is a metadata key",
+      "level": 1,
+      "message": "Invoice sent",
+      "data": { "context": "billing" },
+      "payload": { "level": 1, "message": "Invoice sent", "metadata": { "context": "billing" } }
+    },
+    {
+      "name": "metadata that isn't an object is a metadata key",
+      "level": 1,
+      "message": "Batch",
+      "data": { "metadata": [1, 2, 3] },
+      "payload": { "level": 1, "message": "Batch", "metadata": { "metadata": [1, 2, 3] } }
+    },
+    {
+      "name": "a null context and metadata are left out",
+      "level": 1,
+      "message": "Nothing extra",
+      "data": { "context": null, "metadata": null },
+      "payload": { "level": 1, "message": "Nothing extra" }
+    },
+    {
+      "name": "a level key in the data is metadata, never the log's level",
+      "level": 3,
+      "message": "Disk nearly full",
+      "data": { "level": "high", "message": "ignored" },
+      "payload": { "level": 3, "message": "Disk nearly full", "metadata": { "level": "high", "message": "ignored" } }
+    },
+    {
+      "name": "everything",
+      "level": 4,
+      "message": "DB connection lost ☠",
+      "autoContext": { "pid": 1, "hostname": "db-proxy" },
+      "data": { "requestId": "r1", "traceId": "t1", "context": { "method": "connect" }, "metadata": { "retries": 3 }, "host": "10.0.0.5" },
+      "payload": { "level": 4, "message": "DB connection lost ☠", "requestId": "r1", "traceId": "t1", "context": { "pid": 1, "hostname": "db-proxy", "method": "connect" }, "metadata": { "host": "10.0.0.5", "retries": 3 } }
+    }
+  ],
+  "deliveryOutcomes": [
+    { "status": 200, "outcome": "sent" },
+    { "status": 201, "outcome": "sent" },
+    { "status": 301, "outcome": "retry" },
+    { "status": 400, "outcome": "drop" },
+    { "status": 401, "outcome": "drop" },
+    { "status": 403, "outcome": "drop" },
+    { "status": 404, "outcome": "drop" },
+    { "status": 413, "outcome": "drop" },
+    { "status": 429, "outcome": "pause" },
+    { "status": 500, "outcome": "retry" },
+    { "status": 502, "outcome": "retry" },
+    { "status": 503, "outcome": "retry" },
+    { "status": null, "outcome": "retry" }
+  ],
+  "retryDelaysMs": [
+    { "failedAttempts": 1, "delayMs": 1000 },
+    { "failedAttempts": 2, "delayMs": 2000 },
+    { "failedAttempts": 3, "delayMs": 4000 },
+    { "failedAttempts": 4, "delayMs": 8000 },
+    { "failedAttempts": 5, "delayMs": 16000 },
+    { "failedAttempts": 6, "delayMs": 30000 }
+  ]
+}

package/dist/index.d.mts

@@ -15,6 +15,23 @@ declare const APP_COLORS: readonly ["#EF4444", "#F97316", "#F59E0B", "#84CC16",
 declare const apiErrorCodes: readonly ["APP_LIMIT", "SEAT_LIMIT", "GUEST_LIMIT", "ALREADY_MEMBER", "ALREADY_READS", "ALREADY_INVITED", "HAS_ACCOUNT"];
 type ApiErrorCode = (typeof apiErrorCodes)[number];
 
+/** The Lumber API a plugin sends logs to unless it's given another endpoint. */
+declare const DEFAULT_API_ENDPOINT = "https://api.lumber.infinitetoken.com";
+/** LogEncrypted's keyVersion. Every app has one encryption key, so it's 1 until keys can be rotated. */
+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.
+ */
+declare const logDelivery: {
+    readonly maxAttempts: 5;
+    readonly baseDelayMs: 1000;
+    readonly maxDelayMs: 30000;
+    readonly pauseMs: number;
+};
+
 /** Log severity level. Numeric values match the existing Lumber-API level field. */
 declare const enum LogLevel {
     Debug = 0,
@@ -32,48 +49,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.
@@ -423,7 +398,7 @@ interface LogEncrypted {
     keyVersion: number;
 }
 /**
- * Plaintext shape of log content — encrypted before sending, never stored plaintext on server.
+ * Plaintext shape of log content: a plugin encrypts it into LogEncrypted, and the server never sees it.
  */
 interface LogPayload {
     level: LogLevel;
@@ -433,6 +408,25 @@ interface LogPayload {
     context?: LogContext;
     metadata?: Record<string, unknown>;
 }
+/**
+ * What a plugin's log call takes beside its message (Lumber-Node's second argument). requestId and traceId become the
+ * payload's own fields, context is merged over the plugin's automatic context, and any other key goes into metadata,
+ * where an explicit metadata key wins. A context or metadata that isn't an object is kept as an ordinary metadata key.
+ */
+interface LogData {
+    requestId?: string;
+    traceId?: string;
+    context?: LogContext;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** POST /logs' body. The level stays plaintext for filtering and pushes; everything else is in `encrypted`. */
+interface LogIngestBody {
+    level: LogLevel;
+    encrypted: LogEncrypted;
+}
+/** What a plugin does with a log after POST /logs answers (see logDelivery). */
+type LogDeliveryOutcome = 'sent' | 'retry' | 'drop' | 'pause';
 /**
  * API response shape for a stored log.
  * level is plaintext for server-side notification routing; all content is inside encrypted.
@@ -631,6 +625,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;
@@ -665,6 +671,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[];
@@ -674,7 +682,71 @@ 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>;
+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
+ * as metadata with its explicit metadata over them. A context or metadata that isn't an object (a string, an array) is
+ * kept as an ordinary metadata key, since spreading it would turn `{ context: 'billing' }` into `{ 0: 'b', ... }`, and
+ * a null one is left out. Every plugin builds the same payload: contract/vectors.json pins it for the other languages.
+ */
+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.
+ */
+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;
 /**
@@ -714,4 +786,4 @@ 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_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, type LogContext, type LogEncrypted, 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, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+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, DEFAULT_TIME_FORMAT, 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 TimeClock, type TimeFormat, type TimeZoneChoice, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, buildLogPayload, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, isValidTimeFormat, joinApiKey, logDelivery, logDeliveryOutcome, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, logRetryDelayMs, nameColor, normalizePushThreshold, normalizeTimeFormat, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };

package/dist/index.d.ts

@@ -15,6 +15,23 @@ declare const APP_COLORS: readonly ["#EF4444", "#F97316", "#F59E0B", "#84CC16",
 declare const apiErrorCodes: readonly ["APP_LIMIT", "SEAT_LIMIT", "GUEST_LIMIT", "ALREADY_MEMBER", "ALREADY_READS", "ALREADY_INVITED", "HAS_ACCOUNT"];
 type ApiErrorCode = (typeof apiErrorCodes)[number];
 
+/** The Lumber API a plugin sends logs to unless it's given another endpoint. */
+declare const DEFAULT_API_ENDPOINT = "https://api.lumber.infinitetoken.com";
+/** LogEncrypted's keyVersion. Every app has one encryption key, so it's 1 until keys can be rotated. */
+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.
+ */
+declare const logDelivery: {
+    readonly maxAttempts: 5;
+    readonly baseDelayMs: 1000;
+    readonly maxDelayMs: 30000;
+    readonly pauseMs: number;
+};
+
 /** Log severity level. Numeric values match the existing Lumber-API level field. */
 declare const enum LogLevel {
     Debug = 0,
@@ -32,48 +49,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.
@@ -423,7 +398,7 @@ interface LogEncrypted {
     keyVersion: number;
 }
 /**
- * Plaintext shape of log content — encrypted before sending, never stored plaintext on server.
+ * Plaintext shape of log content: a plugin encrypts it into LogEncrypted, and the server never sees it.
  */
 interface LogPayload {
     level: LogLevel;
@@ -433,6 +408,25 @@ interface LogPayload {
     context?: LogContext;
     metadata?: Record<string, unknown>;
 }
+/**
+ * What a plugin's log call takes beside its message (Lumber-Node's second argument). requestId and traceId become the
+ * payload's own fields, context is merged over the plugin's automatic context, and any other key goes into metadata,
+ * where an explicit metadata key wins. A context or metadata that isn't an object is kept as an ordinary metadata key.
+ */
+interface LogData {
+    requestId?: string;
+    traceId?: string;
+    context?: LogContext;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** POST /logs' body. The level stays plaintext for filtering and pushes; everything else is in `encrypted`. */
+interface LogIngestBody {
+    level: LogLevel;
+    encrypted: LogEncrypted;
+}
+/** What a plugin does with a log after POST /logs answers (see logDelivery). */
+type LogDeliveryOutcome = 'sent' | 'retry' | 'drop' | 'pause';
 /**
  * API response shape for a stored log.
  * level is plaintext for server-side notification routing; all content is inside encrypted.
@@ -631,6 +625,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;
@@ -665,6 +671,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[];
@@ -674,7 +682,71 @@ 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>;
+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
+ * as metadata with its explicit metadata over them. A context or metadata that isn't an object (a string, an array) is
+ * kept as an ordinary metadata key, since spreading it would turn `{ context: 'billing' }` into `{ 0: 'b', ... }`, and
+ * a null one is left out. Every plugin builds the same payload: contract/vectors.json pins it for the other languages.
+ */
+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.
+ */
+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;
 /**
@@ -714,4 +786,4 @@ 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_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, type LogContext, type LogEncrypted, 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, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+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, DEFAULT_TIME_FORMAT, 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 TimeClock, type TimeFormat, type TimeZoneChoice, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, buildLogPayload, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, isValidTimeFormat, joinApiKey, logDelivery, logDeliveryOutcome, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, logRetryDelayMs, nameColor, normalizePushThreshold, normalizeTimeFormat, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };