Afya Digital: Prescription Engine

Library for consuming Afya Digital Prescription Engine - Frontend integration

Previous version status:

Installation

# npm
npm install @afyadigital/rx-engine --save

# yarn
yarn add @afyadigital/rx-engine

#pnpm
pnpm add @afyadigital/rx-engine

API

render

Renders the RX Engine App, given a configuration object

EngineConfiguration Object

* Get the physician authentication token through our api

** serviceAddress is required to issue regulated prescriptions (special, antimicrobial and the ones covered by RDC 1.000/2025). Every field but complement is mandatory: an incomplete serviceAddress is ignored with a warning, and the physician has to fill the address in on the engine. When address is not sent, it is built out of serviceAddress.

*** sex and birthdate are not translated by the lib: it only validates them and forwards them as sent. Do not send male/female or a lowercase m/f — an invalid value is ignored with a warning and the physician fills it in on the engine.

Example:

/** Create a configuration to render the Prescription Engine */

// AppEnvOptions = 'production' | 'development'

const appEnv = "development";

const config: EngineConfig = {
  // target element selector. example: <div id="rx-engine"></div>
  target: `#rx-engine`,
  // physician authentication token
  auth: { token: 'jwt-token' },
  initialValue: {
    appointment: {
      id: '123'
    }
    // patient identification and name to create a prescription with
    patient: {
      id: '123',
      name: 'Jhon Doe',
      civilName: 'Jhonnie',
      address: 'Foo Bar',
      serviceAddress: {
        address: 'Praça da Sé',
        number: '100',
        neighborhood: 'Sé',
        city: 'São Paulo',
        state: 'SP',
        zipCode: '01001000',
        complement: 'Apto 42'
      },
      phone: '45999999999',
      email: '[email protected]',
      cpf: '682.733.635-20',
      height: "179",
      weight: "90",
      motherName: 'Jhoana Doe',
      birthdate: '1990-05-20',
      sex: 'F'
    },
    // medications that could be imported from an external partner
    medications: [
      {
        type: 'freeText',
        title: 'Test Med',
        patientInstruction: '1 pill every morning for 10 days';
        printType: 'simple';
      }
    ]
  },
}

/** Render it on your target element */

render(config, env)

Patient Object

The patient sent on initialValue.patient:

type Patient = {
  id: string;
  name: string;
  cpf?: string;
  civilName?: string;
  motherName?: string;
  address?: string;
  serviceAddress?: ServiceAddress;
  email?: string;
  phone?: string;
  weight?: string;
  height?: string;
  /** ISO 8601 calendar day, `YYYY-MM-DD` (e.g. `1990-05-20`) */
  birthdate?: string;
  /** Closed dictionary: `M` for male, `F` for female */
  sex?: 'M' | 'F';
};

unmount

Clean previous mounted app and listeners

unmount();

events

API so you can register to events from prescription app. Make sure to render the app before subscribing to events.

type FreeTextItem = {
  title: string;
  patientInstruction: string;
  quantity: number;
  unit: string;
};

type MedicationItem = FreeTextItem & {
  id: string;
};

type PrescriptionItemEventPayload = {
  type: 'product' | 'substance' | 'freeText';
  origin: 'user' | 'integration';
  data: FreeTextItem | MedicationItem;
};

Example:

import { events } from '@afyadigital/rx-engine'

const doSomething = (prescriptionItem) => { ... }

// register a callback function to an event
events.listen('prescription:itemAdded', doSomething)

// remove an event listener
events.remove('prescription:itemAdded', doSomething)

// remove all listeners
events.cleanup()

type ServiceAddress = {
  address: string;
  number: string;
  neighborhood: string;
  city: string;
  state: string;
  zipCode: string;
  complement?: string;
};

type Patient = {
  name: string;
  externalId: string;
  address?: string;
  serviceAddress?: ServiceAddress;
  phone?: string;
  email?: string;
  cpf?: string;
  height?: string;
  weight?: string;
  motherName?: string;
};

