@wishknish/knishio-client-ts 0.7.0

package/src/instance/rules/Callback.ts

@@ -0,0 +1,257 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import Meta from './Meta'
+import RuleArgumentException from './exception/RuleArgumentException'
+import { isNumeric } from '@/libraries/strings'
+import { intersect } from '@/libraries/array'
+import { CodeException } from '@/exception'
+import { parseWithSchema } from '@/schemas'
+import type { MetaData, WalletAddress, TokenSlug, MetaType, MetaId } from '@/types'
+import { z } from 'zod'
+
+// Define callback action types as a discriminated union
+export type CallbackAction = 
+  | 'reject'
+  | 'meta'
+  | 'collect'
+  | 'buffer'
+  | 'remit'
+  | 'burn'
+
+// Zod schema for callback validation
+const CallbackParamsSchema = z.object({
+  action: z.string().min(1, 'Action cannot be empty'),
+  metaType: z.union([z.string(), z.null()]).optional(),
+  metaId: z.union([z.string(), z.null()]).optional(),
+  meta: z.union([z.instanceof(Meta), z.record(z.unknown()), z.null()]).optional(),
+  address: z.union([z.string(), z.null()]).optional(),
+  token: z.union([z.string(), z.null()]).optional(),
+  amount: z.union([z.string(), z.null()]).optional(),
+  comparison: z.union([z.string(), z.null()]).optional()
+}).strict()
+
+interface CallbackParams {
+  action: CallbackAction | string
+  metaType?: MetaType | string | null
+  metaId?: MetaId | string | null
+  meta?: Meta<MetaData> | MetaData | null
+  address?: WalletAddress | string | null
+  token?: TokenSlug | string | null
+  amount?: string | null
+  comparison?: string | null
+}
+
+interface CallbackJSON {
+  action: string
+  metaType?: string
+  metaId?: string
+  meta?: MetaData
+  address?: string
+  token?: string
+  amount?: string
+  comparison?: string
+}
+
+/**
+ * Callback class for rule-based actions
+ */
+export default class Callback {
+  private __action: string
+  private __metaType?: string | null
+  private __metaId?: string | null
+  private __meta?: Meta | null
+  private __address?: string | null
+  private __token?: string | null
+  private __amount?: string | null
+  private __comparison?: string | null
+
+  constructor(params: CallbackParams) {
+    // Validate parameters at runtime
+    const validatedParams = parseWithSchema(CallbackParamsSchema, params, 'Callback constructor')
+    
+    if (!validatedParams.action) {
+      throw new RuleArgumentException('Callback structure violated, missing mandatory "action" parameter.')
+    }
+
+    this.__action = validatedParams.action
+    this.__metaType = validatedParams.metaType ?? null
+    this.__metaId = validatedParams.metaId ?? null
+    this.__address = validatedParams.address ?? null
+    this.__token = validatedParams.token ?? null
+    this.__amount = validatedParams.amount ?? null
+    this.__comparison = validatedParams.comparison ?? null
+
+    if (validatedParams.meta) {
+      this.__meta = validatedParams.meta instanceof Meta 
+        ? validatedParams.meta 
+        : Meta.toObject(validatedParams.meta as MetaData)
+    }
+  }
+
+  // Setters
+  set comparison(comparison: string) {
+    this.__comparison = comparison
+  }
+
+  set amount(amount: string) {
+    if (!isNumeric(amount)) {
+      throw new CodeException('Parameter amount should be a string containing numbers')
+    }
+    this.__amount = amount
+  }
+
+  set token(token: string) {
+    this.__token = token
+  }
+
+  set address(address: string) {
+    this.__address = address
+  }
+
+  set meta(meta: Meta<MetaData> | MetaData) {
+    this.__meta = meta instanceof Meta ? meta : Meta.toObject(meta)
+  }
+
+  set metaType(metaType: string) {
+    this.__metaType = metaType
+  }
+
+  set metaId(metaId: string) {
+    this.__metaId = metaId
+  }
+
+  /**
+   * Creates a Callback from a plain object with validation
+   */
+  static toObject(object: CallbackParams): Callback {
+    // Use the constructor which already validates the object
+    return new Callback(object)
+  }
+
+  /**
+   * Converts to JSON representation
+   */
+  toJSON(): CallbackJSON {
+    const meta: CallbackJSON = {
+      action: this.__action
+    }
+
+    if (this.__metaType) {
+      meta.metaType = this.__metaType
+    }
+    if (this.__metaId) {
+      meta.metaId = this.__metaId
+    }
+    if (this.__meta) {
+      meta.meta = this.__meta.toJSON()
+    }
+
+    if (this.__address) {
+      meta.address = this.__address
+    }
+
+    if (this.__token) {
+      meta.token = this.__token
+    }
+
+    if (this.__amount) {
+      meta.amount = this.__amount
+    }
+
+    if (this.__comparison) {
+      meta.comparison = this.__comparison
+    }
+
+    return meta
+  }
+
+  // Action type checkers using discriminated unions
+  isReject(): this is Callback & { __action: 'reject' } {
+    return this._is('reject')
+  }
+
+  isMeta(): this is Callback & { __action: 'meta' } {
+    const prop = intersect(Object.keys(this.toJSON()), ['action', 'metaId', 'metaType', 'meta'])
+    return prop.length === 4 && this._is('meta')
+  }
+
+  isCollect(): this is Callback & { __action: 'collect' } {
+    const prop = intersect(Object.keys(this.toJSON()), ['action', 'address', 'token', 'amount', 'comparison'])
+    return prop.length === 5 && this._is('collect')
+  }
+
+  isBuffer(): this is Callback & { __action: 'buffer' } {
+    const prop = intersect(Object.keys(this.toJSON()), ['action', 'address', 'token', 'amount', 'comparison'])
+    return prop.length === 5 && this._is('buffer')
+  }
+
+  isRemit(): this is Callback & { __action: 'remit' } {
+    const prop = intersect(Object.keys(this.toJSON()), ['action', 'token', 'amount'])
+    return prop.length === 3 && this._is('remit')
+  }
+
+  isBurn(): this is Callback & { __action: 'burn' } {
+    const prop = intersect(Object.keys(this.toJSON()), ['action', 'token', 'amount', 'comparison'])
+    return prop.length === 4 && this._is('burn')
+  }
+
+  /**
+   * Private helper to check action type with type narrowing
+   */
+  private _is(type: CallbackAction): boolean {
+    return this.__action.toLowerCase() === type.toLowerCase()
+  }
+
+  /**
+   * Type-safe getter for action
+   */
+  get action(): string {
+    return this.__action
+  }
+}

