@infinitetoken/lumber-kit 0.4.22 → 0.5.0

package/README.md

@@ -36,6 +36,40 @@ import { LogLevel, LogRecord, LogEncrypted, LogPayload, LogsQuery } from '@infin
 | `subscriptionLimits` | object | Per-tier limits (apps, seats, apiKeys, logRetentionDays, etc.) |
 | `isValidSubscriptionLevel` | function | Type guard for `SubscriptionLevel` values |
 
+### Plans
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `subscriptionPlans` | object | Per-tier display name and monthly price in US dollars (0 free, `null` priced per customer) |
+| `SubscriptionPlanRecord` | interface | A plan GET /subscriptions offers, with its Stripe price id |
+
+### Notifications
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `PUSH_OFF` | constant | A push threshold one past Fatal (5): log pushes off |
+| `PushThreshold` | type | A `LogLevel` or `PUSH_OFF`, stored as a preference's `minimumLevel` |
+| `normalizePushThreshold` | function | A threshold from any stored or sent value: past Fatal is off, not a number is Warn |
+| `PushData` | type | The `data` each push type carries (`log`, `note`, `device_link`, `key_check`, `key_waiting`, `keys_shared`) |
+| `parsePushData` | function | A push's data as `PushData`, or `null` for data no Lumber push sends |
+
+### Socket events
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `ServerToClientEvents` | interface | Every event Lumber-Socket sends, for socket.io's typed `Server` and `Socket` |
+| `ClientToServerEvents` | interface | Every event a client sends Lumber-Socket |
+| `SocketAppPayload` | type | An app as the socket sends it (no wrapped keys) |
+
+### Errors
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `ApiErrorCode` | type | Why the API refused, where the status alone doesn't say (`SEAT_LIMIT`, `ALREADY_MEMBER`, ...) |
+| `apiErrorCodes` | array | Every `ApiErrorCode` |
+| `ApiErrorBody` | interface | An error response's body: `{ message, code? }` |
+| `apiErrorCodeOf` | function | The code in an error body, or `null` |
+
 ### Flag types
 
 | Export | Kind | Purpose |
@@ -51,7 +85,30 @@ import { LogLevel, LogRecord, LogEncrypted, LogPayload, LogsQuery } from '@infin
 | `AppCreatedRecord` | interface | POST /apps 201 response (includes `encryptedKey` once) |
 | `UserRecord` | interface | API response shape for a user |
 | `TeamRecord` | interface | API response shape for a team |
-| `TeamMemberRecord` | interface | Team membership record |
+| `TeamMemberRecord` | interface | Team membership record (listed members carry name, handle, color and picture) |
+| `AppTeamAccess` | type | Who on an app's team reads it: `'everyone'` or `'owner'` |
+| `AppPermission` | type | `'read' \| 'write' \| 'manage'` on an app |
+| `AppPersonRecord` | interface | Someone who can read an app, as GET /apps/:id/people shows them |
+| `InvitationRecord` | interface | An invitation to an address with no account, to a team or an app |
+
+### Key sharing
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `PendingAppKey` | interface | Someone with access to an app and no wrapped copy of its key |
+| `KeyHolder` | interface | Someone who already holds a wrapped copy |
+| `AppKeyUpsertBody` | interface | Body of PUT /apps/:id/keys/:userId |
+| `KeyPin` | interface | An account key a user accepted for someone, with its MAC |
+| `HolderKeyCheck`, `ClaimantKeyCheck`, `KeyCheckResult` | interfaces | A key check as the holder and the person being confirmed read it |
+
+### API keys
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `joinApiKey` | function | Joins an app's API token and its encryption key as `<token>.<encryptionKey>`, the one secret a plugin is configured with |
+| `splitApiKey` | function | Splits an API key into `{ token, encryptionKey? }`; a value with no dot is all token |
+
+A plugin sends only the token to the API (`Authorization: Bearer <token>`) and encrypts with the rest, so the encryption key never leaves it.
 
 ## Wire format
 

package/dist/index.d.mts

