@infinitetoken/lumber-kit 0.6.0 → 0.7.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,
@@ -423,7 +440,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 +450,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.
@@ -674,6 +710,22 @@ interface UserRecord {
     notesReadAt?: Record<string, string>;
 }
 
+/**
+ * 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;
 /** Accepts 3- and 6-digit hex color strings (#rgb, #rrggbb). */
 declare const isValidColor: (value: string) => boolean;
@@ -714,4 +766,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, 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 };

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,
@@ -423,7 +440,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 +450,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.
@@ -674,6 +710,22 @@ interface UserRecord {
     notesReadAt?: Record<string, string>;
 }
 
+/**
+ * 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;
 /** Accepts 3- and 6-digit hex color strings (#rgb, #rrggbb). */
 declare const isValidColor: (value: string) => boolean;
@@ -714,4 +766,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, 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 };

package/dist/index.js

@@ -22,12 +22,15 @@ var index_exports = {};
 __export(index_exports, {
   APP_COLORS: () => APP_COLORS,
   DEFAULT_ACCENT: () => DEFAULT_ACCENT,
+  DEFAULT_API_ENDPOINT: () => DEFAULT_API_ENDPOINT,
   DEFAULT_PUSH_THRESHOLD: () => DEFAULT_PUSH_THRESHOLD,
+  LOG_KEY_VERSION: () => LOG_KEY_VERSION,
   LogLevel: () => LogLevel,
   PUSH_OFF: () => PUSH_OFF,
   SubscriptionLevel: () => SubscriptionLevel,
   apiErrorCodeOf: () => apiErrorCodeOf,
   apiErrorCodes: () => apiErrorCodes,
+  buildLogPayload: () => buildLogPayload,
   isApiErrorCode: () => isApiErrorCode,
   isValidAppearance: () => isValidAppearance,
   isValidColor: () => isValidColor,
@@ -37,10 +40,13 @@ __export(index_exports, {
   isValidSubscriptionLevel: () => isValidSubscriptionLevel,
   isValidTeamMemberRole: () => isValidTeamMemberRole,
   joinApiKey: () => joinApiKey,
+  logDelivery: () => logDelivery,
+  logDeliveryOutcome: () => logDeliveryOutcome,
   logLevelColors: () => logLevelColors,
   logLevelNameToLevel: () => logLevelNameToLevel,
   logLevelToName: () => logLevelToName,
   logLevels: () => logLevels,
+  logRetryDelayMs: () => logRetryDelayMs,
   nameColor: () => nameColor,
   normalizePushThreshold: () => normalizePushThreshold,
   parsePushData: () => parsePushData,
@@ -55,13 +61,13 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/constants/logLevel.ts
-var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
-  LogLevel2[LogLevel2["Debug"] = 0] = "Debug";
-  LogLevel2[LogLevel2["Info"] = 1] = "Info";
-  LogLevel2[LogLevel2["Warn"] = 2] = "Warn";
-  LogLevel2[LogLevel2["Error"] = 3] = "Error";
-  LogLevel2[LogLevel2["Fatal"] = 4] = "Fatal";
-  return LogLevel2;
+var LogLevel = /* @__PURE__ */ ((LogLevel3) => {
+  LogLevel3[LogLevel3["Debug"] = 0] = "Debug";
+  LogLevel3[LogLevel3["Info"] = 1] = "Info";
+  LogLevel3[LogLevel3["Warn"] = 2] = "Warn";
+  LogLevel3[LogLevel3["Error"] = 3] = "Error";
+  LogLevel3[LogLevel3["Fatal"] = 4] = "Fatal";
+  return LogLevel3;
 })(LogLevel || {});
 var logLevelToName = {
   [0 /* Debug */]: "debug",
@@ -108,6 +114,16 @@ var apiErrorCodes = [
   "HAS_ACCOUNT"
 ];
 
+// src/constants/ingest.ts
+var DEFAULT_API_ENDPOINT = "https://api.lumber.infinitetoken.com";
+var LOG_KEY_VERSION = 1;
+var logDelivery = {
+  maxAttempts: 5,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  pauseMs: 60 * 60 * 1e3
+};
+
 // src/constants/notifications.ts
 var PUSH_OFF = 5;
 var DEFAULT_PUSH_THRESHOLD = 2 /* Warn */;
@@ -140,6 +156,32 @@ var subscriptionPlans = {
   [3 /* Enterprise */]: { name: "Enterprise", monthlyPrice: null }
 };
 
+// src/utils/ingest.ts
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var buildLogPayload = (level, message, data, autoContext) => {
+  const { requestId, traceId, context: givenContext, metadata: givenMetadata, ...rest } = data ?? {};
+  const context = isRecord(givenContext) ? givenContext : void 0;
+  const metadata = isRecord(givenMetadata) ? givenMetadata : void 0;
+  if (givenContext != null && !context) rest.context = givenContext;
+  if (givenMetadata != null && !metadata) rest.metadata = givenMetadata;
+  const mergedMetadata = Object.keys(rest).length > 0 ? { ...rest, ...metadata ?? {} } : metadata;
+  const mergedContext = autoContext && Object.keys(autoContext).length > 0 ? { ...autoContext, ...context ?? {} } : context;
+  const payload = { level, message };
+  if (requestId !== void 0) payload.requestId = requestId;
+  if (traceId !== void 0) payload.traceId = traceId;
+  if (mergedContext !== void 0) payload.context = mergedContext;
+  if (mergedMetadata !== void 0) payload.metadata = mergedMetadata;
+  return payload;
+};
+var logDeliveryOutcome = (status) => {
+  if (status === null) return "retry";
+  if (status >= 200 && status < 300) return "sent";
+  if (status === 429) return "pause";
+  if (status >= 400 && status < 500) return "drop";
+  return "retry";
+};
+var logRetryDelayMs = (failedAttempts) => Math.min(logDelivery.baseDelayMs * 2 ** Math.max(0, failedAttempts - 1), logDelivery.maxDelayMs);
+
 // src/utils/index.ts
 var appearanceValues = ["system", "dark", "light"];
 var isValidAppearance = (value) => appearanceValues.includes(value);
@@ -215,12 +257,15 @@ var parsePushData = (data) => {
 0 && (module.exports = {
   APP_COLORS,
   DEFAULT_ACCENT,
+  DEFAULT_API_ENDPOINT,
   DEFAULT_PUSH_THRESHOLD,
+  LOG_KEY_VERSION,
   LogLevel,
   PUSH_OFF,
   SubscriptionLevel,
   apiErrorCodeOf,
   apiErrorCodes,
+  buildLogPayload,
   isApiErrorCode,
   isValidAppearance,
   isValidColor,
@@ -230,10 +275,13 @@ var parsePushData = (data) => {
   isValidSubscriptionLevel,
   isValidTeamMemberRole,
   joinApiKey,
+  logDelivery,
+  logDeliveryOutcome,
   logLevelColors,
   logLevelNameToLevel,
   logLevelToName,
   logLevels,
+  logRetryDelayMs,
   nameColor,
   normalizePushThreshold,
   parsePushData,

package/dist/index.mjs

@@ -1,11 +1,11 @@
 // src/constants/logLevel.ts
-var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
-  LogLevel2[LogLevel2["Debug"] = 0] = "Debug";
-  LogLevel2[LogLevel2["Info"] = 1] = "Info";
-  LogLevel2[LogLevel2["Warn"] = 2] = "Warn";
-  LogLevel2[LogLevel2["Error"] = 3] = "Error";
-  LogLevel2[LogLevel2["Fatal"] = 4] = "Fatal";
-  return LogLevel2;
+var LogLevel = /* @__PURE__ */ ((LogLevel3) => {
+  LogLevel3[LogLevel3["Debug"] = 0] = "Debug";
+  LogLevel3[LogLevel3["Info"] = 1] = "Info";
+  LogLevel3[LogLevel3["Warn"] = 2] = "Warn";
+  LogLevel3[LogLevel3["Error"] = 3] = "Error";
+  LogLevel3[LogLevel3["Fatal"] = 4] = "Fatal";
+  return LogLevel3;
 })(LogLevel || {});
 var logLevelToName = {
   [0 /* Debug */]: "debug",
@@ -52,6 +52,16 @@ var apiErrorCodes = [
   "HAS_ACCOUNT"
 ];
 
+// src/constants/ingest.ts
+var DEFAULT_API_ENDPOINT = "https://api.lumber.infinitetoken.com";
+var LOG_KEY_VERSION = 1;
+var logDelivery = {
+  maxAttempts: 5,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  pauseMs: 60 * 60 * 1e3
+};
+
 // src/constants/notifications.ts
 var PUSH_OFF = 5;
 var DEFAULT_PUSH_THRESHOLD = 2 /* Warn */;
@@ -84,6 +94,32 @@ var subscriptionPlans = {
   [3 /* Enterprise */]: { name: "Enterprise", monthlyPrice: null }
 };
 
+// src/utils/ingest.ts
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var buildLogPayload = (level, message, data, autoContext) => {
+  const { requestId, traceId, context: givenContext, metadata: givenMetadata, ...rest } = data ?? {};
+  const context = isRecord(givenContext) ? givenContext : void 0;
+  const metadata = isRecord(givenMetadata) ? givenMetadata : void 0;
+  if (givenContext != null && !context) rest.context = givenContext;
+  if (givenMetadata != null && !metadata) rest.metadata = givenMetadata;
+  const mergedMetadata = Object.keys(rest).length > 0 ? { ...rest, ...metadata ?? {} } : metadata;
+  const mergedContext = autoContext && Object.keys(autoContext).length > 0 ? { ...autoContext, ...context ?? {} } : context;
+  const payload = { level, message };
+  if (requestId !== void 0) payload.requestId = requestId;
+  if (traceId !== void 0) payload.traceId = traceId;
+  if (mergedContext !== void 0) payload.context = mergedContext;
+  if (mergedMetadata !== void 0) payload.metadata = mergedMetadata;
+  return payload;
+};
+var logDeliveryOutcome = (status) => {
+  if (status === null) return "retry";
+  if (status >= 200 && status < 300) return "sent";
+  if (status === 429) return "pause";
+  if (status >= 400 && status < 500) return "drop";
+  return "retry";
+};
+var logRetryDelayMs = (failedAttempts) => Math.min(logDelivery.baseDelayMs * 2 ** Math.max(0, failedAttempts - 1), logDelivery.maxDelayMs);
+
 // src/utils/index.ts
 var appearanceValues = ["system", "dark", "light"];
 var isValidAppearance = (value) => appearanceValues.includes(value);
@@ -158,12 +194,15 @@ var parsePushData = (data) => {
 export {
   APP_COLORS,
   DEFAULT_ACCENT,
+  DEFAULT_API_ENDPOINT,
   DEFAULT_PUSH_THRESHOLD,
+  LOG_KEY_VERSION,
   LogLevel,
   PUSH_OFF,
   SubscriptionLevel,
   apiErrorCodeOf,
   apiErrorCodes,
+  buildLogPayload,
   isApiErrorCode,
   isValidAppearance,
   isValidColor,
@@ -173,10 +212,13 @@ export {
   isValidSubscriptionLevel,
   isValidTeamMemberRole,
   joinApiKey,
+  logDelivery,
+  logDeliveryOutcome,
   logLevelColors,
   logLevelNameToLevel,
   logLevelToName,
   logLevels,
+  logRetryDelayMs,
   nameColor,
   normalizePushThreshold,
   parsePushData,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infinitetoken/lumber-kit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared TypeScript types and wire format contracts for the Lumber cloud logging suite",
   "keywords": [
     "lumber",
@@ -31,17 +31,20 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
-    }
+    },
+    "./contract/*": "./contract/*"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "contract"
   ],
   "scripts": {
     "build": "tsup",
     "clean": "rm -rf dist coverage",
+    "contract": "node scripts/contract.cjs",
     "fix": "eslint . --fix",
     "lint": "eslint .",
     "prepublishOnly": "npm run build",
@@ -61,9 +64,11 @@
     "@infinitetoken/tsconfig": "^0.6.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.0.0",
+    "ajv": "^8.20.0",
     "eslint": "^10.2.1",
     "jest": "^30.4.2",
     "prettier": "^3.8.3",
+    "ts-json-schema-generator": "^2.9.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3"
   },