### Usage Examples for Account Management

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/ACCOUNT-MANAGEMENT-SUMMARY.md

Provides examples of how to set up, run, and manage test accounts using the npm command interface. These commands facilitate initial setup, running stress tests with existing accounts, and managing the lifecycle of test accounts.

```bash
# First time setup
npm run accounts prepare-stress

# Run stress tests (will use existing accounts)
npm run test:light
npm run test:quick

# Manage accounts
npm run accounts list
npm run accounts cleanup 24

# Check what's saved (not in git)
ls stress-test-accounts/
```

--------------------------------

### Get Test Certificate

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

This example demonstrates how to obtain a test certificate using the staging environment. It includes creating an account key and then requesting the certificate for a test domain.

```bash
# 1. Create account key
acme-love create-account-key -o ./staging-account.json

# 2. Get test certificate
acme-love cert \
 -d test.acme-love.com \
 -e admin@acme-love.com \
 --staging \
 --account-key ./staging-account.json \
 -o ./certificates
```

--------------------------------

### Start Interactive Mode

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Launches the CLI in interactive mode for guided certificate generation. Supports environment pre-selection (staging, production) and custom ACME directories.

```bash
acme-love interactive
# or short form
acme-love i
```

```bash
# With environment pre-selection
acme-love interactive --staging
```

```bash
acme-love interactive --production
```

```bash
acme-love interactive --directory https://custom.acme.com/directory
```

--------------------------------

### Install and Use Acme Love CLI

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Install the CLI globally for recommended usage or use npx for on-demand execution. The --help flag provides command usage information.

```bash
# Global installation (recommended)
npm install -g acme-love
acme-love --help

# Or use without installation
npx acme-love interactive --staging
```

--------------------------------

### Install acme-love Globally

Source: https://github.com/thebitrock/acme-love/blob/main/NPM-README.md

Install the acme-love CLI globally for system-wide access. Use the --staging flag for testing with Let's Encrypt's staging environment.

```bash
npm install -g acme-love
acme-love interactive --staging
```

--------------------------------

### Acme Love CLI DNS-01 Challenge Example

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Example of obtaining a certificate using the DNS-01 challenge. This method is recommended for wildcard certificates and does not require a public web server.

```bash
acme-love cert --challenge dns-01 --domain acme-love.com --email user@acme-love.com --staging
```

--------------------------------

### Setup Accounts for Stress Tests

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-ACCOUNT-MANAGEMENT.md

Run this command to prepare test accounts for stress testing scenarios.

```bash
npm run accounts prepare-stress
```

--------------------------------

### Obtain Staging Certificate with DNS Challenge

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Use the command-line mode to get a staging certificate. This example uses the DNS-01 challenge type, which is recommended for wildcard certificates and does not require a public web server.

```bash
# Get a staging certificate (recommended first)
acme-love cert \
 --domain test.acme-love.com \
 --email admin@acme-love.com \
 --staging \
 --challenge dns-01
```

--------------------------------

### Local Installation and Usage with npx

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Installs the ACME Love CLI as a project dependency and demonstrates its usage via npx. This is useful for project-specific installations.

```bash
# Install in project
npm install acme-love

# Use through npx
npx acme-love --help
```

--------------------------------

### Start Acme Love CLI in Interactive Mode

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Initiate interactive mode to guide through certificate generation. You can select an environment or pre-select one like staging or production.

```bash
# Start interactive mode with environment selection
acme-love interactive

# Or with pre-selected environment
acme-love interactive --staging # For testing
acme-love interactive --production # For real certificates
```

--------------------------------

### Install ACME Love CLI from Source

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Installs the ACME Love CLI by cloning the source repository, installing dependencies, building the project, and linking it globally. This method is suitable for development or when needing the latest code.

```bash
git clone https://github.com/thebitrock/acme-love.git
cd acme-love
npm install
npm run build

# Global installation
npm link

# Now acme-love command is available globally
acme-love --help
```

--------------------------------

### CLI and Development Mode

Source: https://github.com/thebitrock/acme-love/blob/main/CLAUDE.md

Commands to build and run the command-line interface, and to start the project in development watch mode.

```bash
npm run cli             # Build + run CLI
npm run dev             # Nodemon watch mode (tsx)
```

--------------------------------

### Install acme-love

Source: https://github.com/thebitrock/acme-love/blob/main/QUICK-START.md

Install the acme-love package using npm.

