@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.

``bash


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)

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

$3

`bash


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

`

$3

`bash
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:

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

📝 Manual Commands:

`bash
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:

$3

- 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)

$3

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

$3

Create a Suitelet (my_suitelet.js):

`javascript
/**
* @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(

Customer: ${name}

);
}
`

Run it:

`bash
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.

$3

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

`javascript
// 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:

`bash
./dev.sh publish # Automated: test → build → version → publish → git push


OR manually:


npm run build && npm version patch && npm publish
`

API Usage

$3

`bash
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;"
}
`

$3

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

$3

`bash


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

`bash
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:

`bash
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).
``