### Gradual Rollout Strategy for nostrmq

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Demonstrates a phased approach to enabling nostrmq tracking, starting with conservative settings and progressing to optimized production configurations. Includes monitoring setup and testing strategies.

```javascript
// Phase 1: Enable with conservative settings
process.env.NOSTRMQ_TRACK_LIMIT = "50";
process.env.NOSTRMQ_OLDEST_MQ = "1800";

// Phase 2: Monitor and tune
const tracker = createMessageTracker();
setInterval(() => {
  const stats = tracker.getStats();
  if (stats.recentEventsCount > 40) {
    console.warn("High cache usage detected");
  }
}, 30000);

// Phase 3: Optimize for production
process.env.NOSTRMQ_TRACK_LIMIT = "100";
process.env.NOSTRMQ_OLDEST_MQ = "3600";
```

```javascript
// Set up monitoring
function setupTrackingMonitoring(tracker) {
  setInterval(() => {
    const stats = tracker.getStats();

    // Memory usage alert
    if (stats.recentEventsCount > 80) {
      console.warn("High tracking memory usage:", stats);
    }

    // Persistence health check
    if (!stats.persistenceEnabled) {
      console.warn("Tracking persistence disabled - check file system");
    }

    // Log metrics for monitoring system
    console.log("tracking.events.count", stats.recentEventsCount);
    console.log("tracking.persistence.enabled", stats.persistenceEnabled);
  }, 60000);
}
```

```javascript
// Test with tracking disabled
process.env.NOSTRMQ_DISABLE_PERSISTENCE = "true";
await runFunctionalTests();

// Test with tracking enabled
delete process.env.NOSTRMQ_DISABLE_PERSISTENCE;
process.env.NOSTRMQ_CACHE_DIR = "./test-cache";
await runIntegrationTests();

// Test error conditions
process.env.NOSTRMQ_CACHE_DIR = "/invalid/path";
await runErrorHandlingTests();

// Cleanup
await fs.rm("./test-cache", { recursive: true, force: true });
```

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

### Example .env File Configuration

Source: https://github.com/humansinstitute/nostrmq/blob/main/examples/README.md

Provides an example of how to configure NostrMQ settings using a `.env` file in the project root. This file stores required and optional parameters for the library.

```env
# Required
NOSTRMQ_PRIVKEY=your_64_character_hex_private_key
NOSTRMQ_RELAYS=wss://relay.damus.io,wss://nos.lol,wss://relay.nostr.band

# Optional
NOSTRMQ_POW_DIFFICULTY=8
NOSTRMQ_POW_THREADS=4
```

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

### nostrmq Settings by Use Case (Bash)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Provides example environment variable configurations for nostrmq tailored to different operational needs, including production, high-throughput, long-running, and development/testing scenarios. These settings help optimize performance and resource usage.

```bash
# Production Applications
# Balanced performance and reliability
export NOSTRMQ_OLDEST_MQ=3600          # 1 hour
export NOSTRMQ_TRACK_LIMIT=100         # Standard cache
export NOSTRMQ_CACHE_DIR=.nostrmq      # Default location
# NOSTRMQ_DISABLE_PERSISTENCE not set (persistence enabled)

# High-Throughput Services
# Optimized for performance
export NOSTRMQ_OLDEST_MQ=1800          # 30 minutes
export NOSTRMQ_TRACK_LIMIT=50          # Smaller cache
export NOSTRMQ_DISABLE_PERSISTENCE=true # Memory-only

# Long-Running Services
# Extended history tracking
export NOSTRMQ_OLDEST_MQ=7200          # 2 hours
export NOSTRMQ_TRACK_LIMIT=200         # Larger cache
export NOSTRMQ_CACHE_DIR=/var/cache/nostrmq # System location

# Development/Testing
# Isolated testing environment
export NOSTRMQ_OLDEST_MQ=300           # 5 minutes
export NOSTRMQ_TRACK_LIMIT=20          # Minimal cache
export NOSTRMQ_CACHE_DIR=./test-cache  # Test-specific
```

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

### nostrmq Performance Tuning (Bash)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Configuration examples for tuning nostrmq performance, focusing on either maximizing throughput with minimal overhead or maximizing message protection through extended tracking. These settings adjust cache size and persistence.

```bash
# For Maximum Performance
# Minimize overhead
export NOSTRMQ_TRACK_LIMIT=20
export NOSTRMQ_OLDEST_MQ=900
export NOSTRMQ_DISABLE_PERSISTENCE=true

# For Maximum Protection
# Extended tracking
export NOSTRMQ_TRACK_LIMIT=500
export NOSTRMQ_OLDEST_MQ=7200
# Persistence enabled (default)
```

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

### Set NostrMQ Environment Variables

