@ikonintegration/ikapi 4.0.1 → 5.0.0

package/src/Config/Configuration.ts

@@ -0,0 +1,199 @@
+import MemCache from 'node-cache'
+import DurationParser from 'parse-duration'
+
+import EnvironmentVar, { EnvironmentType } from './EnvironmentVar.js'
+
+// Hold cached values at nodeVM level
+// eslint-disable-next-line no-var
+/**
+ * Creates a new instance of a memory cache store.
+ * @returns {MemCache} A new instance of a memory cache store.
+ */
+let cacheStore = new MemCache()
+
+/**
+ * Represents the schema for the configuration object.
+ * @typedef {Object} ConfigurationSchema
+ * @property {Object} [name] - The name of the configuration property.
+ * @property {boolean} [name.isLocal] - Indicates if the property is for local use.
+ * @property {boolean} [name.isRemote] - Indicates if the property is for remote use.
+ * @property {boolean} [name.required] - Indicates if the property is required.
+ * @property {string} [name.cachingPolicy] - The caching policy for the property.
+ * @property {string} [name.nameOverride] - The optional name override if the key differs
+ */
+export type ConfigurationSchema = {
+  [name: string]: {
+    isLocal?: boolean
+    isRemote?: boolean
+    isSecure?: boolean
+    required?: boolean
+    noPrefix?: boolean
+    cachingPolicy?: string
+    nameOverride?: string
+  }
+}
+
+/**
+ * Extracts the properties from a given type that have the `isRemote` property set to `true`.
+ * @param {Type} - The type to extract properties from.
+ * @returns An object type with the extracted properties.
+ */
+// runtime type infer to ConfigurationSchema keys, which type is remote
+type ExtractRemote<Type> = {
+  [Property in keyof Type]-?: Type[Property] extends {
+    isRemote: true
+  }
+    ? Property
+    : null
+}
+/**
+ * Extracts the properties from a given type that have the `isLocal` property set to `true`.
+ * @typeparam Type - The type to extract properties from.
+ * @returns An object type with the extracted properties as keys and their corresponding types.
+ */
+// runtime type infer to ConfigurationSchema keys, which type is local
+type ExtractLocal<Type> = {
+  [Property in keyof Type]-?: Type[Property] extends {
+    isLocal: true
+  }
+    ? Property
+    : null
+}
+
+/**
+ * Creates a new type by omitting keys from type T whose values are of type U.
+ * @param {T} - The original type
+ * @param {U} - The type to omit from T
+ * @returns A new type with the omitted keys
+ */
+// Helpers to filter null keys
+type OmitKeysByValueType<T, U> = {
+  [P in keyof T]: T[P] extends U ? never : P
+}[keyof T]
+/**
+ * Omit properties from an object type by their value type.
+ * @template T - The object type to omit properties from.
+ * @template V - The value type of properties to omit.
+ * @typedef OmitByValueType
+ * @property {T} T - The object type to omit properties from.
+ * @property {V} V - The value type of properties to omit.
+ * @returns {OmitKeysByValueType<T, V>} - The resulting object type after omitting properties.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, prettier/prettier
+type OmitByValueType<T, V> = T extends infer _ 
+  ? {
+      [key in OmitKeysByValueType<T, V>]: T[key]
+    }
+  : never
+
+/**
+ * Represents a configuration object with a specified schema and remote prefix.
+ * @template T - The type of the configuration schema.
+ */
+export default class Configuration<T extends ConfigurationSchema> {
+  /**
+   * The schema for the private readonly property.
+   * @type {T}
+   */
+  private readonly schema: T
+  /**
+   * The prefix used for remote resources.
+   * @type {string}
+   */
+  private readonly remotePrefix: string
+  /**
+   * Indicates if config is local and should attempt to override
+   * remote values from local.
+   * @type {string}
+   */
+  private static readonly isLocal: boolean = process.env.NODE_ENV == 'local'
+
+  /**
+   * Constructs a new instance of the class.
+   * @param {T} schema - The schema object.
+   * @param {string} remotePrefix - The remote prefix string.
+   * @returns None
+   */
+  constructor(schema: T, remotePrefix: string) {
+    this.schema = schema
+    this.remotePrefix = remotePrefix
+  }
+
+  /**
+   * Retrieves the value of a property from the environment variables or cache.
+   * @param {keyof OmitByValueType<ExtractLocal<T>, null>} propName - The name of the property to retrieve.
+   * @returns The value of the property.
+   */
+  public get(propName: keyof OmitByValueType<ExtractLocal<T>, null>): any {
+    const propString = propName as string
+    const propSchema = this.schema[propString]
+    let v = this.getCachedValue(propString)
+    v =
+      v ||
+      new EnvironmentVar<string>(
+        propSchema.nameOverride || propString,
+        EnvironmentType.Local,
+        !propSchema.required,
+        !propSchema.noPrefix ? this.remotePrefix : ''
+      ).syncResolve()
+    this.cacheValue(propString, v, propSchema.cachingPolicy)
+    return v
+  }
+
+  /**
+   * Asynchronously retrieves the value of a property from the remote environment.
+   * @param {keyof OmitByValueType<ExtractRemote<T>, null>} propName - The name of the property to retrieve.
+   * @returns {Promise<any>} - A promise that resolves to the value of the property.
+   */
+  public async asyncGet(propName: keyof OmitByValueType<ExtractRemote<T>, null>): Promise<any> {
+    const propString = propName as string
+    const propSchema = this.schema[propString]
+    // check cache
+    let v = this.getCachedValue(propString)
+    if (v !== undefined) return v
+    // check for local override
+    if (Configuration.isLocal && process.env[propString] !== undefined) {
+      console.log(`Overriding remote variable ${propString} with local value!`)
+      const v = process.env[propString]
+      this.cacheValue(propString, v, propSchema.cachingPolicy)
+      return v
+    }
+    // remote
+    v = await new EnvironmentVar<string>(
+      propSchema.nameOverride || propString,
+      propSchema.isSecure ? EnvironmentType.SecureRemote : EnvironmentType.PlainRemote,
+      !propSchema.required,
+      !propSchema.noPrefix ? this.remotePrefix : ''
+    ).resolve()
+    this.cacheValue(propString, v, propSchema.cachingPolicy)
+    return v
+  }
+
+  /**
+   * Retrieves the cached value associated with the given key from the cache store.
+   * @param {string} valueKey - The key of the value to retrieve from the cache.
+   * @returns The cached value associated with the given key, or undefined if the key does not exist in the cache.
+   */
+  private getCachedValue(valueKey: string): any {
+    return cacheStore.get(valueKey)
+  }
+
+  /**
+   * Caches a value with the specified key and expiration policy.
+   * @param {string} valueKey - The key to associate with the cached value.
+   * @param {any} value - The value to be cached.
+   * @param {string} [policy='1d'] - The expiration policy for the cached value. Defaults to '1d' (1 day).
+   * @returns None
+   */
+  private cacheValue(valueKey: string, value: any, policy: string = '1d'): void {
+    cacheStore.set(valueKey, value, DurationParser(policy, 's') || '')
+  }
+
+  /**
+   * Resets the cache by creating a new instance of the MemCache class and assigning it to the cacheStore variable.
+   * @returns None
+   */
+  private resetCache() {
+    cacheStore = new MemCache()
+  }
+}

