### Install API Plugin

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Add the API plugin to your project. If using a separate client and server setup, install it in both parts.

```bash
npm install @node-zugferd/api
# or
yarn add @node-zugferd/api
```

--------------------------------

### Start Development Server

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/reference/contributing.mdx

Commands to start different development servers for the project. Use `pnpm dev` for the main server, `pnpm -F docs dev` for the docs server, and specific commands for bun and node servers.

```bash
pnpm dev
```

```bash
pnpm -F docs dev
```

```bash
pnpm -F @dev/bun dev
```

```bash
pnpm -F @dev/node dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/reference/contributing.mdx

Install all necessary project dependencies using pnpm. Ensure you have pnpm installed globally.

```bash
pnpm install
```

--------------------------------

### Prepare Environment File

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/reference/contributing.mdx

Copy the example environment file to create your local .env file. This is necessary for certain configurations.

```bash
cp -n ./docs/.env.example ./docs/.env
```

--------------------------------

### Create Client Instance

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Example of how to create a client instance to interact with the zugferd API server from the client-side.

```APIDOC
## Client Instance Creation

### Description
Creates a client instance to interact with the zugferd API server. This is useful for making requests from your frontend or other services.

### Method
`createClient<typeof zugferdApi>`

### Parameters
- **`typeof zugferdApi`** (type) - Required - The type of the zugferd API instance.
- **`baseURL`** (string) - Optional - The base URL of the server. If not provided, it defaults to the same domain.

### Request Example
```ts
import { createClient } from "@node-zugferd/api/client";
import type { zugferdApi } from "./your/path/invoicer"; // Import as type

export const zugferdClient = createClient<typeof zugferdApi>({
  /** the base url of the server (optional if you're using the same domain) */
  baseURL: "http://localhost:3000",
});
```
```

--------------------------------

### Setup API Instance

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Initialize the API instance by passing your invoicer instance. Additional configuration for renderer and templates is required.

```typescript
import { api } from "@node-zugferd/api";