Source: https://github.com/humansinstitute/nostrmq/blob/main/examples/README.md

Demonstrates setting essential environment variables required for NostrMQ operation, including private key, relays, and optional proof-of-work parameters.

```bash
export NOSTRMQ_PRIVKEY="your_private_key_in_hex"
export NOSTRMQ_RELAYS="wss://relay1.com,wss://relay2.com"
export NOSTRMQ_POW_DIFFICULTY="8"  # Optional, default PoW difficulty
export NOSTRMQ_POW_THREADS="4"     # Optional, worker threads for PoW
```

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

### Install nostrmq

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Installs the nostrmq library using npm. This is the first step to integrate nostrmq into your project.

```bash
npm install nostrmq
```

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

### Environment Configuration Example

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/design.md

Provides example environment variables for configuring nostrMQ, including Nostr private key, relays, and optional Proof-of-Work settings.

```dotenv
# Mandatory
NOSTR_PRIVKEY=xxxxxxxx...xxxxxxxx

# Optional
NOSTR_RELAYS=wss://relay.damus.io,wss://relay.snort.social
NOSTR_POW_DIFFICULTY=22       # integer bits; 0 or unset → disable PoW
NOSTR_POW_THREADS=4           # worker threads for mining
```

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

### Test NostrMQ with Multiple Instances

Source: https://github.com/humansinstitute/nostrmq/blob/main/examples/README.md

Illustrates how to set up and run two separate NostrMQ instances in different terminals for testing message exchange between them. Requires setting distinct private keys.

```bash
# Terminal 1 (Receiver):
export NOSTRMQ_PRIVKEY="your_privkey_hex"
export NOSTRMQ_RELAYS="wss://relay.damus.io,wss://nos.lol"
node examples/basic-usage.js

# Terminal 2 (Sender):
export NOSTRMQ_PRIVKEY="different_privkey_hex"
export NOSTRMQ_RELAYS="wss://relay.damus.io,wss://nos.lol"
# Modify the target pubkey in the example to match Terminal 1's pubkey
node examples/basic-usage.js
```

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

### Nostr MQ Installation

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/design.md

Command to install the nostrmq library using npm.

```bash
npm i nostrmq
```

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

### Generate Nostr Private Key

Source: https://github.com/humansinstitute/nostrmq/blob/main/examples/README.md

Shows how to generate a new Nostr private key and derive the corresponding public key using the nostr-tools library. This is crucial for setting up your Nostr identity.

```javascript
import { generateSecretKey, getPublicKey } from "nostr-tools";

const privkey = generateSecretKey();
const pubkey = getPublicKey(privkey);

console.log("Private key:", Buffer.from(privkey).toString("hex"));
console.log("Public key:", pubkey);
```

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

### CI/CD Integration for Package Testing

Source: https://github.com/humansinstitute/nostrmq/blob/main/README-testing.md

Example of integrating the build and test commands into a CI/CD pipeline to ensure package quality.

```bash
npm run build && npm run test:package
```

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

### Production Deployment Configuration

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Shell commands for setting up production environment variables, creating and securing the cache directory, and monitoring application logs for tracking messages.

```bash
# 1. Set production configuration
export NOSTRMQ_OLDEST_MQ=3600
export NOSTRMQ_TRACK_LIMIT=100
export NOSTRMQ_CACHE_DIR=/var/cache/nostrmq

# 2. Ensure cache directory exists
mkdir -p /var/cache/nostrmq
chown app:app /var/cache/nostrmq
chmod 755 /var/cache/nostrmq

# 3. Deploy application
# (No code changes required)

# 4. Monitor logs for tracking messages
tail -f /var/log/app.log | grep "MessageTracker"
```

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

### Container Deployment Configuration (Dockerfile)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Dockerfile for building a nostrmq application container, setting up the cache directory with appropriate permissions, and defining environment variables for tracking configuration.

```dockerfile
# Dockerfile
FROM node:18-alpine

# Create cache directory with proper permissions
RUN mkdir -p /app/.nostrmq && chown node:node /app/.nostrmq

# Set tracking configuration
ENV NOSTRMQ_CACHE_DIR=/app/.nostrmq
ENV NOSTRMQ_TRACK_LIMIT=100
ENV NOSTRMQ_OLDEST_MQ=3600

USER node
WORKDIR /app

# Volume for persistent cache (optional)
VOLUME ["/app/.nostrmq"]
```

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

### Verify NostrMQ Tracking Functionality

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Demonstrates how to initialize the NostrMQ message tracker, retrieve its statistics, and test duplicate event detection using `hasProcessed` and `markProcessed` methods.

