Skip to content

hyunbinseo/new-request

Repository files navigation

new-request

Use 3rd party REST APIs with confidence.

Twilio SMS, SendGrid, Postmark, … 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(
  // First parameter closely matches the API's request body.
  // In this example, reference the SendGrid API documentation.
  // https://docs.sendgrid.com/api-reference/mail-send/mail-send
  {
    personalizations: [{ to: [{ email: '[email protected]' }] }],
    subject: 'title',
    content: [{ type: 'text/plain', value: 'body' }],
    from: { email: '[email protected]' }, // optional, override
    // ...
  },

  // Second parameter `options` can be modularized and reused.
  {
    apiKey: 'SG.this_is_a_secret_api_key.do_not_expose',
    from: { email: '[email protected]' }, // required
    // Custom `fetch` function 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

Click the module name to view the TypeScript type.

POST Method

Category Service Module Name
Email SendGrid SendGridSendEmail3
Email Postmark PostmarkSendEmail
SMS Twilio SMS TwilioSendSms2010
SMS NHN Cloud SMS NhnSendSms3
TTS CLOVA Voice NaverTextToSpeech1
Webhook NHN Dooray! DooraySendMessage

GET Method

Service Module Name
NEIS 학교 기본 정보 NeisSearchSchool