type UserInput = {
  patientInstruction: string;
  quantity?: number;
  unit?: string;
  printType: PrintTypeEnum; // simple | special | antimicrobial
};

type FreeText = {
  type: 'freeText';
  title: string;
} & UserInput;

type Product = {
  type: 'product';
  id: string;
  title: string;
  subtitle: string;
  description: string;
  laboratoryName: string;
  category: string;
  maxPrice: string;
  available: boolean;
} & UserInput;

type Substance = {
  type: 'substance';
  id: string;
  title: string;
} & UserInput;

type PrescriptionItem = FreeText | Product | Substance;

export type Exam = {
  id: string;
  code: string;
  term: string;
};

export type PrescritableExam = {
  quantity: number;
  type: string;
  exam: Exam;
};

export type ExamPage = {
  items: PrescritableExam[];
  clinicalIndication?: string;
};

export type VaccineBase = {
  title: string;
  patientInstruction: string;
  quantity: number;
};

export type VaccineProduct = {
  id: string;
  type: 'product';
} & VaccineBase;

export type VaccineFreeText = {
  type: 'freeText';
} & VaccineBase;

export type Vaccine = VaccineProduct | VaccineFreeText;

export type VaccinePage = {
  items: Vaccine[];
};

export type Lme = {
  patient: {
    fullName: string;
    height: string;
    isCapable: boolean;
    mothersName: string;
    weight: string;
    responsibleName?: string;
    filledBy: {
      responsible:
        | 'patient'
        | 'patientMother'
        | 'responsible'
        | 'physician'
        | 'other';
      name?: string;
      cpf?: string;
    };
    skinColor: 'branca' | 'preta' | 'parda' | 'amarela' | 'indigena';
    ethnicity?: string;
    document: {
      type: 'cpf' | 'cns';
      value: string;
    };
    email: string;
    phone: string;
  };
  org: {
    cnes: string;
    name: string;
  };
  physician: {
    name: string;
    cns: string;
  };
  treatments: LmeTreatment[];
};

export type LmeTreatment = {
  id: string;
  cid10: string;
  diagnostic: string;
  solicitationDate: string;
  anamnese: string;
  exams: {
    id: string;
    term: string;
    code: string;
    type: string;
    quantity: number;
  }[];
  medications: {
    months: string[];
    name: string;
    id: string;
    type: string;
  }[];

  onTreatment: boolean;
  treatmentReport?: string;

  pdfUrl: string; // LME prescription pdf
  examUrl?: string; // prescription pdf for all exams
  protocols?: string[]; // terms prescriptions
  prescriptions?: {
    // LME medications prescriptions
    simple: LmeMedicationPrescription;
    special: LmeMedicationPrescription[];
    antimicrobial: LmeMedicationPrescription[];
  };
};

export type LmeMedicationPrescription = {
  id: string;
  pdfUrl: string;
  prescriptionDate: string;
  quantity: number;
  medications: string[];
};

export type SavedPrescriptionEventPayload = {
  id: string;
  patient: Patient;
  issuedAt?: string;
  items: PrescriptionItem[];
  exams: ExamPage[];
  vaccines: VaccinePage[];
  pdfUrl?: string;
  lme?: Lme;
};

commands

After engine app was initialized (check 'app:init' event above), you can dispatch events on the engine.

addPrescriptionItem(item: PrescriptionItem) : adds item into prescription.

type ItemFreeText = {
  title: string;
  type: 'freeText';
  patientInstruction: string;
  quantity: number;
  unit: string;
};

type ItemMedication = {
  id: string;
  type: 'product' | 'substance';
  patientInstruction: string;
  quantity: number;
  unit: string;
};

export type PrescriptionItem = ItemFreeText | ItemMedication;

Usage example:

import { commands, events } from '@afyadigital/rx-engine';

