Hooks

The Prequel React SDK provides a comprehensive set of React Hooks to help you embed the functionality of Prequel into your React app.

Available Hooks

Hook	Shape	Usage
useDestination	`useDestination(defaultSettings: Partial<Destination>): [Destination, SetDestinationFunction]`	Initialize a `Destination` object and a `setDestination` function to pass to `useDestinationForm` and collect data from your user.
useDestinationForm	`useDestinationForm(destination, orgIdInPrequel): Form`	Get a form object that you can render to collect connection information. The form changes based on fields set on the destination.
useModels	`useModels(fetchToken, origin): ModelConfig[]`	Get all of your Prequel models.
useCreateDestination	`useCreateDestination(fetchToken, origin): CreateDestinationFunction`	Generate a function you can use to submit a completed destination and begin syncing data to your customer.
useTestConnection	`useTestConnection(fetchToken, origin): TestConnectionFunction`	Generate a function you can use to embed a connection test (i.e., to test the destination setup before submitting the destination) into your application.
useUpdateDestination	`useUpdateDestination(fetchToken, origin): UpdateDestinationFunction`	Generate a function you can use to submit changes to an existing destination.
useDeleteDestination	`useDeleteDestination(fetchToken, origin): DeleteDestinationFunction`	Generate a function you can use to delete existing destinations.
useGetTransfers	`useProducts(fetchToken, origin): GetTransfersFunction`	Generate a function you can use to get transfers for an existing destination
useGetDestinations	`useGetDestinations(fetchToken, origin): GetDestinationsForRecipientFunction`	Generate a function you can use to get destinations for the recipient specified in the scoped auth token.
useGetModelsForRecipient	`useGetModelsForRecipient(fetchToken, origin): GetModelsForRecipientFunction`	Generate a function you can use to get the available models for the recipient specified in the scoped auth token.

Hook usage examples

`useDestination`

This hook provides a destination object and a function for updating values on that destination. Usage is very similar to that of React's useState hook.

Parameters

Name	Type	Notes
`initialState`	`Partial<Destination>`	Optional. Defaults to predetermined values.

Return Values

Value	Type
`[destination, setDestination]`	`[Destination, SetDestinationFunction]`

Example

import { useDestination } from "@prequel/react";

const [destination, setDestination] = useDestination({ name: "Example Destination" });
console.log("Destination Name:", destination.name); // "Example Destination"

setDestination((currentDestination) => ({ ...currentDestination, name: "Updated Destination Name" }));
console.log("Destination Name:", destination.name); // "Updated Destination Name"

`useDestinationForm`

This hook provides a form object that changes dynamically based on fields set on the given destination.

Parameters

Name	Type	Notes
`destination`	`Destination`	Required. The form updates dynamically based on changes to this object.
`orgId`	`string`	Required. The Prequel UUID representing your organization.
`includeInternalFields`	`boolean`	Optional. Default `false`. Setting to `true` will include form fields like `name` and `recipient_id` that you likely want to set yourself rather than exposing to the user.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Value	Type
`form`	`Form`.

Example

import { useDestination, useDestinationForm } from "@prequel/react";

const [destination, setDestination] = useDestination();
const destinationForm = useDestinationForm(
  destination,
  "your-prequel-org-uuid",
);