@@ -1,3 +1,10 @@
+/**
+ * Machine-readable reasons the API refuses a request, sent as `code` beside `message` where one status means more than
+ * one thing. Messages are for people and may change; clients decide by the code.
+ */
+declare const apiErrorCodes: readonly ["APP_LIMIT", "SEAT_LIMIT", "GUEST_LIMIT", "ALREADY_MEMBER", "ALREADY_READS", "ALREADY_INVITED", "HAS_ACCOUNT"];
+type ApiErrorCode = (typeof apiErrorCodes)[number];
+
 /** Log severity level. Numeric values match the existing Lumber-API level field. */
 declare const enum LogLevel {
     Debug = 0,
@@ -15,6 +22,13 @@ 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,
@@ -41,6 +55,70 @@ type SubscriptionLimits = {
 };
 /** 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.
+ */
+interface TeamRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    name: string;
+    color?: string;
+    imageUrl?: string;
+    subscriptionLevel: SubscriptionLevel;
+    /** When a canceled plan stops; null while it renews. */
+    subscriptionEnd?: string | null;
+    /** GET /teams only: the caller's role on the team. */
+    role?: TeamMemberRecord['role'];
+    /** GET /teams only: the caller's membership id, which leaving the team deletes. */
+    memberId?: string;
+    /** GET /teams only: the team's apps, as creating one counts them. Null unless the caller is its owner or an admin. */
+    appCount?: number | null;
+    /** GET /teams only: logs its apps sent this UTC month, the monthly cap's count. Null unless owner or admin. */
+    logsThisMonth?: number | null;
+}
+/**
+ * Membership of a user in a team.
+ */
+interface TeamMemberRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    teamId: string;
+    userId: string;
+    role: 'owner' | 'admin' | 'member';
+    /** Listed members only: their display name. Never their email address. */
+    name?: string | null;
+    /** Listed members only: the part of their email before the @. */
+    handle?: string | null;
+    color?: string | null;
+    imageUrl?: string | null;
+}
+/**
+ * A plan GET /subscriptions offers, with its Stripe price (none for Hobby).
+ */
+interface SubscriptionPlanRecord {
+    name: string;
+    priceId: string | null;
+}
+/**
+ * Filter params for GET /teams.
+ */
+interface TeamsQuery {
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
 
 /**
  * Wrapped application encryption key for a specific user.
@@ -50,9 +128,14 @@ interface AppEncryptedKey {
     encryptedKey: string;
     keyVersion: number;
 }
+/**
+ * Who on an app's team can read it: everyone on the team, or only its owner. Its guests read it either way.
+ */
+type AppTeamAccess = 'everyone' | 'owner';
 /**
  * API response shape for a listed or fetched app.
  * encryptedKey is the requesting user's wrapped copy of the app key, or null if none exists.
+ * The optional fields are missing from an API deployed before them, which clients read as the default.
  */
 interface AppRecord {
     id: string;
@@ -63,6 +146,12 @@ interface AppRecord {
     imageUrl?: string;
     teamId?: string;
     encryptedKey: string | null;
+    /** Missing means 'everyone'. */
+    teamAccess?: AppTeamAccess;
+    /** How many days of its logs the app's team's plan keeps, null for no limit (and when missing). */
+    retentionDays?: number | null;
+    /** While the team has sent its plan's monthly logs, when new ones are taken again (the next UTC month); else null. */
+    logsCappedUntil?: string | null;
 }
 /**
  * App creation response.
@@ -92,6 +181,25 @@ interface GuestRecord {
     userId: string;
     role: 'owner' | 'admin' | 'read' | 'write';
 }
+/**
+ * What someone may do on an app. manage: the team's owner or admins, or a guest invited as owner or admin. write: a
+ * team member or a write guest. read: any other access.
+ */
+type AppPermission = 'read' | 'write' | 'manage';
+/**
+ * Someone who can read an app, as the others see them (GET /apps/:id/people): never their email address.
+ */
+interface AppPersonRecord {
+    userId: string;
+    name: string | null;
+    /** The part of their email before the @, for anyone who hasn't set a name. */
+    handle?: string | null;
+    color: string | null;
+    /** Their picture URL, or null for their initial. */
+    imageUrl?: string | null;
+    role: TeamMemberRecord['role'] | GuestRecord['role'];
+    kind: 'team' | 'guest';
+}
 /**
  * Filter params for GET /apps.
  */
@@ -123,6 +231,14 @@ interface DeviceLinkRecord {
     expiresAt: string;
 }
 
+/**
+ * The body of an API error response. `code` is there where the status alone doesn't say what went wrong.
+ */
+interface ApiErrorBody {
+    message: string;
+    code?: ApiErrorCode;
+}
+
 interface FlagRecord {
     id: string;
     createdAt: string;
@@ -137,6 +253,92 @@ interface FlagsQuery {
     cursor?: string;
 }
 
+/**
+ * An invitation to an address with no account yet: to a team (teamId, as a member or admin) or to one app as its guest
+ * (appId). The address joins when it signs up and confirms itself. A live one (unexpired) holds its seat.
+ */
+interface InvitationRecord {
+    id: string;
+    teamId: string | null;
+    appId: string | null;
+    email: string;
+    role: string;
+    /** Null when its email couldn't be sent. */
+    sentAt: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+
+/**
+ * Someone with access to an app who has no wrapped copy of its key yet (GET /apps/keys/pending), with when they last
+ * replaced their account key: null if never, missing from an API before key pins.
+ */
+interface PendingAppKey {
+    appId: string;
+    userId: string;
+    publicKey: string;
+    keyChangedAt?: string | null;
+}
+/**
+ * Someone who reads one of the caller's apps and already has a wrapped copy of its key (GET /apps/keys/holders).
+ */
+interface KeyHolder {
+    userId: string;
+    publicKey: string;
+}
+/**
+ * Body of PUT /apps/:id/keys/:userId: the app key wrapped to that user's account key.
+ */
+interface AppKeyUpsertBody {
+    encryptedKey: string;
+}
+/**
+ * An account key a user has accepted for someone they share apps with (GET /key-pins). `mac` is an HMAC by the user's
+ * own devices, under a key derived from their account key, over the user, the person and the key: the server can drop
+ * a pin but not forge or move one.
+ */
+interface KeyPin {
+    userId: string;
+    publicKey: string;
+    mac: string;
+}
+type KeyCheckResult = 'confirmed' | 'failed' | 'cancelled';
+/**
+ * A key check the caller started, as their devices read it (GET /key-checks/mine): enough to show the code again or
+ * finish the check. The messages are a password-authenticated exchange the server can't read or test codes against.
+ */
+interface HolderKeyCheck {
+    id: string;
+    userId: string;
+    sid: string;
+    holderMessage: string;
+    /** The holder's half of the exchange, sealed under their account key. */
+    holderState: string;
+    claimantMessage: string | null;
+    publicKey: string | null;
+    tag: string | null;
+    answeredAt: string | null;
+    result: KeyCheckResult | null;
+    finishedAt: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+/**
+ * A key check waiting on the caller's answer, or how a recent answer went (GET /key-checks/for-me).
+ */
+interface ClaimantKeyCheck {
+    id: string;
+    holderId: string;
+    holderName: string;
+    sid: string;
+    holderMessage: string;
+    answeredAt: string | null;
+    result: KeyCheckResult | null;
+    finishedAt: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+
 /**
  * Structured log context content.
  */
@@ -235,6 +437,47 @@ interface NotesQuery {
     cursor?: string;
 }
 
+/**
+ * The `data` a push notification carries, which the app reads to open the screen it's about. Expo delivers data as
+ * JSON, but some platforms want strings, so every value is one.
+ */
+type PushData = 
+/** A log at or above the reader's threshold (Lumber-Worker). `level` is the LogLevel as a string. */
+{
+    type: 'log';
+    appId: string;
+    logId: string;
+    level: string;
+}
+/** A note from someone else on an app the reader reads (Lumber-API). */
+ | {
+    type: 'note';
+    appId: string;
+    noteId: string;
+}
+/** A new device asking to link to the account (Lumber-Worker). */
+ | {
+    type: 'device_link';
+    deviceLinkId: string;
+    deviceName: string;
+}
+/** The person the reader gave a code entered it (Lumber-API). */
+ | {
+    type: 'key_check';
+    checkId: string;
+}
+/** Someone is waiting for the reader to confirm their key, as new or changed (Lumber-API). */
+ | {
+    type: 'key_waiting';
+    userId: string;
+}
+/** Someone wrapped app keys for the reader. `appId` when it was one app (Lumber-API). */
+ | {
+    type: 'keys_shared';
+    appId?: string;
+};
+type PushType = PushData['type'];
+
 interface ResponseMetadata {
     requestId: string;
     durationMs: number;
@@ -249,37 +492,45 @@ interface ApiResponse<T> {
     metadata: ResponseMetadata;
 }
 
+/** An app as the socket sends it: no wrapped keys, so a client refetches through the API for its own copy. */
+type SocketAppPayload = Pick<AppRecord, 'id' | 'name' | 'teamId' | 'color' | 'imageUrl' | 'createdAt' | 'updatedAt'>;
 /**
- * An organization that owns apps and pays for member usage.
- * Team subscriptionLevel takes precedence over individual member levels.
+ * What Lumber-Socket sends a client, for socket.io's typed `Server` and `Socket`. Each goes to the users who can read
+ * the app it's about, live updates permitting (the app's team's plan); flags go to the user who set them.
  */
-interface TeamRecord {
-    id: string;
-    createdAt: string;
-    updatedAt: string;
-    name: string;
-    color?: string;
-    imageUrl?: string;
-    subscriptionLevel: SubscriptionLevel;
-}
-/**
- * Membership of a user in a team.
- */
-interface TeamMemberRecord {
-    id: string;
-    createdAt: string;
-    updatedAt: string;
-    teamId: string;
-    userId: string;
-    role: 'owner' | 'admin' | 'member';
-}
-/**
- * Filter params for GET /teams.
- */
-interface TeamsQuery {
-    sort?: string;
-    limit?: number;
-    cursor?: string;
+interface ServerToClientEvents {
+    'log:created': (log: Omit<LogRecord, 'updatedAt'> & {
+        updatedAt?: string;
+    }) => void;
+    'flag:created': (flag: Omit<FlagRecord, 'updatedAt'> & {
+        updatedAt?: string;
+    }) => void;
+    'flag:deleted': (flag: Pick<FlagRecord, 'id'>) => void;
+    'note:created': (note: NoteRecord) => void;
+    'note:updated': (note: NoteRecord) => void;
+    'note:deleted': (note: Pick<NoteRecord, 'id' | 'appId'>) => void;
+    'app:created': (app: SocketAppPayload) => void;
+    'app:updated': (app: SocketAppPayload) => void;
+    /** Deleted, or kept to its team's owner and so gone for the rest of the team. */
+    'app:deleted': (app: Pick<AppRecord, 'id'>) => void;
+    /** Someone joined or left a team or app the user is on. Carries nothing; sent on every plan. */
+    'access:changed': (payload: Record<string, never>) => void;
+    /**
+     * The socket's database connection came back after a gap and has replayed what it could. Deletes, and anything older
+     * or past the replay's cap, need the client's own resync.
+     */
+    'socket:reconnected': () => void;
+    /** The answer to `listMyApps`: the apps the user gets live updates for. */
+    myApps: (payload: {
+        apps: Pick<AppRecord, 'id' | 'name'>[];
+    }) => void;
+    error: (payload: {
+        message: string;
+    }) => void;
+}
+/** What a client sends Lumber-Socket. */
+interface ClientToServerEvents {
+    listMyApps: () => void;
 }
 
 /**
@@ -317,6 +568,8 @@ interface PushToken {
     token: string;
     deviceId?: string;
     platform?: 'ios' | 'android' | 'web';
+    /** The device's IANA time zone, so a push can say a log's time as the device would. */
+    timeZone?: string;
 }
 interface NotificationPreference {
     enabled?: boolean;
@@ -326,6 +579,8 @@ interface NotificationPreference {
 interface NotificationPreferences {
     enabled?: boolean;
     minimumLevel?: number;
+    /** Whether new notes on the user's apps push; on unless false. */
+    notes?: boolean;
     perApp?: Record<string, NotificationPreference>;
 }
 /**
@@ -344,6 +599,10 @@ interface UserRecord {
     agreedToTermsVersion?: string;
     notificationPreferences: NotificationPreferences;
     pushTokens: PushToken[];
+    /** When the address was confirmed, null until it is. Missing from an API before email confirmation. */
+    emailVerifiedAt?: string | null;
+    /** Per app, when the user last had its notes open, from any device. Missing from an API before it was kept. */
+    notesReadAt?: Record<string, string>;
 }
 
 declare const isValidAppearance: (value: unknown) => value is Appearance;
@@ -355,5 +614,26 @@ declare const isValidDeviceLinkStatus: (value: unknown) => value is DeviceLinkSt
 declare const isValidTeamMemberRole: (value: unknown) => value is TeamMemberRecord["role"];
 /** Accepts any valid absolute URL (https://..., http://..., etc.). */
 declare const isValidImageUrl: (value: unknown) => value is string;
+/**
+ * The API key the Lumber app hands out: an app's API token and its encryption key, joined as `<token>.<encryptionKey>`,
+ * so a plugin is configured with one secret. A plugin sends only the token to the API (`Authorization: Bearer <token>`)
+ * and encrypts with the rest, so the encryption key never leaves it. Neither half can contain a `.` (hex and base64).
+ */
+declare const joinApiKey: (token: string, encryptionKey: string) => string;
+/** Splits an API key into its token and encryption key. A value with no dot is all token. */
+declare const splitApiKey: (apiKey: string) => {
+    token: string;
+    encryptionKey?: string;
+};
+/**
+ * A push threshold from a stored or sent preference: a log level, or PUSH_OFF for anything past Fatal. Below Debug is
+ * Debug, a fraction rounds, and anything that isn't a finite number is the default (Warn).
+ */
+declare const normalizePushThreshold: (value: unknown) => PushThreshold;
+declare const isApiErrorCode: (value: unknown) => value is ApiErrorCode;
+/** The code in an API error response's body, or null when it has none. */
+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 { type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppRecord, type Appearance, type AppsQuery, type DeviceLinkCreatedRecord, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, 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, type PushToken, type ResponseMetadata, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, logLevelNameToLevel, logLevelToName, logLevels, subscriptionLevelToName, subscriptionLevels, subscriptionLimits };
+export { 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_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, logLevelNameToLevel, logLevelToName, logLevels, normalizePushThreshold, parsePushData, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Machine-readable reasons the API refuses a request, sent as `code` beside `message` where one status means more than
+ * one thing. Messages are for people and may change; clients decide by the code.
+ */
+declare const apiErrorCodes: readonly ["APP_LIMIT", "SEAT_LIMIT", "GUEST_LIMIT", "ALREADY_MEMBER", "ALREADY_READS", "ALREADY_INVITED", "HAS_ACCOUNT"];
+type ApiErrorCode = (typeof apiErrorCodes)[number];
+
 /** Log severity level. Numeric values match the existing Lumber-API level field. */
 declare const enum LogLevel {
     Debug = 0,
@@ -15,6 +22,13 @@ 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,
@@ -41,6 +55,70 @@ type SubscriptionLimits = {
 };
 /** 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.
+ */
+interface TeamRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    name: string;
+    color?: string;
+    imageUrl?: string;
+    subscriptionLevel: SubscriptionLevel;
+    /** When a canceled plan stops; null while it renews. */
+    subscriptionEnd?: string | null;
+    /** GET /teams only: the caller's role on the team. */
+    role?: TeamMemberRecord['role'];
+    /** GET /teams only: the caller's membership id, which leaving the team deletes. */
+    memberId?: string;
+    /** GET /teams only: the team's apps, as creating one counts them. Null unless the caller is its owner or an admin. */
+    appCount?: number | null;
+    /** GET /teams only: logs its apps sent this UTC month, the monthly cap's count. Null unless owner or admin. */
+    logsThisMonth?: number | null;
+}
+/**
+ * Membership of a user in a team.
+ */
+interface TeamMemberRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    teamId: string;
+    userId: string;
+    role: 'owner' | 'admin' | 'member';
+    /** Listed members only: their display name. Never their email address. */
+    name?: string | null;
+    /** Listed members only: the part of their email before the @. */
+    handle?: string | null;
+    color?: string | null;
+    imageUrl?: string | null;
+}
+/**
+ * A plan GET /subscriptions offers, with its Stripe price (none for Hobby).
+ */
+interface SubscriptionPlanRecord {
+    name: string;
+    priceId: string | null;
+}
+/**
+ * Filter params for GET /teams.
+ */
+interface TeamsQuery {
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
 
 /**
  * Wrapped application encryption key for a specific user.
@@ -50,9 +128,14 @@ interface AppEncryptedKey {
     encryptedKey: string;
     keyVersion: number;
 }
+/**
+ * Who on an app's team can read it: everyone on the team, or only its owner. Its guests read it either way.
+ */
+type AppTeamAccess = 'everyone' | 'owner';
 /**
  * API response shape for a listed or fetched app.
  * encryptedKey is the requesting user's wrapped copy of the app key, or null if none exists.
+ * The optional fields are missing from an API deployed before them, which clients read as the default.
  */
 interface AppRecord {
     id: string;
@@ -63,6 +146,12 @@ interface AppRecord {
     imageUrl?: string;
     teamId?: string;
     encryptedKey: string | null;
+    /** Missing means 'everyone'. */
+    teamAccess?: AppTeamAccess;
+    /** How many days of its logs the app's team's plan keeps, null for no limit (and when missing). */
+    retentionDays?: number | null;
+    /** While the team has sent its plan's monthly logs, when new ones are taken again (the next UTC month); else null. */
+    logsCappedUntil?: string | null;
 }
 /**
  * App creation response.
@@ -92,6 +181,25 @@ interface GuestRecord {
     userId: string;
     role: 'owner' | 'admin' | 'read' | 'write';
 }
+/**
+ * What someone may do on an app. manage: the team's owner or admins, or a guest invited as owner or admin. write: a
+ * team member or a write guest. read: any other access.
+ */
+type AppPermission = 'read' | 'write' | 'manage';
+/**
+ * Someone who can read an app, as the others see them (GET /apps/:id/people): never their email address.
+ */
+interface AppPersonRecord {
+    userId: string;
+    name: string | null;
+    /** The part of their email before the @, for anyone who hasn't set a name. */
+    handle?: string | null;
+    color: string | null;
+    /** Their picture URL, or null for their initial. */
+    imageUrl?: string | null;
+    role: TeamMemberRecord['role'] | GuestRecord['role'];
+    kind: 'team' | 'guest';
+}
 /**
  * Filter params for GET /apps.
  */
@@ -123,6 +231,14 @@ interface DeviceLinkRecord {
     expiresAt: string;
 }
 
+/**
+ * The body of an API error response. `code` is there where the status alone doesn't say what went wrong.
+ */
+interface ApiErrorBody {
+    message: string;
+    code?: ApiErrorCode;
+}
+
 interface FlagRecord {
     id: string;
     createdAt: string;
@@ -137,6 +253,92 @@ interface FlagsQuery {
     cursor?: string;
 }
 
+/**
+ * An invitation to an address with no account yet: to a team (teamId, as a member or admin) or to one app as its guest
+ * (appId). The address joins when it signs up and confirms itself. A live one (unexpired) holds its seat.
+ */
+interface InvitationRecord {
+    id: string;
+    teamId: string | null;
+    appId: string | null;
+    email: string;
+    role: string;
+    /** Null when its email couldn't be sent. */
+    sentAt: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+
+/**
+ * Someone with access to an app who has no wrapped copy of its key yet (GET /apps/keys/pending), with when they last
+ * replaced their account key: null if never, missing from an API before key pins.
+ */
+interface PendingAppKey {
+    appId: string;
+    userId: string;
+    publicKey: string;
+    keyChangedAt?: string | null;
+}
+/**
+ * Someone who reads one of the caller's apps and already has a wrapped copy of its key (GET /apps/keys/holders).
+ */
+interface KeyHolder {
+    userId: string;
+    publicKey: string;
+}
+/**
+ * Body of PUT /apps/:id/keys/:userId: the app key wrapped to that user's account key.
+ */
+interface AppKeyUpsertBody {
+    encryptedKey: string;
+}
+/**
+ * An account key a user has accepted for someone they share apps with (GET /key-pins). `mac` is an HMAC by the user's
+ * own devices, under a key derived from their account key, over the user, the person and the key: the server can drop
+ * a pin but not forge or move one.
+ */
+interface KeyPin {
+    userId: string;
+    publicKey: string;
+    mac: string;
+}
+type KeyCheckResult = 'confirmed' | 'failed' | 'cancelled';
+/**
+ * A key check the caller started, as their devices read it (GET /key-checks/mine): enough to show the code again or
+ * finish the check. The messages are a password-authenticated exchange the server can't read or test codes against.
+ */
+interface HolderKeyCheck {
+    id: string;
+    userId: string;
+    sid: string;
+    holderMessage: string;
+    /** The holder's half of the exchange, sealed under their account key. */
+    holderState: string;
+    claimantMessage: string | null;
+    publicKey: string | null;
+    tag: string | null;
+    answeredAt: string | null;
+    result: KeyCheckResult | null;
+    finishedAt: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+/**
+ * A key check waiting on the caller's answer, or how a recent answer went (GET /key-checks/for-me).
+ */
+interface ClaimantKeyCheck {
+    id: string;
+    holderId: string;
+    holderName: string;
+    sid: string;
+    holderMessage: string;
+    answeredAt: string | null;
+    result: KeyCheckResult | null;
+    finishedAt: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+
 /**
  * Structured log context content.
  */
@@ -235,6 +437,47 @@ interface NotesQuery {
     cursor?: string;
 }
 
+/**
+ * The `data` a push notification carries, which the app reads to open the screen it's about. Expo delivers data as
+ * JSON, but some platforms want strings, so every value is one.
+ */
+type PushData = 
+/** A log at or above the reader's threshold (Lumber-Worker). `level` is the LogLevel as a string. */
+{
+    type: 'log';
+    appId: string;
+    logId: string;
+    level: string;
+}
+/** A note from someone else on an app the reader reads (Lumber-API). */
+ | {
+    type: 'note';
+    appId: string;
+    noteId: string;
+}
+/** A new device asking to link to the account (Lumber-Worker). */
+ | {
+    type: 'device_link';
+    deviceLinkId: string;
+    deviceName: string;
+}
+/** The person the reader gave a code entered it (Lumber-API). */
+ | {
+    type: 'key_check';
+    checkId: string;
+}
+/** Someone is waiting for the reader to confirm their key, as new or changed (Lumber-API). */
+ | {
+    type: 'key_waiting';
+    userId: string;
+}
+/** Someone wrapped app keys for the reader. `appId` when it was one app (Lumber-API). */
+ | {
+    type: 'keys_shared';
+    appId?: string;
+};
+type PushType = PushData['type'];
+
 interface ResponseMetadata {
     requestId: string;
     durationMs: number;
@@ -249,37 +492,45 @@ interface ApiResponse<T> {
     metadata: ResponseMetadata;
 }
 
+/** An app as the socket sends it: no wrapped keys, so a client refetches through the API for its own copy. */
+type SocketAppPayload = Pick<AppRecord, 'id' | 'name' | 'teamId' | 'color' | 'imageUrl' | 'createdAt' | 'updatedAt'>;
 /**
- * An organization that owns apps and pays for member usage.
- * Team subscriptionLevel takes precedence over individual member levels.
+ * What Lumber-Socket sends a client, for socket.io's typed `Server` and `Socket`. Each goes to the users who can read
+ * the app it's about, live updates permitting (the app's team's plan); flags go to the user who set them.
  */
-interface TeamRecord {
-    id: string;
-    createdAt: string;
-    updatedAt: string;
-    name: string;
-    color?: string;
-    imageUrl?: string;
-    subscriptionLevel: SubscriptionLevel;
-}
-/**
- * Membership of a user in a team.
- */
-interface TeamMemberRecord {
-    id: string;
-    createdAt: string;
-    updatedAt: string;
-    teamId: string;
-    userId: string;
-    role: 'owner' | 'admin' | 'member';
-}
-/**
- * Filter params for GET /teams.
- */
-interface TeamsQuery {
-    sort?: string;
-    limit?: number;
-    cursor?: string;
+interface ServerToClientEvents {
+    'log:created': (log: Omit<LogRecord, 'updatedAt'> & {
+        updatedAt?: string;
+    }) => void;
+    'flag:created': (flag: Omit<FlagRecord, 'updatedAt'> & {
+        updatedAt?: string;
+    }) => void;
+    'flag:deleted': (flag: Pick<FlagRecord, 'id'>) => void;
+    'note:created': (note: NoteRecord) => void;
+    'note:updated': (note: NoteRecord) => void;
+    'note:deleted': (note: Pick<NoteRecord, 'id' | 'appId'>) => void;
+    'app:created': (app: SocketAppPayload) => void;
+    'app:updated': (app: SocketAppPayload) => void;
+    /** Deleted, or kept to its team's owner and so gone for the rest of the team. */
+    'app:deleted': (app: Pick<AppRecord, 'id'>) => void;
+    /** Someone joined or left a team or app the user is on. Carries nothing; sent on every plan. */
+    'access:changed': (payload: Record<string, never>) => void;
+    /**
+     * The socket's database connection came back after a gap and has replayed what it could. Deletes, and anything older
+     * or past the replay's cap, need the client's own resync.
+     */
+    'socket:reconnected': () => void;
+    /** The answer to `listMyApps`: the apps the user gets live updates for. */
+    myApps: (payload: {
+        apps: Pick<AppRecord, 'id' | 'name'>[];
+    }) => void;
+    error: (payload: {
+        message: string;
+    }) => void;
+}
+/** What a client sends Lumber-Socket. */
+interface ClientToServerEvents {
+    listMyApps: () => void;
 }
 
 /**
@@ -317,6 +568,8 @@ interface PushToken {
     token: string;
     deviceId?: string;
     platform?: 'ios' | 'android' | 'web';
+    /** The device's IANA time zone, so a push can say a log's time as the device would. */
+    timeZone?: string;
 }
 interface NotificationPreference {
     enabled?: boolean;
@@ -326,6 +579,8 @@ interface NotificationPreference {
 interface NotificationPreferences {
     enabled?: boolean;
     minimumLevel?: number;
+    /** Whether new notes on the user's apps push; on unless false. */
+    notes?: boolean;
     perApp?: Record<string, NotificationPreference>;
 }
 /**
@@ -344,6 +599,10 @@ interface UserRecord {
     agreedToTermsVersion?: string;
     notificationPreferences: NotificationPreferences;
     pushTokens: PushToken[];
+    /** When the address was confirmed, null until it is. Missing from an API before email confirmation. */
+    emailVerifiedAt?: string | null;
+    /** Per app, when the user last had its notes open, from any device. Missing from an API before it was kept. */
+    notesReadAt?: Record<string, string>;
 }
 
 declare const isValidAppearance: (value: unknown) => value is Appearance;
@@ -355,5 +614,26 @@ declare const isValidDeviceLinkStatus: (value: unknown) => value is DeviceLinkSt
 declare const isValidTeamMemberRole: (value: unknown) => value is TeamMemberRecord["role"];
 /** Accepts any valid absolute URL (https://..., http://..., etc.). */
 declare const isValidImageUrl: (value: unknown) => value is string;
+/**
+ * The API key the Lumber app hands out: an app's API token and its encryption key, joined as `<token>.<encryptionKey>`,
+ * so a plugin is configured with one secret. A plugin sends only the token to the API (`Authorization: Bearer <token>`)
+ * and encrypts with the rest, so the encryption key never leaves it. Neither half can contain a `.` (hex and base64).
+ */
+declare const joinApiKey: (token: string, encryptionKey: string) => string;
+/** Splits an API key into its token and encryption key. A value with no dot is all token. */
+declare const splitApiKey: (apiKey: string) => {
+    token: string;
+    encryptionKey?: string;
+};
+/**
+ * A push threshold from a stored or sent preference: a log level, or PUSH_OFF for anything past Fatal. Below Debug is
+ * Debug, a fraction rounds, and anything that isn't a finite number is the default (Warn).
+ */
+declare const normalizePushThreshold: (value: unknown) => PushThreshold;
+declare const isApiErrorCode: (value: unknown) => value is ApiErrorCode;
+/** The code in an API error response's body, or null when it has none. */
+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 { type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppRecord, type Appearance, type AppsQuery, type DeviceLinkCreatedRecord, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, 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, type PushToken, type ResponseMetadata, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, logLevelNameToLevel, logLevelToName, logLevels, subscriptionLevelToName, subscriptionLevels, subscriptionLimits };
+export { 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_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, logLevelNameToLevel, logLevelToName, logLevels, normalizePushThreshold, parsePushData, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };

package/dist/index.js

@@ -20,8 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_PUSH_THRESHOLD: () => DEFAULT_PUSH_THRESHOLD,
   LogLevel: () => LogLevel,
+  PUSH_OFF: () => PUSH_OFF,
   SubscriptionLevel: () => SubscriptionLevel,
+  apiErrorCodeOf: () => apiErrorCodeOf,
+  apiErrorCodes: () => apiErrorCodes,
+  isApiErrorCode: () => isApiErrorCode,
   isValidAppearance: () => isValidAppearance,
   isValidColor: () => isValidColor,
   isValidDeviceLinkStatus: () => isValidDeviceLinkStatus,
@@ -29,23 +34,46 @@ __export(index_exports, {
   isValidLogLevel: () => isValidLogLevel,
   isValidSubscriptionLevel: () => isValidSubscriptionLevel,
   isValidTeamMemberRole: () => isValidTeamMemberRole,
+  joinApiKey: () => joinApiKey,
   logLevelNameToLevel: () => logLevelNameToLevel,
   logLevelToName: () => logLevelToName,
   logLevels: () => logLevels,
+  normalizePushThreshold: () => normalizePushThreshold,
+  parsePushData: () => parsePushData,
+  splitApiKey: () => splitApiKey,
   subscriptionLevelToName: () => subscriptionLevelToName,
   subscriptionLevels: () => subscriptionLevels,
-  subscriptionLimits: () => subscriptionLimits
+  subscriptionLimits: () => subscriptionLimits,
+  subscriptionPlans: () => subscriptionPlans
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/constants/errors.ts
+var apiErrorCodes = [
+  /** 403: the team's plan has no room for another app. */
+  "APP_LIMIT",
+  /** 403: the team's plan has no room for another member (members and live invitations). */
+  "SEAT_LIMIT",
+  /** 403: the app's team's plan has no room for another guest on it (guests and live invitations). */
+  "GUEST_LIMIT",
+  /** 409: the person invited is already on the team. */
+  "ALREADY_MEMBER",
+  /** 409: the person invited can already read the app. */
+  "ALREADY_READS",
+  /** 409: the address invited already has an open invitation. */
+  "ALREADY_INVITED",
+  /** 409: the address invited already has an account, so invite the person instead. */
+  "HAS_ACCOUNT"
+];
+
 // src/constants/logLevel.ts
-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;
+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;
 })(LogLevel || {});
 var logLevelToName = {
   [0 /* Debug */]: "debug",
@@ -63,6 +91,10 @@ var logLevelNameToLevel = {
 };
 var logLevels = [0 /* Debug */, 1 /* Info */, 2 /* Warn */, 3 /* Error */, 4 /* Fatal */];
 
+// src/constants/notifications.ts
+var PUSH_OFF = 5;
+var DEFAULT_PUSH_THRESHOLD = 2 /* Warn */;
+
 // src/constants/subscription.ts
 var SubscriptionLevel = /* @__PURE__ */ ((SubscriptionLevel3) => {
   SubscriptionLevel3[SubscriptionLevel3["Hobby"] = 0] = "Hobby";
@@ -84,6 +116,12 @@ var subscriptionLimits = {
   [2 /* Pro */]: { apps: 20, seats: 20, apiKeys: 15, logRetentionDays: 90, monthlyLogs: 2e6, realtimeLogs: true, minPushLevel: 2 /* Warn */ },
   [3 /* Enterprise */]: { apps: Infinity, seats: Infinity, apiKeys: Infinity, logRetentionDays: Infinity, monthlyLogs: Infinity, realtimeLogs: true, minPushLevel: 0 /* Debug */ }
 };
+var subscriptionPlans = {
+  [0 /* Hobby */]: { name: "Hobby", monthlyPrice: 0 },
+  [1 /* Dev */]: { name: "Dev", monthlyPrice: 9 },
+  [2 /* Pro */]: { name: "Pro", monthlyPrice: 39 },
+  [3 /* Enterprise */]: { name: "Enterprise", monthlyPrice: null }
+};
 
 // src/utils/index.ts
 var appearanceValues = ["system", "dark", "light"];
@@ -104,10 +142,55 @@ var isValidImageUrl = (value) => {
     return false;
   }
 };
+var joinApiKey = (token, encryptionKey) => `${token}.${encryptionKey}`;
+var splitApiKey = (apiKey) => {
+  const value = apiKey.trim();
+  const dot = value.indexOf(".");
+  if (dot === -1) return { token: value };
+  return { token: value.slice(0, dot), encryptionKey: value.slice(dot + 1) };
+};
+var normalizePushThreshold = (value) => {
+  const level = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+  if (!Number.isFinite(level)) return DEFAULT_PUSH_THRESHOLD;
+  if (level > 4 /* Fatal */) return PUSH_OFF;
+  if (level <= 0 /* Debug */) return 0 /* Debug */;
+  return Math.round(level);
+};
+var isApiErrorCode = (value) => apiErrorCodes.includes(value);
+var apiErrorCodeOf = (body) => {
+  const code = body && typeof body === "object" ? body.code : void 0;
+  return isApiErrorCode(code) ? code : null;
+};
+var isId = (value) => typeof value === "string" && value.length > 0;
+var parsePushData = (data) => {
+  if (!data || typeof data !== "object") return null;
+  const d = data;
+  switch (d.type) {
+    case "log":
+      return isId(d.appId) && isId(d.logId) ? { type: "log", appId: d.appId, logId: d.logId, level: String(d.level ?? "") } : null;
+    case "note":
+      return isId(d.appId) && isId(d.noteId) ? { type: "note", appId: d.appId, noteId: d.noteId } : null;
+    case "device_link":
+      return isId(d.deviceLinkId) ? { type: "device_link", deviceLinkId: d.deviceLinkId, deviceName: typeof d.deviceName === "string" ? d.deviceName : "" } : null;
+    case "key_check":
+      return isId(d.checkId) ? { type: "key_check", checkId: d.checkId } : null;
+    case "key_waiting":
+      return isId(d.userId) ? { type: "key_waiting", userId: d.userId } : null;
+    case "keys_shared":
+      return isId(d.appId) ? { type: "keys_shared", appId: d.appId } : { type: "keys_shared" };
+    default:
+      return null;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_PUSH_THRESHOLD,
   LogLevel,
+  PUSH_OFF,
   SubscriptionLevel,
+  apiErrorCodeOf,
+  apiErrorCodes,
+  isApiErrorCode,
   isValidAppearance,
   isValidColor,
   isValidDeviceLinkStatus,
@@ -115,10 +198,15 @@ var isValidImageUrl = (value) => {
   isValidLogLevel,
   isValidSubscriptionLevel,
   isValidTeamMemberRole,
+  joinApiKey,
   logLevelNameToLevel,
   logLevelToName,
   logLevels,
+  normalizePushThreshold,
+  parsePushData,
+  splitApiKey,
   subscriptionLevelToName,
   subscriptionLevels,
-  subscriptionLimits
+  subscriptionLimits,
+  subscriptionPlans
 });

package/dist/index.mjs

@@ -1,11 +1,29 @@
+// src/constants/errors.ts
+var apiErrorCodes = [
+  /** 403: the team's plan has no room for another app. */
+  "APP_LIMIT",
+  /** 403: the team's plan has no room for another member (members and live invitations). */
+  "SEAT_LIMIT",
+  /** 403: the app's team's plan has no room for another guest on it (guests and live invitations). */
+  "GUEST_LIMIT",
+  /** 409: the person invited is already on the team. */
+  "ALREADY_MEMBER",
+  /** 409: the person invited can already read the app. */
+  "ALREADY_READS",
+  /** 409: the address invited already has an open invitation. */
+  "ALREADY_INVITED",
+  /** 409: the address invited already has an account, so invite the person instead. */
+  "HAS_ACCOUNT"
+];
+
 // src/constants/logLevel.ts
-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;
+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;
 })(LogLevel || {});
 var logLevelToName = {
   [0 /* Debug */]: "debug",
@@ -23,6 +41,10 @@ var logLevelNameToLevel = {
 };
 var logLevels = [0 /* Debug */, 1 /* Info */, 2 /* Warn */, 3 /* Error */, 4 /* Fatal */];
 
+// src/constants/notifications.ts
+var PUSH_OFF = 5;
+var DEFAULT_PUSH_THRESHOLD = 2 /* Warn */;
+
 // src/constants/subscription.ts
 var SubscriptionLevel = /* @__PURE__ */ ((SubscriptionLevel3) => {
   SubscriptionLevel3[SubscriptionLevel3["Hobby"] = 0] = "Hobby";
@@ -44,6 +66,12 @@ var subscriptionLimits = {
   [2 /* Pro */]: { apps: 20, seats: 20, apiKeys: 15, logRetentionDays: 90, monthlyLogs: 2e6, realtimeLogs: true, minPushLevel: 2 /* Warn */ },
   [3 /* Enterprise */]: { apps: Infinity, seats: Infinity, apiKeys: Infinity, logRetentionDays: Infinity, monthlyLogs: Infinity, realtimeLogs: true, minPushLevel: 0 /* Debug */ }
 };
+var subscriptionPlans = {
+  [0 /* Hobby */]: { name: "Hobby", monthlyPrice: 0 },
+  [1 /* Dev */]: { name: "Dev", monthlyPrice: 9 },
+  [2 /* Pro */]: { name: "Pro", monthlyPrice: 39 },
+  [3 /* Enterprise */]: { name: "Enterprise", monthlyPrice: null }
+};
 
 // src/utils/index.ts
 var appearanceValues = ["system", "dark", "light"];
@@ -64,9 +92,54 @@ var isValidImageUrl = (value) => {
     return false;
   }
 };
+var joinApiKey = (token, encryptionKey) => `${token}.${encryptionKey}`;
+var splitApiKey = (apiKey) => {
+  const value = apiKey.trim();
+  const dot = value.indexOf(".");
+  if (dot === -1) return { token: value };
+  return { token: value.slice(0, dot), encryptionKey: value.slice(dot + 1) };
+};
+var normalizePushThreshold = (value) => {
+  const level = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+  if (!Number.isFinite(level)) return DEFAULT_PUSH_THRESHOLD;
+  if (level > 4 /* Fatal */) return PUSH_OFF;
+  if (level <= 0 /* Debug */) return 0 /* Debug */;
+  return Math.round(level);
+};
+var isApiErrorCode = (value) => apiErrorCodes.includes(value);
+var apiErrorCodeOf = (body) => {
+  const code = body && typeof body === "object" ? body.code : void 0;
+  return isApiErrorCode(code) ? code : null;
+};
+var isId = (value) => typeof value === "string" && value.length > 0;
+var parsePushData = (data) => {
+  if (!data || typeof data !== "object") return null;
+  const d = data;
+  switch (d.type) {
+    case "log":
+      return isId(d.appId) && isId(d.logId) ? { type: "log", appId: d.appId, logId: d.logId, level: String(d.level ?? "") } : null;
+    case "note":
+      return isId(d.appId) && isId(d.noteId) ? { type: "note", appId: d.appId, noteId: d.noteId } : null;
+    case "device_link":
+      return isId(d.deviceLinkId) ? { type: "device_link", deviceLinkId: d.deviceLinkId, deviceName: typeof d.deviceName === "string" ? d.deviceName : "" } : null;
+    case "key_check":
+      return isId(d.checkId) ? { type: "key_check", checkId: d.checkId } : null;
+    case "key_waiting":
+      return isId(d.userId) ? { type: "key_waiting", userId: d.userId } : null;
+    case "keys_shared":
+      return isId(d.appId) ? { type: "keys_shared", appId: d.appId } : { type: "keys_shared" };
+    default:
+      return null;
+  }
+};
 export {
+  DEFAULT_PUSH_THRESHOLD,
   LogLevel,
+  PUSH_OFF,
   SubscriptionLevel,
+  apiErrorCodeOf,
+  apiErrorCodes,
+  isApiErrorCode,
   isValidAppearance,
   isValidColor,
   isValidDeviceLinkStatus,
@@ -74,10 +147,15 @@ export {
   isValidLogLevel,
   isValidSubscriptionLevel,
   isValidTeamMemberRole,
+  joinApiKey,
   logLevelNameToLevel,
   logLevelToName,
   logLevels,
+  normalizePushThreshold,
+  parsePushData,
+  splitApiKey,
   subscriptionLevelToName,
   subscriptionLevels,
-  subscriptionLimits
+  subscriptionLimits,
+  subscriptionPlans
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infinitetoken/lumber-kit",
-  "version": "0.4.22",
+  "version": "0.5.0",
   "description": "Shared TypeScript types and wire format contracts for the Lumber cloud logging suite",
   "keywords": [
     "lumber",
@@ -56,9 +56,9 @@
   },
   "prettier": "@infinitetoken/eslint-config/prettier",
   "devDependencies": {
-    "@infinitetoken/eslint-config": "^0.1.6",
-    "@infinitetoken/jest-config": "^0.1.3",
-    "@infinitetoken/tsconfig": "^0.3.0",
+    "@infinitetoken/eslint-config": "^0.2.1",
+    "@infinitetoken/jest-config": "^0.5.2",
+    "@infinitetoken/tsconfig": "^0.6.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.0.0",
     "eslint": "^10.2.1",