Fastify integration

A complete, runnable Fastify example lives at easy-sdk/examples/node. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

Source code

Repository: itseasyco/easy-sdk
Path: examples/node
README: examples/node/README.md

What this example covers

Initializing the SDK once at startup as a Fastify plugin.
Customer CRUD (getCustomers, getCustomer, createCustomer, updateCustomer).
Storing payment instruments (createPaymentInstrument, updatePaymentInstrument).
Charging via the all-in-one checkout flow — both the customer_creation: true and customer_creation: false branches.
Product + price CRUD (createProduct, createPrice, archive).
Subscription lifecycle (createSubscription, cancelSubscription).
Direct transfers (createTransfer, getTransfer).
Generated OpenAPI documentation served at /documentation so you can poke every endpoint from a browser.

Key files

File	Demonstrates
`src/server.ts`	Fastify bootstrap: `helmet`, `sensible`, Swagger UI, autoloaded plugins and routes.
`src/plugins/easy-client.ts`	Wraps `createClient` in a Fastify plugin and decorates the instance with `fastify.easyClient`.
`src/routes/customers/index.ts`	List / get / create / update via `fastify.easyClient.getCustomers(...)`, etc.
`src/routes/checkout/index.ts`	Splits `CreateCheckoutSession` on `customer_creation` to expose two endpoints.
`src/routes/subscriptions/index.ts`	Subscription create + cancel.
`src/routes/products/index.ts`, `src/routes/prices/index.ts`	Catalog management.

The plugin is the most-copied file:

// src/plugins/easy-client.ts
import { createClient } from "@easylabs/node";
import type { FastifyPluginAsync } from "fastify";
import fp from "fastify-plugin";

declare module "fastify" {
  interface FastifyInstance {
    easyClient: Awaited<ReturnType<typeof createClient>>;
  }
}

const easyClientPlugin: FastifyPluginAsync = async (fastify) => {
  if (!process.env.EASY_API_KEY) {
    throw new Error("EASY_API_KEY environment variable is required");
  }
  const client = await createClient({ apiKey: process.env.EASY_API_KEY });
  fastify.decorate("easyClient", client);
};

export default fp(easyClientPlugin, { name: "easy-client" });

Run it locally

git clone https://github.com/itseasyco/easy-sdk.git
cd easy-sdk
pnpm install
pnpm --filter node-example build  # builds the workspace deps

cd examples/node
echo "EASY_API_KEY=sk_test_..." > .env.local
pnpm dev
# Visit http://localhost:8008/documentation

Adapting it

Webhooks. The example doesn't ship a webhook route. Add one with fastify.addContentTypeParser("application/json", { parseAs: "string" }, …) so you can pass the raw body to EasyWebhooks.constructEvent. See Webhooks for the full snippet.
Per-request error handling. Today routes catch errors locally and return { error: "..." }. Switch to a global setErrorHandler that branches on err instanceof EasyApiError (status + code) for a consistent API surface.
Multi-tenant. Replace the singleton plugin with a request-scoped factory keyed on tenant ID — see Authentication → Multi-tenant.
Strip __dev. The example sets __dev: true for local convenience. In production, omit it — the SDK picks the URL from your key prefix.