```bash
npm install acme-love
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/thebitrock/acme-love/blob/main/CONTRIBUTING.md

Clone the ACME Love repository and install project dependencies.

```bash
git clone https://github.com/thebitrock/acme-love.git
cd acme-love
npm install
```

--------------------------------

### DNS TXT Record Example

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Example of the DNS TXT record details provided by the CLI for the DNS-01 challenge. This record must be added to your domain's DNS settings.

```text
Record Type: TXT
Record Name: _acme-challenge.acme-love.com
Record Value: AbCdEf123456...
```

--------------------------------

### Acme Love CLI HTTP-01 Challenge Example

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Example of obtaining a certificate using the HTTP-01 challenge. This method involves a simple validation via an HTTP file and requires the domain to point to your web server.

```bash
acme-love cert --challenge http-01 --domain acme-love.com --email user@acme-love.com --staging
```

--------------------------------

### Interactive Mode with Full Algorithm Selection

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Start the interactive mode with the staging environment, allowing for full algorithm selection during the process.

```bash
# Interactive mode with full algorithm selection
acme-love interactive --staging
```

--------------------------------

### Install ACME Love CLI Globally via npm

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Installs the ACME Love CLI globally using npm. After installation, the 'acme-love' command is available system-wide.

```bash
npm install -g acme-love
```

--------------------------------

### Generate P-384 ECDSA Account Key

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Example command to generate an account key using the P-384 ECDSA algorithm and save it to a file.

```bash
# Generate P-384 ECDSA account key
acme-love create-account-key --algo ec-p384 --output ./my-account.json
```

--------------------------------

### Interactive CLI Mode

Source: https://github.com/thebitrock/acme-love/blob/main/NPM-README.md

Use this command for an interactive experience, which is recommended for beginners. It guides users through the certificate issuance process.

```bash
# Interactive mode (recommended for beginners)
acme-love interactive
```

--------------------------------

### Run ACME Love CLI in Interactive Mode

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Starts the ACME Love CLI in interactive mode for a guided certificate acquisition process. Supports both a full command and a short alias.

```bash
acme-love interactive
# or short form
acme-love i
```

--------------------------------

### Obtain Certificate from Google Trust Services

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

This example demonstrates obtaining a certificate from Google Trust Services by providing their specific ACME directory URL. Ensure your domain and email are correctly specified.

```bash
acme-love cert \
 -d acme-love.com \
 -e admin@acme-love.com \
 --directory https://dv.acme-v02.api.pki.goog/directory
```

--------------------------------

### Obtain Production Certificate with HTTP Challenge and Custom Algorithms

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Generate a production certificate using the HTTP-01 challenge. This example also specifies custom cryptographic algorithms for both the certificate and account keys.

```bash
# Get a production certificate with custom algorithms
acme-love cert \
 --domain acme-love.com \
 --email admin@acme-love.com \
 --production \
 --challenge http-01 \
 --account-algo ec-p256 \
 --cert-algo rsa-4096
```

--------------------------------

### Get Production Certificate via Direct Command

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Obtains a production SSL certificate for a specified domain and email address using the direct command-line interface. Use this for live certificates.

```bash
# Get a production certificate
acme-love cert -d acme-love.com -e admin@acme-love.com --production
```

--------------------------------

### Library Usage: Full Certificate Automation

Source: https://github.com/thebitrock/acme-love/blob/main/NPM-README.md

Demonstrates the complete library workflow for obtaining a certificate using DNS-01 challenge. Includes client initialization, key generation, account registration, order creation, DNS record setup, CSR generation, and certificate download.

```typescript
import { AcmeClient, AcmeAccount, provider, generateKeyPair, createAcmeCsr } from 'acme-love';

// 1. Create client with Let's Encrypt staging
const client = new AcmeClient(provider.letsencrypt.staging, {
  nonce: { maxPool: 64 },
});

// 2. Generate account keys (ECDSA P-256 recommended)
const algo = { kind: 'ec', namedCurve: 'P-256', hash: 'SHA-256' } as const;
const keyPair = await generateKeyPair(algo);
const accountKeys = {
  privateKey: keyPair.privateKey,
  publicKey: keyPair.publicKey,
};

// 3. Create account and register
const account = new AcmeAccount(client, accountKeys);
await account.register({
  contact: 'admin@example.com',
  termsOfServiceAgreed: true,
});

// 4. Request certificate via DNS-01 challenge
const order = await account.createOrder(['example.com']);
const ready = await account.solveDns01(order, {
  setDns: async (preparation) => {
    console.log(`Set TXT record: ${preparation.target} = ${preparation.value}`);
    // Implement DNS record creation via your DNS provider
  },
});

