# agentkit

> The billing framework for Swiss software. Business building blocks for
> Swiss products: subscriptions, shop and
> memberships with Swiss QR-bill, TWINT, Swiss VAT (MWST/TVA/IVA) and
> de/fr/it/en built in. The logic runs inside your app as a library (TypeScript and
> PHP), the data stays in your own database through adapters (Drizzle,
> Prisma, Kysely, Eloquent, Doctrine, PDO). No hosted service in between.

Status: early. subkit is in preview (extracted from production code),
the other kits are being extracted or planned. Package names below are the
target names: npm scope `@agentkit`, Composer vendor `agentkit`.

## Kits

- subkit (`@agentkit/subkit`, preview): subscriptions, plans, trials, proration,
  card or invoice billing, dunning, entitlements (`hasFeature`, `getLimit`),
  lifecycle emails, printable invoices, Swiss QR-bill, React `<BillingPortal />`.
- membershipkit (`@agentkit/membershipkit`, in progress): members, membership
  types, seasons, households, renewal campaigns, signup forms, custom fields,
  fee invoices through subkit.
- shopkit (`@agentkit/shopkit`, planned): products, variants, cart, checkout,
  orders, refunds, stock, shipping, discount codes, gift vouchers.

## Languages

- TypeScript (reference implementation): `npm i @agentkit/subkit`.
- PHP 8.3+ (next): `composer require agentkit/subkit`; Laravel and Symfony
  integrations, Eloquent / Doctrine / PDO adapters.
- Every kit is specified once (schema, rules, HTTP API as OpenAPI, emails,
  translations). A language-neutral conformance suite runs the same scenarios
  against every implementation, so behaviour and stored rows are identical.
  The UI components talk to the HTTP API and work with any backend.

## Switzerland

agentkit is built for the Swiss market first.

- Swiss QR-bill (SIX implementation guidelines): QR-IBAN with 27-digit QR
  reference, or IBAN with RF creditor reference (ISO 11649). CHF and EUR.
  `@agentkit/subkit/swiss-qr-bill`, peer dependency `swissqrbill`.
- Payments: zahls.ch (Payrexx) with TWINT, PostFinance and cards.
  Planned: Datatrans, PostFinance Checkout.
- VAT: `tax: { rateBps: 810, inclusive: true }` (8.1 % standard rate).
  Invoices show the VAT line and the seller's CHE number. Planned: per-line
  rates (2.6 %, 3.8 %), 5-Rappen rounding.
- Languages: de, fr, it, en for UI, emails and invoices (`locale: 'de-CH'`).
- Planned: camt.054/camt.053 bank reconciliation by QR reference, reminder
  levels with fees, eBill, Swiss Post shipping in shopkit.
- Data protection: the kits run in your app and store data in your
  database; no extra processor for customer data.

## Concepts

- One config in code: `subkit({ database, provider, plans, defaultPlanId })`,
  or several kits together with `agentkit({ database, payments, kits: [...] })`.
- Storage adapter contract: create, findOne, findMany, count, update
  (atomic compare-and-set), updateMany, delete, optional transaction.
- HTTP: every kit exposes one handler for its self-service API and the
  payment webhook (TypeScript: fetch Request → Response, `toNextJsHandler()`;
  PHP: PSR-7/PSR-15, Laravel route, Symfony controller).
- Payments: `PaymentProvider` interface; zahls.ch (Payrexx, incl. TWINT) ships
  first. Card data never touches your server, only provider tokens.
- Money is always integer Rappen/cents. Swiss VAT via `tax: { rateBps: 810 }`.
- Customers are referenced by `externalId` – the id from your product
  (user, team, association).
- Cron: call `runDue()` every few minutes for renewals, retries and dunning.

## Website languages

The site exists in German (/de), French (/fr), Italian (/it), Romansh (/rm)
and English (/en).

## Source

The repository is private for now. It will be published on GitHub under the
MIT licence with version 0.1.