CypherMed JavaScript SDK

This package serves as an interface for the CypherMed Cloud plaform. It uses React, Redux, and Redux Toolkit to encapsulate HTTP requests and responses, making it easier to work with the API.

RTK Query (from the Redux Toolkit) is used to create API slice definitions and hooks for each of the endpoints, thereby eliminating most of the boilerplate code for data fetching, manipulation, and handling. It promotes best practices such as separation of concerns, type safety, and reusability, allowing developers to focus on building robust and maintainable applications.

You can find the latest, most up to date, SDK documentation here.

Related links:

• REST API documentation
• Python SDK documentation

Installation

This package requires the following peer dependencies to be installed in your project:

• react >=18.2.0
• react-redux >=8.1.2
• redux >=4.2.1
• react-router-dom >=6.18.0
• @reduxjs/toolkit >=1.9.7

Ensure these packages are installed by running:

yarn add react@^18.2.0 react-redux@^8.1.2 redux@>=4.2.1 react-router-dom@^6.18.0 @reduxjs/toolkit@>=1.9.7

Then:

yarn add cyphermed

Usage

Configure the Redux Store

Set up the Redux store in your application by creating a Redux store configuration file. Here's an example of how to configure the Redux store with the RTK Query API slice:

import { configureStore } from "@reduxjs/toolkit";
import { setupListeners } from "@reduxjs/toolkit/query";
import { authReducer, cyphermed, initializerReducer } from "cyphermed";

export const store = configureStore({
  reducer: {
    [cyphermed.reducerPath]: cyphermed.reducer,
    initializer: initializerReducer,
    auth: authReducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(cyphermed.middleware),
});

setupListeners(store.dispatch);

export default store;

In the above we are inserting three reducers from the CypherMed SDK into the Redux store. The first is the core reducer that handles all the API requests and responses. The second is the initializer reducer, which is used to override the target URL of the API if necessary. The third is the auth reducer, which is used to manage the authentication state of the SDK. Below that we are adding the middleware to the store and setting up listeners to dispatch actions for the RTK Query API slice.

Injecting Additional Endpoints

If you are targeting middleware and need to add additional endpoints, you can inject them like so:

import { cyphermed } from "cyphermed";

const versionApi = cyphermed.injectEndpoints({
    endpoints: (builder) => ({
        getVersion: builder.query<string, void>({
            query: () => ({
                url: "/version",
                method: "GET",
            }),
        }),
    }),
});

export const { useGetVersionQuery } = versionApi;

Read more about this capability here.

Using Hooks

Here's an example of how to use a generated hook to fetch your own user info:

import React from "react";
import { useGetUserByIdQuery } from "cyphermed";

function UserInfoExample() {
  const {
    data: currentUser,
    error,
    isLoading,
  } = useGetUserByIdQuery({ userId: "me" });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <p>Username: {currentUser.username}</p>;
}

export default UserInfoExample;

Read more about using hooks here.

Dispatching Mutations

You can also dispatch mutations to update data on the server. Here's an example of how to dispatch a mutation to update a user's profile:

import React, { useState } from "react";
import { usePatchUserMutation } from "cyphermed";

function EditUserExample({ userId }) {
  const [email, setEmail] = useState("");
  const [patchUser, { isError, isLoading }] = usePatchUserMutation();

  const handleSubmit = () => {
    patchUser({ userId: userId, patchUserBody: { email: email } });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
      <button type="submit" disabled={isLoading}>Save</button>
      {isError && <div>Error: Failed to update user email</div>}
    </form>
  );
}

export default EditUserExample;

Read more about dispatching mutations here.

Getting Help

If you have any questions or need help, please contact us at [email protected]