@keeper-security/keeper-sdk-javascript 0.1.0

package/src/utils/constants.ts

@@ -0,0 +1,63 @@
+export const SdkDefaults = {
+    CLIENT_VERSION: 'c17.0.0',
+    DEVICE_NAME: 'JavaScript Keeper SDK',
+    CONFIG_DIR: '.keeper',
+    LOG_FORMAT: '!',
+} as const
+
+export const AuthDefaults = {
+    MAX_LOGIN_ATTEMPTS: 5,
+    APPROVAL_TIMEOUT_MS: 60_000,
+    CODE_VALIDATION_DELAY_MS: 2_000,
+} as const
+
+export enum AuthErrorCode {
+    InvalidCredentials = 'invalid_credentials',
+    MissingUsername = 'missing_username',
+    MissingPassword = 'missing_password',
+    MaxAttemptsExceeded = 'max_attempts_exceeded',
+    UserCancelled = 'user_cancelled',
+    Unsupported2FAChannel = 'unsupported_2fa_channel',
+}
+
+export enum SessionErrorCode {
+    NotLoggedIn = 'not_logged_in',
+    DeviceNotRegistered = 'device_not_registered',
+    NoPreviousLogin = 'no_previous_login',
+    NoCloneCode = 'no_clone_code',
+    PersistentLoginFailed = 'persistent_login_failed',
+    SessionTokenExpired = 'session_token_expired',
+}
+
+export enum TeamErrorCode {
+    TeamRequired = 'team_required',
+    TeamNotFound = 'team_not_found',
+    MultipleTeamMatches = 'multiple_team_matches',
+}
+
+export const ResultCodes = {
+    INVALID_CREDENTIALS: AuthErrorCode.InvalidCredentials,
+    MISSING_USERNAME: AuthErrorCode.MissingUsername,
+    MISSING_PASSWORD: AuthErrorCode.MissingPassword,
+    MAX_ATTEMPTS_EXCEEDED: AuthErrorCode.MaxAttemptsExceeded,
+    USER_CANCELLED: AuthErrorCode.UserCancelled,
+    UNSUPPORTED_2FA_CHANNEL: AuthErrorCode.Unsupported2FAChannel,
+    NOT_LOGGED_IN: SessionErrorCode.NotLoggedIn,
+    DEVICE_NOT_REGISTERED: SessionErrorCode.DeviceNotRegistered,
+    NO_PREVIOUS_LOGIN: SessionErrorCode.NoPreviousLogin,
+    NO_CLONE_CODE: SessionErrorCode.NoCloneCode,
+    PERSISTENT_LOGIN_FAILED: SessionErrorCode.PersistentLoginFailed,
+    SESSION_TOKEN_EXPIRED: SessionErrorCode.SessionTokenExpired,
+    TEAM_REQUIRED: TeamErrorCode.TeamRequired,
+    TEAM_NOT_FOUND: TeamErrorCode.TeamNotFound,
+    MULTIPLE_TEAM_MATCHES: TeamErrorCode.MultipleTeamMatches,
+} as const
+
+export const KEEPER_PUBLIC_HOSTS: Record<string, string> = {
+    US: 'keepersecurity.com',
+    EU: 'keepersecurity.eu',
+    AU: 'keepersecurity.com.au',
+    CA: 'keepersecurity.ca',
+    JP: 'keepersecurity.jp',
+    GOV: 'govcloud.keepersecurity.us',
+}

package/src/utils/errors.ts

