@rivet-one/rivet

Rivet

The library that calls your APIs for you

Rivet parses third party API documentation and automatically transforms requests and responses to the shapes of your choosing, so you can leverage data structures that your application already uses. Any external API you use in your application will "just work."

Installation

npm install @rivet-one/rivet

Or the equivalent in your package manager.

You must use the @rivet-one-scoped package. Omitting the scope will install something else.

Use

There are two steps to using Rivet to make an API call: configuring the Proc in the Rivet dashboard; and calling the Proc from your code.

1. Configuring a Proc in the Rivet dashboard
   1. Visit the Rivet dashboard, log in, and select a Project or create a new Project.
      1. Projects are one-to-one with your apps. For each application you build which uses Rivet, you will create one Project.
      2. Note the API Key in the Project view; you will need this later
   2. Select a Proc or create a new Proc.
      1. Procs are one-to-one with external API calls. For each request you send to a third-party API, you will create one Proc.
      2. Note the Proc ID in the Proc view; you will need this later
   3. Follow the prompts, which will guide you to select a library, provide authentication secrets, define a request and response shape, and a text prompt.
2. Calling a Proc from your code
   1. Set the environment variable RIVET_API_KEY to the API Key found in your Project.
   2. Import rivet and call rivet.rpc with an options object and a data object.
      1. If using TypeScript, rivet.rpc can optionally be parameterized with a request type and response type.

A full example in TypeScript and NodeJS might look like this:

import rivet from "rivet";
...
type Req = { foo: string };
type Rsp = { bar: string };
const rsp = await rivet.rpc<Req, Rsp>({procId: "proc1234"}, {foo: "abc"});
console.log(rsp.response?.bar);