types.ts

import { rootRecord } from "./commands";

export type CommandType =
  | "GET"
  | "SET"
  | "ADD"
  | "DELETE"
  | "OPERATE"
  | "NOTIFY"
  | "GET_SUPPORTED_DM"
  | "GET_INSTANCES"
  | "GET_SUPPORTED_PROTO";

export type GetReturn = string | Record<string, any> | Record<string, any>[];
export type GetCommand = (paths: string | string[]) => Promise<GetReturn>;
export type SetCommand = (
  path: string,
  value: JSValue | JSValue[] | InputRecord
) => Promise<void>;
export type AddCommand = (path: string, value?: InputRecord) => Promise<string | string[]>;
export type DelCommand = (
  path: string,
  allowPartial?: boolean
) => Promise<void>;
export type OperateFn = (input?: Record<string, any>) => Promise<any>;
export type OperateClearFn = () => Promise<void>;
export type OperateRecipe = (
  path: string,
  opts?: OperateOptions
) => Promise<[OperateFn, OperateClearFn]>;
export type SupportedDMCommand = (
  paths: string | string[],
  opts?: SuportedCommandOpts
) => Promise<Record<string, any>>;
export type InstancesCommand = (
  paths: string | string[],
  opts?: { firstLevelOnly?: boolean }
) => Promise<Record<string, any>>;
export type SupportedProtoCommand = (versions: string) => Promise<string>;
export type SubscribeRecipe = (
  opts: SubscriptionOptions,
  callback: SubscriptionCallback
) => Promise<PromiseClearFn>;

export type PromiseClearFn = () => Promise<void>;

export type Command =
  | GetCommand
  | SetCommand
  | AddCommand
  | DelCommand
  | OperateRecipe
  | SubscribeRecipe
  | SupportedDMCommand
  | InstancesCommand
  | SupportedProtoCommand;

export type PbRequestCommand =
  | PbRequestCommandGet
  | PbRequestCommandSet
  | PbRequestCommandAdd
  | PbRequestCommandDel
  | PbRequestCommandOperate
  | PbRequestCommandSupport
  | PbRequestCommandInstance
  | PbRequestCommandSupportProto;

export interface SuportedCommandOpts {
  firstLevelOnly?: boolean;
  returnCommands?: boolean;
  returnEvents?: boolean;
  returnParams?: boolean;
}

export type InputRecord = {
  [k: string]:
    | {
        required: boolean;
        value: any;
      }
    | string
    | number
    | boolean;
} & { allowPartial?: boolean };

export type PbRequestCommandSupportProto = {
  getSupportedProtocol: {
    controllerSupportedProtocolVersions: string;
  };
};

export type PbRequestCommandInstance = {
  getInstances: {
    objPaths: string[];
    firstLevelOnly: boolean;
  };
};

export type PbRequestCommandSupport = {
  getSupportedDm: {
    objPaths: string[];
    firstLevelOnly: boolean;
    returnCommands: boolean;
    returnEvents: boolean;
    returnParams: boolean;
  };
};

export type PbRequestCommandOperate = {
  operate: {
    command: string;
    commandKey: string;
    sendResp: boolean;
    inputArgs: Record<string, any>;
  };
};

export type PbRequestCommandDel = {
  delete: {
    allowPartial: boolean;
    objPaths: string[];
  };
};

export type PbRequestCommandGet = {
  get: {
    paramPaths: string[];
  };
};

export type PbRequestCommandSet = {
  set: {
    allowPartial: boolean;
    updateObjs: {
      objPath: string;
      lookup: "Set.UpdateObject";
      paramSettings: {
        lookup: "Set.UpdateParamSetting";
        param: string;
        value: any;
        required: boolean;
      }[];
    }[];
  };
};

export type PbRequestCommandAdd = {
  add: {
    allowPartial: boolean;
    createObjs: {
      lookup: "Add.CreateObject";
      objPath: string;
      paramSettings: {
        param: string;
        value: any;
        required: boolean;
        lookup: "Add.CreateParamSetting";
      }[];
    }[];
  };
};

export type Recipe = ResolveRecipe;
export type ResolveRecipe = (
  msg: GetReturn,
  level?: number
) => Promise<GetReturn>;

/** Device API */
export interface USP {
  /**
   * Get value at path
   * @param path Location of value (e.g. "Device.DeviceInfo.")
   * ```
   * await usp.get("Device.WiFi.Radio.1.")
   * // or
   * await usp.get(["Device.WiFi.Radio.1.", "Device.WiFi.Radio.2."])
   * ```
   */
  get: GetCommand;

  /**
   * Set value at path
   * @param path Location of value (e.g. "Device.DeviceInfo.")
   * @param value Value to assign
   * ```
   * await usp.set("Device.WiFi.Radio.1.", { Name: "radio-1" })
   * // or
   * await usp.set("Device.WiFi.Radio.1.Name", "radio-1")
   * ```
   */
  set: SetCommand;

  /**
   * Create a command
   * @param path Full path of command (e.g. "Device.IP.Diagnostics.IPPing()")
   * @param opts Subscription options (not required)
   * @returns Function that executes command
   * ```
   * const [ping, cleanPing] = await usp.operate("Device.IP.Diagnostics.IPPing()")
   * const results = await ping({ Host: "iopsys.eu" })
   * await cleanPing()
   * ```
   */
  operate: OperateRecipe;

