Massimo API SDK Client and CLI

Use the massimo CLI to generate a Fastify plugin that exposes a client for a remote or local OpenAPI or GraphQL API. The generated client is available on the Fastify request object.

By default, the command creates a folder named after the client (or the -f flag value) containing the client file. If a Platformatic configuration file is present, it will be automatically updated with a clients section.

Common usage patterns:

• Remote OpenAPI: Provide the URL to the schema.
• Remote GraphQL: Provide the URL to the GraphQL endpoint.
• Local File: Provide the path to a local schema file.
• Types Only: Use the --types-only flag to generate only the .d.ts type definitions without the implementation.

# Generate client from remote OpenAPI schema
$ massimo http://example.com/to/schema/file -n myclient

# Generate client from remote GraphQL API
$ massimo http://example.com/graphql -n myclient

# Generate client from a local schema file
$ massimo path/to/schema -n myclient

# Generate only TypeScript types
$ massimo http://example.com/to/schema/file --name myclient --types-only

Massimo provides a Fastify plugin to attach the generated client to the Fastify request object.

Basic Setup:

import fastify from "fastify";
import pltClient from "massimo/fastify-plugin.js";

const server = fastify();

server.register(pltClient, {
  url: "http://example.com",
  type: "openapi", // or "graphql"
});

server.post("/", async (request, reply) => {
  const res = await request.movies.createMovie({ title: "foo" });
  return res;
});

server.listen({ port: 3000 });

TypeScript Support: To get type safety on request.movies, extend the FastifyRequest interface.

Method A: Global extension

declare module "fastify" {
  interface FastifyRequest {
    movies: MoviesClient;
  }
}

Method B: Local extension

interface MoviesRequest extends FastifyRequest {
  movies: MoviesClient;
}

server.get("/movies", async (request: MoviesRequest, reply: FastifyReply) => {
  return request.movies.getMovies();
});

When using Massimo to generate a GraphQL client, the resulting code consists of two main parts: TypeScript interfaces representing your schema types and an implementation function that initializes the client using buildGraphQLClient from the massimo package.

Generated Interfaces

• Type Interfaces: For every non-internal OBJECT type in your GraphQL schema (excluding Query, Mutation, Subscription, Boolean, and String), Massimo generates a corresponding TypeScript interface with optional properties.
• GraphQLQueryOptions: An interface defining the shape of a query request:
  • query: string
  • headers: Record<string, string>
  • variables: Record<string, unknown>
• GraphQLClient: The client interface providing the core method:
  • graphql<T>(options: GraphQLQueryOptions): PromiseLike<T>

Generated Implementation

Massimo generates a function named generate<Name>Client (where <Name> is your schema name capitalized and camelcased). This function:

1. Accepts PlatformaticClientOptions.
2. Uses buildGraphQLClient with type: 'graphql'.
3. Automatically points to a local .schema.graphql file (e.g., mySchema.schema.graphql) relative to the generated file's directory.
4. Supports both ESM (import/export) and CommonJS (require/module.exports) based on the provided moduleFormat.

You can integrate Massimo into a Fastify application using its official plugin. The plugin automatically builds either a GraphQL or OpenAPI client and decorates the Fastify request object with the client instance, making it available for use in your route handlers.

Configuration Options

When registering the plugin, you provide an opts object:

• type: Must be either 'openapi' or 'graphql'.
• applicationId: (Optional) If provided without a url, the plugin constructs a default URL: http://${applicationId}.plt.local.
• url: The base URL of the service.
• name: (Optional) The name used to decorate the request object. Defaults to 'client'.
• getHeaders: (Optional) A function used to inject headers into requests. If provided during plugin registration, it is used for all requests. If you need to update this dynamically, use the configure<Name> method.

Usage in Route Handlers

The client is attached to the request object using the name specified in the options. If no name is provided, use req.client.

Dynamic Header Configuration

If you need to change the getHeaders function after the plugin has been initialized, use the configure<Name> method on the Fastify application instance (where <Name> is your client name with the first letter capitalized).

import Fastify from 'fastify'
import massimoPlugin from '@platformatic/massimo/fastify-plugin'

const app = Fastify()

// Register the plugin
await app.register(massimoPlugin, {
  type: 'graphql',
  applicationId: 'my-service',
  name: 'api'
})

// Use the client in a route
app.get('/test', async (req, reply) => {
  // The client is available on req.api
  const data = await req.api.query('{ someQuery }')
  return data
})

// Update headers dynamically
app.configureApi({
  getHeaders: (req, reply) => ({
    Authorization: `Bearer ${req.headers.authorization}`
  })
})