npm package: @scottybee84/mock-netsuite
Description: Mock NetSuite API and SuiteScript host for testing SuiteQL queries and SuiteScripts without a NetSuite account
Author: Scott Brown
Latest version: 0.5.25

# @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](https://volta.sh) 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
```

### SuiteScript Hosting

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

### API Only

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

### 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`):

```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(`<h1>Customer: ${name}</h1>`);
}
```

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](SUITESCRIPT-GUIDE.md).

### 🤖 AI Integration Example

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](https://makersuite.google.com/app/apikey)
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](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

### Query Endpoint

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

### Record Lookups

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

### Testing

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