package/src/instance/rules/Condition.ts

@@ -0,0 +1,96 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import RuleArgumentException from './exception/RuleArgumentException'
+
+interface ConditionParams {
+  key: string
+  value: any
+  comparison: string
+}
+
+/**
+ * Condition class for rule-based logic
+ */
+export default class Condition {
+  private __key: string
+  private __value: any
+  private __comparison: string
+
+  constructor({ key, value, comparison }: ConditionParams) {
+    if ([key, value, comparison].some(item => !item)) {
+      throw new RuleArgumentException('Condition::constructor( { key, value, comparison } ) - not all class parameters are initialised!')
+    }
+
+    this.__key = key
+    this.__value = value
+    this.__comparison = comparison
+  }
+
+  /**
+   * Creates a Condition from a plain object
+   */
+  static toObject(object: ConditionParams): Condition {
+    return new this({
+      key: object.key,
+      value: object.value,
+      comparison: object.comparison
+    })
+  }
+
+  /**
+   * Converts to JSON representation
+   */
+  toJSON(): ConditionParams {
+    return {
+      key: this.__key,
+      value: this.__value,
+      comparison: this.__comparison
+    }
+  }
+}

package/src/instance/rules/Meta.ts

@@ -0,0 +1,163 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import { MetaDataSchema, parseWithSchema } from '@/schemas'
+import type { MetaData } from '@/types'
+
+/**
+ * Meta class for handling dynamic metadata objects with type safety
+ * 
+ * Uses TypeScript 2025 patterns with proper generics and runtime validation
+ */
+export default class Meta<T extends MetaData = MetaData> {
+  private readonly __data: Map<string, T[keyof T]> = new Map()
+
+  constructor(args: T = {} as T) {
+    // Validate input at runtime using Zod
+    const validatedArgs = parseWithSchema(MetaDataSchema, args, 'Meta constructor')
+    
+    // Store validated data
+    for (const [key, value] of Object.entries(validatedArgs)) {
+      this.__data.set(`__${key}`, value)
+    }
+  }
+
+  /**
+   * Creates a Meta object from a plain object with runtime validation
+   */
+  static toObject<U extends MetaData>(object: U): Meta<U> {
+    return new Meta(object)
+  }
+
+  /**
+   * Gets a metadata value by key
+   */
+  get<K extends keyof T>(key: K): T[K] | undefined {
+    return this.__data.get(`__${String(key)}`) as T[K] | undefined
+  }
+
+  /**
+   * Sets a metadata value by key
+   */
+  set<K extends keyof T>(key: K, value: T[K]): void {
+    this.__data.set(`__${String(key)}`, value)
+  }
+
+  /**
+   * Checks if a key exists
+   */
+  has<K extends keyof T>(key: K): boolean {
+    return this.__data.has(`__${String(key)}`)
+  }
+
+  /**
+   * Gets all keys
+   */
+  keys(): string[] {
+    return Array.from(this.__data.keys()).map(key => 
+      key.startsWith('__') ? key.substring(2) : key
+    )
+  }
+
+  /**
+   * Converts Meta object back to plain object
+   */
+  toJSON(): T {
+    const object = {} as Record<string, T[keyof T]>
+
+    for (const [key, value] of this.__data.entries()) {
+      if (key.startsWith('__')) {
+        const plainKey = key.substring(2)
+        object[plainKey] = value
+      }
+    }
+
+    return object as unknown as T
+  }
+
+  /**
+   * Creates a typed copy of this Meta object
+   */
+  clone(): Meta<T> {
+    return new Meta(this.toJSON())
+  }
+
+  /**
+   * Merges another Meta object into this one
+   */
+  merge<U extends MetaData>(other: Meta<U>): Meta<T & U> {
+    const combined = { ...this.toJSON(), ...other.toJSON() }
+    return new Meta(combined)
+  }
+
+  /**
+   * Type-safe iteration over metadata entries
+   */
+  forEach<K extends keyof T>(callback: (value: T[K], key: K) => void): void {
+    for (const [key, value] of this.__data.entries()) {
+      if (key.startsWith('__')) {
+        const plainKey = key.substring(2) as K
+        callback(value as T[K], plainKey)
+      }
+    }
+  }
+
+  /**
+   * Returns the size of the metadata object
+   */
+  get size(): number {
+    return this.__data.size
+  }
+
+  /**
+   * Clears all metadata
+   */
+  clear(): void {
+    this.__data.clear()
+  }
+}

