Sonic Point - AI-Powered API Endpoint Scanner & Tester

Sonic Point adalah CLI tool yang powerful untuk melakukan scanning, testing, dan dokumentasi otomatis terhadap API endpoints backend. Didesain untuk developer yang ingin automation testing endpoint dengan intelligence menggunakan AI.

Fitur Utama

1. Endpoint Discovery & Scanning 🔍

• Otomatis scan dan discover semua endpoint dari codebase backend
• Support untuk berbagai framework (Express, FastAPI, Django, dll)
• Parse dynamic routes dan parameters secara intelligent
• Ekstrak HTTP method, path, dan parameter info

2. Schema Extraction & Validation 📋

• Extract validation schemas dari codebase
• Connect endpoint dengan request/response schemas
• Build API graph relationship antar endpoints
• Support untuk Zod, Joi, Yup, dan schema lainnya

3. Backend Knowledge Graph 🧠

• Build relationship graph dari backend code
• Analisis controller, service, middleware relationships
• Generate context untuk AI payload generation
• Snippet collection dari source code

4. AI-Powered Payload Generation 🤖

• Generate realistic test payloads menggunakan Gemini AI
• Smart payload generation berdasarkan schema definition
• Support untuk request body auto-generation
• Cache payload untuk consistency

5. Interactive Testing & Reporting ✅

• Send HTTP requests dengan authentication
• Dynamic parameter resolution
• Beautiful CLI table output dengan status indicators
• Session-based reporting system
• Supabase-backed storage untuk persistence

6. Enhanced CLI Output 🎨

• Loading spinner dengan ora untuk better UX
• Color-coded status symbols (✔ ✖ ⚠)
• Styled boxes dengan boxen untuk important messages
• Clean table formatting dengan cli-table3
• Beautiful JSON response formatting

Commands Reference

sonic-point init

Inisialisasi konfigurasi project

Setup backend target dan provider configuration:

sonic-point init

Langkah-langkah:

1. Input Base URL backend (e.g., http://localhost:3000)
2. Input login endpoint (e.g., /api/auth/login)
3. Input credentials untuk authentication
4. Input token field path (e.g., data.token)
5. Configuration disimpan di .sonicpoint.json

sonic-point scan [options]

Scan dan discover endpoints dari codebase

# Scan basic endpoints
sonic-point scan

# Scan dengan schema connection
sonic-point scan --schema

# Build backend knowledge graph
sonic-point scan --context

# Output source snippets as JSON
sonic-point scan --snippets

Options:

• --schema - Connect endpoints dengan validation schemas, build API graph
• --context - Build backend knowledge graph untuk advanced analysis
• --snippets - Output source code snippets sebagai JSON

Output:

• Daftar semua endpoints dengan method & path
• Visual API graph (jika --schema)
• Backend context info (jika --context)

sonic-point schema

Extract dan tampilkan validation schemas

sonic-point schema

Fungsi:

• Extract semua validation schemas dari codebase
• Show schema type (Zod, Joi, Yup, custom, dll)
• Display field definitions
• Render dalam format tabel yang rapi

sonic-point send [endpoint] [options]

Send HTTP requests dan testing endpoints

# Send all endpoints (interactive selection)
sonic-point send --all

# Send specific endpoint
sonic-point send /api/users

# Send specific method on endpoint
sonic-point send /api/users --method GET

# Send dan sync ke Supabase
sonic-point send --all --sync

Options:

• --all - Send semua endpoints tanpa prompt
• --method <method> - Filter by HTTP method (GET, POST, PUT, etc)
• --sync - Sync results ke Supabase setelah testing

Fitur Intelligent:

• Auto-resolve dynamic parameters (:id, :userId, dll)
• Fetch sample values dari collection endpoints
• Manual input jika tidak ada sample value
• Generate AI payloads untuk POST/PUT/PATCH (jika Gemini available)
• Show loading spinner untuk AI generation
• Display summary table di akhir

Output:

• Summary table dengan STATUS per endpoint
• Request/Response detail untuk setiap endpoint
• Success/Error indicators dengan symbols

sonic-point report [method] [endpoint]

Publish test results dan generate report link

# Publish all cached results
sonic-point report

# Publish specific HTTP method
sonic-point report GET

# Publish specific endpoint
sonic-point report GET /api/users

Fungsi:

• Publish cached local test results ke Supabase
• Generate unique session ID
• Create sharable report link
• Show report URL untuk akses di web dashboard

Output:

✓ Report published successfully!
Session ID: abc-123-xyz
Report URL: https://sider.hackathon.sev-2.com/report/session/abc-123-xyz

Architecture & Modules

Core Modules

📱 src/scanner.ts - Endpoint Discovery

Fungsi: Scan codebase dan discover API endpoints

• Parse file syntax menggunakan Babel parser
• Extract route definitions dari controller files
• Identify HTTP methods dan path patterns
• Handle dynamic route parameters

Algoritma:

• Traverse AST (Abstract Syntax Tree) untuk find route definitions
• Pattern matching untuk detect common route declaration patterns
• Support untuk: Express Router, FastAPI, Django, custom patterns

🔗 src/apiGraph.ts - API Graph Builder

Fungsi: Build relationship graph antar endpoints dan schemas

• Connect endpoints dengan validation schemas
• Analyze endpoint dependencies
• Create visual API map
• Export graph structure

Algoritma:

• Build node-based graph representation
• Link endpoints dengan request/response schemas
• Calculate relationship scores
• Support untuk nested/hierarchical endpoints

🧠 src/backendGraph.ts - Backend Knowledge Graph

Fungsi: Build comprehensive knowledge graph dari backend architecture

• Map controllers, services, middlewares
• Analyze function relationships
• Generate context snippets
• Support untuk smart AI generation

Algoritma:

• Deep code analysis dengan Babel traverse
• Build multi-level graph (controller → service → handler)
• Extract relevant context untuk AI
• Score relevance untuk prioritization

🤖 src/ai/generateRequestBody.ts - AI Payload Generator

Fungsi: Generate realistic test payloads menggunakan Gemini AI

• Parse schema definitions
• Generate context string
• Call Gemini API dengan smart prompting
• Cache dan reuse generated payloads

Kelebihan Algoritma:

1. Schema-aware generation
   - Parse validation schema
   - Understand field types & constraints
   - Generate valid data

2. Context-enriched prompting
   - Include backend logic context
   - Consider business rules
   - Generate realistic scenarios

3. Smart caching
   - Cache generated payloads
   - Reuse untuk consistency
   - Reduce API calls

4. Error handling
   - Fallback ke dummy data
   - Graceful degradation
   - User warnings

📊 src/tester.ts - Test Executor & Reporter

Fungsi: Execute tests, render output, publish reports

• Authentication & token management
• Dynamic parameter resolution
• HTTP request execution
• Beautiful output rendering
• Session management

Fitur:

• Auto-login dengan credentials
• Parameter caching untuk efficiency
• Retry logic untuk failed requests
• Status tracking & aggregation

📝 src/schemaExtractor.ts - Schema Analysis

Fungsi: Extract validation schemas dari codebase

• Detect Zod, Joi, Yup schemas
• Parse schema definitions
• Extract field information
• Generate schema documentation

Support Schemas:

• Zod (popular TypeScript validation)
• Joi (Node.js validation)
• Yup (JavaScript schema validation)
• Custom validation patterns

Renderer Modules (CLI Output)

🎨 src/renderer/cliRenderer.ts

Render endpoint list dalam format table dengan colors

🗺️ src/renderer/apiGraphRenderer.ts

Render API graph structure dengan relationship visualization

📊 src/renderer/schemaRenderer.ts

Render schema definitions dalam format mudah dibaca

🌳 src/renderer/backendGraphRenderer.ts

Render backend knowledge graph summary

Key Advantages & Features

1. Smart Dependency Resolution

Algorithm:
- Analyze parent collection endpoints
- Extract ID dari resource objects
- Fetch sample values secara otomatis
- Manual input sebagai fallback

2. Intelligent AI Payload Generation

Benefits:
✓ Schema-aware (understand field types)
✓ Context-enriched (backend logic aware)
✓ Realistic data (not random/dummy)
✓ Cached (efficiency)
✓ Fallback logic (no crashes)

3. Beautiful CLI Output

Libraries:
- ora: Loading spinner animation
- log-symbols: Text-based status symbols (✔ ✖ ⚠)
- boxen: Styled containers untuk messages
- cli-table3: Professional table rendering
- chalk: Color output untuk readability

4. Session-Based Reporting

Workflow:
Local Testing → Cache Results → Publish to Supabase
→ Generate Session URL → Share Report Link

5. Type-Safe Implementation

• Full TypeScript support
• Strong typing untuk data structures
• Better IDE autocomplete
• Runtime safety checks

Data Flow

┌─────────────────────────────────────────────────────┐
│           SONIC POINT DATA FLOW                      │
├─────────────────────────────────────────────────────┤
│                                                     │
│  1. INITIALIZATION                                 │
│     sonic-point init                              │
│     ↓ (Save config)                               │
│     .sonicpoint.json                              │
│                                                     │
│  2. SCANNING                                        │
│     sonic-point scan [--schema|--context]         │
│     ↓ (Analyze codebase)                          │
│     Endpoints + Schemas + Knowledge Graph         │
│                                                     │
│  3. TESTING                                         │
│     sonic-point send [--all|specific]             │
│     ↓ (Execute tests)                             │
│     Local results cached                          │
│                                                     │
│  4. REPORTING                                       │
│     sonic-point report [method|endpoint]          │
│     ↓ (Publish results)                           │
│     Supabase Storage → Shareable Report URL       │
│                                                     │
└─────────────────────────────────────────────────────┘

Technology Stack

| Layer | Technology | Purpose | | ----------------- | ----------------------------- | -------------------------- | | Language | TypeScript | Type-safe, better DX | | CLI | Commander.js | Command parsing & routing | | Code Analysis | Babel Parser/Traverse | AST analysis, code parsing | | AI | Google Gemini API | Payload generation | | HTTP | Fetch API | HTTP requests | | CLI Output | ora, chalk, boxen, cli-table3 | Beautiful terminal UI | | Storage | Supabase PostgreSQL | Persistent report storage | | Config | dotenv, JSON | Configuration management |

Setup & Installation

Prerequisites

• Node.js 18+
• npm atau pnpm
• Backend project accessible
• Gemini API key (optional, untuk AI generation)

Install

npm install -g sonic-point
# atau
pnpm install -g sonic-point

Quick Start

# 1. Initialize
sonic-point init

# 2. Scan endpoints
sonic-point scan

# 3. Send requests
sonic-point send --all

# 4. Publish report
sonic-point report

Configuration

.sonicpoint.json

{
  "baseUrl": "http://localhost:3000",
  "loginEndpoint": "/api/auth/login",
  "email": "[email protected]",
  "password": "password123",
  "tokenField": "data.token",
  "token": "jwt-token-here"
}

.env (Optional)

GEMINI_API_KEY=your-api-key-here

Performance Considerations

Optimization Strategies

1. Caching

   • Parameter values cached during session
   • AI payloads cached untuk reuse
   • Avoid redundant API calls

2. Parallel Processing

   • Multiple endpoint scanning
   • Concurrent schema extraction
   • Batch result collection

3. Smart Defaults

   • Auto-detect common patterns
   • Intelligent parameter resolution
   • Graceful fallbacks

4. Async/Await

   • Non-blocking HTTP requests
   • Parallel test execution
   • Efficient resource usage

Dokumentasi Lainnya

• Session Report Contract
• Supabase Schema
• Session Schema SQL
• Provider Setup
• CLI Output Improvements
• Before/After Comparison