return (
  <div>
  {destinationForm.map((section) => (
    // Render the section...
    {section.fields((field) => (
      // Render the field...
    )}
  ))}
  </div>
);

`useModels`

This hook returns a list of all your models. This hook is most commonly used to add model selection to your destination form.

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthToken`	Required.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Value	Type
`modelConfigs`	`ModelConfig[] \| undefined`.

Example

import { useModels } from "@prequel/react";

const models = useModels(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

`useCreateDestination`

This hook generates a function that you can use to create a destination. This function is most commonly used in the submit functionality of your destination form.

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthTokenWithDestination`	Required. Consumes a `PreparedDestination` and generates a scoped auth token.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Value	Type
`createDestination`	`(d: PreparedDestination) => Promise<APIResponse<CreateOrUpdateDestinationResponse>>`.

Example

import { useCreateDestination, prepareDestinationWithForm } from "@prequel/react";

const createDestination = useCreateDestination(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

// prepareDestinationWithForm usage elided...

async function onFormSubmit() {
  const response = await createDestination(preparedDestination);
  if (response.status === "success") {
    // handle creation success
  } else {
    // handle creation failure
  }
}

`useTestConnection`

This hook generates a function that you can use to test a destination connection. This function is most commonly used to test new destinations in your form.

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthTokenWithDestination`	Required. Consumes a `PreparedDestination` and generates a scoped auth token.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Value	Type
`testConnection`	`(d: PreparedDestination) => Promise<APIResponse<{ status: string }>>`.

Example

import { useTestConnection } from "@prequel/react";

const testConnection = useTestConnection(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

async function testDestinationConnection() {
  const { data, status, message } = await testConnection(preparedDestination);
  if (response.status === "success") {
    // handle test success
  } else {
    // handle test failure
  }
}

`useUpdateDestination`

This hook generates a function that you can use to update a destination.

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthTokenWithExistingDestination`	Required. Consumes an `ExistingDestination` and generates a scoped auth token.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Value	Type
`updateDestination`	`(destination: ExistingDestination, changed: Partial<PreparedDestination>) => Promise<APIResponse<CreateOrUpdateDestinationResponse>>`.

Example

const { useUpdateDestination } from "@prequel/react";

const updateDestination = useUpdateDestination(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

// destination edits and preparation elided...

async function onSubmitUpdate() {
  const response = await updateDestination(existingDestination, editedPreparedDestination);
  if (response.status === "success") {
    // handle update success
  } else {
    // handle update failure
  }
}

`useDeleteDestination`

This hook generates a function that you can use to delete a destination.

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthTokenWithExistingDestination`	Required. Consumes an `ExistingDestination` and generates a scoped auth token.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Value	Type
`deleteDestination`	`(destination: ExistingDestination) => Promise<APIResponse<{}>>`.

Example

import { useDeleteDestination } from "@prequel/react";

const deleteDestination = useDeleteDestination(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

async function onSubmitDelete() {
  const response = await deleteDestination(existingDestination);
  if (response.status === "success") {
    // handle update success
  } else {
    // handle update failure
  }
}

`useGetDestinations`

This hook generates a function that you can use to get destinations for a given recipient.

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthTokenWithRecipientId`	Required. Consumes a recipient ID and generates a scoped auth token.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Input	Type
`getDestinations`	`() => Promise<APIResponse<GetDestinationsAPIResponse>>`.

Example

import { useGetDestinations } from "@prequel/react";

const getDestinations = useGetDestinations(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

const destinations = getDestinations();

`useGetModelsForRecipient`

This hook generates a function that you can use to get destinations for a given recipient.

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthTokenWithRecipientId`	Required. Consumes a recipient ID and generates a scoped auth token.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Input	Type
`getModelsForRecipient`	`() => Promise<ModelsResponse>`.

Example

import { useGetModelsForRecipient } from "@prequel/react";

const getModels = useGetModelsForRecipient(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

const models = getModels();

`useGetTransfers`

This hook generates a function you can use to fetch transfers for an ExistingDestination

Parameters

Name	Type	Notes
`fetchToken`	`FetchAuthTokenWithExistingDestination`	Required. Consumes an `ExistingDestination` and generates a scoped auth token.
`origin`	`string`	Required. The origin of your React app using the hooks.
`host`	`string`	Optional. Defaults to Prequel's US API. Update this if you are running a self-hosted deployment or you are registered with Prequel in another region.

Return Values

Value	Type
`getTransfers`	`(d: ExistingDestination, params?: GetTransfersParams) => Promise<APIResponse<TransfersResponse>>`.

Example

import { useGetTransfers, TransferStatus } from "@prequel/react";

// destination fetching elided...

const getTransfers = useGetTransfers(
  fetchToken,
  "app.example.co",
  PREQUEL_HOST
);

// Get all transfers for destination
const allTransfers = getTransfers(destination);

// Get transfers for destination with limit
const someTransfers = getTransfers(destination, { count: 5 });

// Get all transfers for destination with success status
const successfulTransfers = getTransfers(destination, { status: TransferStatus.SUCCESS });

Hooks vs. Components

Prequel provides a comprehensive set of React Hooks to help you embed Prequel's functionality into your app, though there are no pre-built React Components at this time. We hope the provided Hooks can help you build your own React Components into your app that adhere perfectly to your branding and design guides.