// 5. Generate CSR and finalize
const { derBase64Url } = await createAcmeCsr(['example.com'], algo);
const finalized = await account.finalize(ready, derBase64Url);
const valid = await account.waitOrder(finalized, ['valid']);
const certificate = await account.downloadCertificate(valid);
```

--------------------------------

### Solve HTTP-01 Challenge with Validation

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

This example demonstrates how to solve an HTTP-01 challenge by serving the challenge content and then validating it using a provided URL. It includes setting up a local HTTP server and performing the validation.

```typescript
const ready = await acct.solveHttp01(order, {
  setHttp: async (preparation) => {
    // Serve challenge at: preparation.target
    // Content: preparation.value
    console.log(`Serve ${preparation.value} at ${preparation.target}`);
  },
  waitFor: async (preparation) => {
    // Built-in HTTP validator
    const { validateHttp01ChallengeByUrl } = await import('acme-love/validator');
    const result = await validateHttp01ChallengeByUrl(preparation.target, preparation.value);
    if (!result.ok) throw new Error('HTTP validation failed');
  },
});
```

--------------------------------

### Get Production Certificate

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

This command is used to obtain a production certificate. It's crucial to test thoroughly with staging first due to Let's Encrypt's rate limits. This involves creating a production account key and then requesting the certificate.

```bash
# 1. Create production account key
acme-love create-account-key -o ./production-account.json

# 2. Get production certificate
acme-love cert \
 -d acme-love.com \
 -e admin@acme-love.com \
 --production \
 --account-key ./production-account.json \
 -o ./certificates
```

--------------------------------

### Get Staging Certificate via Direct Command

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Obtains a staging SSL certificate for a specified domain and email address using the direct command-line interface. Staging certificates are for testing purposes.

```bash
# Get a staging certificate (recommended first)
acme-love cert -d acme-love.com -e admin@acme-love.com --staging
```

--------------------------------

### Configure ACME Client for High Load

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Example configuration for initializing the AcmeClient with specific nonce pool settings for high-load scenarios. Tune timeouts and retry strategies as needed.

```typescript
const client = new AcmeClient(directoryUrl, {
  nonce: {
    maxPool: 64,
    prefetchLowWater: 8,
    prefetchHighWater: 32,
  },
  // Optional: tune timeouts / retry strategies as needed
});
```

--------------------------------

### Branded Type Examples

Source: https://github.com/thebitrock/acme-love/blob/main/CLAUDE.md

Illustrates the use of branded types for semantically distinct string values. Use helper functions like `asAccountUrl()` at trust boundaries.

```text
| Type              | Use for                       | Example                                          |
| ----------------- | ----------------------------- | ------------------------------------------------ |
| `AccountUrl`      | Account kid URLs              | `https://acme.test/acct/123`                     |
| `Nonce`           | Replay-nonce values           | Anti-replay tokens                               |
| `Base64UrlString` | Base64url-encoded data        | CSR DER, JWK thumbprints                         |
| `PemString`       | PEM-encoded certificates/keys | `-----BEGIN CERTIFICATE-----`                    |
| `ChallengeToken`  | ACME challenge tokens         | RFC 8555 §8.1 tokens                             |
| `DirectoryUrl`    | ACME directory URLs           | `https://acme-v02.api.letsencrypt.org/directory` |
```

--------------------------------

### Commercial CA with External Account Binding

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Example of obtaining a certificate from a commercial Certificate Authority using External Account Binding (EAB).

```bash
# Commercial CA with External Account Binding
acme-love cert \
 --domain acme-love.com \
 --directory https://acme.zerossl.com/v2/DV90 \
 --eab-kid "your-eab-key-id" \
 --eab-hmac-key "your-eab-hmac-key"
```

--------------------------------

### Enable and Use Debug Logging

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

This example demonstrates how to enable debug logging for the ACME Love library and use specific debug loggers for nonces and HTTP operations. Enable debug logging during development to inspect library behavior.

```typescript
import { enableDebug, debugNonce, debugHttp } from 'acme-love';

// Enable debug for development
enableDebug();

// Use specific debug loggers in your code
debugNonce('Custom nonce debug message');
debugHttp('HTTP operation debug info');
```

--------------------------------

### Initialize ACME Client and Account

Source: https://github.com/thebitrock/acme-love/blob/main/src/lib/README.md

Instantiate the ACME client with the directory URL and generate a new key pair. Then, create an ACME account, register it with contact information, and agree to the terms of service. Finally, create a new order for a domain.

```typescript
import { AcmeClient, AcmeAccount, generateKeyPair, createAcmeCsr } from 'acme-love';

const client = new AcmeClient('https://acme-v02.api.letsencrypt.org/directory');
const keys = await generateKeyPair({ kind: 'ec', namedCurve: 'P-256', hash: 'SHA-256' });

const account = new AcmeAccount(client, keys);
await account.register({ contact: ['mailto:admin@example.com'], termsOfServiceAgreed: true });