@@ -0,0 +1,108 @@
+import type { KeeperError } from '@keeper-security/keeperapi'
+
+function parseJsonObjectIfPresent(s: string): Record<string, unknown> | null {
+    const t = s.trim()
+    if (t.length === 0 || (t[0] !== '{' && t[0] !== '[')) return null
+    try {
+        const parsed: unknown = JSON.parse(s)
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed as Record<string, unknown>
+        }
+    } catch {
+        /* not JSON */
+    }
+    return null
+}
+
+export function isKeeperError(err: unknown): err is KeeperError {
+    return (
+        err != null &&
+        typeof err === 'object' &&
+        !(err instanceof Error) &&
+        ('result_code' in err || 'error' in err || 'response_code' in err)
+    )
+}
+
+export function extractResultCode(err: unknown): string | undefined {
+    if (isKeeperError(err)) {
+        return err.result_code || err.error
+    }
+    if (err instanceof Error) {
+        const msg = err.message
+        if (msg.length > 0 && (msg[0] === '{' || msg[0] === '[')) {
+            try {
+                const parsed = JSON.parse(msg)
+                return parsed.result_code || parsed.error
+            } catch {}
+        }
+    }
+    if (typeof err === 'string') {
+        const parsed = parseJsonObjectIfPresent(err)
+        if (parsed) {
+            if (typeof parsed.result_code === 'string') return parsed.result_code
+            if (typeof parsed.error === 'string') return parsed.error
+        }
+        return err
+    }
+    if (typeof err === 'object' && err !== null) {
+        const obj = err as Record<string, unknown>
+        if (typeof obj.result_code === 'string') return obj.result_code
+        if (typeof obj.error === 'string') return obj.error
+    }
+    return undefined
+}
+
+export function extractErrorMessage(err: unknown): string {
+    if (isKeeperError(err)) {
+        return err.message || err.result_code || err.error || 'Unknown Keeper error'
+    }
+    if (err instanceof Error) {
+        const parsed = parseJsonObjectIfPresent(err.message)
+        if (parsed) {
+            if (typeof parsed.message === 'string') return parsed.message
+            if (typeof parsed.result_code === 'string') return parsed.result_code
+            if (typeof parsed.error === 'string') return parsed.error
+        }
+        return err.message
+    }
+    if (typeof err === 'string') {
+        const parsed = parseJsonObjectIfPresent(err)
+        if (parsed) {
+            if (typeof parsed.message === 'string') return parsed.message
+            if (typeof parsed.result_code === 'string') return parsed.result_code
+            if (typeof parsed.error === 'string') return parsed.error
+        }
+        return err
+    }
+    if (typeof err === 'object' && err !== null) {
+        const obj = err as Record<string, unknown>
+        if (typeof obj.message === 'string') return obj.message
+        if (typeof obj.result_code === 'string') return obj.result_code
+    }
+    return String(err)
+}
+
+export class KeeperSdkError extends Error {
+    readonly resultCode?: string
+    readonly keeperError?: KeeperError
+
+    constructor(message: string, resultCode?: string, keeperError?: KeeperError) {
+        super(message)
+        this.name = 'KeeperSdkError'
+        this.resultCode = resultCode
+        this.keeperError = keeperError
+    }
+
+    static from(err: unknown): KeeperSdkError {
+        if (err instanceof KeeperSdkError) return err
+        if (isKeeperError(err)) {
+            return new KeeperSdkError(
+                err.message || err.result_code || err.error || 'Unknown Keeper error',
+                err.result_code || err.error,
+                err
+            )
+        }
+        if (err instanceof Error) return new KeeperSdkError(err.message)
+        return new KeeperSdkError(extractErrorMessage(err))
+    }
+}

package/src/utils/guards.ts

@@ -0,0 +1,24 @@
+export function isBoolean(value: unknown): value is boolean {
+    return typeof value === 'boolean'
+}
+
+export function isString(value: unknown): value is string {
+    return typeof value === 'string'
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+    return typeof value === 'string' && value.trim().length > 0
+}
+
+export function isNumber(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value)
+}
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** True if at least one of the values is a boolean (true or false). */
+export function anyIsBoolean(...values: unknown[]): boolean {
+    return values.some(isBoolean)
+}

package/src/utils/index.ts

@@ -0,0 +1,22 @@
+export {
+    SdkDefaults,
+    AuthDefaults,
+    ResultCodes,
+    AuthErrorCode,
+    SessionErrorCode,
+    TeamErrorCode,
+    KEEPER_PUBLIC_HOSTS,
+} from './constants'
+export { Logger, ConsoleLogger, LogLevel, logger, setLogger, getLogger, resetLogger } from './Logger'
+export type { ILogger } from './Logger'
+export { KeeperSdkError, isKeeperError, extractErrorMessage, extractResultCode } from './errors'
+export type { Nullable, Optional, DeepPartial, Immutable } from './types'
+export { isBoolean, isString, isNonEmptyString, isNumber, isObject, anyIsBoolean } from './guards'
+export {
+    EMAIL_PATTERN,
+    EMAIL_LIST_SEPARATOR_PATTERN,
+    TOKEN_SEPARATOR_PATTERN,
+    REGEX_ESCAPE_PATTERN,
+    isValidEmail,
+    escapeRegExp,
+} from './patterns'

package/src/utils/patterns.ts

@@ -0,0 +1,20 @@
+export const EMAIL_PATTERN = /^[^\s@]+@[^\s@.]+\.[^\s@]+$/
+
+/** Splits user-entered email lists on whitespace, commas, and semicolons. */
+export const EMAIL_LIST_SEPARATOR_PATTERN = /[\s,;]+/
+
+/** Splits free-form text into search tokens on whitespace and common punctuation. */
+export const TOKEN_SEPARATOR_PATTERN = /[\s\-_.,;:!?@#$%^&*()[\]{}|\\/<>]+/
+
+/** Characters that must be escaped when embedding user input into a RegExp. */
+export const REGEX_ESCAPE_PATTERN = /[.+^${}()|[\]\\]/g
+
+const MAX_EMAIL_LENGTH = 254
+
+export function isValidEmail(value: string): boolean {
+    return value.length <= MAX_EMAIL_LENGTH && EMAIL_PATTERN.test(value)
+}
+
+export function escapeRegExp(value: string): string {
+    return value.replace(REGEX_ESCAPE_PATTERN, '\\$&')
+}

package/src/utils/types.ts

@@ -0,0 +1,11 @@
+/** A value of type T or null. Use this for caches and computed-but-empty results. */
+export type Nullable<T> = T | null
+
+/** A value of type T or undefined. Use this for "not provided" inputs. */
+export type Optional<T> = T | undefined
+
+/** Recursively makes every property optional. */
+export type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
+
+/** Helper to mark properties as readonly. */
+export type Immutable<T> = { readonly [K in keyof T]: T[K] }