package/src/instance/rules/Rule.ts

@@ -0,0 +1,29 @@
+/**
+ * Rule class - Policy and rule management for KnishIO DLT
+ * STUB IMPLEMENTATION - Full implementation pending
+ */
+export default class Rule {
+  public name: string
+  public conditions: any[]
+  public actions: any[]
+
+  constructor(data: any = {}) {
+    this.name = data.name || ''
+    this.conditions = data.conditions || []
+    this.actions = data.actions || []
+  }
+
+  /**
+   * Convert rule data to Rule object
+   * @param data - Rule data to convert
+   * @return Rule instance
+   */
+  static toObject(data: any): Rule {
+    if (data instanceof Rule) {
+      return data
+    }
+    return new Rule(data)
+  }
+
+  // TODO: Implement remaining Rule methods
+}

package/src/instance/rules/exception/RuleArgumentException.ts

@@ -0,0 +1,65 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import BaseException from '@/exception/BaseException'
+
+/**
+ * Thrown when rule arguments are invalid or missing
+ */
+export class RuleArgumentException extends BaseException {
+  /**
+   * Constructor
+   */
+  constructor(
+    message: string = 'An incorrect argument!'
+  ) {
+    super('RULE_ARGUMENT_ERROR', message)
+  }
+}
+
+export default RuleArgumentException