casa-massimo

A CASA plugin wrapper for the Massimo API library generator.

Installation

npm install @dwp/casa-massimo-plugin

Usage

Create a CASA plugin by passing in Massimo buildOpenAPIClient() options:

import { join } from "node:path";
import { configure } from "@dwp/govuk-casa";
import casaMassimo from "@dwp/casa-massimo-plugin";

// Build a plugin for our movies API
const moviesClientPlugin = await casaMassimo({
  // Property name for request object
  name: "movies",
  // Path to Open API spec
  path: join(import.meta.dirname, "./schemas/movies.openapi.json"),
  // The base URL of the API, method paths in the spec will be appended to this
  url: process.env.MOVIES_API_URL,
  // Throw an error on 400 and 500 level status codes
  throwOnError: true,
  // Return full response ({ headers, body, statusCode }) if `true`, otherwise
  // the client will just return the response body.
  fullResponse: true,
  // If `true` require full request options including param type, rather than
  // flat object: `req.movies.getMovieById({ path: { id: 100 } })` vs
  // `req.movies.getMovieById({ id: 100 })`. May be required if you have
  // duplicate key names across path params, query, headers and/or body.
  fullRequest: false,
  // Validate the HTTP response against the Open API schema and throw on error.
  validateResponse: false,
  // Function to add headers to the HTTP request
  getHeaders(req, res, opts) {
    // Send inbound correlation on all outbound HTTP requests from the client
    return { "x-correlation-id": req.get("x-correlation-id") };
  },
});

// Load it into our CASA app
const casa = configure({
  ...
  plugins: [moviesClientPlugin],
});

This will build a client from the "movies" OpenAPI JSON spec and bind it to the express request:

export default () => [
  {
    waypoint: "my-page",
    view: "pages/my-page",
    hooks: [
      {
        hook: "prerender",
        async middleware(req, res, next) {
          const { body } = await req.movies.getMovieById({ id: req.params.id });
          res.locals.movie = body;
          next();
        },
      },
    ],
  },
];

The Massimo buildOpenAPIClient function is also available as a named export:

import { buildOpenAPIClient } from "@dwp/casa-massimo-plugin";

const client = await buildOpenAPIClient({
  name: "movies",
  path: join(import.meta.dirname, "./schemas/movies.openapi.json"),
  url: process.env.MOVIES_API_URL,
  throwOnError: true,
  fullResponse: false,
  fullRequest: false,
  validateResponse: false,
});

const movie = await client.getMovieById({ id: 100 });

For more information see the Massimo documentation.