```javascript
import { createMessageTracker } from "nostrmq";

async function validateTracking() {
  const tracker = createMessageTracker();
  await tracker.initialize();

  const stats = tracker.getStats();
  console.log("Tracking validation:", {
    initialized: true,
    persistenceEnabled: stats.persistenceEnabled,
    cacheDir: stats.cacheDir,
    lastProcessed: stats.lastProcessedDate,
  });

  // Test duplicate detection
  const testEventId = "test-" + Date.now();
  const testTimestamp = Math.floor(Date.now() / 1000);

  console.log(
    "Before processing:",
    tracker.hasProcessed(testEventId, testTimestamp)
  );
  await tracker.markProcessed(testEventId, testTimestamp);
  console.log(
    "After processing:",
    tracker.hasProcessed(testEventId, testTimestamp)
  );
}

validateTracking().catch(console.error);
```

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

### Kubernetes Deployment Configuration

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Kubernetes Deployment manifest for deploying a nostrmq application, defining environment variables and volume mounts for cache persistence.

```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nostrmq-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: nostrmq-app:latest
          env:
            - name: NOSTRMQ_CACHE_DIR
              value: "/cache"
            - name: NOSTRMQ_TRACK_LIMIT
              value: "100"
          volumeMounts:
            - name: cache-volume
              mountPath: /cache
      volumes:
        - name: cache-volume
          emptyDir: {}
```

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

### Microservices Architecture Configuration

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

JavaScript code for configuring nostrmq in a microservices environment, including service-specific cache directories and shared configuration parameters.

```javascript
// Service-specific cache directories
const serviceName = process.env.SERVICE_NAME || "unknown";
process.env.NOSTRMQ_CACHE_DIR = `.nostrmq-${serviceName}`;

// Shared configuration
const trackingConfig = {
  oldestMqSeconds: parseInt(process.env.TRACKING_LOOKBACK || "3600"),
  trackLimit: parseInt(process.env.TRACKING_LIMIT || "100"),
  enablePersistence: process.env.NODE_ENV === "production",
};
```

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

### Container Deployment Configuration (docker-compose.yml)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Docker Compose configuration for deploying a nostrmq application, specifying environment variables and volumes for persistent cache management.

```yaml
# docker-compose.yml
version: "3.8"
services:
  nostrmq-app:
    build: .
    environment:
      - NOSTRMQ_CACHE_DIR=/app/.nostrmq
      - NOSTRMQ_TRACK_LIMIT=100
    volumes:
      - nostrmq-cache:/app/.nostrmq

volumes:
  nostrmq-cache:
```

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

### Nostr MQ Server Pong Example

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/design.md

Example of a Nostr MQ server responding to a 'ping' message with a 'pong' reply. It demonstrates using both `receive` to listen for messages and `send` to reply.

```ts
import "dotenv/config";
import { receive, send } from "nostrmq";

receive({
  async onMessage(payload, sender) {
    if (payload?.method === "ping") {
      await send({
        payload: { method: "pong", ts: Date.now() },
        target: sender,
        pow: false,
      });
    }
  },
});
```

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

### Nostr MQ Client Ping Example

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/design.md

Example of sending a 'ping' message from a Nostr MQ client. It uses the `send` function and optionally enables Proof-of-Work based on the `NOSTR_POW_DIFFICULTY` environment variable.

```ts
import "dotenv/config";
import { send } from "nostrmq";

await send({
  payload: { method: "ping" },
  target: "targetHexPubkey",
  pow: true, // uses NOSTR_POW_DIFFICULTY env
});
```

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

### NostrMQ Custom Configuration with Environment Variables

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Shows how to optionally configure NostrMQ's active tracking feature using environment variables. This allows for customization of lookback time, tracking limits, and cache directory.

```javascript
// Optional: Configure tracking via environment variables
process.env.NOSTRMQ_OLDEST_MQ = "7200"; // 2 hours lookback
process.env.NOSTRMQ_TRACK_LIMIT = "200"; // Track 200 events
process.env.NOSTRMQ_CACHE_DIR = "./cache"; // Custom cache directory

const subscription = receive({
  onMessage: handleMessage,
  relays: customRelays,
});
```

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

### Basic NostrMQ Receive Usage

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Demonstrates the basic usage of the `receive` function from the nostrmq library. This code works identically before and after the active tracking feature update, automatically benefiting from replay protection.

```javascript
import { receive } from "nostrmq";

const subscription = receive({
  onMessage: (payload, sender, rawEvent) => {
    console.log("Received:", payload);
  },
});
```

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

### Troubleshoot nostrmq Cache Directory Creation (Bash)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Solutions for nostrmq failing to create its cache directory, often due to permission issues or disk space. Includes commands to fix permissions, use a custom directory, or disable persistence.