package/src/Config/EnvironmentVar.ts

@@ -0,0 +1,142 @@
+import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager'
+import { SSMClient, GetParameterCommand } from '@aws-sdk/client-ssm'
+
+// Explicity setting VM level variables in order to persist
+// client across different important and instances.
+// eslint-disable-next-line no-var
+/**
+ * Variables to hold instances of SSMClient and SecretsManagerClient, initialized as null.
+ * @type {SSMClient | null} ssmClient - Instance of SSMClient or null if not initialized.
+ * @type {SecretsManagerClient | null} secretsClient - Instance of SecretsManagerClient or null if not initialized.
+ */
+let ssmClient: SSMClient | null = null,
+  secretsClient: SecretsManagerClient | null = null
+
+/**
+ * An enumeration representing different types of environments.
+ * @enum {number}
+ * @readonly
+ * @property {number} PlainRemote - Represents a plain remote environment.
+ * @property {number} SecureRemote - Represents a secure remote environment.
+ * @property {number} Local - Represents a local environment.
+ */
+export enum EnvironmentType {
+  PlainRemote,
+  SecureRemote,
+  Local,
+}
+/**
+ * Represents an environment variable with methods to resolve its value based on the environment type.
+ * @template T - The type of the environment variable value.
+ */
+export default class EnvironmentVar<T> {
+  /**
+   * The name of the parameter.
+   */
+  private readonly paramName: string
+  /**
+   * The type of environment.
+   * @readonly
+   */
+  private readonly type: EnvironmentType
+  /**
+   * A boolean flag indicating whether the field is optional or not.
+   */
+  private readonly optional: boolean
+  /**
+   * The prefix used for parameters in the class.
+   * @type {string}
+   */
+  private readonly paramPrefix: string
+
+  /**
+   * Constructs a new instance of the EnvironmentVar class.
+   * @param {string} paramName - The name of the environment variable.
+   * @param {EnvironmentType} type - The type of the environment.
+   * @param {boolean} [optional] - Indicates whether the environment variable is optional.
+   * @param {string} [paramPrefix] - The prefix to be added to the environment variable name.
+   */
+  constructor(paramName: string, type: EnvironmentType, optional = true, paramPrefix: string) {
+    this.paramName = paramName
+    this.type = type
+    this.optional = !!optional
+    this.paramPrefix = paramPrefix
+  }
+
+  /**
+   * Resolves the value of the environment variable synchronously.
+   * @returns {T} - The resolved value of the environment variable.
+   * @throws {Error} - If the environment type is not 'Local'.
+   */
+  public syncResolve(): T {
+    if (this.type == EnvironmentType.Local) return this.getLocalValue()
+    else {
+      throw new Error(
+        "EnvironmentVar syncResolve method can only be called for environments of type 'Local'"
+      )
+    }
+  }
+
+  /**
+   * Resolves the value based on the environment type.
+   * @returns {Promise<any>} - The resolved value.
+   */
+  public async resolve() {
+    if (this.type == EnvironmentType.Local) return this.getLocalValue()
+    else if (this.type == EnvironmentType.SecureRemote) return this.getSecureValue()
+    else return this.getPlainValue()
+  }
+
+  /**
+   * Retrieves the value of a local environment variable.
+   * @returns {T} - The value of the local environment variable.
+   * @throws {Error} - If the local environment variable is not defined and is not optional.
+   */
+  private getLocalValue(): T {
+    const value = process.env[this.paramName]
+    if (!value && !this.optional) {
+      throw new Error(
+        `Local environment ${this.paramName} is not defined, please reconfigure the application and redeploy!`
+      )
+    }
+    return value as T
+  }
+
+  /**
+   * Retrieves the plain value of a remote environment parameter.
+   * @returns {Promise<T>} - A promise that resolves to the plain value of the parameter.
+   * @throws {Error} - If the parameter cannot be retrieved and is not optional.
+   */
+  private async getPlainValue(): Promise<T | undefined> {
+    if (!ssmClient) ssmClient = new SSMClient()
+    const pName = `${this.paramPrefix}${this.paramName}`
+    try {
+      const data = await ssmClient.send(new GetParameterCommand({ Name: pName }))
+      if (data.Parameter && data.Parameter.Value) return data.Parameter.Value as T
+    } catch (error) {
+      console.error(error)
+    }
+    if (!this.optional) {
+      throw new Error(`Unable to retrieve plain remote env value: ${pName}`)
+    }
+  }
+
+  /**
+   * Retrieves a secure value from the secrets manager.
+   * @returns {Promise<T>} - A promise that resolves to the secure value.
+   * @throws {Error} - Throws an error if the secure value cannot be retrieved and is not optional.
+   */
+  private async getSecureValue(): Promise<T | undefined> {
+    if (!secretsClient) secretsClient = new SecretsManagerClient()
+    const pName = `${this.paramPrefix}${this.paramName}`
+    try {
+      const data = await secretsClient.send(new GetSecretValueCommand({ SecretId: pName }))
+      if (data.SecretString) return data.SecretString as T
+    } catch (error) {
+      console.error(error)
+    }
+    if (!this.optional) {
+      throw new Error(`Unable to retrieve secure remote env: ${pName}`)
+    }
+  }
+}

