@amerilux/netsuite-api 0.2.1 → 0.5.0

package/README.md

@@ -2,11 +2,11 @@
 
 The API layer for a NetSuite single-page app. The app's server side is SuiteScript; its browser side is a bundle served by a Suitelet. This package holds what sits between them, so a project writes controllers and services and nothing else:
 
-- **`@amerilux/netsuite-api/server`**: declare a controller's endpoints and the script that serves them, expose them as a Restlet or a Suitelet, reject a call with an `ApiError`, call another Suitelet controller from server code, and find a File Cabinet file by name.
+- **`@amerilux/netsuite-api/server`**: declare a controller's endpoints and the script that serves them, expose them as a Restlet or a Suitelet, reject a call with an `ApiError`, call another Suitelet controller from server code, write a Map/Reduce job as stages and start one, and find a File Cabinet file by name.
 - **`@amerilux/netsuite-api/client`**: a typed browser client per controller, built from the endpoint types.
 - **`@amerilux/netsuite-api/testing`**: stubs for the `N/*` modules and the vitest wiring that routes imports to them.
-- **`netsuite-api generate`**: reads the controllers and writes the client's whole view of the backend, one module per controller and an index re-exporting them, plus the server-side map of scripts. The client never imports from the server tree.
-- **`@amerilux/netsuite-api`** (the root): the wire itself. The envelope, the endpoint types, `ScriptDeclaration`, `ScriptRef`.
+- **`netsuite-api generate`**: reads the controllers and the jobs and writes the client's whole view of the backend, one module each and an index re-exporting them, plus the server-side map of scripts and jobs. The client never imports from the server tree.
+- **`@amerilux/netsuite-api`** (the root): the wire itself. The envelope, the endpoint types, `ScriptDeclaration`, `ScriptRef`, `JobRef`, `JobRun`.
 
 The layout it assumes is the one `create-netsuite-project` scaffolds: `api/` (SuiteScript) and `client/` (React) as workspaces.
 
@@ -45,7 +45,7 @@ export const post = defineRestlet({
 }, customerEndpoints);
 ```
 
-Every call is a POST whose JSON body carries the request plus an `endpoint` property naming the endpoint. The handler answers with data, or throws an `ApiError` for a status the caller should see; anything else is a 500 with the details logged. A Suitelet controller is the same file with `defineSuitelet` and `onRequest` instead, and `browser: false` in the declaration when only server code calls it.
+Every call is a POST whose JSON body carries the request plus an `endpoint` property naming the endpoint. The handler answers with data, or throws an `ApiError` for a status the caller should see, with a `details` object the caller can act on (a per-field validation map, the offending id) that travels in the envelope; anything else is a 500 whose cause is logged and never sent. A Suitelet controller is the same file with `defineSuitelet` and `onRequest` instead, and `browser: false` in the declaration when only server code calls it.
 
 The declaration is the controller's own statement of the script it is deployed as. It creates nothing: the controller builds, tests and bundles before any script record exists. The ids are how a client reaches the controller once it is deployed, so set them to whatever the record and deployment are called in NetSuite and in the SDF object; the generator wires every client to them.
 
@@ -53,7 +53,7 @@ The generator reads the file as source, so a few things are rules rather than co
 
 - Handlers are written inline with their parameter and return types annotated. A reference to a service function carries no types the generator can read.
 - Every type in the file is a wire shape and is exported.
-- A type is imported only from the inlined files (the generated entity types, by default), the carried modules (the package's server entry, for `RawResponse`) or another controller. A service's return type is never used as a DTO by reference.
+- A type is imported only from the inlined files (by default the generated entity types and the services: what a service returns is the domain type a wire shape is built from), the carried modules (the package's server entry, for `RawResponse`) or another controller. A service's function is never referenced by the handler in place of an annotation.
 - The script declaration is an object literal with literal ids, its `name` is the file name without `Controller`, and the entry point export and the `@NScriptType` header agree with the define function.
 - Script ids are unique across controllers, and no wire shape is named `Endpoints`. A shape's name carries no controller prefix: each controller's generated module is its own namespace.
 
@@ -67,7 +67,7 @@ The generator reads the file as source, so a few things are rules rather than co
 // client/src/api/customer.gen.ts
 import { createApiClient } from '@amerilux/netsuite-api/client';
 
-// Entity types from api/src/types/models.gen.ts, copied so this module stands on its own.
+// Types from api/src/types/models.gen.ts, copied so this module stands on its own.
 
 export interface Customer {
     id: number;
@@ -91,7 +91,9 @@ export type Endpoints = {
 export const api = createApiClient<Endpoints>({ kind: 'restlet', scriptId: 'customscript_app_customer', deployId: 'customdeploy_app_customer' });
 ```
 