const order = await account.createOrder(['example.com']);
```

--------------------------------

### Development Usage: Direct Wrapper Script

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Demonstrates using the CLI directly via a wrapper script, typically when developing from source. Shows how to access help and run in staging mode.

```bash
# Direct wrapper script (if developing from source)
./acme-love --help
./acme-love interactive --staging
```

--------------------------------

### Development and Production Builds

Source: https://github.com/thebitrock/acme-love/blob/main/CLAUDE.md

Commands for building the project for development (including tests) and production (optimized for deployment).

```bash
npm run build           # Dev build (includes tests in tsconfig)
npm run build:prod      # Production build (src/ only, no sourcemaps)
```

--------------------------------

### Create Account

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-ACCOUNT-MANAGEMENT.md

Use this command to create a new account. Ensure the account ID is provided.

```bash
# Create the account first
npm run accounts create <account-id>
```

--------------------------------

### Build and Test Project

Source: https://github.com/thebitrock/acme-love/blob/main/CONTRIBUTING.md

Commands to build the project and run various types of tests, including unit, E2E, and coverage.

```bash
# Build the project
npm run build

# Run tests
npm test # Unit tests
npm run test:e2e # E2E tests (requires setup)
npm run test:coverage # Coverage report

# Code quality
npm run lint # Check code style
npm run format # Format code

# CLI development
npm run cli:help # Test CLI
npm run cli:staging # Interactive staging mode
```

--------------------------------

### Initialize AcmeClient with Provider Presets

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Demonstrates initializing the AcmeClient using predefined provider entries from the 'provider' object. This is the recommended method for standard CAs.

```typescript
import { AcmeClient, provider } from 'acme-love';

// Using predefined provider entries (recommended)
const client = new AcmeClient(provider.letsencrypt.staging);
const client2 = new AcmeClient(provider.google.production);
const client3 = new AcmeClient(provider.zerossl.production);

// With configuration options
const client4 = new AcmeClient(provider.letsencrypt.production, {
  nonce: { maxPool: 64 },
});
```

--------------------------------

### Get ACME Account Information

Source: https://github.com/thebitrock/acme-love/blob/main/QUICK-START.md

Retrieve information about the registered ACME account.

```typescript
// Get account info
const accountInfo = await account.getAccount();
```

--------------------------------

### Conventional Commits Format

Source: https://github.com/thebitrock/acme-love/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
type(scope): description

[optional body]

[optional footer]
```

```text
feat(cli): add support for wildcard certificates
fix(nonce): resolve race condition in nonce manager
docs(readme): update installation instructions
test(e2e): add tests for EAB functionality
```

--------------------------------

### Display Help Information

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Shows general help or help for a specific command. Use this to understand available options and subcommands.

```bash
acme-love --help
```

```bash
acme-love <command> --help
```

--------------------------------

### Get Nonce with Namespace Isolation

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-SUITE-REPORT.md

Demonstrates obtaining a nonce within a specific namespace, ensuring isolation of operations.

```typescript
const nonce = await nonceManager.getNonce(namespace);
```

--------------------------------

### Implement Request Spacing with Delays

Source: https://github.com/thebitrock/acme-love/blob/main/docs/RATE-LIMIT-GUIDE.md

Add small delays between non-urgent requests to avoid hitting rate limits. This example uses a 500ms delay.

```typescript
// Add small delays between non-urgent requests
await delay(500); // 500ms between requests

function delay(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}
```

--------------------------------

### Initialize Rate Limiter and Nonce Manager

Source: https://github.com/thebitrock/acme-love/blob/main/docs/RATE-LIMIT-GUIDE.md

Configure the RateLimiter with retry settings and the NonceManager for efficient nonce fetching, including rate limit awareness.

```typescript
import { NonceManager, RateLimiter } from 'acme-love';

// Create rate limiter with production settings
const rateLimiter = new RateLimiter({
  maxRetries: 5, // 5 retry attempts
  baseDelayMs: 2000, // 2 seconds base delay
  maxDelayMs: 300000, // 5 minutes maximum delay
  respectRetryAfter: true, // Respect Retry-After headers
});

// NonceManager with rate limiting
const nonceManager = new NonceManager({
  newNonceUrl: 'https://acme-v02.api.letsencrypt.org/acme/new-nonce',
  fetch: yourFetchFunction,
  rateLimiter,
  prefetchLowWater: 2, // Minimum 2 nonces in pool
  prefetchHighWater: 5, // Maximum 5 nonces in pool
  maxPool: 10, // Absolute pool maximum
});
```

--------------------------------

### CI/CD Integration for Certificate Renewal

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

A GitHub Actions workflow to automate monthly SSL certificate renewal. It installs the ACME Love CLI and uses secrets for sensitive information.

```yaml
# .github/workflows/renew-cert.yml
name: Renew SSL Certificate

on:
 schedule:
 - cron: '0 0 1 * *' # Monthly
 workflow_dispatch:

jobs:
 renew:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3

 - name: Setup Node.js
 uses: actions/setup-node@v3
 with:
 node-version: '20'

 - name: Install ACME Love
 run: npm install -g acme-love

 - name: Renew Certificate
 run: |
 echo "${{ secrets.ACCOUNT_KEY }}" > account-key.json
 acme-love cert \
 -d ${{ secrets.DOMAIN }}
 -e ${{ secrets.EMAIL }}
 --production \
 --account-key ./account-key.json
 env:
 # Add these secrets in GitHub
 DOMAIN: acme-love.com
 EMAIL: admin@acme-love.com
 ACCOUNT_KEY: ${{ secrets.ACME_ACCOUNT_KEY }}
```

