@scottybee84/mock-netsuite

Mock NetSuite API and SuiteScript host for learning and testing without a NetSuite account.

🔥 NEW in v0.2.0: Full SuiteScript hosting support! Run Suitelets, Restlets, User Events, and Map/Reduce scripts against a mock database.

Built with TypeScript and compiled to JavaScript for production use. Features auto-seeding and a CLI for easy setup.

Features

• 🌐 Mock NetSuite API - SuiteQL queries, record lookups
• 📄 SuiteScript Host - Run Suitelets as web pages, Restlets as APIs
• 🔧 Mock N/* Modules - N/record, N/search, N/log, N/runtime, N/email, N/https
• 🤖 AI Integration Ready - Example with Gemini AI for customer analysis
• 🎓 Training Ready - Perfect for NetSuite training courses
• 🚀 Zero Setup - Auto-seeds database, handles all dependencies

Prerequisites

⚠️ Important: Node.js Version

This package requires Node.js 18-22 (tested on 18/20/22). It will NOT work with Node.js 23+ due to better-sqlite3 ABI compatibility.

# Check your version
node --version

# If you need to switch (using nvm):
nvm install 20
nvm use 20

# Or install Volta for automatic switching:
# https://volta.sh
curl https://get.volta.sh | bash
volta pin node@20

💡 For consuming projects: Install Volta to automatically use the correct Node version when working with this package.

Quick Start (Global Install)

npm install -g @scottybee84/mock-netsuite
mock-netsuite

SuiteScript Hosting

# Run a Suitelet as a web page
mock-netsuite --suitelet path/to/my_suitelet.js
# Access at: http://localhost:3000/app/site/hosting/script/my_suitelet

# Run a Restlet as a REST API
mock-netsuite --restlet path/to/my_restlet.js
# Access at: http://localhost:3000/app/site/hosting/restlet/my_restlet

API Only

mock-netsuite
# Basic API endpoints at http://localhost:3000

The CLI will automatically:

• ✅ Check Node.js version compatibility
• 🚀 Start the Mock NetSuite API
• 📊 Seed database with 500 customers + 2000 invoices (first run only)
• 🌐 Launch server on port 3000 (or PORT env var)

Development Workflow

🚀 Quick Setup:

./dev.sh setup          # One-time setup
./dev.sh watch          # Auto-rebuild + restart on file changes

📝 Manual Commands:

npm install
npm run build           # Compile TypeScript → dist/
npm run dev:watch       # Watch TypeScript files for changes
npm run dev:cli         # Build and test CLI
npm run reset           # Reset database with fresh data
npm run dev             # Build and start server once

🎯 VS Code Integration:

• Ctrl+Shift+P → "Tasks: Run Task" → "Watch TypeScript"
• Ctrl+Shift+P → "Tasks: Run Task" → "Start CLI"

📄 SuiteScript Hosting

Write real NetSuite SuiteScript code and test it locally! The mock environment includes:

Mock N/* Modules

• N/record - load(), create(), save(), submitFields()
• N/search - create(), run(), filters, columns
• N/log - debug(), audit(), error(), emergency()
• N/runtime - getCurrentUser(), getCurrentScript()
• N/email - send(), sendBulk() (mocked to console)
• N/https - get(), post(), put(), delete() (mocked responses)

Supported Script Types

• ✅ Suitelets - Mounted as web endpoints
• ✅ Restlets - Mounted as REST API endpoints
• 🔧 User Events - Execute with mock context
• 🔧 Map/Reduce - Execute phases against mock data

Example Usage

Create a Suitelet (my_suitelet.js):

/**
 * @NApiVersion 2.1
 * @NScriptType Suitelet
 */
import * as record from "N/record";
import * as log from "N/log";

export function onRequest(ctx) {
  const customer = record.load({ type: "customer", id: 1 });
  const name = customer.getValue({ fieldId: "companyname" });

  log.audit("Customer Loaded", name);
  ctx.response.write(`<h1>Customer: ${name}</h1>`);
}

Run it:

mock-netsuite --suitelet my_suitelet.js
# Visit: http://localhost:3000/app/site/hosting/script/my_suitelet