  /**
   * Add object to path
   * @param path Path to add to (e.g. "Device.NAT.PortMapping.")
   * @param values Optional object to add (if skipped will use default values)
   * @returns Full path of new object
   * ```
   * await usp.add("Device.NAT.PortMapping.")
   * await usp.add("Device.NAT.PortMapping.", { Description: "cpe-1", allowPartial: true })
   * ```
   */
  add: AddCommand;

  /**
   * Delete object at path
   * @param path Full path to delete (e.g. "Device.NAT.PortMapping.1.")
   * @param allowPartial [Optional] Allow partial (defaults to false)
   * ```
   * await usp.del("Device.NAT.PortMapping.1.")
   * await usp.del("Device.NAT.PortMapping.1.", true)
   * ```
   */
  del: DelCommand;

  /**
   * Resolve references in message
   * @param msg Message with reference in it
   * @param level Optional level of nesting to resolve to (avoid using high numbers)
   * ```
   * await usp.get("Device.WiFi.Radio.1.").then(device.resolve)
   * ```
   */
  resolve: ResolveRecipe;

  /**
   * Get Supported DM
   * @param paths Path(s)
   * @param opts [Optional] Response options
   * ```
   * await usp.supportedDM("Device.WiFi.")
   * ```
   */
  supportedDM: SupportedDMCommand;

  /**
   * Get Supported Protocol
   * @param versions Controller supported protocol versions
   * ```
   * await usp.supportedProto("1.0")
   * ```
   */
  supportedProto: SupportedProtoCommand;

  /**
   * Get instances
   * @param paths Path(s)
   * @param firstLevelOnly [Optional] Return only first level
   * ```
   * await usp.instances("Device.WiFi.")
   * ```
   */
  instances: SupportedDMCommand;

  /**
   * Subscribe to event
   * @param options Subscription options
   * @param callback Callback on relevant message
   * @returns Returns function to clear subscription
   * ```
   * const clearSub = await usp.subscribe({ id: '1234', notif: 'ObjectCreation', reference: 'Device.NAT.PortMapping.' }, console.log)
   * ```
   */
  subscribe: SubscribeRecipe;

  /**
   * Add handler for messages
   * @param ident Message identifier (identifies by id, can be a string or regexp)
   * @param callback Callback on relevant message
   * @returns Returns function to clear handler
   * ```
   * const clear = usp.on("error", () => console.log('An error!'))
   * ```
   */
  on: OnFn;

  /**
   * Disconnect from device
   * ```
   * await usp.disconnect()
   * ```
   */
  disconnect: () => Promise<void>;
}

export type Connect = (
  options: ConnectionOptions,
  events?: ConnectionEvents
) => Promise<USP>;

type NotifType =
  | "Event"
  | "ValueChange"
  | "ObjectCreation"
  | "ObjectDeletion"
  | "OperationComplete"
  | "OnBoardRequest";

export interface SubscriptionOptions {
  id?: string;
  notif: NotifType;
  reference: string | string[];
}

export type SubscriptionCallback = (
  msg: Response,
  fullMsg?: Record<string, any>
) => void;

export interface OperateOptions {
  ID?: string;
  Persistent?: boolean;
}

export interface PbRequestHeader {
  msgId: string;
  msgType: CommandType;
  lookup: "Header";
}

export interface PbRequestBody {
  lookup: "Body";
  request: {
    lookup: "Request";
  } & PbRequestCommand;
}

export interface PbRequestMessage {
  header: PbRequestHeader;
  body: PbRequestBody;
  lookup: "Msg";
}

export type URLConnectionOptions = {
  url: string;
} & OtherConnectionOptions;

export type HostConnectionOptions = {
  host: string;
  port: number;
  protocol: "wss" | "ws" | "mqtt" | "mqtts" | "tcp" | "ssl" | "wx" | "wxs";
} & OtherConnectionOptions;

export type CertType = string | string[] | Buffer | Buffer[];
export interface OtherConnectionOptions {
  username: string;
  password: string;
  fromId?: string;
  toId?: string;
  idEndpoint?: string;
  publishEndpoint?: string;
  subscribeEndpoint?: string;
  ca?: CertType | Object[];
  key?: CertType;
  cert?: CertType;
}

export type ConnectionOptions = URLConnectionOptions | HostConnectionOptions;

export type Response = string | Record<string, any>;
export type DecodeFn = (msg: Record<string, any>) => DecodeResponse | [any];
export type DecodeResponse = [any, ResponseID | null, null | Response] | [any];
export type EncodeArgs = {
  rootMsg: protobuf.Root;
  rootRecord: protobuf.Root;
  header: any;
  options: Record<string, string>;
  args: Record<string, any>;
};

export type OnIdent = string | RegExp;

export type EncodeFn = (args: Record<string, any>) => PbRequestMessage;
export type CallArgs = Record<string, any>;
export type ClearFn = () => void;
export type OnFn = (ident: OnIdent, callback: SubscriptionCallback) => ClearFn;
export type MakeFn = (call: CallFn, on: OnFn) => Command;
export type MakeRecipeFn = (call: CallFn) => Recipe;
export type CommandTrigger = {
  decode: string | ((msg: Record<string, string>) => boolean);
  encode: string;
};
export type CommandObject = {
  encode: EncodeFn;
  decode: DecodeFn;
};

export interface ConnectionEvents {
  onError?: (err: string) => void;
}

export interface RecipeObject {
  name: string;
  make: MakeFn;
}

export type ResponseID = "ignore" | "error" | string;
export type JSValue = string | number | boolean;
export type CallFn = (cmd: CommandType, args: Record<string, any>) => any;