new-request

Use 3rd party REST APIs with confidence.

SendGrid, Twilio SMS, CLOVA Voice, … show more

Benefits

• Type Safety: Fully typed request and response bodies.
• Easy Migration: Uses the API's request body format.
• Small in Size: Mostly types. Minimum runtime code.
• Error Handling without using a try...catch block.
• Fetch API ❤️ with a custom fetch function support.

Usage

npm i new-request -D

All modules have a similar structure.

// Pseudocode using TypeScript type names.
const response = await moduleName(RequestBody, Options);

// Response body type can be easily narrowed.
if (response.ok) response.body; // ResponseBody
if (!response.ok) response.body; // ResponseBody4xx

Reference the services section for the specific types.

// Example using the SendGrid mail send API v3.

// Rename the imported module for better readability.
import { SendGridSendEmail3 as sendEmail } from 'new-request';

// Everything is typed and autocompleted.
const response = await sendEmail(
  {
    // Request body goes here. Reference the official documentation.
    // The only exception is `from`. Pass it in the next argument.
    // https://docs.sendgrid.com/api-reference/mail-send/mail-send
  },
  {
    apiKey: 'SG.this_is_a_secret_api_key.do_not_expose',
    from: { email: '[email protected]' },
    // Custom `fetch` can be provided here.
  },
);

if (response instanceof Error) {
  // Handle fetch error, which is most-likely a network issue.
} else if (!response.ok) {
  response.status; // 400 | 401 | 403 | 404 | 413 | 500
  // The response body can be narrowed based on the status.
  if (response.status !== 500) response.body; // ResponseBody4xx
  if (response.status === 500) response.body; // ResponseBody5xx
} else {
  response.status; // 202, Successfully sent the mail.
}

Services

POST Method

| Service | Module Name | Types | | --------------- | -------------------- | ----------------------------------------------------- | | SendGrid | SendGridSendEmail3 | types.ts | | Twilio SMS | TwilioSendSms2010 | types.ts | | NHN Cloud SMS | NhnSendSms3 | types.ts | | CLOVA Voice | NaverTextToSpeech1 | types.ts |

GET Method

| Service | Module Name | Types | | --------------------- | ------------------ | ----------------------------------------- | | NEIS 학교 기본 정보 | NeisSearchSchool | types.ts |