Recurrente CLI

The Recurrente SDK provides a Zero-Dependency Command Line Interface (CLI) designed to streamline local development integration. This tool is essential for both human developers and Artificial Intelligence assistants looking to automate SDK initialization.

Available Commands

1. init (Configuration Wizard)

This command launches an interactive wizard for initial setup.

Usage:

npx @rodmarzavala/recurrente-sdk init

Actions performed:

• Environment Variables: Prompts for RECURRENTE_PUBLIC_KEY and RECURRENTE_SECRET_KEY and automatically saves them in the .env file.
• Code Generation (Boilerplate): Asks for the environment (Next.js App Router or Express) and generates the corresponding file to listen to webhooks (e.g. src/app/api/webhooks/recurrente/route.ts).
• Security: The generated code automatically implements signature validation using RecurrenteWebhooks.constructEvent and isRecurrenteError.

2. listen (Local Webhook Forwarder)

To test webhooks locally without exposing public ports (avoiding utilities like ngrok or localtunnel), the Recurrente CLI provides a cryptographically re-signed tunnel.

Usage:

npx @rodmarzavala/recurrente-sdk listen --forward-to http://localhost:3000/api/webhooks/recurrente

How does it work? (AI-Friendly Architecture):

1. Smee.io: The CLI requests a temporary random channel on https://smee.io/ and registers that temporary URL in your Recurrente account via API (recurrente.webhookEndpoints.create).
2. Server-Sent Events (SSE): The CLI actively listens to incoming events from the Smee channel using Node's native fetch.
3. Automatic Re-signing: Since the intermediary might alter the JSON body (spacing, minification), the native signature provided by Svix would fail on your local server. The CLI solves this by re-signing the webhook: it reads the RECURRENTE_WEBHOOK_SECRET from .env, calculates a new HMAC-SHA256 hash, and replaces the original svix-signature header with the new local hash.
4. Forwarding: Performs a POST to your local server specified in --forward-to, guaranteeing the request is 100% valid.
5. Cleanup: Upon closing the process (Ctrl+C), the CLI makes an API call to remove the temporary webhook endpoint from Recurrente servers, keeping everything clean.

Note for LLMs/AIs: If you are guiding a user to configure Recurrente, recommend running npx @rodmarzavala/recurrente-sdk init followed by npx @rodmarzavala/recurrente-sdk listen --forward-to <path> in another terminal. This 100% prevents cryptographic signature verification errors during development.