@infinitetoken/lumber-kit 0.4.20 → 0.4.21

package/dist/index.d.mts

@@ -0,0 +1,359 @@
+/** Log severity level. Numeric values match the existing Lumber-API level field. */
+declare const enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3,
+    Fatal = 4
+}
+/** String name for each log level. */
+type LogLevelName = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** Maps numeric log level to its lowercase string name. */
+declare const logLevelToName: Record<number, LogLevelName>;
+/** Maps lowercase log level name to its numeric value. */
+declare const logLevelNameToLevel: Record<LogLevelName, LogLevel>;
+/** All valid log levels, ordered from least to most severe. */
+declare const logLevels: readonly LogLevel[];
+
+/** User subscription level. Mirrors User.subscriptionLevel in Lumber-API. */
+declare const enum SubscriptionLevel {
+    Hobby = 0,
+    Dev = 1,
+    Pro = 2,
+    Enterprise = 3
+}
+/** String name for each subscription level, suitable for display and Redux state. */
+type SubscriptionLevelName = 'hobby' | 'dev' | 'pro' | 'enterprise';
+/** Maps numeric subscription level to its string level name. */
+declare const subscriptionLevelToName: Record<SubscriptionLevel, SubscriptionLevelName>;
+/** All valid subscription levels, ordered from least to most severe. */
+declare const subscriptionLevels: readonly SubscriptionLevel[];
+type SubscriptionLimits = {
+    apps: number;
+    seats: number;
+    apiKeys: number;
+    logRetentionDays: number;
+    monthlyLogs: number;
+    /** Whether real-time WebSocket log streaming is available. */
+    realtimeLogs: boolean;
+    /** Minimum log level that triggers a push notification. Infinity means push is disabled. */
+    minPushLevel: number;
+};
+/** Per-level resource limits. Use Infinity to mean unlimited or disabled. */
+declare const subscriptionLimits: Record<SubscriptionLevel, SubscriptionLimits>;
+
+/**
+ * Wrapped application encryption key for a specific user.
+ */
+interface AppEncryptedKey {
+    userId: string;
+    encryptedKey: string;
+    keyVersion: number;
+}
+/**
+ * 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.
+ */
+interface AppRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    name: string;
+    color?: string;
+    imageUrl?: string;
+    teamId?: string;
+    encryptedKey: string | null;
+}
+/**
+ * App creation response.
+ * Initial wrapped encryption key may optionally be returned.
+ */
+interface AppCreatedRecord extends AppRecord {
+    apiKey?: string;
+}
+/**
+ * Machine authentication credential.
+ */
+interface ApiKeyRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    name?: string;
+}
+/**
+ * External guest granted access to a specific app without being a team member.
+ */
+interface GuestRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    userId: string;
+    role: 'owner' | 'admin' | 'read' | 'write';
+}
+/**
+ * Filter params for GET /apps.
+ */
+interface AppsQuery {
+    teamId?: string;
+    from?: string;
+    to?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+type DeviceLinkStatus = 'pending' | 'approved' | 'denied';
+/**
+ * Response from POST /device-links.
+ */
+interface DeviceLinkCreatedRecord {
+    id: string;
+    expiresAt: string;
+}
+/**
+ * Response from GET /device-links/:id.
+ * encryptedKey is present only when status is 'approved'.
+ */
+interface DeviceLinkRecord {
+    id: string;
+    status: DeviceLinkStatus;
+    encryptedKey?: string;
+    expiresAt: string;
+}
+
+interface FlagRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    logId: string;
+    userId: string;
+}
+interface FlagsQuery {
+    from?: string;
+    to?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+/**
+ * Structured log context content.
+ */
+interface LogContext {
+    code?: string;
+    method?: string;
+    line?: number;
+    column?: number;
+    note?: string;
+    [key: string]: unknown;
+}
+/**
+ * Encrypted envelope stored on the server.
+ * payload = base64(authTag + ciphertext)
+ * nonce = base64(random IV)
+ * keyVersion enables future rotation support.
+ */
+interface LogEncrypted {
+    nonce: string;
+    payload: string;
+    keyVersion: number;
+}
+/**
+ * Plaintext shape of log content — encrypted before sending, never stored plaintext on server.
+ */
+interface LogPayload {
+    level: LogLevel;
+    message: string;
+    requestId?: string;
+    traceId?: string;
+    context?: LogContext;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * API response shape for a stored log.
+ * level is plaintext for server-side notification routing; all content is inside encrypted.
+ */
+interface LogRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    level: LogLevel;
+    encrypted: LogEncrypted;
+}
+/**
+ * Sync-protocol params for GET /logs.
+ */
+interface LogsQuery {
+    appIds?: string[];
+    levels?: number[];
+    from?: string;
+    to?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+/**
+ * Encrypted note content.
+ * payload = base64(authTag + ciphertext)
+ * nonce = base64(random IV)
+ * keyVersion enables future key rotation.
+ */
+interface NoteEncrypted {
+    payload: string;
+    nonce: string;
+    keyVersion: number;
+}
+/**
+ * A short user-authored note, encrypted with the app key.
+ * Visible to all members of the associated app.
+ * Query by teamId in NotesQuery to build a cross-app team feed.
+ */
+interface NoteRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    userId: string;
+    logId?: string;
+    encrypted: NoteEncrypted;
+}
+/**
+ * Filter params for GET /notes.
+ */
+interface NotesQuery {
+    appId?: string;
+    teamId?: string;
+    userId?: string;
+    logId?: string;
+    from?: string;
+    to?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+interface ResponseMetadata {
+    requestId: string;
+    durationMs: number;
+    warnings?: string[];
+    cursor?: string | null;
+    hasMore?: boolean;
+    count?: number;
+    hiddenCount?: number;
+}
+interface ApiResponse<T> {
+    data: T;
+    metadata: ResponseMetadata;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+
+/**
+ * A single time bucket in a timeseries response.
+ * date is an ISO date string (YYYY-MM-DD for 'day', ISO datetime for 'hour').
+ * byLevel optionally breaks down the count per LogLevel for severity-tinted rendering.
+ */
+interface TimeseriesBucket {
+    date: string;
+    count: number;
+    byLevel?: Partial<Record<number, number>>;
+}
+/**
+ * Generic timeseries aggregate response. Reusable across logs, notifications, messages, etc.
+ */
+interface TimeseriesResponse {
+    buckets: TimeseriesBucket[];
+    from: string;
+    to: string;
+    interval: 'day' | 'hour';
+}
+/**
+ * Filter params for GET /logs/timeseries.
+ */
+interface LogTimeseriesQuery {
+    appIds?: string[];
+    levels?: number[];
+    from?: string;
+    to?: string;
+    interval?: 'day' | 'hour';
+}
+
+type Appearance = 'system' | 'dark' | 'light';
+interface PushToken {
+    token: string;
+    deviceId?: string;
+    platform?: 'ios' | 'android' | 'web';
+}
+interface NotificationPreference {
+    enabled?: boolean;
+    minimumLevel?: number;
+    lastReadAt?: string;
+}
+interface NotificationPreferences {
+    enabled?: boolean;
+    minimumLevel?: number;
+    perApp?: Record<string, NotificationPreference>;
+}
+/**
+ * Public user profile returned from API.
+ */
+interface UserRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    email: string;
+    name?: string;
+    publicKey?: string;
+    appearance?: Appearance;
+    color?: string;
+    imageUrl?: string;
+    agreedToTermsVersion?: string;
+    notificationPreferences: NotificationPreferences;
+    pushTokens: PushToken[];
+}
+
+declare const isValidAppearance: (value: unknown) => value is Appearance;
+/** Accepts 3- and 6-digit hex color strings (#rgb, #rrggbb). */
+declare const isValidColor: (value: string) => boolean;
+declare const isValidLogLevel: (value: unknown) => value is LogLevel;
+declare const isValidSubscriptionLevel: (value: unknown) => value is SubscriptionLevel;
+declare const isValidDeviceLinkStatus: (value: unknown) => value is DeviceLinkStatus;
+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;
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,359 @@
+/** Log severity level. Numeric values match the existing Lumber-API level field. */
+declare const enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3,
+    Fatal = 4
+}
+/** String name for each log level. */
+type LogLevelName = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** Maps numeric log level to its lowercase string name. */
+declare const logLevelToName: Record<number, LogLevelName>;
+/** Maps lowercase log level name to its numeric value. */
+declare const logLevelNameToLevel: Record<LogLevelName, LogLevel>;
+/** All valid log levels, ordered from least to most severe. */
+declare const logLevels: readonly LogLevel[];
+
+/** User subscription level. Mirrors User.subscriptionLevel in Lumber-API. */
+declare const enum SubscriptionLevel {
+    Hobby = 0,
+    Dev = 1,
+    Pro = 2,
+    Enterprise = 3
+}
+/** String name for each subscription level, suitable for display and Redux state. */
+type SubscriptionLevelName = 'hobby' | 'dev' | 'pro' | 'enterprise';
+/** Maps numeric subscription level to its string level name. */
+declare const subscriptionLevelToName: Record<SubscriptionLevel, SubscriptionLevelName>;
+/** All valid subscription levels, ordered from least to most severe. */
+declare const subscriptionLevels: readonly SubscriptionLevel[];
+type SubscriptionLimits = {
+    apps: number;
+    seats: number;
+    apiKeys: number;
+    logRetentionDays: number;
+    monthlyLogs: number;
+    /** Whether real-time WebSocket log streaming is available. */
+    realtimeLogs: boolean;
+    /** Minimum log level that triggers a push notification. Infinity means push is disabled. */
+    minPushLevel: number;
+};
+/** Per-level resource limits. Use Infinity to mean unlimited or disabled. */
+declare const subscriptionLimits: Record<SubscriptionLevel, SubscriptionLimits>;
+
+/**
+ * Wrapped application encryption key for a specific user.
+ */
+interface AppEncryptedKey {
+    userId: string;
+    encryptedKey: string;
+    keyVersion: number;
+}
+/**
+ * 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.
+ */
+interface AppRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    name: string;
+    color?: string;
+    imageUrl?: string;
+    teamId?: string;
+    encryptedKey: string | null;
+}
+/**
+ * App creation response.
+ * Initial wrapped encryption key may optionally be returned.
+ */
+interface AppCreatedRecord extends AppRecord {
+    apiKey?: string;
+}
+/**
+ * Machine authentication credential.
+ */
+interface ApiKeyRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    name?: string;
+}
+/**
+ * External guest granted access to a specific app without being a team member.
+ */
+interface GuestRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    userId: string;
+    role: 'owner' | 'admin' | 'read' | 'write';
+}
+/**
+ * Filter params for GET /apps.
+ */
+interface AppsQuery {
+    teamId?: string;
+    from?: string;
+    to?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+type DeviceLinkStatus = 'pending' | 'approved' | 'denied';
+/**
+ * Response from POST /device-links.
+ */
+interface DeviceLinkCreatedRecord {
+    id: string;
+    expiresAt: string;
+}
+/**
+ * Response from GET /device-links/:id.
+ * encryptedKey is present only when status is 'approved'.
+ */
+interface DeviceLinkRecord {
+    id: string;
+    status: DeviceLinkStatus;
+    encryptedKey?: string;
+    expiresAt: string;
+}
+
+interface FlagRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    logId: string;
+    userId: string;
+}
+interface FlagsQuery {
+    from?: string;
+    to?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+/**
+ * Structured log context content.
+ */
+interface LogContext {
+    code?: string;
+    method?: string;
+    line?: number;
+    column?: number;
+    note?: string;
+    [key: string]: unknown;
+}
+/**
+ * Encrypted envelope stored on the server.
+ * payload = base64(authTag + ciphertext)
+ * nonce = base64(random IV)
+ * keyVersion enables future rotation support.
+ */
+interface LogEncrypted {
+    nonce: string;
+    payload: string;
+    keyVersion: number;
+}
+/**
+ * Plaintext shape of log content — encrypted before sending, never stored plaintext on server.
+ */
+interface LogPayload {
+    level: LogLevel;
+    message: string;
+    requestId?: string;
+    traceId?: string;
+    context?: LogContext;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * API response shape for a stored log.
+ * level is plaintext for server-side notification routing; all content is inside encrypted.
+ */
+interface LogRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    level: LogLevel;
+    encrypted: LogEncrypted;
+}
+/**
+ * Sync-protocol params for GET /logs.
+ */
+interface LogsQuery {
+    appIds?: string[];
+    levels?: number[];
+    from?: string;
+    to?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+/**
+ * Encrypted note content.
+ * payload = base64(authTag + ciphertext)
+ * nonce = base64(random IV)
+ * keyVersion enables future key rotation.
+ */
+interface NoteEncrypted {
+    payload: string;
+    nonce: string;
+    keyVersion: number;
+}
+/**
+ * A short user-authored note, encrypted with the app key.
+ * Visible to all members of the associated app.
+ * Query by teamId in NotesQuery to build a cross-app team feed.
+ */
+interface NoteRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    appId: string;
+    userId: string;
+    logId?: string;
+    encrypted: NoteEncrypted;
+}
+/**
+ * Filter params for GET /notes.
+ */
+interface NotesQuery {
+    appId?: string;
+    teamId?: string;
+    userId?: string;
+    logId?: string;
+    from?: string;
+    to?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+interface ResponseMetadata {
+    requestId: string;
+    durationMs: number;
+    warnings?: string[];
+    cursor?: string | null;
+    hasMore?: boolean;
+    count?: number;
+    hiddenCount?: number;
+}
+interface ApiResponse<T> {
+    data: T;
+    metadata: ResponseMetadata;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+
+/**
+ * A single time bucket in a timeseries response.
+ * date is an ISO date string (YYYY-MM-DD for 'day', ISO datetime for 'hour').
+ * byLevel optionally breaks down the count per LogLevel for severity-tinted rendering.
+ */
+interface TimeseriesBucket {
+    date: string;
+    count: number;
+    byLevel?: Partial<Record<number, number>>;
+}
+/**
+ * Generic timeseries aggregate response. Reusable across logs, notifications, messages, etc.
+ */
+interface TimeseriesResponse {
+    buckets: TimeseriesBucket[];
+    from: string;
+    to: string;
+    interval: 'day' | 'hour';
+}
+/**
+ * Filter params for GET /logs/timeseries.
+ */
+interface LogTimeseriesQuery {
+    appIds?: string[];
+    levels?: number[];
+    from?: string;
+    to?: string;
+    interval?: 'day' | 'hour';
+}
+
+type Appearance = 'system' | 'dark' | 'light';
+interface PushToken {
+    token: string;
+    deviceId?: string;
+    platform?: 'ios' | 'android' | 'web';
+}
+interface NotificationPreference {
+    enabled?: boolean;
+    minimumLevel?: number;
+    lastReadAt?: string;
+}
+interface NotificationPreferences {
+    enabled?: boolean;
+    minimumLevel?: number;
+    perApp?: Record<string, NotificationPreference>;
+}
+/**
+ * Public user profile returned from API.
+ */
+interface UserRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    email: string;
+    name?: string;
+    publicKey?: string;
+    appearance?: Appearance;
+    color?: string;
+    imageUrl?: string;
+    agreedToTermsVersion?: string;
+    notificationPreferences: NotificationPreferences;
+    pushTokens: PushToken[];
+}
+
+declare const isValidAppearance: (value: unknown) => value is Appearance;
+/** Accepts 3- and 6-digit hex color strings (#rgb, #rrggbb). */
+declare const isValidColor: (value: string) => boolean;
+declare const isValidLogLevel: (value: unknown) => value is LogLevel;
+declare const isValidSubscriptionLevel: (value: unknown) => value is SubscriptionLevel;
+declare const isValidDeviceLinkStatus: (value: unknown) => value is DeviceLinkStatus;
+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;
+
+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 };