Commands

The Commands API lets you expose commands of your plugin to be used by other plugins or by other Qatium components, like Q, our digital assistant.

addCommand()

Allows the plugin to expose commands to be used by other components: Digital assistant (Q), other plugins, other Qatium components, etc.

Method signature

type CommandDescription = <
  Receives extends Record<string, string>,
  Returns extends Record<string, unknown>
>{
  name: string;
  description: string;
  aliases: string[];
  arguments: Receives;
  returnType: Record<keyof Returns, string>;
}

export type CommandAnswer<Returns extends Record<string, unknown>> = {
  data: Returns;
  openPanel?: boolean;
  turnOnVisuals?: boolean;
};

addCommand<Receives, Returns>(
  description: CommandDescription<Receives, Returns>,
  fn: (args: Record<keyof Receives, string>) => Promise<CommandAnswer<Returns>>
): void

Parameters

• description: CommandDescription<Receives, Returns>:

  • name: The name of the command.
  • description: A description of the command.
  • aliases: A list of aliases for the command.
  • arguments: An object describing the arguments your command will receive.
  • returnType: An object describing the returned result type.

  const commandDescription = {
    name: "Close Valves",
    description: "It closes valves from the network",
    aliases: ["shutdown valves", "close TCV", "close shut-off valves"],
    arguments: {
      numOfValves: "number of valves to close"
    },
    returnType: {
      valvesClosed: "how many valves the command was able to close"
    }
  }

• fn: <Receives, Returns>(args: Record<keyof Receives, string>) => Promise<CommandAnswer<Returns>>: It will perform the command and then return a Promise<CommandAnswer>:

  type CommandAnswer<Returns> = {
  /**
   * The data returned by the command.
   * It should match the keys in {@link CommandDescription.returnType}
   */
  data: Returns;
  /**
   * Whether or not to open the plugin panel after the command succeeds.
   *
   * @default false.
   */
  openPanel?: boolean;
  /**
   * Whether or not to turn on the plugin visuals after the command succeeds.
   *
   * @default false.
   */
  turnOnVisuals?: boolean;
  };

  // A command that sets the demand of a junction
  type Receives = { junctionId: string; demand: string };
  type Returns = { junctionId: string; newDemand: string };
  
  const setJunctionDemandCommand: CommandFn<Receives, Returns> = async (args) => {
    const { junctionId, demand } = args;
  
    sdk.network.setDemand(junctionId, demand);
  
    return {
      data: {
        junctionId,
        newDemand: demand
      },
      openPanel: true,
      turnOnVisuals: false
    };
  };

Example

sdk.commands.addCommand(
  {
    name: "Set junction demand",
    description: "sets the demand of a junction",
    aliases: [
      "set demand",
      "change demand",
      "increase flow in junction",
      "set flow in junction"
    ],
    arguments: {
      junctionId: "the id of the junction",
      demand: "the new demand of the junction"
    },
    returnType: {
      junctionId: "the id of the junction",
      newDemand: "the new demand of the junction"
    }
  },
  async (args) => {
    const { junctionId, demand } = args;

    sdk.network.setDemand(junctionId, Number(demand));

    return {
      data: {
        junctionId,
        newDemand: demand
      },
      openPanel: true,
      turnOnVisuals: false
    };
  }
);

availableCommands()

Returns the available commands to call. You can use this method to connect your plugin with other plugins, or with other Qatium components.

Usually you would connect two plugins you own, so they can interact with each other.

Method signature

 type Command<Receives, Returns> = {
  /**
   * The unique identifier of the command.
   */
  id: string;

  /**
   * The description of the command.
   *
   * @see {@link CommandDescription}
   */
  description: CommandDescription<Receives, Returns>;

  /**
   * The function that will be executed when the command is called.
   *
   * @param args - An object `Record<string, string>` being the keys the ones defined in {@link CommandDescription.arguments}
   * @returns A {@link CommandAnswer.data}
   */
  fn: (args: Record<keyof Receives, string>) => Promise<CommandAnswer["data"]>;
};

type AvailableCommands = () => Command[];