export const zugferdApi = api({
  invoicer,
  // ...
});
```

--------------------------------

### Install Node-Zugferd

Source: https://github.com/jslno/node-zugferd/blob/main/README.md

Install the latest version of the node-zugferd package using npm.

```bash
npm install node-zugferd@latest
```

--------------------------------

### Mount Handler for Various Frameworks

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Examples of how to set up a route handler for the `/api/zugferd/*` path in different backend frameworks to handle API requests.

```APIDOC
## Next.js Handler

### Description
Handles API requests for Next.js applications.

### Method
POST, GET

### Endpoint
`/app/api/zugferd/[...all]/route.ts`

### Request Example
```ts
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { toNextJsHandler } from "@node-zugferd/api/next-js";

export const { POST, GET } = toNextJsHandler(zugferdApi);
```

## Nuxt Handler

### Description
Handles API requests for Nuxt applications.

### Method
Any (via `defineEventHandler`)

### Endpoint
`/server/api/zugferd/[...all].ts`

### Request Example
```ts
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance

export default defineEventHandler((event) => {
    return zugferdApi.handler(toWebRequest(event));
});
```

## SvelteKit Handler

### Description
Handles API requests for SvelteKit applications.

### Method
Any (via `handle` hook)

### Endpoint
`hooks.server.ts`

### Request Example
```ts
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { svelteKitHandler } from "node-zugferd/svelte-kit";

export async function handle({ event, resolve }) {
    return svelteKitHandler({ event, resolve, api: zugferdApi });
}
```

## Remix Handler

### Description
Handles API requests for Remix applications.

### Method
GET, POST (via `loader` and `action` functions)

### Endpoint
`/app/routes/api.zugferd.$.ts`

### Request Example
```ts
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";

export async function loader({ request }: LoaderFunctionArgs) {
    return zugferdApi.handler(request);
}

export async function action({ request }: ActionFunctionArgs) {
    return zugferdApi.handler(request);
}
```

## SolidStart Handler

### Description
Handles API requests for SolidStart applications.

### Method
GET, POST

### Endpoint
`/routes/api/zugferd/*.all.ts`

### Request Example
```ts
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { toSolidStartHandler } from "@node-zugferd/api/solid-start";

export const { GET, POST } = toSolidStartHandler(zugferdApi);
```

## Hono Handler

### Description
Handles API requests for Hono applications.

### Method
GET, POST

### Endpoint
`src/index.ts` (for `/api/zugferd/**` path)

### Request Example
```ts
import { Hono } from "hono";
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { serve } from "@hono/node-server";
import { cors } from "hono/cors";

const app = new Hono();

app.on(["GET", "POST"], "/api/zugferd/\*\*", (c) => zugferdApi.handler(c.req.raw));

serve(app);
```

## Express Handler

### Description
Handles API requests for Express.js applications.

### Method
ALL (supports GET, POST, etc.)

### Endpoint
`/api/zugferd/*`

### Request Example
```ts
import express from "express";
import { toNodeHandler } from "@node-zugferd/api/node";
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance

const app = express();
const port = 8000;

app.all("/api/zugferd/*", toNodeHandler(zugferdApi)); // For ExpressJS v4
// app.all("/api/zugferd/*splat", toNodeHandler(zugferdApi)); For ExpressJS v5

// Mount express json middleware after node-zugferd handler
// or only apply it to routes that don't interact with node-zugferd
app.use(express.json());

app.listen(port, () => {
    console.log(`node-zugferd app listening on port ${port}`);
});
```

## Elysia Handler

### Description
Handles API requests for Elysia applications.

### Method
ALL (supports GET, POST, etc.)

### Endpoint
`/api/zugferd/*`

### Request Example
```ts
import { Elysia, type Context } from "elysia";
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance

const nodeZugferdView = (ctx: Context) => {
  const NODE_ZUGFERD_ACCEPT_METHODS = ["GET", "POST"];
  // validate request method
  if (NODE_ZUGFERD_ACCEPT_METHODS.includes(ctx.request.method)) {
    return zugferdApi.handler(ctx.request);
  } else {
    ctx.error(405);
  }
}

const app = new Elysia().all("/api/zugferd/\*", nodeZugferdView).listen(3000);

console.log(
`🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);
```

## TanStack Start Handler

### Description
Handles API requests for TanStack Start applications.

### Method
GET, POST

### Endpoint
`/routes/api/zugferd/$.ts`

### Request Example
```ts
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { createAPIFileRoute } from "@tanstack/react-start/api";

export const APIRoute = createAPIFileRoute("/api/zugferd/$")({
    GET: ({ request }) => {
        return zugferdApi.handler(request);
    },
    POST: ({ request }) => {
        return zugferdApi.handler(request);
    },
});
```
```

--------------------------------

### Configure API with Invoicer Instance

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Initialize the API plugin by providing the invoicer instance. This is a fundamental setup step for the API.

```typescript
import { invoicer } from "./your/path/invoicer";

api({
  invoicer,
});
```

--------------------------------

### TanStack Start API Route Handler

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Define API routes in TanStack Start using createAPIFileRoute to handle GET and POST requests for the zugferd API.

```typescript
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { createAPIFileRoute } from "@tanstack/react-start/api";

export const APIRoute = createAPIFileRoute("/api/zugferd/$")({
    GET: ({ request }) => {
        return zugferdApi.handler(request);
    },
    POST: ({ request }) => {
        return zugferdApi.handler(request);
    },
});
```

--------------------------------

### Install node-zugferd

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/basic-usage.mdx

Add the node-zugferd package to your project using npm or yarn.

```bash
npm install node-zugferd
# or
yarn add node-zugferd
```

--------------------------------

### Run Development Server

Source: https://github.com/jslno/node-zugferd/blob/main/docs/README.md

Use this command to start the development server for the Node Zugferd project. Open http://localhost:3000 in your browser to view the application.

```bash
pnpm -F docs dev
```

--------------------------------

### Integrate Plugins

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/reference/options.mdx

Provide a list of node-zugferd plugins to extend functionality. The example shows how to include a plugin using `api<typeof BASIC>()()`.

```typescript
import { zugferd } from "node-zugferd";

export const invoicer = zugferd({
  profile: BASIC,
  plugins: [
    api<typeof BASIC>()(),
    // or `api(BASIC)()`
  ],
});
```

--------------------------------

### Setup Zugferd with Extended Profile

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/profiles/extended.mdx

Configure the zugferd instance to use the Extended profile, defining the invoice standard and complexity.

```typescript
import { EXTENDED } from "node-zugferd/profile/extended"; // [!code highlight]

export const invoicer = zugferd({
  profile: EXTENDED, // [!code highlight]
});
```

--------------------------------

### Write Unit Tests with Vitest

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/reference/contributing.mdx

Example of how to write a basic unit test using Vitest. Place test files adjacent to the source files they cover.

```typescript
import { describe, it, expect } from "vitest";

describe("Feature", () => {
  it("should work as expected", async () => {
    // Test code here
    expect(result).toBeDefined();
  });
});
```

--------------------------------

### Disable API Paths

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Specify API paths that should be disabled. This example disables the '/preview' path.

```typescript
api({
  disabledPaths: ["/preview"],
});
```

--------------------------------

### Initialize ZUGFeRD Instance

Source: https://context7.com/jslno/node-zugferd/llms.txt

Demonstrates how to create a ZUGFeRD instance using the `zugferd` function, specifying a profile and optional configuration like strict mode and logging.

```APIDOC
## zugferd(options)

### Description
The main entry point for creating a ZUGFeRD instance. It accepts a configuration object with a required `profile` and optional `strict`, `plugins`, and `logger` fields. It returns an invoicer object with a fully-typed `create` method.

### Parameters
#### Options Object
- **profile** (Profile) - Required - The ZUGFeRD compliance profile to use (e.g., `BASIC`, `EN 16931`).
- **strict** (boolean) - Optional - Enables or disables strict XSD validation. Defaults to `true`.
- **plugins** (Array<Plugin>) - Optional - An array of plugins to extend functionality.
- **logger** (Logger) - Optional - Configuration for the logger.
  - **disabled** (boolean) - Whether to disable logging. Defaults to `false`.
  - **level** (string) - The logging level (`info`, `warn`, `error`, `debug`). Defaults to `warn`.
  - **log** (function) - A custom logging function.

### Returns
An invoicer object with a `create` method and an `$Infer.Schema` property for type inference.

### Example
```ts
import { zugferd } from "node-zugferd";
import { BASIC } from "node-zugferd/profile/basic";

export const invoicer = zugferd({
  profile: BASIC,
  strict: true, // default; set false to skip XSD validation
  logger: {
    disabled: false,
    level: "warn", // "info" | "warn" | "error" | "debug"
    log: (level, message, ...args) => {
      console.log(`[${level}] ${message}`, ...args);
    },
  },
});

// $Infer.Schema gives you the TypeScript type for invoice data
type InvoiceData = typeof invoicer.$Infer.Schema;
```
```

--------------------------------

### Next.js API Route Handler

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Set up a POST and GET handler for the /api/zugferd/* route in Next.js using the toNextJsHandler.

```typescript
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { toNextJsHandler } from "@node-zugferd/api/next-js";

export const { POST, GET } = toNextJsHandler(zugferdApi);
```

--------------------------------

### Configure API Authorization

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Set up an authorization function to restrict access to API endpoints. This example checks for an 'admin' role.

```typescript
api({
  authorize: async (ctx) => {
    const user = await getUser(ctx.request);

    if (user.role === "admin") {
      return true;
    }

    return false;
  },
});
```

--------------------------------

### Create a Basic Profile Configuration

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/guides/create-your-first-profile.mdx

Defines a new profile using `createProfile` with essential parameters like context, extensions, XSD path, conformance level, and document details. Ensure all required imports are present.

```typescript
import { createProfile } from "node-zugferd/profile";

export const demo = createProfile({
    contextParameter:
		"urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic",
	extends: [...BASIC_WL.extends, BASIC_WL],
	xsdPath: "Factur-X_1.07.2_BASIC.xsd",
	conformanceLevel: "BASIC",
	documentFileName: "factur-x.xml",
	documentType: "INVOICE",
	version: "1.0",
});
```

--------------------------------

### Configure SolidStart Template

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Set up a SolidStart template for PDF invoice rendering. This uses the Solid renderer and a JSX-based template structure.

```typescript
import { solidRenderer } from "@node-zugferd/api/solid-start/renderer";
api({
  invoicer,
  renderer: solidRenderer(),
  templates: {
    myTemplate: (data) => {
      return {
        body: (
          <h1>Invoice {data.number}</h1>
        ),
      };
    },
  },
});
```

--------------------------------

### Import Basic WL Profile

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/profiles/basic-wl.mdx

Import the BASIC_WL profile and its type for use in your project.

```typescript
import { BASIC_WL, type ProfileBasicWL } from "node-zugferd/profile/basic-wl";
```

--------------------------------

### Remix API Route Handler

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Define loader and action functions in Remix to handle GET and POST requests for the zugferd API.

```typescript
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";

export async function loader({ request }: LoaderFunctionArgs) {
    return zugferdApi.handler(request);
}

export async function action({ request }: ActionFunctionArgs) {
    return zugferdApi.handler(request);
}
```

--------------------------------

### Configure Vanilla Template

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Set up a vanilla HTML template for PDF invoice rendering. This uses the vanilla renderer and a string-based template.

```typescript
import { vanillaRenderer } from "@node-zugferd/api/vanilla/renderer";

api({
  invoicer,
  renderer: vanillaRenderer(),
  templates: {
    myTemplate: (data) => {
      return {
        body: `<h1>${data.number}</h1>`,
      };
    },
  },
});
```

--------------------------------

### Hono API Route Handler

Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/plugins/api.mdx

Integrate zugferd API with Hono framework, setting up a route for GET and POST requests and enabling CORS.

```typescript
import { Hono } from "hono";
import { zugferdApi } from "./your/path/invoicer"; // path to your api instance
import { serve } from "@hono/node-server";
import { cors } from "hono/cors";

const app = new Hono();

app.on(["GET", "POST"], "/api/zugferd/\*\*", (c) => zugferdApi.handler(c.req.raw));

serve(app);
```