Kamy

<p align="center"> <a href="https://kamy.dev"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rakanalalami/kamy/main/apps/web/public/brand/logo-light.svg"> <img alt="Kamy" src="https://raw.githubusercontent.com/rakanalalami/kamy/main/apps/web/public/brand/logo.svg" width="220"> </picture> </a> </p>

<p align="center"> <a href="https://www.npmjs.com/package/@kamydev/sdk"><img alt="SDK on npm" src="https://img.shields.io/npm/v/@kamydev/sdk?label=%40kamydev%2Fsdk&color=1863dc"></a> <a href="https://www.npmjs.com/package/@kamydev/cli"><img alt="CLI on npm" src="https://img.shields.io/npm/v/@kamydev/cli?label=%40kamydev%2Fcli&color=1863dc"></a> <a href="https://github.com/rakanalalami/kamy/blob/main/LICENSE"><img alt="MIT License" src="https://img.shields.io/npm/l/@kamydev/sdk"></a> </p>

PDF generation API for developers. Ship invoices, receipts, contracts, and reports with gorgeous defaults.

Install

# SDK — in your app
npm i @kamydev/sdk

# CLI — globally for scripts, CI, previews
npm i -g @kamydev/cli

import Kamy from "@kamydev/sdk";

const kamy = new Kamy({ apiKey: process.env.KAMY_API_KEY! });
const pdf = await kamy.render({
  template: "invoice",
  data: { invoiceNumber: "INV-001", total: 1500, currency: "USD" },
});
console.log(pdf.url); // signed URL, valid 1 hour

What's New

Date	Change
Apr 2026	GET /v1/renders now returns a per-render cost (in major currency units) plus a top-level currency: "usd". Denormalized at insert time via a Postgres trigger reading users.plan, so the cost reflects your plan when the render happened. Surfaced in SDK 0.2.3 as RenderSummary.cost / RendersListResult.currency.
Apr 2026	SDK now ships OpenAPI-generated types — import type { paths, components } from "@kamydev/sdk/openapi" for fully-typed request/response shapes derived from the live spec. Raw openapi.json shipped too.
Apr 2026	Per-template JSON Schema validation at render time via Ajv (formats enabled). Previously only required was checked — full type/format/enum/oneOf enforcement is now live.
Apr 2026	options.encrypt — AES-256 password protection + permission flags (printing, copying, modifying, annotating, form-fill, accessibility, assembly).
Apr 2026	OpenAPI 3.0.3 spec now covers all 19 /v1/* routes with full request/response schemas — https://kamy.dev/api/openapi.json
Apr 2026	kamy push <file> CLI + client.pushTemplate() SDK + idempotent PUT /v1/templates upsert. Run it on every commit to sync templates from the repo.
Apr 2026	options.validateOnly: true — dry-run any render to validate the payload without consuming quota.
Apr 2026	options.pdfA: "1b" | "2b" | "3b" — best-effort PDF/A archival tagging via embedded sRGB ICC OutputIntent + XMP.
Apr 2026	options.metadata (info dict) + options.watermark (pdf-lib stamp, distinct from theme.watermark).
Apr 2026	options.inlineImages + options.compressImages — server-side image hardening, defends against expiring signed URLs.

Full per-release detail in CHANGELOG.md.

Architecture

Kamy is a Turborepo monorepo containing:

Package	Description
apps/web	Next.js 15 app — landing page, dashboard, REST API
apps/mcp	Cloudflare Worker — MCP server for AI coding agents
apps/docs	Nextra docs site
packages/sdk	@kamydev/sdk — publishable TypeScript SDK
packages/templates	@kamy/templates — PDF template HTML/CSS + Zod schemas
packages/ui	@kamy/ui — shared shadcn/Radix UI components
packages/shared	@kamy/shared — types, utils, observability, email
packages/tsconfig	@kamy/tsconfig — shared TypeScript configs

Prerequisites

• Node.js 22+
• pnpm 10+
• Supabase CLI (brew install supabase/tap/supabase)
• Wrangler CLI (pnpm add -g wrangler) — for MCP server

Local Development

# 1. Install dependencies
pnpm install

# 2. Copy env file and fill in values
cp .env.example apps/web/.env.local

# 3. Start local Supabase (requires Docker)
supabase start

# 4. Apply database migrations
supabase db reset

# 5. Generate TypeScript types from schema
supabase gen types typescript --local > packages/shared/src/types/database.ts

# 6. Start all apps in dev mode
pnpm dev

The web app runs at https://kamy.dev

Commands

pnpm dev          # Start all apps with Turbopack (hot reload)
pnpm build        # Production build all apps
pnpm typecheck    # TypeScript check across all packages
pnpm lint         # Biome lint + format check
pnpm lint:fix     # Biome auto-fix
pnpm test         # Run all tests (Vitest unit + Playwright E2E)
pnpm test:unit    # Vitest unit tests only
pnpm test:e2e     # Playwright E2E tests only
pnpm clean        # Remove all build artifacts

Database

Migrations live in supabase/migrations/. They are applied in order by timestamp.

# Reset and reseed local DB
supabase db reset

# Create a new migration
supabase migration new <name>

# Push to remote Supabase project
supabase db push

Deployment

• Web app: Deployed to Vercel on merge to main
• MCP server: Deployed to Cloudflare Workers via wrangler deploy
• Database: Hosted on Supabase Cloud

Environment Variables

See .env.example for all required variables with descriptions.

Tech Stack

• Framework: Next.js 15 (App Router, React Server Components, Turbopack)
• Language: TypeScript 5.7+ strict
• Database: Supabase (Postgres 16 + Auth + Storage)
• Styling: Tailwind CSS v4 (Oxide engine)
• Payments: Stripe (Meters API)
• PDF Engine: Browserless.io v2
• Email: Resend + React Email
• Observability: Sentry + PostHog + Axiom
• Testing: Vitest + Playwright + MSW

<!-- build: 2026-04-22T09:20:52.217Z -->

Open Plugins

This repository ships an Open Plugins distribution so AI coding agents (Cursor, Claude Code, and any other Open-Plugins-compatible tool) can install Kamy as a single plugin and get a ready-to-use PDF pipeline.

The plugin bundles four components at the repo root:

Path	Component	Purpose
.plugin/plugin.json	Manifest	Name, version, metadata, declared components
skills/kamy/SKILL.md	Skill	Teaches the agent when and how to render PDFs
rules/kamy-sdk.mdc	Rule	Coding conventions for @kamydev/sdk and the REST API
agents/pdf-template-author.md	Sub-agent	Specialised template-design agent (Handlebars + print CSS)
.mcp.json	MCP server	Hosted MCP at mcp.kamy.dev exposing render tools

To install the plugin in a supported agent, point it at this repository (https://github.com/rakanalalami/kamy) and follow the host's plugin-install flow. The agent will read the manifest and load the components automatically.

See the Open Plugins specification for the full schema.