Skip to content

Latest commit

 

History

History
177 lines (127 loc) · 6.31 KB

README.md

File metadata and controls

177 lines (127 loc) · 6.31 KB
Raw

E2E Tests Build

JavaScript/TypeScript (Node.js) Buttondown API wrapper.

Buttondown API

This library allows you to quickly and easily use the Buttondown API v1 via Node.js.

This project is not officially affiliated with Buttondown, it's maintained by community members. For any feedback, questions or issues, please create issues and pull requests or merely upvote or comment on existing issues or pull requests.

Table of Contents

Installation

Prerequisites

Obtain an API Key

Grab your API Key from the Buttondown Setting Page.

Setup Environment Variables

Do not hardcode your Buttondown API Key into your code. Instead, use an environment variable or some other secure means of protecting your Buttondown API Key. Following is an example of using an environment variable.

Update the development environment with your BUTTONDOWN_API_KEY, for example:

echo "export BUTTONDOWN_API_KEY='YOUR_API_KEY'" > buttondown.env
echo "buttondown.env" >> .gitignore
source ./buttondown.env

Install Package

The following recommended installation requires npm. If you are unfamiliar with npm, see the npm docs. Npm comes installed with Node.js since node version 0.8.x, therefore, you likely already have it.

npm install --save buttondown

You may also use yarn to install.

yarn add buttondown

Quick Start, Create a Draft

The following is the minimum needed code to create a new draft email. Use this example, and modify the to and from variables:

For more complex use cases, please see USE_CASES.md.

const buttondown = require('buttondown');
buttondown.setApiKey(process.env.BUTTONDOWN_API_KEY);
const draft = {
  subject: 'Creating a new Buttondown draft',
  body: '<strong>and easy to do from Node.js</strong>',
};
//ES6
buttondown.drafts.create(draft)
  .then(() => {}, error => {
    console.error(error);

    if (error.response) {
      console.error(error.response.body)
    }
  });
//ES8
(async () => {
  try {
    await buttondown.drafts.create(draft);
  } catch (error) {
    console.error(error);

    if (error.response) {
      console.error(error.response.body)
    }
  }
})();

After executing the above code, you should have a draft in your Buttondown account. You view it in the UI.

Roadmap

If you are interested in the future direction of this project, please take a look at the open issues and pull requests. I would love to hear your feedback!

Contributing

Requirements

  • Node 10
  • Yarn 1.x or npm

Setup

  1. Clone the repository
  2. Run yarn or npm install installs all required dependencies.
  3. Run yarn build to build from TypeScript to common JavaScript distribution formats.
  4. Run yarn test to run all tests :D.

npm scripts

Equivalent npm run <script> should also work

  • yarn test run tests against built output with ava. Important: runs against build output so run yarn build beforehand.
  • yarn build run build from TypeScript to UMD, CJS, ESM with microbundle
  • yarn watch runs build in watch mode with microbundle
  • yarn lint will lint all of the files with xo
  • yarn format will run lint with --fix option on all the examples files (and tests).
  • yarn release, run clean, production build and release with np.

Partial generated TypeScript SDK using the OpenAPI schema

The auto-generated SDK contains TS errors, eg. _gen/services/SubscribersService.ts has email in the list twice, however it's useful to lift typings from

To re-generate:

  1. Fetch the schema from the API docs
curl https://api.buttondown.email/v1/schema\?format\=openapi >> schema.json
  1. Convert using openapi-typescript-codegen
npx openapi-typescript-codegen --input schema.json --output ./_gen
  1. Keep only the services folder
rm -rf _gen/core _gen/index.ts _gen/models

About

This package is maintained by Hugo from Code with Hugo and Alpine.js Weekly.

Acknowledgments

Special thanks to:

  • Justin Duke for creating Buttondown
  • The Twilio SendGrid team for the inspiration on how to structure this package and docs
  • The developers behind

LICENSE

Code is licensed under the MIT License.