--------------------------------

### Increase DNS Challenge Validation Timeout

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

If DNS propagation is slow, you may need to increase the timeout in your DNS challenge validation function. This example shows waiting for 30 seconds.

```bash
# If DNS propagation is slow, increase timeout in your waitFor function
await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30s
```

--------------------------------

### Cleanup Old Accounts and Wait

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-ACCOUNT-MANAGEMENT.md

Execute this command to clean up old accounts and then wait for the rate limit to reset. A wait of 3+ hours or using a different IP address is recommended.

```bash
# Clean up old accounts and wait
npm run accounts cleanup 1
# Wait 3+ hours or use different IP
```

--------------------------------

### Check Code Style and Formatting

Source: https://github.com/thebitrock/acme-love/blob/main/CONTRIBUTING.md

Verify code linting and formatting before submitting changes.

```bash
npm run lint:check # Check for issues
npm run format:check # Check formatting
npm test # Ensure tests pass
```

--------------------------------

### Rebuild Project

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-ACCOUNT-MANAGEMENT.md

Run this command to rebuild the project, which can resolve "Module not found" errors.

```bash
# Rebuild the project
npm run build
```

--------------------------------

### Get ACME Provider Directory URL

Source: https://github.com/thebitrock/acme-love/blob/main/src/lib/README.md

Access pre-configured ACME provider URLs from the '/directory' subpath export. This is useful for quickly obtaining the correct directory endpoint for known providers like Let's Encrypt staging.

```typescript
import { provider } from 'acme-love/directory';

const url = provider.letsencrypt.staging.directoryUrl;
```

--------------------------------

### Run Unit Tests

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-SUITE-REPORT.md

Execute unit tests only. Use this to quickly check the logic of individual components.

```bash
npm run test:unit # Unit tests only
```

--------------------------------

### Create ACME Client with Provider Preset

Source: https://github.com/thebitrock/acme-love/blob/main/QUICK-START.md

Instantiate the AcmeClient using a recommended provider preset.

```typescript
import { AcmeClient, provider } from 'acme-love';

// Using provider preset (recommended)
const client = new AcmeClient(provider.letsencrypt.staging);
```

--------------------------------

### Get or Create Account Keys in Test Code

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-ACCOUNT-MANAGEMENT.md

Programmatically retrieve existing or create new persistent account keys for a named test account within your TypeScript test suite. This is useful for reusing accounts across test runs.

```typescript
import { testAccountManager } from './utils/account-manager.js';

// Get or create persistent account keys
const accountKeys = await testAccountManager.getOrCreateAccountKeys('my-test-account');

// Use with ACME client
const client = new AcmeClient(STAGING_DIRECTORY_URL);
const account = new AcmeAccount(client, accountKeys);
```

--------------------------------

### get(namespace = 'default')

Source: https://github.com/thebitrock/acme-love/blob/main/docs/NONCE-MANAGER.md

Retrieves an available fresh nonce from the pool or waits for a refill. It triggers an asynchronous refill if the pool is depleted. The namespace defaults to 'default', but can be customized using the CA hostname or a custom key to isolate nonce pools.

```APIDOC
## get(namespace = 'default')

### Description
Returns an available fresh nonce or waits for a refill. Triggers async refill if pool depleted.

### Parameters
#### Query Parameters
- **namespace** (string) - Optional - Namespace defaults to 'default' — use the CA hostname or a custom key to isolate pools.

### Response
#### Success Response (200)
- **nonce** (string) - A fresh nonce.
```

--------------------------------

### Initialize AcmeClient with String URLs

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Shows how to initialize the AcmeClient by providing ACME directory URLs as strings. This method is useful for custom or enterprise ACME directories.

```typescript
import { AcmeClient } from 'acme-love';

// Using string URLs directly
const client = new AcmeClient('https://acme-staging-v02.api.letsencrypt.org/directory');
const client2 = new AcmeClient('https://dv.acme-v02.api.pki.goog/directory');

// Custom ACME directory
const client3 = new AcmeClient('https://my-custom-ca.com/acme/directory');
```

--------------------------------

### Generate Key Pairs and CSRs with Custom Algorithms

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

This snippet shows how to generate cryptographic key pairs and create ACME Certificate Signing Requests (CSRs) using custom algorithms. It provides examples for both high-security (P-521, RSA-4096) and performance-optimized (P-256) configurations.

