new-request

new-request

Use 3rd party REST APIs with confidence.

Twilio SMS, SendGrid, Postmark, … show more

// before
await fetch('https://api.sendgrid.com/v3/mail/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer secret`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body), // not typed.
});

// after - the request body is fully typed!
await sendEmail(body, { apiKey: 'secret' });

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

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 all available modules.

import { send // This will autocomplete module import in most IDEs.

The parameter types are exported for TypeScript and JSDoc usage.

import type { RequestBody, Options } from 'new-request/email/send-grid/v3/POST/index.js';

type Email = NonNullable<RequestBody['from']>;

Example

SendGrid mail send API v3

import { sendEmail } from 'new-request/email/send-grid/v3/POST/index.js';

// 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: '[e-mail]' }] }],
    subject: 'title',
    content: [{ type: 'text/plain', value: 'body' }],
    from: { email: '[e-mail]' }, // optional, override
    // ...
  },

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

Email: SendGrid, Postmark

import { sendEmail } from 'new-request/email/send-grid/v3/POST';
import { sendEmail } from 'new-request/email/postmark/POST';

SMS: Twilio SMS, NHN Cloud SMS

import { sendSms } from 'new-request/sms/twilio/2010-04-01/POST';
import { sendSms } from 'new-request/sms/nhn/v3.0/POST';

Message: Pushover, NHN Dooray!

import { pushMessage } from 'new-request/message/pushover/1';
import { sendMessage } from 'new-request/message/dooray';

TTS: CLOVA Voice

import { textToSpeech } from 'new-request/tts/naver/v1';

Misc: NEIS 학교 기본 정보

import { searchSchool } from 'new-request/misc/neis/info';