-A type imported from another controller becomes an import of that controller's module. A type built on something the entity file imports itself (`CustomerCreate`, `CustomerPatch`: the repository package's input types) is an error, because the client could not carry it; write the wire shape out in the controller instead. A generated module no controller owns any more is deleted on the next run.
+A type imported from a service is copied the same way, with the entity types it is built on following it in from the models file. A type imported from another controller becomes an import of that controller's module. A type built on something no inlined file declares (`CustomerCreate`, `CustomerPatch`: the repository package's input types; a type a service imports from a package) is an error, because the client could not carry it; write the wire shape out in the controller instead. So is a type reached through a renamed import (`import type { Employee as EmployeeRecord }`) in a service: import it under its own name. A generated module no controller owns any more is deleted on the next run.
+
+JSON carries no dates. A `Date` in a response shape (an entity's `tranDate`) arrives in the browser as an ISO 8601 string, so the generated module writes `string` wherever the shape says `Date`; the page formats it. A `Date` in a request shape is an error, because the handler would receive a string where its annotation promises a Date: take a string and parse it in the handler.
 
 **`client/src/api/index.gen.ts`**, the client's view of the backend: every controller's module re-exported under the controller's name.
 
@@ -113,16 +115,17 @@ A hook imports `{ customer }` from it, calls `customer.api.search({ search: 'acm
 ```json
 {
   "controllers": "api/src/controllers",
+  "jobs": "api/src/jobs",
   "outDir": "client/src/api",
   "scriptsOutFile": "api/src/scripts.gen.ts",
   "clientModule": "@amerilux/netsuite-api/client",
   "wireModule": "@amerilux/netsuite-api",
   "typeImports": { "@amerilux/netsuite-api/server": "@amerilux/netsuite-api/client" },
-  "inlineTypes": { "../types/models.gen": "api/src/types/models.gen.ts" }
+  "inlineTypes": { "../types/models.gen": "api/src/types/models.gen.ts", "../services/*": "api/src/services/*.ts" }
 }
 ```
 
-Paths are relative to the config file. `outDir` holds the controller modules and the index, and nothing else. `inlineTypes` maps a specifier as written in a controller to the type-only file whose declarations are copied into the module of every controller importing from it. `typeImports` maps a specifier to the one the client resolves, for a type that stays an import (the package's server entry maps to its client entry so `RawResponse` carries over). A type imported from any other module is an error.
+Paths are relative to the config file. `outDir` holds the controller and job modules and their indexes, and nothing else. A project with jobs adds a `jobRuns` block naming the run record it deployed; see **Jobs**. `inlineTypes` maps a specifier as written in a controller to the file whose type declarations are copied into the module of every controller importing from it; a key with one `*` stands for a file name and the `*` in its file takes that name, so `../services/*` covers every service. Only the type declarations of a file are read, so a service's functions are skipped; a type in one inlined file that refers to a type imported from another (a service's summary type built on an entity type) brings that type along, the import resolved through the same map as written from the same folder depth. `typeImports` maps a specifier to the one the client resolves, for a type that stays an import (the package's server entry maps to its client entry so `RawResponse` carries over). A type imported from any other module is an error.
 
 ## The client at runtime
 
@@ -134,7 +137,7 @@ import { configureApiClient } from '@amerilux/netsuite-api/client';
 if (import.meta.env.DEV) configureApiClient({ basePaths: { restlet: '/api/restlet', suitelet: '/api/suitelet' } });
 ```
 
-A failed call rejects with an `ApiClientError` carrying the envelope's status and message; a call that got no answer at all carries `NO_RESPONSE_STATUS` (0). Before it rejects, the failure goes to the handler `configureApiClient` was given, with the script, the endpoint and the request, so the app reports every failure in one place and a hook carries no error handling of its own:
+A failed call rejects with an `ApiClientError` carrying the envelope's status, message and `details` (whatever the handler gave its `ApiError`, for a form to show per field); a call that got no answer at all carries `NO_RESPONSE_STATUS` (0). Before it rejects, the failure goes to the handler `configureApiClient` was given, with the script, the endpoint and the request, so the app reports every failure in one place and a hook carries no error handling of its own:
 
 ```ts
 configureApiClient({ onError: (error, { endpoint }) => showBanner(`${endpoint}: ${error.message}`) });
@@ -190,9 +193,84 @@ const userRolesApi = createSuiteletClient<UserRolesEndpoints>(scripts.userRoles)
 export const listRolesForEmployee = (employeeId: number) => userRolesApi.byEmployee({ employeeId }).roles;
 ```
 
+## Jobs
+
+A job is a Map/Reduce script written as stages. What the wrapper adds is the run: a Map/Reduce answers nothing and cannot be waited on, so every run is a row in a record of the application's own, and that row is what server code and the browser talk about.
+
+```ts
+/**
+ * @NApiVersion 2.1
+ * @NScriptType MapReduceScript
+ */
+import { defineJob } from '@amerilux/netsuite-api/server';
+import { jobRuns } from '../scripts.gen';
+import { closeOrder, listStaleOrders, type StaleOrder } from '../services/staleOrderService';
+
+export interface CloseStaleRequest { olderThanDays: number }
+export interface CloseStaleResult { closed: number }
+
+export const { getInputData, map, summarize } = defineJob({
+    name: 'closeStaleOrders',
+    scriptId: 'customscript_app_close_stale_mr',
+    deployments: ['customdeploy_app_close_stale_mr', 'customdeploy_app_close_stale_mr_2'],
+    runParameter: 'custscript_app_close_stale_run',
+    parameters: { batchSize: { id: 'custscript_app_close_stale_batch', type: 'integer' } },
+    runs: jobRuns,
+}, {
+    getInputData: (input: CloseStaleRequest): StaleOrder[] => listStaleOrders(input.olderThanDays),
+    map: (order: StaleOrder, job): void => {
+        if (closeOrder(order.id)) job.write(String(order.id), order.id);
+    },
+    summarize: (summary): CloseStaleResult => ({ closed: summary.output.length }),
+});
+```
+
+The first parameter of `getInputData` is the run's input and the return type of `summarize` is its result: the generator reads the shapes from those two annotations, the way it reads an endpoint's request and response. The values carried between stages are JSON, so each stage annotates what it expects (`values: number[]` on a reduce stage, `summary: JobSummary<Total>` on summarize) and the wrapper hands them back that way. Export the stages the job has, and `summarize` always: the run is closed there. A stage exported without being declared throws when NetSuite calls it, rather than quietly passing values through.
+
+Plenty of jobs answer nothing, because the records they write are the point. Such a job declares no `summarize` and still exports it, and the wrapper closes the run for it; one that wants a last word without a result (a notification when the run ends) declares `summarize` with a `void` return. Either way the run's `Result` is `null`, and a page watches `status`, the progress fields and `errors` instead of a result.
+
+Reading a run asks the task about progress as well. `stagePercentComplete` is `getPercentageCompleted()`, which NetSuite documents as the percentage complete of the **stage being processed**, so it counts to 100 once per stage; `itemsProcessed` and `itemsTotal` come from that stage's `getTotal*Count()` and `getPending*Count()` pair and only go up. The record keeps the percent (100 once a run ends) but never the counts, so the counts are null for a run that has ended or whose task id NetSuite has purged — by then the run has the result, which the record did keep.
+
+The store belongs in a repository, because it writes a record and submits a task. Keep it job-agnostic: whatever decides a run should start (a service, in the layout the template scaffolds) passes the job and the input.
+
+```ts
+// api/src/repositories/jobRunRepository.ts
+import { createJobRunStore } from '@amerilux/netsuite-api/server';
+import type { JobRef, JobRun } from '@amerilux/netsuite-api/server';
+import { jobRuns } from '../scripts.gen';
+
+const jobRunStore = createJobRunStore(jobRuns);
+
+export const startJobRun = (job: JobRef, input: unknown): string => jobRunStore.start(job, input);
+export const findJobRun = (runId: string): JobRun | null => jobRunStore.read(runId);
+
+// api/src/services/ordersService.ts
+export const startClosingOldOrders = (olderThanDays: number) => startJobRun(jobs.closeOldOrders, { olderThanDays } satisfies CloseOldOrdersRequest);
+```
+
+`start` writes the run, then submits the task to the first deployment that takes it; NetSuite runs one instance of a deployment at a time, so the list in the declaration is how many runs can overlap. When they are all running it throws `ApiError.conflict` (409) and removes the run it had written, because nothing started. A controller endpoint hands the run id to the browser, which polls another endpoint for `read`.
+
+`read` is the reason a dead run does not look like a working one: it takes status, stage and progress from `N/task.checkStatus` as well as the record, so a task NetSuite gave up on is `failed`, and a task that finished without writing a result is `failed` too. `findExpired(days)` and `remove` are what a cleanup job runs on a schedule; run records are not meant to be permanent.
+
+`findRuns({ job, startedBy, unfinishedOnly, limit })` answers the matching runs newest first, in one query and without loading a record: it is how a page finds the run it lost track of, because the run knows who started it even after a browser has forgotten. Its rows carry what the record says, not what the task says, so read a run by id before believing one is still working — and they carry no progress at all, because only the task has any.
+
+### The run record
+
+The shape is this package's and the ids are the application's, because the record carries the application's prefix. `netsuite-api.config.json` names them and the generator writes them into the scripts map as `jobRuns`:
+
+```json
+"jobRuns": {
+  "recordType": "customrecord_app_job_run",
+  "fieldPrefix": "custrecord_app_jr",
+  "extraFields": { "customerId": { "id": "custrecord_app_jr_customer", "type": "integer" } }
+}
+```
+
+Each field's id is the prefix plus a short suffix (`_job`, `_status`, `_stage`, `_percent`, `_input`, `_result`, `_errors`, `_task`, `_deploy`, `_by`, `_start`, `_end`); `fields` overrides any one of them for a record whose field is named differently. `extraFields` are the fields the application added: `start` sets them (`{ extra: { customerId } }`) and a run reports them back under `extra`, typed.
+
 ## Tests
 
-`N/*` modules exist only inside NetSuite. The `testing` entry ships a stub per module, each export a `vi.fn()`, and the vitest wiring:
+`N/*` modules exist only inside NetSuite. The `testing` entry ships a stub per module, each export a `vi.fn()`, the Map/Reduce contexts a job's stages are called with (`mapContextFor`, `reduceContextFor`, `summarizeContextFor`, each capturing what the stage wrote), and the vitest wiring:
 
 ```ts
 import { inlinedPackagesForNetsuiteStubs, netsuiteModuleStubAliases } from '@amerilux/netsuite-api/testing';

package/dist/client/apiClient.js

@@ -80,7 +80,7 @@ export function callEndpoint(scriptRef, endpointName, request = {}, options = {}
             throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
         }
         if (envelope.error !== null || envelope.status >= 400) {
-            throw new ApiClientError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`);
+            throw new ApiClientError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`, envelope.details);
         }
         return envelope.data;
     });
@@ -99,7 +99,7 @@ export function callRawEndpoint(scriptRef, endpointName, request = {}, options =
             const text = await response.text();
             const envelope = parseEnvelope(text);
             if (envelope && (envelope.error !== null || envelope.status >= 400))
-                throw new ApiClientError(envelope.status, (_b = envelope.error) !== null && _b !== void 0 ? _b : `Request failed (${envelope.status})`);
+                throw new ApiClientError(envelope.status, (_b = envelope.error) !== null && _b !== void 0 ? _b : `Request failed (${envelope.status})`, envelope.details);
             if (!response.ok)
                 throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
             throw new ApiClientError(response.status, `${scriptRef.scriptId}.${endpointName} answered JSON where a document was expected.`, text.slice(0, 500));

package/dist/client/index.d.ts

@@ -5,4 +5,4 @@
 export { ApiClientError, NETSUITE_API_BASE_PATHS, NO_RESPONSE_STATUS, buildApiUrl, callEndpoint, callRawEndpoint, configureApiClient, createApiClient } from './apiClient.js';
 export type { ApiBasePaths, ApiCallContext, ApiCallOptions, ApiClient, ApiClientConfiguration, ApiClientOptions, ApiErrorHandler, ClientResponse } from './apiClient.js';
 export { ENDPOINT_PARAMETER } from '../index.js';
-export type { ApiEnvelope, ApiErrorBody, Endpoint, Endpoints, EndpointRequest, EndpointResponse, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef } from '../index.js';
+export type { ApiEnvelope, ApiErrorBody, Endpoint, Endpoints, EndpointRequest, EndpointResponse, JobRun, JobRunError, JobRunListEntry, JobRunQuery, JobRunStage, JobRunStatus, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef, } from '../index.js';

package/dist/index.d.ts

@@ -2,11 +2,16 @@
  * The wire: what a controller answers with, how a call names its endpoint, and how a script is
  * reached. Both sides import this module; nothing in it touches NetSuite or the browser.
  */
-/** Every controller answers with this envelope; `data` is null whenever `error` is set. */
+/**
+ * Every controller answers with this envelope; `data` is null whenever `error` is set. `details` is
+ * whatever the handler gave its ApiError (a per-field validation map, the offending id), sent so the
+ * caller can act on it; a 500 carries none, its cause stays in the log.
+ */
 export interface ApiEnvelope<TData> {
     status: number;
     error: string | null;
     data: TData | null;
+    details?: unknown;
 }
 /** The body of a failed call, as thrown by the client's ApiClientError. */
 export interface ApiErrorBody {
@@ -74,3 +79,140 @@ export interface ScriptRef {
     deployId: string;
     browser?: boolean;
 }
+/**
+ * Jobs: the Map/Reduce side of the wire. A job answers nothing, so its run is the thing both sides
+ * talk about: server code starts one and gets a run id, and the browser asks what that run is doing.
+ * A run lives in a record of the application's own (`customrecord_<prefix>_job_run`, whose ids the
+ * generator reads from netsuite-api.config.json), so a job that dies before it writes anything is
+ * still a run that failed, not a page waiting forever.
+ */
+/** How NetSuite stores a script parameter or a run field, and the type the stages and the page see. */
+export type NetsuiteValueType = 'text' | 'integer' | 'decimal' | 'checkbox' | 'date' | 'select';
+/** One script parameter of a job: its id in NetSuite and what NetSuite stores in it. */
+export interface JobParameterDeclaration {
+    id: string;
+    type: NetsuiteValueType;
+}
+/** The value of one parameter as the stages see it. A date arrives as the ISO string, never a Date: a stage is not the wire, but a run record is read by both sides. */
+export type JobParameterValue<TType extends NetsuiteValueType> = TType extends 'integer' | 'decimal' ? number : TType extends 'checkbox' ? boolean : string;
+/** Every parameter a job declares, by the name the stages use. */
+export type JobParameterValues<TParameters extends Record<string, JobParameterDeclaration>> = {
+    readonly [TName in keyof TParameters]: JobParameterValue<TParameters[TName]['type']>;
+};
+/** Where a run is: NetSuite's own stage names, as the run record and the page speak them. */
+export type JobRunStage = 'input' | 'map' | 'shuffle' | 'reduce' | 'summarize';
+/**
+ * A run's state. `pending` is submitted but not started, `running` is anything between, and
+ * `complete` means summarize wrote the result. `failed` is either a stage that threw or a task
+ * NetSuite gave up on, which is why a run is read through checkStatus as well as its record.
+ */
+export type JobRunStatus = 'pending' | 'running' | 'complete' | 'failed';
+/** One thing that went wrong in a run: a stage's own throw, or a key NetSuite could not finish. */
+export interface JobRunError {
+    stage: JobRunStage;
+    /** The key the map or reduce stage was working on, when the failure belongs to one. */
+    key?: string;
+    message: string;
+}
+/**
+ * A run as anyone asking about it sees it: the record's own fields refined by what NetSuite says
+ * about the task. Every time is an ISO string, so this shape crosses to the browser unchanged.
+ */
+export interface JobRun<TResult = unknown, TExtra extends Record<string, unknown> = Record<string, never>> {
+    /** The run record's internal id: what startJob answers and a page polls with. */
+    id: string;
+    /** The job's name, as its declaration gives it. */
+    job: string;
+    status: JobRunStatus;
+    /** The stage the task is in, or null before it starts and after it ends. */
+    stage: JobRunStage | null;
+    /**
+     * How far the stage being processed has got, 0 to 100, as NetSuite reports it. It counts up inside a
+     * stage and starts again at the next one, so it is progress rather than a fraction of the whole run;
+     * a finished run reads 100. For something to put next to a progress bar, prefer the item counts.
+     */
+    stagePercentComplete: number;
+    /** Rows the stage being processed has finished, or null when the task can no longer say. */
+    itemsProcessed: number | null;
+    /** Rows the stage being processed was given, or null when the task can no longer say: a run that has ended, or an id NetSuite has purged. */
+    itemsTotal: number | null;
+    /** The employee who started it, or null for a scheduled run. */
+    startedBy: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    /** The NetSuite task id, kept so a run can be asked about after the fact. */
+    taskId: string | null;
+    /** What summarize returned, once it has. */
+    result: TResult | null;
+    errors: JobRunError[];
+    /** The fields this application added to the run record, as netsuite-api.config.json declares them. */
+    extra: TExtra;
+}
+/**
+ * A run as a list shows it: the fields a query can read, so finding a run costs one query rather than a
+ * record load each. It carries no input, result or errors — a page finds a run here and then asks about
+ * it by id, which is also the only reading that consults the task, so a `running` row in a list is
+ * "last we knew", not a promise. Progress is not here either, for the same reason: only the task has it.
+ */
+export interface JobRunListEntry {
+    id: string;
+    job: string;
+    status: JobRunStatus;
+    stage: JobRunStage | null;
+    startedBy: number | null;
+}
+/** Which runs to list. Every field narrows; the newest are answered first. */
+export interface JobRunQuery {
+    job?: string;
+    /** The employee who started them: how a page finds its own caller's runs again. */
+    startedBy?: number;
+    /** Only runs that have not ended, for "is one of these already going?". */
+    unfinishedOnly?: boolean;
+    /** How many, newest first. Defaults to 10, capped at 100. */
+    limit?: number;
+}
+/** One deployed job as server code starts it: `scripts.<job>` in the generated scripts map. */
+export interface JobRef {
+    kind: 'mapreduce';
+    /** The job's name, as its declaration gives it and the run record records it. */
+    name: string;
+    scriptId: string;
+    /**
+     * Every deployment the job may run on, in the order they are tried. NetSuite runs one instance of
+     * a deployment at a time, so this list is how many runs of the job can overlap.
+     */
+    deployments: readonly string[];
+    /** The script parameter the run id is passed in; every stage reads the run back from it. */
+    runParameter: string;
+    /** The job's own script parameters, by the name the stages use. */
+    parameters?: Readonly<Record<string, string>>;
+}
+/** One field an application added to its run record, as netsuite-api.config.json declares it. */
+export interface JobRunExtraField {
+    id: string;
+    type: NetsuiteValueType;
+}
+/**
+ * The run record as this application deployed it, written by the generator from the `jobRuns` block
+ * of netsuite-api.config.json. The field names are the package's; their ids are the application's,
+ * because the record carries the application's prefix.
+ */
+export interface JobRunsConfig {
+    recordType: string;
+    fields: {
+        job: string;
+        status: string;
+        stage: string;
+        stagePercentComplete: string;
+        input: string;
+        result: string;
+        errors: string;
+        taskId: string;
+        deployment: string;
+        startedBy: string;
+        startedAt: string;
+        finishedAt: string;
+    };
+    /** Fields this application added, by the name the code uses for them. */
+    extraFields: Readonly<Record<string, JobRunExtraField>>;
+}

package/dist/server/apiError.d.ts

@@ -6,4 +6,6 @@ export declare class ApiError extends Error {
     static badRequest(message: string, details?: unknown): ApiError;
     static notFound(message: string, details?: unknown): ApiError;
     static forbidden(message?: string): ApiError;
+    /** The request was fine but the account cannot take it now: every deployment of a job is already running. */
+    static conflict(message: string, details?: unknown): ApiError;
 }

package/dist/server/apiError.js

@@ -15,4 +15,8 @@ export class ApiError extends Error {
     static forbidden(message = 'Not permitted') {
         return new ApiError(403, message);
     }
+    /** The request was fine but the account cannot take it now: every deployment of a job is already running. */
+    static conflict(message, details) {
+        return new ApiError(409, message, details);
+    }
 }

package/dist/server/defineJob.d.ts

@@ -0,0 +1,95 @@
+import type { EntryPoints } from 'N/types';
+import type { JobParameterDeclaration, JobParameterValues, JobRunError, JobRunsConfig } from '../index.js';
+/**
+ * A job is a Map/Reduce script written as stages instead of entry points:
+ *
+ *     export const { getInputData, map, summarize } = defineJob({
+ *         name: 'closeStaleOrders',
+ *         scriptId: 'customscript_app_close_stale_orders_mr',
+ *         deployments: ['customdeploy_app_close_stale_orders_mr', 'customdeploy_app_close_stale_orders_mr_2'],
+ *         runParameter: 'custscript_app_close_stale_run',
+ *         runs: jobRuns,
+ *     }, {
+ *         getInputData: (input: CloseStaleRequest): StaleOrder[] => listStaleOrders(input.olderThanDays),
+ *         map: (order: StaleOrder, job) => { job.write(String(order.id), closeOrder(order.id)); },
+ *         summarize: (summary): CloseStaleResult => ({ closed: summary.output.length }),
+ *     });
+ *
+ * What the wrapper adds is the run: the values between stages are typed and parsed, getInputData's
+ * input comes from the run record rather than a parameter the stage has to decode, summarize's
+ * return value becomes the run's result, and the errors NetSuite collected are written onto the run
+ * with it. A stage that throws marks the run failed and rethrows, so the failure is in the execution
+ * log where NetSuite puts it and on the run where the page is looking.
+ *
+ * Export the stages the job has. Every job exports summarize even when it has no summarize stage of
+ * its own, because that is where the run is closed. A stage exported but not declared throws when
+ * NetSuite calls it, rather than quietly passing values through.
+ */
+/** A job's script: what the generator reads, and what the run record's rows point back at. */
+export interface JobDeclaration<TParameters extends Record<string, JobParameterDeclaration> = Record<string, never>> {
+    /** The job's name, as the run record records it and the scripts map keys it: the file name. */
+    name: string;
+    /** The script record's id, `customscript_<prefix>_<name>_mr`. */
+    scriptId: string;
+    /**
+     * Every deployment of the script, in the order startJob tries them. NetSuite runs one instance of
+     * a deployment at a time, so the length of this list is how many runs can overlap; a job started
+     * from a page answers 409 when they are all busy.
+     */
+    deployments: string[];
+    /** The script parameter carrying the run id, `custscript_<prefix>_<name>_run`. */
+    runParameter: string;
+    /** The job's own script parameters, by the name the stages use. */
+    parameters?: TParameters;
+    /** The application's run record, from the generated scripts map: `runs: jobRuns`. */
+    runs: JobRunsConfig;
+}
+/** What every stage is given besides its own values. */
+export interface JobContext<TParameters extends Record<string, JobParameterDeclaration>> {
+    /** The run this stage belongs to, as the page polls it. */
+    readonly runId: string;
+    /** The script parameters the declaration names, typed. */
+    readonly parameters: JobParameterValues<TParameters>;
+}
+/** A stage that writes values for the stage after it. */
+export interface JobWriteContext<TParameters extends Record<string, JobParameterDeclaration>, TValue> extends JobContext<TParameters> {
+    /** Hands one value to the next stage under a key; the value is carried as JSON and comes back typed. */
+    write(key: string, value: TValue): void;
+}
+/** What the run produced, as summarize sees it. */
+export interface JobSummary<TOutput> {
+    /** Every key and value the reduce stage wrote, or the map stage's when the job has no reduce. */
+    output: {
+        key: string;
+        value: TOutput;
+    }[];
+    /** Everything that failed anywhere in the run; these are written onto the run whatever summarize returns. */
+    errors: JobRunError[];
+    seconds: number;
+    usage: number;
+    concurrency: number;
+    yields: number;
+}
+/**
+ * The stages of a job. getInputData's first parameter is the run's input and summarize's return type
+ * is the run's result: the generator reads both from those annotations, the way it reads an endpoint's
+ * request and response. The items getInputData returns are typed from there on.
+ *
+ * The values between map, reduce and summarize are carried as JSON, so each stage says what it
+ * expects: a reduce stage writes `values: number[]` and a summarize stage `summary: JobSummary<Total>`,
+ * and the wrapper hands them back as annotated. The stages are written as methods for that reason.
+ */
+export interface JobStages<TInput, TItem, TValue = unknown, TOutput = unknown, TResult = null, TParameters extends Record<string, JobParameterDeclaration> = Record<string, never>> {
+    getInputData(input: TInput, job: JobContext<TParameters>): TItem[] | Record<string, TItem>;
+    map?(item: TItem, job: JobWriteContext<TParameters, TValue>): void;
+    reduce?(key: string, values: TValue[], job: JobWriteContext<TParameters, TOutput>): void;
+    summarize?(summary: JobSummary<TOutput>, job: JobContext<TParameters>): TResult;
+}
+/** The four NetSuite entry points, of which a job file exports the ones it has. */
+export interface JobEntryPoints {
+    getInputData: (context: EntryPoints.MapReduce.getInputDataContext) => unknown;
+    map: (context: EntryPoints.MapReduce.mapContext) => void;
+    reduce: (context: EntryPoints.MapReduce.reduceContext) => void;
+    summarize: (context: EntryPoints.MapReduce.summarizeContext) => void;
+}
+export declare function defineJob<TInput, TItem, TValue = unknown, TOutput = unknown, TResult = null, TParameters extends Record<string, JobParameterDeclaration> = Record<string, never>>(declaration: JobDeclaration<TParameters>, stages: JobStages<TInput, TItem, TValue, TOutput, TResult, TParameters>): JobEntryPoints;

package/dist/server/defineJob.js

@@ -0,0 +1,150 @@
+import * as log from 'N/log';
+import * as runtime from 'N/runtime';
+import { createJobRunStore } from './jobRuns.js';
+function readParameterValue(id, type) {
+    const raw = runtime.getCurrentScript().getParameter({ name: id });
+    if (raw === null || raw === undefined || raw === '')
+        return type === 'checkbox' ? false : type === 'integer' || type === 'decimal' ? 0 : '';
+    if (type === 'integer' || type === 'decimal')
+        return Number(raw);
+    if (type === 'checkbox')
+        return raw === true || raw === 'T' || raw === 'true';
+    if (raw instanceof Date)
+        return raw.toISOString();
+    return String(raw);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The errors NetSuite collected, in the order the run met them. */
+function readCollectedErrors(summary) {
+    var _a;
+    const errors = [];
+    if ((_a = summary.inputSummary) === null || _a === void 0 ? void 0 : _a.error)
+        errors.push({ stage: 'input', message: summary.inputSummary.error });
+    const collect = (stage, container) => {
+        container === null || container === void 0 ? void 0 : container.errors.iterator().each((key, error) => {
+            errors.push({ stage, key, message: error });
+            return true;
+        });
+    };
+    collect('map', summary.mapSummary);
+    collect('reduce', summary.reduceSummary);
+    return errors;
+}
+export function defineJob(declaration, stages) {
+    const store = createJobRunStore(declaration.runs);
+    const { name } = declaration;
+    const readParameters = () => {
+        var _a;
+        const values = {};
+        for (const [parameterName, parameter] of Object.entries((_a = declaration.parameters) !== null && _a !== void 0 ? _a : {}))
+            values[parameterName] = readParameterValue(parameter.id, parameter.type);
+        return values;
+    };
+    const readRunIdParameter = () => {
+        const raw = runtime.getCurrentScript().getParameter({ name: declaration.runParameter });
+        return typeof raw === 'string' && raw !== '' ? raw : undefined;
+    };
+    /**
+     * The run a stage belongs to. getInputData has it from the parameter or opens one; the stages
+     * after it read the parameter again, and a scheduled run (which has no parameter to read) is
+     * found by the deployment it is running on, one run at a time being all a deployment can do.
+     */
+    const buildContext = (runIdSource) => {
+        let resolvedRunId;
+        let resolvedParameters;
+        return {
+            get runId() {
+                resolvedRunId = resolvedRunId !== null && resolvedRunId !== void 0 ? resolvedRunId : runIdSource();
+                return resolvedRunId;
+            },
+            get parameters() {
+                resolvedParameters = resolvedParameters !== null && resolvedParameters !== void 0 ? resolvedParameters : readParameters();
+                return resolvedParameters;
+            },
+        };
+    };
+    const lateRunId = () => {
+        var _a, _b;
+        const deployment = String(runtime.getCurrentScript().deploymentId);
+        return (_b = (_a = readRunIdParameter()) !== null && _a !== void 0 ? _a : store.findRunningRunId(name, deployment)) !== null && _b !== void 0 ? _b : '';
+    };
+    /** A stage's own failure: logged, written onto the run when the run is the only place it would show, and rethrown for NetSuite. */
+    const runStage = (stage, context, markRun, work) => {
+        try {
+            return work();
+        }
+        catch (error) {
+            const message = describeError(error);
+            log.error('job stage failed', { job: name, stage, runId: context.runId, message });
+            if (markRun && context.runId !== '')
+                store.fail(context.runId, { stage, message });
+            throw error;
+        }
+    };
+    return {
+        getInputData(scriptContext) {
+            const deployment = String(runtime.getCurrentScript().deploymentId);
+            const runId = store.claimRun({ job: name, runId: readRunIdParameter(), deployment });
+            const context = buildContext(() => runId);
+            log.audit('job started', { job: name, runId, deployment, restarted: scriptContext.isRestarted });
+            return runStage('input', context, true, () => stages.getInputData(store.readInput(runId), context));
+        },
+        map(scriptContext) {
+            const context = buildContext(lateRunId);
+            runStage('map', context, false, () => {
+                if (!stages.map)
+                    throw new Error(`${name} declares no map stage; remove map from this file's exports.`);
+                stages.map(JSON.parse(scriptContext.value), {
+                    get runId() {
+                        return context.runId;
+                    },
+                    get parameters() {
+                        return context.parameters;
+                    },
+                    write: (key, value) => scriptContext.write({ key, value: JSON.stringify(value) }),
+                });
+            });
+        },
+        reduce(scriptContext) {
+            const context = buildContext(lateRunId);
+            runStage('reduce', context, false, () => {
+                if (!stages.reduce)
+                    throw new Error(`${name} declares no reduce stage; remove reduce from this file's exports.`);
+                stages.reduce(scriptContext.key, scriptContext.values.map((value) => JSON.parse(value)), {
+                    get runId() {
+                        return context.runId;
+                    },
+                    get parameters() {
+                        return context.parameters;
+                    },
+                    write: (key, value) => scriptContext.write({ key, value: JSON.stringify(value) }),
+                });
+            });
+        },
+        summarize(scriptContext) {
+            var _a;
+            const context = buildContext(lateRunId);
+            const errors = readCollectedErrors(scriptContext);
+            const output = [];
+            scriptContext.output.iterator().each((key, value) => {
+                output.push({ key, value: JSON.parse(value) });
+                return true;
+            });
+            const summary = {
+                output,
+                errors,
+                seconds: scriptContext.seconds,
+                usage: scriptContext.usage,
+                concurrency: scriptContext.concurrency,
+                yields: scriptContext.yields,
+            };
+            const result = runStage('summarize', context, true, () => (stages.summarize ? stages.summarize(summary, context) : null));
+            const status = ((_a = scriptContext.inputSummary) === null || _a === void 0 ? void 0 : _a.error) ? 'failed' : 'complete';
+            if (context.runId !== '')
+                store.finish(context.runId, { status, result, errors });
+            log.audit('job finished', { job: name, runId: context.runId, status, errors: errors.length, seconds: scriptContext.seconds, usage: scriptContext.usage });
+        },
+    };
+}

package/dist/server/endpoint.js

@@ -83,7 +83,7 @@ export function invokeEndpoint(controllerName, endpoints, rawRequest, options =
         if (error instanceof ApiError) {
             status = error.status;
             log.debug('endpoint rejected', { controller: controllerName, endpoint: endpointName, status, message: error.message, details: error.details });
-            return { envelope: { status, error: error.message, data: null } };
+            return { envelope: error.details === undefined ? { status, error: error.message, data: null } : { status, error: error.message, data: null, details: error.details } };
         }
         status = 500;
         log.error('endpoint failed', { controller: controllerName, endpoint: endpointName, ...describeError(error) });