```typescript
import { generateKeyPair, createAcmeCsr } from 'acme-love';

// High-security setup: P-521 for account, RSA-4096 for certificate
const accountAlgo = { kind: 'ec', namedCurve: 'P-521', hash: 'SHA-512' };
const certAlgo = { kind: 'rsa', modulusLength: 4096, hash: 'SHA-384' };

const accountKeys = await generateKeyPair(accountAlgo);
const { derBase64Url, keys: certKeys } = await createAcmeCsr(['acme-love.com'], certAlgo);

// Performance-optimized setup: P-256 for both
const fastAlgo = { kind: 'ec', namedCurve: 'P-256', hash: 'SHA-256' };
const accountKeys = generateKeyPair(fastAlgo);
const { derBase64Url } = await createAcmeCsr(['acme-love.com'], fastAlgo);
```

--------------------------------

### Create a Specific Test Account

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Create a new test account with a custom name. This allows for better organization and isolation of accounts for different testing scenarios.

```bash
npm run accounts create my-test-account
```

--------------------------------

### List All Test Accounts

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-ACCOUNT-MANAGEMENT.md

Command to display a list of all currently managed test accounts.

```bash
# List all accounts
npm run accounts list
```

--------------------------------

### Comprehensive ACME Error Handling in TypeScript

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Implement detailed error handling for ACME protocol errors using specific error types provided by `acme-love`. This example demonstrates handling server maintenance, rate limiting, nonce issues, account errors, order status, EAB requirements, and general ACME errors.

```typescript
import {
  AcmeError,
  ServerMaintenanceError,
  RateLimitedError,
  BadNonceError,
  AccountDoesNotExistError,
  OrderNotReadyError,
  ExternalAccountRequiredError,
  RateLimitError, // From rate limiter
} from 'acme-love';

try {
  await account.createOrder(['acme-love.com']);
} catch (error) {
  // Server maintenance detection
  if (error instanceof ServerMaintenanceError) {
    console.log(' Service is under maintenance');
    console.log(' Check https://letsencrypt.status.io/');
    console.log(' Please try again later when the service is restored.');
    return;
  }

  // Rate limiting with automatic retry information
  if (error instanceof RateLimitedError) {
    const retrySeconds = error.getRetryAfterSeconds();
    console.log(` Rate limited. Retry in ${retrySeconds} seconds`);
    console.log(` Details: ${error.detail}`);

    // Wait and retry automatically
    if (retrySeconds && retrySeconds < 300) {
      // Max 5 minutes
      await new Promise((resolve) => setTimeout(resolve, retrySeconds * 1000));
      // Retry the operation...
    }
    return;
  }

  // Nonce issues (automatically handled by nonce manager)
  if (error instanceof BadNonceError) {
    console.log(' Invalid nonce - this should be handled automatically');
    // The NonceManager typically retries these automatically
  }

  // Account-related errors
  if (error instanceof AccountDoesNotExistError) {
    console.log(' Account does not exist - need to register first');
  }

  // Order state errors
  if (error instanceof OrderNotReadyError) {
    console.log(' Order not ready for finalization - complete challenges first');
  }

  // EAB requirement
  if (error instanceof ExternalAccountRequiredError) {
    console.log(' This CA requires External Account Binding (EAB)');
    console.log(' Use --eab-hmac-key option or provide EAB credentials');
  }

  // Rate limiter errors (from internal rate limiting system)
  if (error instanceof RateLimitError) {
    console.log(` Internal rate limit: ${error.message}`);
    console.log(` Attempts: ${error.rateLimitInfo.attempts}`);
    console.log(` Retry in ${error.rateLimitInfo.retryDelaySeconds}s`);
  }

  // Generic ACME error with details
  if (error instanceof AcmeError) {
    console.log(` ACME Error: ${error.detail}`);
    console.log(` Type: ${error.type}`);
    console.log(` Status: ${error.status}`);

    // Handle subproblems for compound errors
    if (error.subproblems?.length) {
      console.log(' Subproblems:');
      error.subproblems.forEach((sub, i) => {
        console.log(` ${i + 1}. ${sub.detail} (${sub.type})`);
      });
    }
  }
}
```

--------------------------------

### Create Account Key with ACME Love CLI

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Creates an account key file for ACME protocol operations, saving it to a specified output path. This key is essential for interacting with ACME CAs.

```bash
# Create account key
acme-love create-account-key -o ./my-account.json
```

--------------------------------

### Create Account Key with Specific Algorithm

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Create an account key using a specific cryptographic algorithm, such as ECDSA P-521 for maximum security. The output is saved to a JSON file.

```bash
acme-love create-account-key --algo ec-p521 -o high-security-account.json
```

--------------------------------

### Run Unit Tests with Coverage

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-SUITE-REPORT.md

Execute unit tests and generate a coverage report. Useful for identifying untested code sections.

