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),
});

// after - and 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: '[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 Methods

Category	Service	Module Name
Email	SendGrid	sendEmail
Email	Postmark	sendEmail
Message	Pushover	pushMessage
SMS	Twilio SMS	sendSms
SMS	NHN Cloud SMS	sendSms
TTS	CLOVA Voice	textToSpeech
Webhook	NHN Dooray!	sendMessage

GET Methods

Service	Module Name
NEIS 학교 기본 정보	searchSchool