```bash
# Option 1: Fix permissions
chmod 755 .
mkdir -p .nostrmq
chmod 755 .nostrmq

# Option 2: Use custom directory
export NOSTRMQ_CACHE_DIR=/tmp/nostrmq-cache

# Option 3: Disable persistence
export NOSTRMQ_DISABLE_PERSISTENCE=true
```

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

### NostrMQ Debugging Commands

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Provides commands for enabling debug logging for NostrMQ and inspecting its cache files. This helps in diagnosing issues and understanding the system's state.

```bash
# Enable debug logging
DEBUG=nostrmq:* node your-app.js

# Check cache files
ls -la .nostrmq/
cat .nostrmq/timestamp.json
cat .nostrmq/snapshot.json
```

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

### NostrMQ High-Performance Configuration

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Illustrates how to tune NostrMQ for high-performance applications by disabling persistence or adjusting tracking parameters. This balances replay protection with throughput requirements.

```javascript
// Option 1: Use memory-only mode for maximum performance
process.env.NOSTRMQ_DISABLE_PERSISTENCE = "true";

// Option 2: Tune for high throughput
process.env.NOSTRMQ_TRACK_LIMIT = "50"; // Smaller cache
process.env.NOSTRMQ_OLDEST_MQ = "1800"; // Shorter window

const subscription = receive({
  onMessage: processHighVolumeMessages,
});
```

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

### NostrMQ Testing and Development Configuration

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Provides options for configuring NostrMQ during testing and development, such as disabling tracking or using a test-specific cache directory. Includes optional cleanup for the test cache.

```javascript
// Option 1: Disable tracking for tests
process.env.NOSTRMQ_DISABLE_PERSISTENCE = 'true';

// Option 2: Use test-specific cache directory
process.env.NOSTRMQ_CACHE_DIR = './test-cache';

function runTests() {
  const subscription = receive({
    onMessage: testHandler
  });

  // Send test events...

  // Optional: Clean up test cache
  await fs.rm('./test-cache', { recursive: true, force: true });
}
```

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

### Troubleshoot nostrmq File Permission Errors (Bash)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Provides solutions for nostrmq encountering file permission errors when trying to save timestamps, often indicated by 'EACCES: permission denied'. Includes commands to fix ownership, permissions, or use alternative directories.

```bash
# Fix ownership and permissions
sudo chown -R $USER:$USER .nostrmq
chmod -R 755 .nostrmq

# Use user-specific directory
export NOSTRMQ_CACHE_DIR=$HOME/.nostrmq

# Use temporary directory
export NOSTRMQ_CACHE_DIR=/tmp/nostrmq-$USER
```

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

### Pipeline Trigger and Response Specification

Source: https://github.com/humansinstitute/nostrmq/blob/main/sendToPipe-plan.md

Defines the JSON structure for initiating a pipeline job and the expected response formats from the service. This includes the 'pipeline-trigger' payload with parameters and the 'pipeline-ack' and 'pipeline-response' formats for job status updates.

```APIDOC
Pipeline Communication Specification:

1. Pipeline Trigger Payload:
   - Type: "pipeline-trigger"
   - Pipeline: Name of the pipeline to execute (e.g., "dialogue")
   - Parameters: Object containing specific inputs for the pipeline.
     - sourceText: Initial text for processing.
     - discussionPrompt: Prompt for AI discussion.
     - iterations: Number of processing iterations.
     - summaryFocus: Guidance for summary generation.
   - RequestId: Unique identifier for the request.
   - Options: Additional settings.
     - priority: Execution priority (e.g., "normal").

   Example:
   {
     "type": "pipeline-trigger",
     "pipeline": "dialogue",
     "parameters": {
       "sourceText": "Artificial Intelligence is rapidly transforming various industries, from healthcare to finance. While AI offers tremendous potential for improving efficiency and solving complex problems, it also raises concerns about job displacement, privacy, and ethical decision-making.",
       "discussionPrompt": "What are the most significant opportunities and challenges that AI presents for society, and how should we approach AI development responsibly?",
       "iterations": 3,
       "summaryFocus": "Summarize the key opportunities and challenges discussed, along with any recommendations for responsible AI development."
     },
     "requestId": "dialogue-request-001",
     "options": {
       "priority": "normal"
     }
   }

2. Immediate Acknowledgment Response:
   - Type: "pipeline-ack"
   - JobId: Unique identifier assigned to the job.
   - Status: "accepted" indicates the job was received and queued.
   - Message: Descriptive message about the job status.
   - RequestId: Corresponds to the original trigger request.

   Example:
   {
     "type": "pipeline-ack",
     "jobId": "job_abc123",
     "status": "accepted",
     "message": "Pipeline execution started",
     "requestId": "dialogue-request-001"
   }

3. Completion Response:
   - Type: "pipeline-response"
   - JobId: Identifier for the completed job.
   - Status: "completed" indicates successful execution.
   - RequestId: Corresponds to the original trigger request.
   - Result: Object containing the output of the pipeline execution.
     - runId: Identifier for this specific pipeline run.
     - conversation: Array of conversation turns.
     - summary: Summary object.
     - files: Object containing file references.
   - ExecutionTime: Time taken for execution in seconds.

   Example:
   {
     "type": "pipeline-response",
     "jobId": "job_abc123",
     "status": "completed",
     "requestId": "dialogue-request-001",
     "result": {
       "runId": "pipeline_xyz789",
       "conversation": [...],
       "summary": {...},
       "files": {...}
     },
     "executionTime": 120.5
   }
```

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