package/src/Crypto/Crypto.ts

@@ -0,0 +1,89 @@
+import {
+  KMSClient,
+  EncryptCommand,
+  DecryptCommand,
+  EncryptionAlgorithmSpec,
+} from '@aws-sdk/client-kms'
+
+/**
+ * Represents a Crypto class that provides encryption and decryption functionality using AWS KMS.
+ */
+export default class Crypto {
+  /**
+   * The KMSClient instance used for making requests to the Key Management Service (KMS).
+   */
+  private readonly client: KMSClient
+  /**
+   * The AWS region of the object. This property is readonly and cannot be modified once set.
+   */
+  private readonly region: string
+  /**
+   * The unique identifier for the KMS.
+   * @readonly
+   * @type {string}
+   */
+  private readonly keyId: string
+  /**
+   * Specifies the encryption algorithm used for encryption.
+   */
+  private readonly encryptionAlgorithm: EncryptionAlgorithmSpec
+
+  /**
+   * Constructs a new instance of a KeyManager with the provided region, keyId, and optional encryption algorithm.
+   * @param {string} region - The region where the key is stored.
+   * @param {string} keyId - The ID of the key.
+   * @param {EncryptionAlgorithmSpec} [optEncryptionAlgorithm='RSAES_OAEP_SHA_256'] - The encryption algorithm to use (default is RSAES_OAEP_SHA_256).
+   * @returns None
+   */
+  constructor(region: string, keyId: string, optEncryptionAlgorithm?: EncryptionAlgorithmSpec) {
+    this.region = region
+    this.keyId = keyId
+    this.encryptionAlgorithm = optEncryptionAlgorithm || 'RSAES_OAEP_SHA_256'
+    this.client = new KMSClient({ region: this.region })
+  }
+
+  /**
+   * Encrypts the given data using RSAES_OAEP_SHA_256 encryption algorithm.
+   * @param {string | any} data - The data to be encrypted.
+   * @returns {Promise<string | null>} - A promise that resolves to the encrypted data as a hexadecimal string.
+   */
+  public async encryptData(data: string | any): Promise<string | null> {
+    try {
+      const resp = await this.client.send(
+        new EncryptCommand({
+          KeyId: this.keyId,
+          EncryptionAlgorithm: this.encryptionAlgorithm,
+          Plaintext: new TextEncoder().encode(
+            typeof data === 'string' ? data : JSON.stringify(data)
+          ),
+        })
+      )
+      return Buffer.from(resp.CiphertextBlob as any, 'utf8').toString('hex')
+    } catch (e) {
+      console.error('Encryption failure', e)
+      return null
+    }
+  }
+
+  /**
+   * Decrypts the given data using the RSAES_OAEP_SHA_256 encryption algorithm.
+   * @param {string} data - The encrypted data to decrypt.
+   * @returns {Promise<string | null>} - A promise that resolves to the decrypted plaintext string.
+   * If decryption fails, null is returned.
+   */
+  public async decryptData(data: string): Promise<string | null> {
+    try {
+      const resp = await this.client.send(
+        new DecryptCommand({
+          KeyId: this.keyId,
+          CiphertextBlob: Buffer.from(data, 'hex'),
+          EncryptionAlgorithm: this.encryptionAlgorithm,
+        })
+      )
+      return new TextDecoder().decode(resp.Plaintext)
+    } catch (e) {
+      console.error('Decryption failure', e)
+      return null
+    }
+  }
+}