```bash
npm run test:coverage # Unit tests with coverage report
```

--------------------------------

### Library Usage: HTTP-01 Challenge

Source: https://github.com/thebitrock/acme-love/blob/main/NPM-README.md

Shows how to solve the HTTP-01 challenge within the library workflow. Requires serving a specific file content at a given target URL.

```typescript
const ready = await account.solveHttp01(order, {
  setHttp: async (preparation) => {
    console.log(`Serve file at: ${preparation.target}`);
    console.log(`Content: ${preparation.value}`);
    // Place file on your web server
  },
});
```

--------------------------------

### Run All Tests

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-SUITE-REPORT.md

Execute all tests, including unit and E2E tests. This provides a comprehensive check of the application.

```bash
npm test # All tests (unit + e2e)
```

--------------------------------

### Initialize NonceManager

Source: https://github.com/thebitrock/acme-love/blob/main/docs/NONCE-MANAGER.md

Instantiate NonceManager with configuration for nonce fetching and pooling. Ensure your httpGet function returns an object with status, headers, and data properties.

```typescript
import { NonceManager } from 'acme-love';
import { httpGet } from './http-wrapper.js'; // must return { status, headers, data }

const nm = new NonceManager({
  newNonceUrl: 'https://acme-v02.api.letsencrypt.org/acme/new-nonce',
  fetch: httpGet,
  maxPool: 32,
  prefetchLowWater: 4,
  prefetchHighWater: 16,
});

// Manual flow (namespace defaults to 'default')
const nonce = await nm.get('letsencrypt');
// sign JWS with `nonce` ... send request ... capture response
// Nonces from responses are harvested automatically inside withNonceRetry.
```

--------------------------------

### Generate Certificate with DNS-01 Challenge

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Use the DNS-01 challenge for certificate generation. This method is recommended for wildcard certificates and does not require a public web server.

```bash
acme-love cert --challenge dns-01 -d acme-love.com -e user@acme-love.com --staging
```

--------------------------------

### Run Standard Test Suite

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Executes the default test suite, which excludes stress tests. This is the primary command for general testing.

```bash
# Run standard test suite (fast, excludes stress tests)
npm test
```

--------------------------------

### Default CLI Directory Structure

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Illustrates the default directory structure created by the ACME Love CLI for certificates and configuration files. Includes paths for certificates, keys, CSRs, and order details.

```bash
# Default directory structure created by CLI
./certificates/
 acme-love.com/
 cert.pem # Certificate chain
 cert-key.json # Certificate private key (JWK format)
 cert.csr.pem # Certificate signing request
 order.json # ACME order details
 account-key.json # ACME account keys (JWK format)
```

--------------------------------

### Download Certificate

Source: https://github.com/thebitrock/acme-love/blob/main/QUICK-START.md

Wait for the order to be valid and download the certificate.

```typescript
const valid = await account.waitOrder(finalized, ['valid']);
const certificate = await account.downloadCertificate(valid);
```

--------------------------------

### CLI Account Management Commands

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/TEST-ACCOUNT-MANAGEMENT.md

Use these npm scripts to manage test accounts. They allow listing, creating, deleting, cleaning up old accounts, and preparing accounts for stress tests.

```bash
npm run accounts list # List all accounts
```

```bash
npm run accounts create <account-id> # Create/load account
```

```bash
npm run accounts delete <account-id> # Delete account
```

```bash
npm run accounts cleanup [hours] # Delete old accounts
```

```bash
npm run accounts prepare-stress # Prepare all stress test accounts
```

--------------------------------

### Run Acme Love CLI via Development Wrapper

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Execute the CLI directly from the development source. This wrapper automatically builds the CLI when needed.

```bash
./acme-love --help
```

--------------------------------

### Generate Certificate with HTTP-01 Challenge

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Use the HTTP-01 challenge for certificate generation. This method requires your domain to point to a web server that can serve files from a specific directory.

```bash
acme-love cert --challenge http-01 -d acme-love.com -e user@acme-love.com --staging
```

--------------------------------

### Obtain Certificate with External Account Binding (EAB)

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Use this command for CAs like ZeroSSL or Google Trust Services that require External Account Binding (EAB). Ensure you replace 'your-key-identifier' and 'your-base64url-hmac-key' with your actual EAB credentials.

```bash
acme-love cert \
 -d acme-love.com \
 -e admin@acme-love.com \
 --eab-kid "your-key-identifier" \
 --eab-hmac-key "your-base64url-hmac-key" \
 --directory https://acme.zerossl.com/v2/DV90
```

--------------------------------

### Create ACME Client with Custom URL and Options

Source: https://github.com/thebitrock/acme-love/blob/main/QUICK-START.md

Instantiate the AcmeClient with a custom directory URL and nonce management options.