### NostrMQ Active Tracking Configuration Options

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Details the environment variables available for configuring NostrMQ's active tracking feature. These variables allow fine-tuning of message history, tracking limits, cache location, and persistence.

```APIDOC
NostrMQ Active Tracking Configuration:

Environment Variables:

| Variable                      | Default    | Description                                  |
| ----------------------------- | ---------- | -------------------------------------------- |
| `NOSTRMQ_OLDEST_MQ`           | `3600`     | Lookback time in seconds for tracking.       |
| `NOSTRMQ_TRACK_LIMIT`         | `100`      | Maximum number of events to track in memory. |
| `NOSTRMQ_CACHE_DIR`           | `.nostrmq` | Directory for persisting tracking state.     |
| `NOSTRMQ_DISABLE_PERSISTENCE` | `false`    | If true, disables file caching (memory-only).|
```

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

### Configure Message Tracker for High Throughput

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Shows an example of custom configuration for the MessageTracker, optimizing for high-throughput scenarios. This includes setting a shorter lookback window, increasing the track limit, and disabling persistence.

```typescript
import { MessageTracker } from "nostrmq";

// High-throughput configuration
const tracker = new MessageTracker({
  oldestMqSeconds: 1800, // 30 minutes lookback
  trackLimit: 500, // Track more events
  enablePersistence: false, // Memory-only for speed
});

await tracker.initialize();
```

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

### Load Timestamp with Corrupted Cache Handling

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Illustrates the process of loading a timestamp from a cache file, including validation of the cache structure and handling of file read or JSON parsing errors by returning null to start fresh.

```typescript
export async function loadTimestamp(dir: string): Promise<number | null> {
  try {
    const content = await fs.readFile(timestampFile, "utf-8");
    const cache: TimestampCache = JSON.parse(content);

    // Validate cache structure
    if (typeof cache.lastProcessed === "number" && cache.lastProcessed > 0) {
      return cache.lastProcessed;
    }
    return null; // Invalid format
  } catch (error) {
    return null; // Start fresh
  }
}
```

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

### Troubleshoot nostrmq High Memory Usage (Bash & JS)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Addresses high memory consumption in nostrmq, typically caused by an overly large tracking limit. Provides bash commands to reduce the cache size or use memory-only mode, and a JavaScript snippet to add runtime monitoring of tracker statistics.

```bash
# Reduce tracking cache size
export NOSTRMQ_TRACK_LIMIT=50

# Use memory-only mode
export NOSTRMQ_DISABLE_PERSISTENCE=true
```

```javascript
import { createMessageTracker } from "nostrmq";

const tracker = createMessageTracker();
await tracker.initialize();

setInterval(() => {
  const stats = tracker.getStats();
  console.log("Tracking stats:", stats);
}, 60000); // Log every minute
```

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

### Build NostrMQ Package

Source: https://github.com/humansinstitute/nostrmq/blob/main/README-testing.md

Command to build the NostrMQ package, preparing it for testing or deployment.

```bash
npm run build
```

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

### Rollback Strategy: Disable Tracking

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Methods to temporarily disable nostrmq tracking, either via environment variables, clearing the cache directory, or code-level configuration.

```bash
export NOSTRMQ_DISABLE_PERSISTENCE=true
# Restart application
```

```bash
rm -rf .nostrmq/
# Restart application
```

```javascript
// Temporary override in code
import { createMessageTracker } from "nostrmq";

const tracker = createMessageTracker({
  enablePersistence: false,
  trackLimit: 0, // Minimal tracking
});
```

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

### Get Subscription Since Timestamp

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Retrieves the timestamp to be used for filtering relay subscriptions. This ensures only new events since the last processed one are fetched.

```typescript
const since = tracker.getSubscriptionSince();
const filter = {
  kinds: [4],
  "#p": [pubkey],
  since: since, // Only fetch events after this timestamp
};
```

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

### Configure Environment Variables

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Sets up essential configuration parameters for nostrmq by creating a .env file. Key variables include Nostr private key and optional relay URLs or Proof-of-Work settings.