package/src/Database/Database.ts

@@ -0,0 +1,22 @@
+import { DatabaseTransaction } from './DatabaseTransaction.js'
+import { DbConfig } from './types.js'
+
+/**
+ * Abstract class representing a Database with a generic type extending DatabaseTransaction.
+ * @template T - The type of DatabaseTransaction to be used.
+ */
+export abstract class Database<T extends DatabaseTransaction> {
+  /**
+   * Constructor for a class that takes in a database configuration object.
+   * @param {DbConfig<any>} config - The database configuration object.
+   * @returns None
+   */
+  protected constructor(public readonly config: DbConfig<any>) {}
+
+  /**
+   * Represents an abstract method for a transaction that returns a Promise of type T.
+   * This method needs to be implemented by subclasses.
+   * @returns A Promise that resolves to a value of type T.
+   */
+  public abstract transaction(): Promise<T>
+}

package/src/Database/DatabaseManager.ts

@@ -0,0 +1,67 @@
+import hash from 'object-hash'
+
+import { DynamoDatabase } from './integrations/dynamo/DynamoDatabase.js'
+import { KyselyDatabase } from './integrations/kysely/KyselyDatabase.js'
+import { PostgresDatabase } from './integrations/pgsql/PostgresDatabase.js'
+import type { DatabaseImplType, DatabaseType, DbConfig } from './types.js'
+
+/**
+ * Object containing different database implementations.
+ * @type {Object}
+ * @property {PostgresDatabase} pg - Postgres database implementation
+ * @property {KyselyDatabase<any>} kysely - Kysely database implementation
+ */
+export const DATABASES = {
+  pg: PostgresDatabase,
+  kysely: KyselyDatabase,
+  dynamo: DynamoDatabase,
+}
+
+/**
+ * Manages the creation and storage of database instances.
+ */
+export class DatabaseManager {
+  /**
+   * Singleton instance of the DatabaseManager class.
+   * This instance is used to interact with the database.
+   */
+  public static readonly INSTANCE = new DatabaseManager()
+  /**
+   * A private property that holds a reference to the DATABASES constant.
+   * @type {typeof DATABASES}
+   */
+  private databases: typeof DATABASES = DATABASES
+  /**
+   * An object that stores instances of DatabaseImplType objects with keys of type string.
+   * @type {Object.<string, DatabaseImplType<any, any>>}
+   */
+  private instances: { [k: string]: DatabaseImplType<any, any> } = {}
+
+  /**
+   * Creates a database instance based on the provided configuration.
+   * @param {DbConfig<S>} config - The configuration object for the database.
+   * @returns {DatabaseImplType<S, DBSchema>} An instance of the database based on the configuration.
+   */
+  public create<S extends DatabaseType, DBSchema>(
+    config: DbConfig<S>
+  ): DatabaseImplType<S, DBSchema> {
+    const configHash = hash(config)
+    if (this.instances[configHash]) {
+      return this.instances[configHash] as any
+    }
+    const instance = this.instantiateDb<S, DBSchema>(config as any)
+    this.instances[configHash] = instance
+    return instance
+  }
+
+  /**
+   * Instantiates a database connection based on the provided configuration.
+   * @param {DbConfig<'pg'> | DbConfig<'kysely'>} config - The configuration object specifying the type of database.
+   * @returns {DatabaseImplType<S, DBSchema>} An instance of the specified database connection.
+   */
+  private instantiateDb<S extends DatabaseType, DBSchema>(
+    config: DbConfig<'pg'> | DbConfig<'kysely'> | DbConfig<'dynamo'>
+  ): DatabaseImplType<S, DBSchema> {
+    return new this.databases[config.type](config as any) as any
+  }
+}