```typescript
import { AcmeClient, provider } from 'acme-love';

// Or with a string URL and options
const client = new AcmeClient('https://acme-v02.api.letsencrypt.org/directory', {
  nonce: {
    maxPool: 20,
    prefetchLowWater: 5,
    maxAgeMs: 120_000,
  },
});
```

--------------------------------

### NonceManager Constructor

Source: https://github.com/thebitrock/acme-love/blob/main/docs/NONCE-MANAGER.md

Initializes a new NonceManager instance with specified options. The constructor allows configuration of nonce URLs, fetch functions, age limits, pool sizes, and logging.

```APIDOC
## constructor(options: NonceManagerOptions)

### Description
Initializes a new NonceManager instance.

### Parameters
#### Request Body
- **newNonceUrl** (string) - Required - Absolute ACME newNonce endpoint.
- **fetch** (FetchLike) - Required - Function performing HEAD/GET returning `HttpResponse`.
- **maxAgeMs** (number) - Optional - Discard nonce older than this (avoid replay window issues). Defaults to 120000.
- **maxPool** (number) - Optional - Hard upper bound of stored nonces. Defaults to 32.
- **prefetchLowWater** (number) - Optional - When pool size below this, start prefetching (0 disables). Defaults to 0.
- **prefetchHighWater** (number) - Optional - Target level to fill up to (<= maxPool). Defaults to `prefetchLowWater`.
- **log** (function) - Optional - Diagnostic logger. Defaults to a noop function.
```

--------------------------------

### Project Structure Overview

Source: https://github.com/thebitrock/acme-love/blob/main/CONTRIBUTING.md

Illustrates the directory structure of the ACME Love project, highlighting key directories and entry points.

```text
src/
 cli.ts # CLI entry point
 index.ts # Library entry point
 types.ts # TypeScript definitions
 acme/ # ACME protocol implementation
 utils/ # Utility functions
 ...

__tests__/ # Test files
docs/ # Documentation
```

--------------------------------

### Create Cloudflare DNS-01 Solver

Source: https://github.com/thebitrock/acme-love/blob/main/README.md

Import and instantiate the Cloudflare DNS-01 solver using your API token. This is used for automating DNS challenges with Cloudflare.

```typescript
import { createCloudflareDns01Solver } from 'acme-love-cloudflare';
// or
import { createRoute53Dns01Solver } from 'acme-love-route53';

const solver = createCloudflareDns01Solver({ apiToken: process.env.CF_API_TOKEN! });
const ready = await account.solveDns01(order, solver);
```

--------------------------------

### One-time Certificate Generation via CLI

Source: https://github.com/thebitrock/acme-love/blob/main/NPM-README.md

Generate a certificate using the acme-love CLI for a single domain. Supports DNS-01 challenge and staging environment.

```bash
npx acme-love cert \
  --domain example.com \
  --email admin@example.com \
  --staging \
  --challenge dns-01
```

--------------------------------

### Development Usage: Make Commands

Source: https://github.com/thebitrock/acme-love/blob/main/docs/CLI.md

Leverages make targets for streamlined CLI operations in a development environment. Offers commands for help, general CLI help, and interactive modes.

```bash
# Make commands
make help # Show all make targets
make cli # Show CLI help
make interactive # Interactive mode
make staging # Staging mode
```

--------------------------------

### Linting and Formatting

Source: https://github.com/thebitrock/acme-love/blob/main/CLAUDE.md

Commands for checking code style with ESLint and Prettier, and for automatically fixing formatting issues.

```bash
npm run lint:check      # ESLint check
npm run format:check    # Prettier check
npm run lint:format     # Fix both lint and format
```

--------------------------------

### Development and Production Rate Limiter Configurations

Source: https://github.com/thebitrock/acme-love/blob/main/docs/reports/RATE-LIMITING-SUMMARY.md

Configure RateLimiter instances for development (fast retries) and production (conservative settings) environments. Adjust maxRetries, baseDelayMs, and maxDelayMs according to your needs.

```typescript
const devRateLimiter = new RateLimiter({
  maxRetries: 2,
  baseDelayMs: 100,
  maxDelayMs: 5000,
});

const prodRateLimiter = new RateLimiter({
  maxRetries: 5,
  baseDelayMs: 5000,
  maxDelayMs: 600000, // 10 minutes
});
```

--------------------------------

### Running Tests

Source: https://github.com/thebitrock/acme-love/blob/main/CLAUDE.md

Commands for executing various types of tests, including unit, end-to-end, and coverage reports. Some tests require specific environment variables.

```bash
npm test                # Unit tests (excludes stress, rate-limiting, e2e)
npm run test:unit       # Unit tests only (__tests__/unit/)
npm run test:e2e        # E2E tests (needs ACME_E2E_ENABLED=1 for CI)
npm run test:coverage   # Unit tests with coverage report
```