diff --git a/README.md b/README.md index 4117c7e..1399232 100644 --- a/README.md +++ b/README.md @@ -17,14 +17,14 @@ Authentication on every call: | `X-Killbill-ApiKey` | Kill Bill tenant API key (must match your Kintsugi Kill Bill connection) | | `X-Killbill-Kintsugi-Signature` | HMAC-SHA256 hex digest of the **raw JSON body** | -The HMAC secret must match on both the Kill Bill plugin config and your Kintsugi Kill Bill connection. +The HMAC secret is stored on both the Kill Bill plugin config (`hmacSecret`) and the Kintsugi connection. In the product flow Kintsugi generates it and uploads plugin config when you **Enable Tax Collection** — you do not paste a secret by hand. ## Prerequisites - JDK 11+ - Maven 3.9+ (build from source) or a release JAR - Kill Bill **0.24.x** with invoice plugin support -- A Kintsugi account with Kill Bill connected and the tax engine enabled +- A Kintsugi account with Kill Bill connected and tax collection enabled ### Kill Bill compatibility @@ -65,51 +65,32 @@ See [Kill Bill plugin installation](https://docs.killbill.io/latest/plugin_insta ## Tenant configuration -### 1. Enable the invoice plugin +After the plugin JAR is installed and running on Kill Bill, configure the tenant from Kintsugi (no manual `uploadPluginConfig` / `uploadPerTenantConfig` curls): -Kill Bill 0.24+ expects JSON for per-tenant config: +1. In Kintsugi, **Connect Kill Bill** (base URL, tenant API key/secret, admin username/password). +2. Click **Enable Tax Collection** on the connection. -```bash -curl -u ':' \ - -H 'X-Killbill-ApiKey: ' \ - -H 'X-Killbill-ApiSecret: ' \ - -H 'Content-Type: text/plain' \ - -H 'X-Killbill-CreatedBy: setup' \ - -d '{"org.killbill.invoice.plugin":"killbill-kintsugi"}' \ - 'https:///1.0/kb/tenants/uploadPerTenantConfig' -``` - -### 2. Upload plugin config +Kintsugi then generates an HMAC secret (if needed), uploads plugin config (`kintsugiUrl` + `hmacSecret`), and enables `killbill-kintsugi` as the tenant invoice plugin. You do not paste secrets by hand. -```bash -curl -u ':' \ - -H 'X-Killbill-ApiKey: ' \ - -H 'X-Killbill-ApiSecret: ' \ - -H 'Content-Type: text/plain' \ - -H 'X-Killbill-CreatedBy: setup' \ - -d 'kintsugiUrl: https://api.trykintsugi.com -hmacSecret: ' \ - 'https:///1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi' -``` - -YAML POJO form is also supported — see `KintsugiConfigurationHandler` in this repo. +For local docker / maintainer smoke tests that talk to Kill Bill without the product UI, see [docker/README.md](docker/README.md). | Config key | Required | Description | |------------|----------|-------------| -| `kintsugiUrl` | Yes | Kintsugi API base URL (no trailing slash), e.g. `https://api.trykintsugi.com` | -| `hmacSecret` | Yes | Shared secret; must match the HMAC secret on your Kintsugi Kill Bill connection | +| `kintsugiUrl` | Yes | Kintsugi API base URL (no trailing slash), e.g. `https://api.trykintsugi.com` — set by Enable Tax | +| `hmacSecret` | Yes | Shared secret for request signatures — generated and uploaded by Enable Tax | | `killbillUrl` | No | Kill Bill base URL for optional Aviate billing-account lookup (default `http://127.0.0.1:8080`) | | `aviateIdToken` | No | Aviate JWT ([Aviate auth](https://docs.killbill.io/latest/aviate-authentication)). When set, the plugin reads [billing accounts](https://docs.killbill.io/latest/aviate-billing-account) before falling back to custom fields. Omit for non-Aviate deployments. | `kintsugiUrl` must be reachable from the Kill Bill JVM (network/firewall/DNS). -## Kintsugi setup - -In your Kintsugi account: +To **inspect** the stored tenant plugin config (not the healthcheck): -1. Connect Kill Bill (base URL, tenant API key/secret, admin credentials). -2. Set the connection HMAC secret to the same value as plugin `hmacSecret`. -3. Enable the tax engine on the connection. +```bash +curl -u ':' \ + -H 'X-Killbill-ApiKey: ' \ + -H 'X-Killbill-ApiSecret: ' \ + 'https:///1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi' +``` See [Kintsugi documentation](https://trykintsugi.com/docs) for the full setup guide. @@ -128,7 +109,13 @@ curl -u ':' \ 'https:///plugins/killbill-kintsugi/healthcheck' ``` -Returns healthy when the plugin is loaded and tenant config is present. +Healthy response (plugin loaded and tenant config present): + +```json +{"message":"Kintsugi plugin configured"} +``` + +The healthcheck does **not** return `kintsugiUrl` or `hmacSecret`. To read those values, use `GET .../uploadPluginConfig/killbill-kintsugi` (see above). ## Local development @@ -145,11 +132,12 @@ See [docker/README.md](docker/README.md) for step-by-step scripts, configuration | Symptom | Likely cause | |---------|----------------| -| No `TAX` lines on invoice | Tax engine not enabled in Kintsugi, or ship-to address has no tax obligation | -| `401` / `403` from Kintsugi | HMAC mismatch — verify the same secret on plugin config and Kintsugi connection | -| `Kintsugi plugin not configured` in logs | Missing `uploadPluginConfig/killbill-kintsugi` for the tenant | +| No `TAX` lines on invoice | Tax collection not enabled in Kintsugi, or ship-to address has no tax obligation | +| `401` / `403` from Kintsugi | HMAC mismatch — re-run **Enable Tax Collection** (re-uploads matching secret) | +| `Kintsugi plugin not configured` in logs | Tenant plugin config missing — re-run **Enable Tax Collection** | | Connection timeout | Kill Bill cannot reach `kintsugiUrl` (DNS, firewall, or Docker networking) | -| Healthcheck unhealthy | Plugin config missing `kintsugiUrl` or `hmacSecret` for the tenant | +| Healthcheck unhealthy | Plugin config missing `kintsugiUrl` or `hmacSecret` for the tenant — re-run **Enable Tax Collection** | +| Expected config keys in healthcheck body | Wrong endpoint — healthcheck only returns `{"message":"..."}`; use `GET .../uploadPluginConfig/killbill-kintsugi` to inspect | ## Behavior notes diff --git a/docker/README.md b/docker/README.md index c0b5bbc..5338eb9 100644 --- a/docker/README.md +++ b/docker/README.md @@ -14,7 +14,9 @@ against a local Kill Bill stack. No dependency on the Kintsugi platform repo. ```bash cp docker/.env.example docker/.env -# Edit KINTSUGI_HMAC_SECRET (must match Kintsugi Kill Bill connection) +# Edit KINTSUGI_HMAC_SECRET for this local stack (setup-tenant.sh uploads it) +# For a real Kintsugi connection, Enable Tax Collection provisions HMAC instead — +# only set this env when using the manual docker scripts below. # Edit KILLBILL_API_KEY / KILLBILL_API_SECRET for your tenant docker compose -f docker/docker-compose.yml up -d @@ -58,14 +60,13 @@ Kintsugi provisions a **test org** for Kill Bill maintainers. You do not put `or |----------|-------------| | `KILLBILL_API_KEY` / `KILLBILL_API_SECRET` | Kill Bill tenant credentials (create in Kaui). **Must equal** the Kintsugi Kill Bill connection `external_id`. | | `KINTSUGI_URL` | Kintsugi API base URL reachable **from the Kill Bill container** | -| `KINTSUGI_HMAC_SECRET` | HMAC secret from the Kintsugi Kill Bill connection (not an API key) | +| `KINTSUGI_HMAC_SECRET` | Secret uploaded by `setup-tenant.sh` as plugin `hmacSecret`. Product path: Kintsugi **Enable Tax Collection** generates this; for docker smoke, put the same value on the test connection (or let enable-tax overwrite Kill Bill and skip re-running setup with a different secret). | | `SMOKE_TAX_STATE` | US state for smoke ship-to (default `TX`; needs tax registration in the test org) | **Test org checklist (Kintsugi side):** -1. Kill Bill connection created with tax engine enabled -2. Connection HMAC secret → `KINTSUGI_HMAC_SECRET` -3. Connection tenant API key → `KILLBILL_API_KEY` (and matching Kill Bill tenant in Kaui) +1. Kill Bill connection created with tax collection enabled (provisions HMAC + plugin config), **or** connection + matching `KINTSUGI_HMAC_SECRET` for manual docker setup +2. Connection tenant API key → `KILLBILL_API_KEY` (and matching Kill Bill tenant in Kaui) For a Kintsugi API running on the host machine: diff --git a/docs/killbill-docs-pr.md b/docs/killbill-docs-pr.md index 068b6e3..2f0d677 100644 --- a/docs/killbill-docs-pr.md +++ b/docs/killbill-docs-pr.md @@ -12,12 +12,6 @@ Install: kpm install_java_plugin kintsugi --from-source-file=target/kintsugi-plugin-0.1.0.jar ``` -Per-tenant configuration: +Per-tenant configuration is provisioned from Kintsugi: connect Kill Bill, then **Enable Tax Collection** (sets the invoice plugin and uploads `kintsugiUrl` / `hmacSecret`). See the plugin README for setup and verification steps. -```properties -org.killbill.invoice.plugin=killbill-kintsugi -``` - -Upload plugin config via `uploadPluginConfig/killbill-kintsugi` with `kintsugiUrl` and `hmacSecret`. See the plugin README for setup and verification steps. - -Healthcheck: `GET /plugins/killbill-kintsugi/healthcheck` +Healthcheck: `GET /plugins/killbill-kintsugi/healthcheck` → `{"message":"Kintsugi plugin configured"}` (does not return config keys; use `GET .../uploadPluginConfig/killbill-kintsugi` to inspect).