package/src/Database/DatabaseTransaction.ts

@@ -0,0 +1,170 @@
+import { Database } from './Database.js'
+
+/**
+ * Abstract class representing a database transaction.
+ * Warning: These need to be arrow functions!
+ * @class DatabaseTransaction
+ */
+export abstract class DatabaseTransaction extends Function {
+  /**
+   * A boolean flag indicating whether a certain feature is open or closed.
+   * @type {boolean}
+   */
+  protected _isOpen: boolean
+  /**
+   * A property representing a writer object.
+   * @type {any}
+   */
+  public readonly writer: any
+  /**
+   * A property representing a reader object.
+   * @type {any}
+   */
+  public readonly reader: any
+  /**
+   * A protected property representing a transaction.
+   * @type {any}
+   */
+  protected transaction: any
+  /**
+   * A protected property representing a database of type Database<any>.
+   * This property is accessible within the class and its subclasses.
+   */
+  protected database: Database<any>
+
+  /**
+   * Constructor for a class that interacts with a database using a writer and reader.
+   * @param {any} writer - The object responsible for writing to the database.
+   * @param {Database<any>} database - The database to interact with.
+   * @param {any} [reader] - The object responsible for reading from the database (optional).
+   * @returns None
+   */
+  protected constructor(writer: any, database: Database<any>, reader?: any) {
+    super('...args', 'return this.transaction(...args)')
+    this.writer = writer
+    this.database = database
+    this.reader = reader
+  }
+
+  /**
+   * Creates a proxy instance for the given subclass of DatabaseTransaction.
+   * The proxy handles method binding and transaction execution based on the subclass state.
+   * @param {T} subclass - The subclass of DatabaseTransaction to proxy.
+   * @returns A proxied instance of the subclass with method binding and transaction execution logic.
+   */
+  protected static proxyInstance<T extends DatabaseTransaction>(subclass: T): T {
+    const bind = (target: any, key: string | symbol) =>
+      typeof target[key] === 'function' ? target[key].bind(target) : target[key]
+
+    return new Proxy<T>(subclass, {
+      get(target: T, p: string | symbol): any {
+        if (target[p] !== undefined) {
+          return bind(target, p)
+        } else if (target._isOpen) {
+          return bind(target.transaction, p)
+        }
+        return undefined
+      },
+      apply(target: T, thisArg: any, argArray: any[]): any {
+        if (target._isOpen) {
+          return target.transaction(...argArray)
+        }
+        throw new Error('Transaction is closed!')
+      },
+    })
+  }
+
+  /**
+   * Check if the object is open.
+   * @returns {boolean} - true if the object is open, false otherwise.
+   */
+  public isOpen = (): boolean => {
+    return this._isOpen
+  }
+
+  /**
+   * Begins a transaction asynchronously.
+   * @returns {Promise<void>} A Promise that resolves when the transaction has begun.
+   * @throws {Error} If the transaction is already open.
+   */
+  public begin = async (): Promise<void> => {
+    if (this._isOpen) {
+      throw new Error('Cannot begin, transaction is already opened!')
+    }
+    await this.doBegin()
+    this._isOpen = true
+  }
+
+  /**
+   * Asynchronously commits the transaction.
+   * If the transaction is already closed, an error is thrown.
+   * @returns Promise<void>
+   * @throws Error if the transaction is already closed
+   */
+  public commit = async (): Promise<void> => {
+    if (!this._isOpen) {
+      throw new Error('Cannot commit, transaction is already closed!')
+    }
+    await this.doCommit()
+    this._isOpen = false
+  }
+
+  /**
+   * Rollback the transaction by reverting any changes made within the transaction.
+   * If the transaction is already closed, an error is thrown.
+   * @returns Promise<void>
+   * @throws Error if the transaction is already closed.
+   */
+  public rollback = async (): Promise<void> => {
+    if (!this._isOpen) {
+      throw new Error('Cannot rollback, transaction is already closed!')
+    }
+    await this.doRollback()
+    this._isOpen = false
+  }
+
+  /**
+   * Closes the success modal, committing or rolling back changes based on the autoCommit setting.
+   * If the modal is open and autoCommit is enabled, it will commit the changes.
+   * If autoCommit is disabled, it will rollback the changes.
+   * @returns {Promise<void>} A promise that resolves once the commit or rollback operation is completed.
+   */
+  public closeSuccess = async () => {
+    if (this._isOpen) {
+      if (this.database.config['autoCommit']) {
+        await this.doCommit()
+      } else {
+        await this.doRollback()
+      }
+    }
+  }
+
+  /**
+   * Closes the failure by performing a rollback if the failure is currently open.
+   * @returns {Promise<void>} A promise that resolves once the rollback is completed.
+   */
+  public closeFailure = async () => {
+    if (this._isOpen) {
+      await this.doRollback()
+    }
+  }
+
+  /**
+   * Abstract method that should be implemented by subclasses to perform a commit operation.
+   * @returns A Promise that resolves when the commit operation is completed.
+   */
+  protected abstract doCommit: () => Promise<any>
+
+  /**
+   * An abstract method that defines the rollback functionality.
+   * This method should be implemented by subclasses to perform the actual rollback operation.
+   * @returns A Promise that resolves when the rollback operation is completed.
+   */
+  protected abstract doRollback: () => Promise<any>
+
+  /**
+   * Abstract method that defines the beginning of an asynchronous operation.
+   * @returns A Promise that resolves when the operation begins.
+   */
+  protected abstract doBegin: () => Promise<any>
+}