```bash
# Required: Your Nostr private key (64 hex characters)
NOSTRMQ_PRIVKEY=your_private_key_here

# Optional: Relay URLs (comma-separated)
NOSTRMQ_RELAYS=wss://relay.damus.io,wss://relay.snort.social

# Optional: Proof-of-Work settings
NOSTRMQ_POW_DIFFICULTY=0
NOSTRMQ_POW_THREADS=4
```

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

### Integrate Package Testing into package.json

Source: https://github.com/humansinstitute/nostrmq/blob/main/README-testing.md

Shows how to add the local package testing script as a script command within the `package.json` file for easy execution.

```json
{
  "scripts": {
    "test:package": "node test-local-package.js"
  }
}
```

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

### Get Message Tracker Statistics

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Demonstrates how to retrieve monitoring statistics from a MessageTracker instance. It logs key metrics like last processed timestamp, event counts, and persistence status.

```typescript
const stats = tracker.getStats();
console.log({
  lastProcessed: stats.lastProcessed,
  lastProcessedDate: stats.lastProcessedDate,
  recentEventsCount: stats.recentEventsCount,
  persistenceEnabled: stats.persistenceEnabled,
  cacheDir: stats.cacheDir,
});
```

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

### Validate NostrMQ Performance

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Measures the performance of the NostrMQ tracker by processing a batch of events and analyzing execution time and memory usage. It checks if processing 100 events is within acceptable limits.

```javascript
async function validatePerformance() {
  const tracker = createMessageTracker();
  await tracker.initialize();

  const startTime = process.hrtime.bigint();
  const startMemory = process.memoryUsage().heapUsed;

  // Process 100 test events
  for (let i = 0; i < 100; i++) {
    const eventId = `perf-test-${i}`;
    const timestamp = Math.floor(Date.now() / 1000) - i;

    if (!tracker.hasProcessed(eventId, timestamp)) {
      await tracker.markProcessed(eventId, timestamp);
    }
  }

  const endTime = process.hrtime.bigint();
  const endMemory = process.memoryUsage().heapUsed;

  const durationMs = Number(endTime - startTime) / 1_000_000;
  const memoryIncrease = endMemory - startMemory;

  console.log("Performance validation:", {
    eventsPerSecond: Math.round(100 / (durationMs / 1000)),
    memoryIncrease: `${(memoryIncrease / 1024).toFixed(2)} KB`,
    acceptable: durationMs < 1000 && memoryIncrease < 10240, // < 1s, < 10KB
  });
}
```

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

### Basic Usage and Upgrade Compatibility

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Demonstrates the basic usage of the NostrMQ receive function and highlights its backward compatibility. The tracking system automatically activates and provides replay protection without requiring any code modifications for existing applications using the `receive` function.

```javascript
// This code works the same before and after tracking
const subscription = receive({
  onMessage: (payload, sender) => {
    console.log("Received:", payload);
  },
});
```

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

### Run Local Package Tests

Source: https://github.com/humansinstitute/nostrmq/blob/main/README-testing.md

Executes the comprehensive local testing script for the NostrMQ package.

```bash
node test-local-package.js
```

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

### Basic Usage: Send and Receive

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Demonstrates the fundamental usage of nostrmq for sending encrypted messages and subscribing to incoming messages. It shows how to initialize the send and receive functions with necessary options.

```javascript
import { send, receive } from "nostrmq";

// Send a message
const eventId = await send({
  target: "recipient_pubkey_hex",
  payload: { message: "Hello from NostrMQ!" },
});

// Receive messages
const subscription = receive({
  onMessage: (payload, sender, rawEvent) => {
    console.log("Received:", payload, "from:", sender);
  },
});

// Clean up when done
subscription.close();
```

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

### NostrMQ Environment Variables

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Lists environment variables that can be used to configure NostrMQ's active tracking system, overriding default settings for lookback time, track limit, cache directory, and persistence.

```bash
Variable                      | Default    | Description                    
------------------------------|------------|--------------------------------
NOSTRMQ_OLDEST_MQ             | `3600`     | Lookback time in seconds       
NOSTRMQ_TRACK_LIMIT           | `100`      | Maximum recent events to track 
NOSTRMQ_CACHE_DIR             | `.nostrmq` | Cache directory path           
NOSTRMQ_DISABLE_PERSISTENCE | `false`    | Disable file-based caching     
```

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

### Create MessageTracker Instance

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Initializes a MessageTracker with optional configuration for lookback, tracking limits, and cache directory. This allows customization of the active tracking behavior.

```typescript
const tracker = new MessageTracker({
  oldestMqSeconds: 7200, // 2 hours lookback
  trackLimit: 200, // Track 200 recent events
  cacheDir: "./cache", // Custom cache directory
});
```

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

### NPM Package Metadata

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/design.md

Defines the package name, version, entry points, keywords, and dependencies for the nostrMQ NPM package.

