securenow 7.6.7 → 7.6.8

package/docs/CUSTOMER-GUIDE.md

@@ -1,364 +0,0 @@
-# 🚀 Add Observability to Your Next.js App in 2 Minutes
-
-**Send traces to SecureNow with just 1-2 steps. No webpack warnings!**
-
----
-
-## Step 1: Install SecureNow
-
-```bash
-npm install securenow
-```
-
-**🎉 That's it!** The installer will automatically:
-- Detect your Next.js project
-- Offer to create `instrumentation.ts` (or `.js`)
-- Create `.env.local` template
-- **No webpack bundling warnings** (uses @vercel/otel)
-
-Just answer **"Y"** when prompted!
-
----
-
-## Step 2: Configure Environment Variables
-
-The installer created `.env.local` for you. Just edit it:
-
-```typescript
-import { registerSecureNow } from 'securenow/nextjs';
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-**Using JavaScript?** Create `instrumentation.js` instead:
-
-```javascript
-const { registerSecureNow } = require('securenow/nextjs');
-
-export function register() {
-  registerSecureNow();
-}
-```
-
----
-
-## Step 3: Add Environment Variables
-
-Create or update `.env.local`:
-
-```bash
-# Just update these two values:
-SECURENOW_APPID=my-nextjs-app              # Your app name
-SECURENOW_INSTANCE=http://your-otlp-backend:4318 # Your OTLP / SecureNow URL
-```
-
----
-
-## That's It! 🎉
-
----
-
-## Alternative Setup Methods
-
-### If You Skipped Auto-Setup
-
-**Option 1: Use the CLI (Recommended)**
-
-```bash
-npx securenow init
-```
-
-**Option 2: Create Manually**
-
-Create `instrumentation.ts` at project root:
-
-```typescript
-import { registerSecureNow } from 'securenow/nextjs';
-export function register() { registerSecureNow(); }
-```
-
-Then create `.env.local`:
-
-```bash
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://your-otlp-backend:4318
-```
-
----
-
-## Run Your App
-
-Run your app:
-
-```bash
-npm run dev
-```
-
-You should see:
-
-```
-[securenow] Next.js integration loading
-[securenow] 🚀 Next.js App → service.name=my-nextjs-app
-[securenow] ✅ OpenTelemetry started for Next.js
-```
-
-Open your **SecureNow dashboard** and you'll see traces immediately!
-
----
-
-## 📊 What You Get Automatically
-
-### 🌐 User & Request Data (NEW!)
-- **IP Addresses** - Automatically captured from all sources
-- **User Agents** - Browser/device information
-- **Referers** - Traffic sources
-- **Geographic Data** - Country, region, city (on Vercel/Cloudflare)
-- **Request Headers** - Host, scheme, request IDs
-- **Response Codes** - 200, 404, 500, etc.
-
-**Perfect for:**
-- Debugging location-specific issues
-- Tracking user journeys
-- Bot detection
-- Performance analysis by region
-- Marketing attribution
-
-### 📝 Request Body Capture (Optional - Enable It!)
-- **JSON Payloads** - Capture API request bodies
-- **GraphQL Queries** - See full queries in traces
-- **Form Submissions** - Track form data
-- **Auto-Redaction** - Passwords, tokens, cards automatically hidden
-- **Size Limits** - Configurable max body size
-- **GDPR-Friendly** - Built-in sensitive field protection
-
-**Enable in 2 steps:**
-1. Set `SECURENOW_CAPTURE_BODY=1` in `.env.local`
-2. Create `middleware.ts`: `export { middleware } from 'securenow/nextjs-middleware';`
-
-(The installer can create both files for you automatically!)
-
-**Perfect for:**
-- Debugging API issues with exact inputs
-- Monitoring GraphQL query patterns
-- Understanding user input behavior
-- Validating request schemas
-- Troubleshooting edge cases
-
-See [REQUEST-BODY-CAPTURE.md](./REQUEST-BODY-CAPTURE.md)
-
-### ✅ Next.js Built-in Spans
-- HTTP requests
-- API routes
-- Page rendering
-- Server-side props
-- Metadata generation
-- Time to First Byte (TTFB)
-
-### ✅ Backend Instrumentation
-- **Databases:** PostgreSQL, MySQL, MongoDB, Redis
-- **HTTP Calls:** fetch, axios, http/https
-- **GraphQL** queries
-- **gRPC** calls
-- **And 30+ more libraries**
-
-No additional code needed!
-
----
-
-## ⚙️ Optional: Add Authentication
-
-If your OTLP backend requires an API key:
-
-```bash
-# Add to .env.local
-OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key-here"
-```
-
----
-
-## 🔧 Optional: Advanced Configuration
-
-Want more control? You can pass options:
-
-```typescript
-import { registerSecureNow } from 'securenow/nextjs';
-
-export function register() {
-  registerSecureNow({
-    serviceName: 'my-app',
-    endpoint: 'http://otel-collector:4318',
-    headers: {
-      'x-api-key': process.env.SECURENOW_API_KEY || '',
-    },
-    disableInstrumentations: ['fs'],  // Optional: disable specific instrumentations
-  });
-}
-```
-
----
-
-## 🚨 Troubleshooting
-
-### Not seeing traces?
-
-**1. Check the console output**
-```bash
-npm run dev
-# Look for: [securenow] ✅ OpenTelemetry started
-```
-
-**2. Enable debug mode**
-```bash
-# Add to .env.local
-OTEL_LOG_LEVEL=debug
-```
-
-**3. Create a test span**
-```bash
-# Add to .env.local
-SECURENOW_TEST_SPAN=1
-```
-
-**4. Verify your OTLP endpoint is accessible**
-```bash
-curl http://your-otlp-backend:4318/v1/traces
-```
-
----
-
-## 🎯 Next.js Version Requirements
-
-| Next.js Version | Setup Required |
-|----------------|----------------|
-| **Next.js 15+** | ✅ Just create `instrumentation.ts` |
-| **Next.js 14 and below** | ⚠️ Also add to `next.config.js`: |
-
-For Next.js 14 and below, update `next.config.js`:
-
-```javascript
-const nextConfig = {
-  experimental: {
-    instrumentationHook: true,  // Required for Next.js 14 and below
-  },
-};
-
-module.exports = nextConfig;
-```
-
----
-
-## ☁️ Deployment
-
-### Vercel
-
-1. Go to your Vercel project settings
-2. Add environment variables:
-   - `SECURENOW_APPID=my-nextjs-app`
-   - `SECURENOW_INSTANCE=http://your-otlp-backend:4318`
-3. Redeploy
-
-**Done!** Traces will appear in SecureNow.
-
-### Docker
-
-```dockerfile
-FROM node:20-alpine
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci --production
-
-COPY . .
-RUN npm run build
-
-ENV SECURENOW_APPID=my-nextjs-app
-ENV SECURENOW_INSTANCE=http://otel-collector:4318
-
-EXPOSE 3000
-CMD ["npm", "start"]
-```
-
-### Self-Hosted / VPS
-
-```bash
-export SECURENOW_APPID=my-nextjs-app
-export SECURENOW_INSTANCE=http://your-otlp-backend:4318
-npm start
-```
-
----
-
-## 🎓 Environment Variables Reference
-
-```bash
-# ===== REQUIRED =====
-SECURENOW_APPID=my-app-name           # Your app identifier
-SECURENOW_INSTANCE=http://host:4318   # OTLP / SecureNow endpoint
-
-# ===== OPTIONAL =====
-OTEL_EXPORTER_OTLP_HEADERS="key=val"  # API keys/headers
-SECURENOW_NO_UUID=1                   # Don't append UUID
-OTEL_LOG_LEVEL=info                   # debug|info|warn|error
-SECURENOW_DISABLE_INSTRUMENTATIONS=fs # Comma-separated
-SECURENOW_TEST_SPAN=1                 # Test span on startup
-```
-
----
-
-## 💡 Best Practices
-
-### ✅ DO
-- Use descriptive app names: `checkout-service`, `user-api`
-- Set `SECURENOW_APPID` in production
-- Keep UUID enabled in production (unique per deployment)
-- Use `OTEL_LOG_LEVEL=info` or `warn` in production
-
-### ❌ DON'T
-- Use generic names: `app`, `test`, `api`
-- Hardcode API keys in code
-- Disable important instrumentations without reason
-- Use `OTEL_LOG_LEVEL=debug` in production (too verbose)
-
----
-
-## 📚 More Resources
-
-- **[Complete Guide](./NEXTJS-GUIDE.md)** - In-depth documentation
-- **[Quick Start](./NEXTJS-QUICKSTART.md)** - Condensed version
-- **[Examples](./examples/)** - Code examples
-- **[Architecture](./ARCHITECTURE.md)** - How it works
-
----
-
-## 🆘 Need Help?
-
-- **Documentation:** [Full guides](./NEXTJS-GUIDE.md)
-- **Examples:** See `examples/` folder
-- **SecureNow:** [securenow.ai](https://securenow.ai/)
-
----
-
-## ✨ Why SecureNow?
-
-| Feature | SecureNow | Manual Setup | @vercel/otel |
-|---------|-----------|--------------|--------------|
-| Lines of code | 3 | 100+ | 20+ |
-| Setup time | 2 min | 1-2 hours | 30 min |
-| Auto-instrumentation | 30+ libs | Manual | Limited |
-| Configuration | Env vars | Complex | Medium |
-| Production ready | ✅ Yes | Depends | ✅ Yes |
-
-**Choose SecureNow for the easiest setup!**
-
----
-
-<div align="center">
-
-**Made with ❤️ for Next.js and SecureNow**
-
-[Website](http://securenow.ai/) • [NPM](https://www.npmjs.com/package/securenow) • [Documentation](./NEXTJS-GUIDE.md)
-
-</div>
-

package/docs/EASIEST-SETUP.md

@@ -1,342 +0,0 @@
-# 🎯 Easiest Setup: Next.js with Body Capture
-
-## ✨ The Simplest Way (No Code Changes!)
-
-**Your customers add ONE line and bodies are captured automatically!**
-
----
-
-## 🚀 Setup (2 Steps, 30 Seconds)
-
-### Step 1: Configure Environment
-
-```bash
-# .env.local
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://your-otlp-backend:4318
-SECURENOW_CAPTURE_BODY=1
-```
-
-### Step 2: Add Auto-Capture Import
-
-```typescript
-// instrumentation.ts (or instrumentation.js)
-import { registerSecureNow } from 'securenow/nextjs';
-import 'securenow/nextjs-auto-capture'; // ← ADD THIS LINE!
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-### That's ALL! 🎉
-
-**No other code changes needed!**
-
----
-
-## ✅ What Happens Automatically
-
-### All API Routes Capture Bodies
-
-```typescript
-// app/api/login/route.ts
-// NO CHANGES NEEDED - WORKS AS-IS!
-
-export async function POST(request: Request) {
-  const body = await request.json(); // ← Automatically captured!
-  
-  // Your auth logic...
-  
-  return Response.json({ success: true });
-}
-```
-
-### Sensitive Data Automatically Redacted
-
-```json
-// Request body:
-{
-  "email": "user@example.com",
-  "password": "secret123"
-}
-
-// Captured in SecureNow (password redacted):
-{
-  "email": "user@example.com",
-  "password": "[REDACTED]"
-}
-```
-
-### Works with Everything
-
-- ✅ NextAuth (no conflicts!)
-- ✅ Any middleware
-- ✅ App Router & Pages Router
-- ✅ JSON, GraphQL, Form data
-- ✅ All HTTP methods (POST/PUT/PATCH)
-
----
-
-## 🎓 Complete Example
-
-### File Structure
-
-```
-your-nextjs-app/
-├── instrumentation.ts          ← Add import here
-├── .env.local                  ← Configure here
-├── middleware.ts               ← No changes!
-└── app/
-    └── api/
-        ├── login/route.ts      ← No changes!
-        ├── register/route.ts   ← No changes!
-        └── graphql/route.ts    ← No changes!
-```
-
-### instrumentation.ts
-
-```typescript
-import { registerSecureNow } from 'securenow/nextjs';
-import 'securenow/nextjs-auto-capture'; // ← Enable auto-capture
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-### .env.local
-
-```bash
-# Required
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://otel-collector:4318
-
-# Enable body capture
-SECURENOW_CAPTURE_BODY=1
-
-# Optional: Customize
-SECURENOW_MAX_BODY_SIZE=10240              # 10KB default
-SECURENOW_SENSITIVE_FIELDS=email,phone     # Additional fields to redact
-```
-
-### middleware.ts (Your Existing Code - No Changes!)
-
-```typescript
-// Keep your existing middleware exactly as-is
-import { getToken } from 'next-auth/jwt';
-
-export async function middleware(request) {
-  const token = await getToken({ req: request });
-  if (!token) {
-    return NextResponse.redirect('/login');
-  }
-  return NextResponse.next();
-}
-```
-
-### API Routes (Your Existing Code - No Changes!)
-
-```typescript
-// app/api/login/route.ts
-export async function POST(request: Request) {
-  const { email, password } = await request.json();
-  // Your logic...
-  return Response.json({ success: true });
-}
-
-// app/api/register/route.ts
-export async function POST(request: Request) {
-  const formData = await request.formData();
-  // Your logic...
-  return Response.json({ registered: true });
-}
-
-// app/api/graphql/route.ts
-export async function POST(request: Request) {
-  const { query, variables } = await request.json();
-  // Your logic...
-  return Response.json({ data: result });
-}
-```
-
-**All bodies automatically captured with sensitive data redacted!**
-
----
-
-## 📊 What You Get
-
-### Automatic Capture
-- ✅ All POST/PUT/PATCH requests
-- ✅ JSON bodies
-- ✅ GraphQL queries
-- ✅ Form data
-- ✅ With size limits
-
-### Automatic Redaction (20+ Fields)
-```
-password, passwd, pwd, secret, token, api_key, apikey,
-access_token, auth, credentials, card, cvv, cvc, ssn,
-pin, mysql_pwd, stripeToken, and more...
-```
-
-### Automatic Metadata
-- ✅ IP address
-- ✅ User agent
-- ✅ Headers
-- ✅ Geographic data (Vercel)
-- ✅ Request/response times
-- ✅ Status codes
-
----
-
-## 🔒 Security Built-In
-
-### Safe by Default
-- ✅ 20+ sensitive fields auto-redacted
-- ✅ Size limits enforced (10KB default)
-- ✅ Multipart files NOT captured
-- ✅ Production-ready
-
-### Customizable
-```bash
-# Add your own sensitive fields
-SECURENOW_SENSITIVE_FIELDS=credit_card,ssn,bank_account
-
-# Adjust size limit
-SECURENOW_MAX_BODY_SIZE=20480  # 20KB
-```
-
----
-
-## ⚡ Performance
-
-**Impact: Negligible**
-- First `.json()` call: < 1ms (caching)
-- Subsequent calls: 0ms (cached)
-- Capture: Async, non-blocking
-- Memory: Body cached once, then GC'd
-
-**Production-ready!**
-
----
-
-## 🎯 Customer Journey
-
-### 1. Installation
-
-```bash
-npm install securenow
-```
-
-**Installer auto-creates `instrumentation.ts`!**
-
-### 2. Add Auto-Capture (One Line!)
-
-```typescript
-// instrumentation.ts
-import { registerSecureNow } from 'securenow/nextjs';
-import 'securenow/nextjs-auto-capture'; // ← Add this!
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-### 3. Configure Environment
-
-```bash
-# .env.local
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://otel-collector:4318
-SECURENOW_CAPTURE_BODY=1
-```
-
-### 4. Run App
-
-```bash
-npm run dev
-```
-
-### 5. Check SecureNow
-
-**See traces with:**
-- ✅ Request bodies (redacted)
-- ✅ IP addresses
-- ✅ Response times
-- ✅ All metadata
-
----
-
-## ❓ FAQ
-
-### Q: Do I need to change my API routes?
-
-**A:** No! They work exactly as-is. The capture happens automatically when you call `.json()`.
-
-### Q: Will this break NextAuth?
-
-**A:** No! This patches the Request object safely. Your middleware is completely unaffected.
-
-### Q: What if I don't want to capture all routes?
-
-**A:** For per-route control, use the wrapper approach instead. But for most users, capturing everything is fine (sensitive data is redacted anyway).
-
-### Q: Is this safe for production?
-
-**A:** Yes! It's:
-- Non-invasive (only caches body text)
-- Non-blocking (async capture)
-- Fail-safe (errors don't break app)
-- Battle-tested (standard patching pattern)
-
-### Q: How do I disable body capture?
-
-**A:** Remove `SECURENOW_CAPTURE_BODY=1` or set it to `0`. You'll still get full tracing, just no bodies.
-
----
-
-## 🎉 Comparison
-
-| Setup | Code Changes | Lines Added | Conflicts | Recommended |
-|-------|--------------|-------------|-----------|-------------|
-| **Auto-Capture** | ✅ None | 1 import | ✅ None | ✅ **YES!** |
-| Wrapper | ⚠️ Wrap each route | 1 per route | ✅ None | ⚠️ If you need per-route control |
-| Middleware | ✅ None | 1 export | ❌ Possible | ❌ Not recommended |
-
-**Auto-Capture is the easiest and safest!**
-
----
-
-## ✅ Summary
-
-**What your customers do:**
-1. Add `import 'securenow/nextjs-auto-capture';` to `instrumentation.ts`
-2. Set `SECURENOW_CAPTURE_BODY=1` in `.env.local`
-
-**What they get:**
-- ✅ All request bodies captured automatically
-- ✅ Sensitive fields redacted automatically
-- ✅ Zero code changes in handlers
-- ✅ No middleware conflicts
-- ✅ Works with NextAuth
-- ✅ Production-ready
-
-**Total setup time: 30 seconds!** 🚀
-
----
-
-## 📚 Documentation
-
-- `AUTO-BODY-CAPTURE.md` - Full auto-capture guide
-- `QUICKSTART-BODY-CAPTURE.md` - Quick setup guide
-- `NEXTJS-WRAPPER-APPROACH.md` - Manual wrapper approach
-- `NEXTJS-BODY-CAPTURE-COMPARISON.md` - Compare all approaches
-
----
-
-**The easiest way to trace request bodies in Next.js!** 🎊
-
-
-
-