For complete examples and advanced usage, see SUITESCRIPT-GUIDE.md.

🤖 AI Integration Example

The package includes an example showing how to integrate Google's Gemini AI for customer analysis:

// examples/sl_customer_lookup.js with AI analysis
import * as https from "N/https";
import { GEMINI_API_KEY } from "./config.js";

function analyzeCustomerWithAI(customerData) {
  const response = https.post({
    url: `https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-latest:generateContent?key=${GEMINI_API_KEY}`,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      /* Gemini payload */
    }),
  });
  return JSON.parse(response.body);
}

To try the AI example:

1. Get a Gemini API key
2. Edit examples/config.js with your API key
3. Run: node suitescript-runtime.js
4. Visit: http://localhost:3001/suitelet/sl_customer_lookup?id=1

See examples/AI_CUSTOMER_ANALYSIS.md for complete setup and technical details.

📦 Publishing:

./dev.sh publish        # Automated: test → build → version → publish → git push
# OR manually:
npm run build && npm version patch && npm publish

API Usage

Query Endpoint

POST http://localhost:3000/query/v1/suiteql
Content-Type: application/json

{
  "query": "SELECT tranid,total,duedate,status FROM invoice WHERE status='Overdue' AND total > 10000 ORDER BY duedate ASC LIMIT 5;"
}

Record Lookups

• Customer: GET /record/v1/customer/{id}
• Invoice: GET /record/v1/invoice/{id}

Testing

# Health check
curl -s http://localhost:3000/health

# SuiteQL query example
curl -s -X POST http://localhost:3000/query/v1/suiteql \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT c.companyname, i.tranid, i.total FROM customer c JOIN invoice i ON c.id = i.customerid LIMIT 3;"}' | jq

Project Structure

• src/ - TypeScript source files
  • cli.ts - Command-line interface with auto-seeding
  • server.ts - Express API server
  • seed.ts - Database seeding script
• dist/ - Compiled JavaScript files (auto-generated)
• schema.sql - SQLite database schema with NetSuite-style field names
• tsconfig.json - TypeScript configuration

NetSuite-Style Fields

The database uses NetSuite internal ID conventions:

• entityid (not entity_id)
• companyname (not company_name)
• tranid (not tran_id)
• customerid (not customer_id)
• duedate (not due_date)
• datecreated (not created_at)

License

MIT - See LICENSE file for details. AI → SuiteQL without a NetSuite account.

Built with TypeScript and compiled to JavaScript for production use.

Development

npm install
npm run build      # Compile TypeScript to dist/
npm run reset      # Reset database with fresh data
npm run dev        # Start server
npm run dev:watch  # Watch TypeScript files for changes

Query

POST http://localhost:3000/query/v1/suiteql

{ "query": "SELECT tranid,total,duedate,status FROM invoice WHERE status='Overdue' AND total > 10000 ORDER BY duedate ASC LIMIT 20;" }

STEP 2 — Install, run, verify

In VS Code terminal:

npm i
npm run seed
npm run dev


Test (Terminal or Postman):

curl -s -X POST http://localhost:3000/query/v1/suiteql \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT tranid,total,duedate,status FROM invoice WHERE status=''Overdue'' AND total > 10000 ORDER BY duedate ASC LIMIT 5;"}' | jq

## Version Compatibility

**Node.js Support:** This package supports Node.js 18-22 (tested on 18/20/22) with fail-fast version checking.

**ABI Compatibility:** Uses `better-sqlite3` which requires native compilation. Version constraints ensure compatibility across the tested Node.js matrix.

**Auto-Version Management:**
- **Volta users:** Run `volta pin node@20` in your consuming project for automatic version switching
- **nvm users:** Use the included `.nvmrc` file with `nvm use`
- **CI/CD:** The `engines` field in package.json enforces version constraints

**Installation Flow:**
1. `preinstall` hook runs `scripts/check-node.js` for immediate version verification
2. `postinstall` hook rebuilds native modules for your specific Node version
3. Helpful error messages guide users to version management solutions


You should see an items array of invoices.

Back in GitHub Desktop: commit → “init mock-netsuite” → Publish repository (public).