```json
{
  "name": "nostrmq",
  "version": "0.3.0",
  "type": "module",
  "exports": {
    ".": "./dist/index.js"
  },
  "files": ["dist"],
  "keywords": ["nostr", "mq", "rpc", "nip04", "nip13", "pow"],
  "dependencies": {
    "nostr-tools": "^2.0.0",
    "ws": "^8.16.0"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "vitest": "^1.5.0",
    "@types/ws": "^8.5.8"
  }
}
```

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

### Troubleshoot nostrmq Missing Recent Messages (Bash)

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/TRACKING-MIGRATION.md

Solutions for scenarios where recent messages are not being received or appear filtered by nostrmq. This can be due to clock skew or cache corruption, and solutions involve adjusting the lookback window, clearing the cache, or disabling tracking.

```bash
# Option 1: Increase lookback window
export NOSTRMQ_OLDEST_MQ=7200

# Option 2: Clear cache to reset
rm -rf .nostrmq/

# Option 3: Disable tracking temporarily
export NOSTRMQ_DISABLE_PERSISTENCE=true
```

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

### Enable Debug Logging for NostrMQ

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Shows how to enable verbose debugging output for the NostrMQ library. This is achieved by setting the `DEBUG` environment variable to `nostrmq:*` before running the Node.js application.

```bash
DEBUG=nostrmq:* node your-app.js
```

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

### Handle Cache Directory Creation Failure

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Demonstrates how the system handles failure to create a cache directory by falling back to memory-only mode. It logs a warning and disables persistence.

```typescript
const dirCreated = await ensureCacheDir(this.cacheDir);
if (!dirCreated) {
  console.warn(
    "Failed to create cache directory, falling back to memory-only mode"
  );
  this.persistenceEnabled = false;
  return;
}
```

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

### API: loadConfig()

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Loads configuration settings from environment variables. It returns a NostrMQConfig object containing validated settings such as the public key and connected relays.

```APIDOC
loadConfig()
  Load configuration from environment variables.

  Returns: NostrMQConfig object with validated settings

  Example:
  const config = loadConfig();
  console.log("Using pubkey:", config.pubkey);
  console.log("Connected to relays:", config.relays);
```

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

### NostrMQ Configuration Environment Variables

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

NostrMQ offers several environment variables to customize its automatic replay protection mechanism. These variables allow tuning lookback time, event tracking limits, cache directory location, and persistence behavior.

```bash
# Override defaults if needed
NOSTRMQ_OLDEST_MQ=3600          # Lookback time in seconds (default: 1 hour)
NOSTRMQ_TRACK_LIMIT=100         # Max recent events to track (default: 100)
NOSTRMQ_CACHE_DIR=.nostrmq      # Cache directory (default: .nostrmq)
NOSTRMQ_DISABLE_PERSISTENCE=false  # Disable file caching (default: false)
```

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

### Advanced Usage: Proof-of-Work Mining

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Illustrates advanced usage for Proof-of-Work mining, showing both automatic mining via the `send` function and manual mining using `mineEventPow` with a custom event template.

```javascript
import { send, mineEventPow } from "nostrmq";

// Send with automatic PoW mining
const eventId = await send({
  target: "recipient_pubkey",
  payload: { urgent: true, data: "Important message" },
  pow: 12, // 12-bit difficulty
});

// Manual PoW mining
const eventTemplate = {
  kind: 30072,
  pubkey: "your_pubkey",
  content: "encrypted_content",
  tags: [],
  created_at: Math.floor(Date.now() / 1000),
};

const minedEvent = await mineEventPow(eventTemplate, 8, 4);
```

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

### Enable Debug Logging for Tracking

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Provides instructions on how to enable detailed debug logging for the nostrmq tracking module using an environment variable. This is useful for troubleshooting and understanding internal operations.

```bash
DEBUG=nostrmq:tracking node your-app.js
```

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

### Integrate Message Tracking in receive()

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Demonstrates how the message tracking system is integrated into the `receive()` function to initialize a tracker, create a filter with a `since` clause, and process incoming events while checking for duplicates.

```typescript
export async function receive(opts: ReceiveOpts): Promise<SubscriptionHandle> {
  // ... relay connection setup ...

  // Initialize message tracker
  const tracker = createMessageTracker();
  await tracker.initialize();

  // Create subscription filter with tracking
  const filter = {
    kinds: [4],
    "#p": [pubkey],
    since: tracker.getSubscriptionSince(), // Only fetch new messages
  };

  // Process incoming events
  const handleEvent = async (event: NostrEvent) => {
    // Check for duplicates
    if (tracker.hasProcessed(event.id, event.created_at)) {
      return; // Skip duplicate
    }

    try {
      // Decrypt and process message
      const decrypted = await nip04.decrypt(
        privkey,
        event.pubkey,
        event.content
      );
      const payload = JSON.parse(decrypted);

      // Mark as processed after successful handling
      await tracker.markProcessed(event.id, event.created_at);

      // Call user callback
      await opts.onMessage(payload, event.pubkey, event);
    } catch (error) {
      console.warn("Failed to process event:", error);
      // Don't mark as processed if handling failed
    }
  };

  // ... subscription management ...
}
```

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

