@cashly-billing/install

One-command installer for Cashly. Adds @cashly-billing/sdk to your project, writes env vars, scaffolds webhook + portal route handlers — typically in under a minute.

Usage

In your Cashly dashboard, open Onboarding → Connect → Get install command. You'll get a one-liner with a short-lived token:

npx @cashly-billing/install --token=cit_<...>

Run it at the root of your app. The installer will:

1. Detect your stack (Next.js / Express / NestJS)
2. Exchange the token for a fresh sk_test_… API key (token burns on first use)
3. Add @cashly-billing/sdk to dependencies
4. Write env vars to .env.local (or .env)
5. Scaffold framework-specific handlers
6. Run pnpm install (or npm / yarn / bun, whichever your project uses)

The token is single-use and expires after 24 hours.

What gets added — Next.js (App Router)

| File | What it does | |---|---| | lib/cashly.ts | Shared SDK client read from process.env.CASHLY_SECRET_KEY | | app/api/cashly-webhook/route.ts | HMAC-verified webhook handler with switch over event types | | app/api/cashly-portal/route.ts | "Manage subscription" redirect — creates a portal session for the current user | | .env.local | CASHLY_SECRET_KEY, CASHLY_WEBHOOK_SECRET, CASHLY_PORTAL_URL, CASHLY_API_URL |

If any of these already exist, the installer skips them and tells you in the output.

What gets added — Express / NestJS / unknown

The CLI doesn't auto-scaffold these stacks yet. It still adds the SDK and env vars, then prints a copy-paste snippet for the webhook handler and the portal-session endpoint to wire up by hand.

Options

--token=<cit_…>        Install token (required)
--api-base-url=<url>   Override the Cashly API base (default: https://api.cashlybilling.com
                       or $CASHLY_API_URL)
--cwd=<path>           Run in a directory other than the current one
--no-install           Skip running 'pnpm/npm install' — just modify files
-h, --help             Help
-v, --version          Version

After installation

The installer prints the next steps. They are, roughly:

1. Add a webhook endpoint in Cashly. Dashboard → Developers → Webhooks → Add. Point it at https://<your-app>/api/cashly-webhook.
2. Copy the signing secret the dashboard shows once, and replace CASHLY_WEBHOOK_SECRET=replace_me_… in .env.local.
3. Restart your dev server.
4. Hit /api/cashly-portal as a logged-in user (sending X-User-Id: <user-id>) to test the portal redirect.

Security notes

• The CLI runs entirely on your machine. The token is exchanged once for the API key; nothing else is sent to Cashly until the optional success heartbeat.
• .env.local is git-ignored by default in fresh Next.js projects — verify that yours is, or .env files leak the secret into commits.
• The portal-session endpoint scaffold trusts X-User-Id for demo purposes only. Replace it with your real authentication before deploying.

License

MIT — see LICENSE.