🪄 Ollivander

Wonde API client for Node.js, browsers, and workers

• ⏳ Promise-based API. For all of that async/await goodness!
• 🏫 Multi-school support. Make one request for multiple schools!
• 📄 Automatic pagination aggregation. Wonde's paginated API responses are automatically aggregated into one!
• 💪 TypeScript. Fully typed and self-documenting!

🚀 Quick Start

Install

# npm
npm i ollivander

# or yarn
yarn add ollivander

Import

// ESM / TypeScript
import { $wonde } from "ollivander";

// or CommonJS
const { $wonde } = require("ollivander");

Example Usage

Fetch all students for two schools:

const schools = await $wonde((school) => `/schools/${school}/students`, {
  schools: ["A123456789", "A987654321"],
  token: "abc123",
});

console.log(schools["A123456789"]);
// => Array of school A123456789's students

🏫 Single versus multi-school

Single school mode

const students = await $wonde("/schools/A123456789/students", {
  token: "abc123",
});

console.log(students);
// => Array of school A123456789's students
// => i.e. [ ... ]

Multi-school mode

const schools = await $wonde((school) => `/schools/${school}/students`, {
  schools: ["A123456789", "A987654321"],
  token: "abc123",
});

console.log(schools);
// => Object mapping schools to their array of students
// => i.e. { 'A123456789': [ ... ], 'A987654321': [ ... ] }

💪 TypeScript Support

Wonde responses can be type assisted using generics:

type Student = { ... };

const students = await $wonde<Student>("/schools/A123456789/students", {
  token: "abc123",
});

// => Students now has type definitions

♻ Auto Retry

Ollivander can be configured to retry requests if an error is encountered:

const students = await $wonde("/schools/A123456789/students", {
  token: "abc123",
  retry: 5, // => Request will retry 5 times before giving up
});

By default, requests will retry 1 time (except for POST, PUT, and PATCH requests, which will not retry).

📂 HTTP Headers

You can supply additional HTTP headers to Wonde's API:

const students = await $wonde("/schools/A123456789/students", {
  token: "abc123",
  headers: {
    some: "header", // => This will be included in the request (including every paginated request)
  },
});

⛓ Includes

You can instruct Wonde's API to populate relationships with includes. Typically, this would be done with the includes search parameter, but Ollivander has a specific option for includes:

const students = await $wonde("/schools/A123456789/students", {
  token: "abc123",
  includes: ["classes"], // => Each student object will include their respective classes
});

🔢 Per Page

Wonde's API returns paginated responses for arrays of data. You can increase the number of resources returned per request (reducing the overall number of requests):

const students = await $wonde("/schools/A123456789/students", {
  token: "abc123",
  perPage: 200, // => Wonde's API caps this value at 200 (5000 when retrieving attendance sessions)
});

⚠ It's important to remember that Ollivander will handle paginated responses from Wonde so you never need to make more than one request.

However, increasing the perPage option will still reduce Ollivander's request time because of the overhead encountered when making a request to Wonde's API.

🌍 Wonde Endpoints

Wonde's API has separate endpoints/base URLs for the UK and Australia/New Zealand. You can find these endpoints on Wonde's API Reference, or import them as constants from Ollivander:

// ESM / TypeScript
import {
  UK,
  REST_OF_THE_WORLD,
  AUSTRALIA,
  NEW_ZEALAND,
} from "ollivander/endpoints";

// or CommonJS
const {
  UK,
  REST_OF_THE_WORLD,
  AUSTRALIA,
  NEW_ZEALAND,
} = require("ollivander/endpoints");

const students = await $wonde("/schools/A123456789/students", {
  baseURL: AUSTRALIA,
});

By default, Ollivander will use Wonde's endpoint for the UK/Rest of the World.

⚖ License

Ollivander is licensed under the MIT License.