const onInit = async () => {
  await commands.addPrescriptionItem({
    title: 'Paracetamol',
    type: 'freeText',
    patientInstruction: 'tomar 2x ao dia com intervalo de 4 horas',
    quantity: 2,
    unit: 'comprimidos',
  });
};

events.listen('app:init', onInit);

savePrescriptionItem(item: SaveItemMedication) : Adds item into prescription or save to add in next prescription.

export type SaveItemMedication = {
  id: string;
  type: 'product' | 'substance';
  patientInstruction: string;
  quantity: number;
  highlight: {
    title: string;
    subtitle?: string;
  };
  unit: {
    singular: string;
    plural: string;
  };
  title: string;
  subtitle: string;
  description: string;
  laboratoryName: string;
  category: string;
  maxPrice: string;
  available: string | boolean;
  listType: string;
  prescriptionType: string;
  ean1: string;
};

Usage example:

import { commands, events } from '@afyadigital/rx-engine';

const onInit = async () => {
  commands.savePrescriptionItem({
    id: '11a111bc-de12-461b-b0fe-62e7a8f83cb0',
    highlight: {
      title: '<mark>Neosaldina</mark>',
    },
    unit: {
      singular: 'comprimido',
      plural: 'comprimidos',
    },
    type: 'product',
    title: 'Neosaldina',
    subtitle: 'Comprimido revestido • 60 un',
    description:
      'Dipirona 300 mg + Mucato de Isometepteno 30 mg + Cafeína 30 mg',
    laboratoryName: 'Takeda',
    category: 'Referência',
    maxPrice: '60,03',
    available: true,
    listType: '',
    prescriptionType: '',
    ean1: '7896641810985',
    patientInstruction: '',
    quantity: 0,
  });
};

events.listen('app:init', onInit);

updateToken(token: string) : Updates the physician token

Usage example:

import { commands, events } from '@afyadigital/rx-engine';

events.listen('revokedToken', async () => {
  const token = await getPhysicianToken(); // check physician login below*

  await commands.updateToken(token);
});

*physician login

updateFullScreen(isFullScreen: boolean) : Updates the engine fullscreen state

Usage example:

import { commands } from '@afyadigital/rx-engine';

await commands.updateFullScreen(true);

searchPrescriptionItem(term: string) : Searches for a prescription item by term.

Usage example:

import { commands } from '@afyadigital/rx-engine';

await commands.searchPrescriptionItem('aspirina');

trackUserActivity(click: TrackUserActivityEvent): Trigger event from user source

enum TrackActivityClickEnum {
  MenuPep = 'menuPep',
}

type TrackUserActivityEvent = {
  click: TrackActivityClickEnum;
};

Usage example:

import { commands } from '@afyadigital/rx-engine'

const handleClick = () => {
  commands.trackUserActivity({ click: TrackActivityClickEnum.MenuPep })
}

return (
  <MenuItem>
    <Button onClick={handleClick}>Prescrição</Button>
  </MenuItem>
)

React dummy example

import { useEffect } from 'react'
import { render, unmount } from '@afyadigital/rx-engine'
import type { EngineConfig } from '@afyadigital/rx-engine'

const TARGET_ID = 'rx-engine-container'

function AfyaPrescription() {
  useEffect(() => {
    const config: EngineConfig = {
      target: `#${TARGET_ID}`,
      auth: { token: 'physician-auth-token' },
      initialValue: {
        patient: {
          id: '123',
          name: 'Jhon Doe',
          civilName: 'Jonnie',
          address: 'Foo Bar',
          serviceAddress: {
            address: 'Praça da Sé',
            number: '100',
            neighborhood: 'Sé',
            city: 'São Paulo',
            state: 'SP',
            zipCode: '01001000',
          },
          phone: '45999999999',
          email: '[email protected]',
          cpf: '682.733.635-20',
          height: '179',
          weight: '90',
          motherName: 'Jhoana Doe',
          birthdate: '1990-05-20',
          sex: 'F',
        },
      },
    }

    render(config)

    return () => unmount()
  }, [])

  return <div id={TARGET_ID} />
}