@infinitetoken/lumber-kit 0.5.2 → 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,
@@ -222,7 +239,24 @@ interface AppsQuery {
     cursor?: string;
 }
 
-type DeviceLinkStatus = 'pending' | 'approved' | 'denied';
+/**
+ * A device link request: a new device asking for the account key from a device that has it. `failed` is a code that
+ * didn't match, which ends the request.
+ */
+type DeviceLinkStatus = 'pending' | 'approved' | 'denied' | 'failed';
+/** What a request comes from, so the device answering it can say so and offer a QR code only to a phone's camera. */
+type DeviceLinkPlatform = 'ios' | 'android' | 'web' | 'desktop' | 'cli';
+/**
+ * Body of POST /device-links.
+ */
+interface DeviceLinkCreateBody {
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The public half of the new device's one-off X25519 keypair, which the account key is wrapped to. */
+    publicKey: string;
+    /** The new device's push device id, so the push asking the account's devices to link it skips it. */
+    deviceId?: string;
+}
 /**
  * Response from POST /device-links.
  */
@@ -231,14 +265,48 @@ interface DeviceLinkCreatedRecord {
     expiresAt: string;
 }
 /**
- * Response from GET /device-links/:id.
- * encryptedKey is present only when status is 'approved'.
+ * Body of POST /device-links/:id/approve: the account key wrapped to the new device, and a tag over it made from the
+ * code's secret, which the new device checks before storing the key, so the server can't hand it a key of its own.
+ */
+interface DeviceLinkApproveBody {
+    encryptedKey: string;
+    deliveryTag: string;
+}
+/**
+ * Response from GET /device-links/:id, as the new device reads it.
+ * encryptedKey and deliveryTag are present only when status is 'approved'. sid and holderMessage are set once a device
+ * holding the account key shows the request's code, and answeredAt once the new device has answered it.
  */
 interface DeviceLinkRecord {
     id: string;
     status: DeviceLinkStatus;
     encryptedKey?: string;
+    deliveryTag?: string;
     expiresAt: string;
+    sid?: string | null;
+    holderMessage?: string | null;
+    answeredAt?: string | null;
+}
+/**
+ * A request waiting on the caller's account key (GET /device-links/pending), as a device holding it reads it: enough
+ * to show its code, and to finish it once answered. The messages are the same password-authenticated exchange as a key
+ * check's, so the server can't read or test codes against them. holderState is the code's side of the exchange, sealed
+ * under the account key, so any of the account's devices can show the same code or finish the request.
+ */
+interface PendingDeviceLink {
+    id: string;
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The new device's one-off public key, which an answer's tag has to cover before anything is wrapped to it. */
+    publicKey: string;
+    sid: string | null;
+    holderMessage: string | null;
+    holderState: string | null;
+    claimantMessage: string | null;
+    tag: string | null;
+    answeredAt: string | null;
+    expiresAt: string;
+    createdAt: string;
 }
 
 /**
@@ -372,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;
@@ -382,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.
@@ -471,6 +558,12 @@ type PushData =
     deviceLinkId: string;
     deviceName: string;
 }
+/** The new device entered its link code, which a device holding the account key now checks (Lumber-API). */
+ | {
+    type: 'device_link_answered';
+    deviceLinkId: string;
+    deviceName: string;
+}
 /** The person the reader gave a code entered it (Lumber-API). */
  | {
     type: 'key_check';
@@ -617,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;
@@ -657,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 DeviceLinkCreatedRecord, 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 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,
@@ -222,7 +239,24 @@ interface AppsQuery {
     cursor?: string;
 }
 
-type DeviceLinkStatus = 'pending' | 'approved' | 'denied';
+/**
+ * A device link request: a new device asking for the account key from a device that has it. `failed` is a code that
+ * didn't match, which ends the request.
+ */
+type DeviceLinkStatus = 'pending' | 'approved' | 'denied' | 'failed';
+/** What a request comes from, so the device answering it can say so and offer a QR code only to a phone's camera. */
+type DeviceLinkPlatform = 'ios' | 'android' | 'web' | 'desktop' | 'cli';
+/**
+ * Body of POST /device-links.
+ */
+interface DeviceLinkCreateBody {
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The public half of the new device's one-off X25519 keypair, which the account key is wrapped to. */
+    publicKey: string;
+    /** The new device's push device id, so the push asking the account's devices to link it skips it. */
+    deviceId?: string;
+}
 /**
  * Response from POST /device-links.
  */
@@ -231,14 +265,48 @@ interface DeviceLinkCreatedRecord {
     expiresAt: string;
 }
 /**
- * Response from GET /device-links/:id.
- * encryptedKey is present only when status is 'approved'.
+ * Body of POST /device-links/:id/approve: the account key wrapped to the new device, and a tag over it made from the
+ * code's secret, which the new device checks before storing the key, so the server can't hand it a key of its own.
+ */
+interface DeviceLinkApproveBody {
+    encryptedKey: string;
+    deliveryTag: string;
+}
+/**
+ * Response from GET /device-links/:id, as the new device reads it.
+ * encryptedKey and deliveryTag are present only when status is 'approved'. sid and holderMessage are set once a device
+ * holding the account key shows the request's code, and answeredAt once the new device has answered it.
  */
 interface DeviceLinkRecord {
     id: string;
     status: DeviceLinkStatus;
     encryptedKey?: string;
+    deliveryTag?: string;
     expiresAt: string;
+    sid?: string | null;
+    holderMessage?: string | null;
+    answeredAt?: string | null;
+}
+/**
+ * A request waiting on the caller's account key (GET /device-links/pending), as a device holding it reads it: enough
+ * to show its code, and to finish it once answered. The messages are the same password-authenticated exchange as a key
+ * check's, so the server can't read or test codes against them. holderState is the code's side of the exchange, sealed
+ * under the account key, so any of the account's devices can show the same code or finish the request.
+ */
+interface PendingDeviceLink {
+    id: string;
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The new device's one-off public key, which an answer's tag has to cover before anything is wrapped to it. */
+    publicKey: string;
+    sid: string | null;
+    holderMessage: string | null;
+    holderState: string | null;
+    claimantMessage: string | null;
+    tag: string | null;
+    answeredAt: string | null;
+    expiresAt: string;
+    createdAt: string;
 }
 
 /**
@@ -372,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;
@@ -382,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.
@@ -471,6 +558,12 @@ type PushData =
     deviceLinkId: string;
     deviceName: string;
 }
+/** The new device entered its link code, which a device holding the account key now checks (Lumber-API). */
+ | {
+    type: 'device_link_answered';
+    deviceLinkId: string;
+    deviceName: string;
+}
 /** The person the reader gave a code entered it (Lumber-API). */
  | {
     type: 'key_check';
@@ -617,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;
@@ -657,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 DeviceLinkCreatedRecord, 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 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 };