### TrackingConfig Interface

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Defines the configuration options for the MessageTracker, including lookback window, event tracking limits, cache directory, and persistence enablement.

```typescript
interface TrackingConfig {
  oldestMqSeconds: number; // Lookback window (default: 3600)
  trackLimit: number; // Max events to track (default: 100)
  cacheDir: string; // Cache directory (default: ".nostrmq")
  enablePersistence: boolean; // Enable file caching (default: true)
}
```

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

### Initialize MessageTracker

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Loads cached state from disk to initialize the tracker, enabling persistence across restarts. Falls back to memory-only mode if file operations fail.

```typescript
await tracker.initialize();
// Loads timestamp.json and snapshot.json if available
// Falls back to memory-only mode if file operations fail
```

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

### Send Structured Application Data with NostrMQ

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Demonstrates sending structured application data using the `send` function. It includes details on the payload structure, including message type, operation, user data, and metadata with a timestamp.

```javascript
await send({
  target: "recipient_pubkey",
  payload: {
    type: "user_update",
    operation: "profile_change",
    data: {
      userId: 12345,
      name: "Alice Smith",
      email: "alice@example.com",
      preferences: {
        notifications: true,
        theme: "dark",
      },
    },
    metadata: {
      version: "1.0",
      source: "user-service",
      timestamp: new Date().toISOString(),
    },
  },
});
```

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

### Use NostrMQ with TypeScript

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Demonstrates how to integrate NostrMQ into a TypeScript project. It shows importing necessary types and functions like `send`, `receive`, `SendOpts`, and `ReceiveOpts` from the 'nostrmq' package.

```typescript
import { send, receive, SendOpts, ReceiveOpts, NostrMQConfig } from "nostrmq";

const sendOptions: SendOpts = {
  target: "recipient_pubkey",
  payload: { message: "Hello TypeScript!" },
  pow: 8,
};

const eventId: string = await send(sendOptions);
```

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

### API: mineEventPow(event, bits, threads?)

Source: https://github.com/humansinstitute/nostrmq/blob/main/README.md

Mines proof-of-work for an event template. It takes an event object, target difficulty in bits, and an optional number of threads. Returns the event template with the nonce tag added.

```APIDOC
mineEventPow(event, bits, threads?)
  Mine proof-of-work for an event template.

  Parameters:
  - event (object): Event template to mine
  - bits (number): Target difficulty in leading zero bits
  - threads (number, optional): Number of worker threads (default: 1)

  Returns: Promise<object> - Event template with nonce tag added

  Example:
  const eventTemplate = {
    kind: 30072,
    pubkey: "your_pubkey",
    content: "encrypted_content",
    tags: [],
    created_at: Math.floor(Date.now() / 1000),
  };

  const minedEvent = await mineEventPow(eventTemplate, 12, 4);
  console.log(
    "Mined with nonce:",
    minedEvent.tags.find((t) => t[0] === "nonce")
  );
```

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

### NostrMQ MessageTracker Test Infrastructure

Source: https://github.com/humansinstitute/nostrmq/blob/main/test/TEST-RESULTS.md

Overview of the test utilities and runner features developed for validating the NostrMQ MessageTracker.

```APIDOC
Test Infrastructure:

Test Utilities Created:
  - MockDataGenerator: Generates realistic Nostr events for testing scenarios.
  - TestCacheManager: Manages test cache directories and associated files.
  - PerformanceHelper: Measures timing and memory usage during tests.
  - AssertionHelpers: Provides custom assertions for tracking-specific validations.

Test Runner Features:
  - Comprehensive Reporting: Delivers detailed pass/fail analysis.
  - Performance Metrics: Tracks timing and memory usage for performance evaluation.
  - Cleanup Management: Automates the cleanup of test artifacts.
  - Multiple Formats: Supports integration with different test frameworks.
```

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

### Custom Cache Backend Interface

Source: https://github.com/humansinstitute/nostrmq/blob/main/docs/active-tracking.md

Defines the interface for custom cache backends that can be implemented to extend NostrMQ's persistence capabilities. It specifies methods for saving and loading data, allowing users to integrate with different storage solutions.

```typescript
// Custom cache backend
interface CacheBackend {
  save(key: string, value: any): Promise<boolean>;
  load(key: string): Promise<any>;
}
```