@amerilux/netsuite-api 0.2.1 → 0.5.0

package/dist/server/index.d.ts

@@ -1,12 +1,17 @@
 /**
  * The server side of the API: declare a controller's endpoints, expose them as a Restlet or a
  * Suitelet, reject a call with an ApiError, authorize calls, answer with a document instead of JSON,
- * call another Suitelet controller from server code, and find a File Cabinet file by name. Runs
- * inside NetSuite only; the modules here import N/*.
+ * call another Suitelet controller from server code, write a Map/Reduce job and the record its runs
+ * live in, and find a File Cabinet file by name. Runs inside NetSuite only; the modules here import
+ * N/*.
  */
 export { ApiError } from './apiError.js';
 export { defineEndpoints, invokeEndpoint, parseEndpointRequest, readEndpointCall } from './endpoint.js';
 export type { AuthorizeEndpoint, ControllerOptions, EndpointCall, EndpointCallContext, EndpointOutcome, InvokeEndpointOptions } from './endpoint.js';
+export { defineJob } from './defineJob.js';
+export type { JobContext, JobDeclaration, JobEntryPoints, JobStages, JobSummary, JobWriteContext } from './defineJob.js';
+export { createJobRunStore } from './jobRuns.js';
+export type { ClaimRunDetails, FinishRunOutcome, JobRunStore, StartJobOptions } from './jobRuns.js';
 export { defineRestlet } from './defineRestlet.js';
 export type { RestletEntryPoint } from './defineRestlet.js';
 export { defineSuitelet } from './defineSuitelet.js';
@@ -18,4 +23,4 @@ export type { SuiteletClient } from './suiteletClient.js';
 export { findFileId, findFolderId, getFileUrlByName } from './fileCabinet.js';
 export type { FileCabinetLocation } from './fileCabinet.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, JobParameterDeclaration, JobParameterValue, JobParameterValues, JobRef, JobRun, JobRunError, JobRunListEntry, JobRunQuery, JobRunExtraField, JobRunsConfig, JobRunStage, JobRunStatus, NetsuiteValueType, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef, } from '../index.js';

package/dist/server/index.js

@@ -1,11 +1,14 @@
 /**
  * The server side of the API: declare a controller's endpoints, expose them as a Restlet or a
  * Suitelet, reject a call with an ApiError, authorize calls, answer with a document instead of JSON,
- * call another Suitelet controller from server code, and find a File Cabinet file by name. Runs
- * inside NetSuite only; the modules here import N/*.
+ * call another Suitelet controller from server code, write a Map/Reduce job and the record its runs
+ * live in, and find a File Cabinet file by name. Runs inside NetSuite only; the modules here import
+ * N/*.
  */
 export { ApiError } from './apiError.js';
 export { defineEndpoints, invokeEndpoint, parseEndpointRequest, readEndpointCall } from './endpoint.js';
+export { defineJob } from './defineJob.js';
+export { createJobRunStore } from './jobRuns.js';
 export { defineRestlet } from './defineRestlet.js';
 export { defineSuitelet } from './defineSuitelet.js';
 export { isRawResponse, rawResponse, writeRawResponse } from './rawResponse.js';

package/dist/server/jobRuns.d.ts

@@ -0,0 +1,65 @@
+import type { JobRef, JobRun, JobRunError, JobRunListEntry, JobRunQuery, JobRunStatus, JobRunsConfig } from '../index.js';
+/**
+ * The run record: everything a job run is, outside the job. A Map/Reduce script answers nothing and
+ * cannot be waited on, so starting one writes a record first and passes its id in as the script
+ * parameter; the stages read their input back from it and summarize writes the result to it. Reading
+ * a run asks NetSuite about the task as well, which is what tells a run that died apart from one
+ * still working: a record left at `running` under a task NetSuite has finished or given up on is a
+ * failure, not something to keep polling.
+ *
+ * The record is the application's own (`customrecord_<prefix>_job_run`), so the ids come in as the
+ * generated `jobRuns` config rather than being written here. A repository builds the store once and
+ * the jobs build their own from the same config; nothing is global.
+ */
+/** What startJob may add to the run beyond the input: the application's own fields on the run record. */
+export interface StartJobOptions {
+    /** Values for the fields declared in `jobRuns.extraFields`, by name. */
+    extra?: Record<string, unknown>;
+}
+/** What a stage's wrapper needs to find or open a run; not used by application code. */
+export interface ClaimRunDetails {
+    job: string;
+    /** The run id the script parameter carried, or undefined for a scheduled run, which opens its own. */
+    runId?: string;
+    deployment: string;
+}
+/** How a run ended, as summarize leaves it. */
+export interface FinishRunOutcome {
+    status: Extract<JobRunStatus, 'complete' | 'failed'>;
+    result: unknown;
+    errors: JobRunError[];
+}
+export interface JobRunStore {
+    /**
+     * Starts a job: writes the run, then submits the task to the first deployment that takes it. The
+     * run id is what a page polls with. Throws a 409 when every deployment is already running, and
+     * leaves no run behind when it does, because nothing started.
+     */
+    start(job: JobRef, input?: unknown, options?: StartJobOptions): string;
+    /** The run as anyone asking sees it: the record refined by what NetSuite says about the task. Null when the record is gone (cleaned up, or never existed). */
+    read<TResult = unknown, TExtra extends Record<string, unknown> = Record<string, never>>(runId: string): JobRun<TResult, TExtra> | null;
+    /**
+     * The runs matching the query, newest first: one query, no record loads, so a page can find the run it
+     * lost track of. The rows carry what the record says and not what the task says, so read a run by id
+     * before believing it is still working.
+     */
+    findRuns(runQuery?: JobRunQuery): JobRunListEntry[];
+    /** Run ids older than the given number of days, for the cleanup job. */
+    findExpired(olderThanDays: number): string[];
+    remove(runId: string): void;
+    /** Opens the run a stage belongs to, creating one for a scheduled run. Called by the job wrapper. */
+    claimRun(details: ClaimRunDetails): string;
+    /** The input the run was started with; `{}` for a scheduled run. Called by the job wrapper. */
+    readInput<TInput>(runId: string): TInput;
+    /** The run id of whatever is running on this deployment, for the stages after getInputData. Called by the job wrapper. */
+    findRunningRunId(job: string, deployment: string): string | undefined;
+    /** Writes the result and the errors, and closes the run. Called by the job wrapper. */
+    finish(runId: string, outcome: FinishRunOutcome): void;
+    /** Marks the run failed with one error, for a stage that threw. Called by the job wrapper. */
+    fail(runId: string, error: JobRunError): void;
+}
+/**
+ * The store for one application's run record. Build it once where it is used: a repository for the
+ * application's own calls, and the job wrapper for the stages.
+ */
+export declare function createJobRunStore(config: JobRunsConfig): JobRunStore;

package/dist/server/jobRuns.js

@@ -0,0 +1,292 @@
+import * as log from 'N/log';
+import * as query from 'N/query';
+import * as record from 'N/record';
+import * as runtime from 'N/runtime';
+import * as task from 'N/task';
+import { ApiError } from './apiError.js';
+const STAGE_BY_TASK_STAGE = {
+    GET_INPUT: 'input',
+    MAP: 'map',
+    SHUFFLE: 'shuffle',
+    REDUCE: 'reduce',
+    SUMMARIZE: 'summarize',
+};
+/** NetSuite hands a field back as whatever it stores; the declared type says what the code asked for. */
+function readTypedValue(raw, type) {
+    if (raw === null || raw === undefined || raw === '')
+        return null;
+    if (type === 'integer' || type === 'decimal') {
+        const parsed = Number(raw);
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    if (type === 'checkbox')
+        return raw === true || raw === 'T' || raw === 'true';
+    if (raw instanceof Date)
+        return raw.toISOString();
+    return String(raw);
+}
+function writeTypedValue(value, type) {
+    if (value === null || value === undefined)
+        return '';
+    if (type === 'integer' || type === 'decimal')
+        return Number(value);
+    if (type === 'checkbox')
+        return Boolean(value);
+    if (type === 'date')
+        return value instanceof Date ? value : String(value);
+    return String(value);
+}
+function parseJsonField(raw, fallback) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+function readDateField(raw) {
+    if (raw instanceof Date)
+        return raw.toISOString();
+    if (typeof raw === 'string' && raw !== '')
+        return raw;
+    return null;
+}
+/**
+ * The store for one application's run record. Build it once where it is used: a repository for the
+ * application's own calls, and the job wrapper for the stages.
+ */
+export function createJobRunStore(config) {
+    const { recordType, fields, extraFields } = config;
+    function loadRun(runId) {
+        try {
+            return record.load({ type: recordType, id: runId });
+        }
+        catch (error) {
+            log.debug('job run missing', { record: recordType, runId, message: error instanceof Error ? error.message : String(error) });
+            return undefined;
+        }
+    }
+    function writeFields(runId, values) {
+        const runRecord = loadRun(runId);
+        if (!runRecord)
+            return;
+        for (const [fieldId, value] of Object.entries(values))
+            runRecord.setValue({ fieldId, value });
+        runRecord.save({ ignoreMandatoryFields: true });
+    }
+    function createRun(job, input, extra, startedBy) {
+        const runRecord = record.create({ type: recordType });
+        runRecord.setValue({ fieldId: 'name', value: job });
+        runRecord.setValue({ fieldId: fields.job, value: job });
+        runRecord.setValue({ fieldId: fields.status, value: 'pending' });
+        runRecord.setValue({ fieldId: fields.input, value: JSON.stringify(input !== null && input !== void 0 ? input : {}) });
+        if (startedBy !== null)
+            runRecord.setValue({ fieldId: fields.startedBy, value: startedBy });
+        for (const [name, value] of Object.entries(extra !== null && extra !== void 0 ? extra : {})) {
+            const field = extraFields[name];
+            if (!field)
+                throw new Error(`The run record has no field '${name}'; declare it in the jobRuns block of netsuite-api.config.json.`);
+            runRecord.setValue({ fieldId: field.id, value: writeTypedValue(value, field.type) });
+        }
+        return String(runRecord.save({ ignoreMandatoryFields: true }));
+    }
+    /** The task as NetSuite sees it, or undefined when it can no longer say (an id it has purged). */
+    function checkTask(taskId) {
+        var _a, _b;
+        try {
+            const status = task.checkStatus({ taskId });
+            /** One of the task's counts, called on the task itself, or null when it has none to give. */
+            const readCount = (getterName) => {
+                const getter = status[getterName];
+                if (typeof getter !== 'function')
+                    return null;
+                const count = Number(getter.call(status));
+                return Number.isFinite(count) ? count : null;
+            };
+            const stage = (_a = status.stage) !== null && _a !== void 0 ? _a : undefined;
+            // Every count belongs to the stage being worked, so only map and reduce have one to give.
+            const total = stage === 'MAP' ? readCount('getTotalMapCount') : stage === 'REDUCE' ? readCount('getTotalReduceCount') : null;
+            const pending = stage === 'MAP' ? readCount('getPendingMapCount') : stage === 'REDUCE' ? readCount('getPendingReduceCount') : null;
+            return {
+                status: (_b = status.status) !== null && _b !== void 0 ? _b : undefined,
+                stage,
+                stagePercentComplete: typeof status.getPercentageCompleted === 'function' ? Number(status.getPercentageCompleted()) || 0 : 0,
+                itemsTotal: total,
+                itemsProcessed: total === null || pending === null ? null : Math.max(total - pending, 0),
+            };
+        }
+        catch (error) {
+            log.debug('job task unknown', { taskId, message: error instanceof Error ? error.message : String(error) });
+            return undefined;
+        }
+    }
+    return {
+        start(job, input, options = {}) {
+            const startedBy = runtime.getCurrentUser().id;
+            const runId = createRun(job.name, input, options.extra, typeof startedBy === 'number' ? startedBy : null);
+            const refusals = [];
+            for (const deployment of job.deployments) {
+                try {
+                    const submitted = task
+                        .create({ taskType: task.TaskType.MAP_REDUCE, scriptId: job.scriptId, deploymentId: deployment, params: { [job.runParameter]: runId } })
+                        .submit();
+                    writeFields(runId, { [fields.taskId]: submitted, [fields.deployment]: deployment });
+                    log.audit('job submitted', { job: job.name, runId, taskId: submitted, deployment });
+                    return runId;
+                }
+                catch (error) {
+                    refusals.push(`${deployment}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            // Nothing started, so nothing is left to poll: the run is removed and the caller is told to try later.
+            record.delete({ type: recordType, id: runId });
+            log.audit('job not started', { job: job.name, deployments: job.deployments.length, refusals });
+            throw ApiError.conflict(`${job.name} is already running on every deployment it has; try again shortly.`, { job: job.name, deployments: job.deployments.length });
+        },
+        read: function readRun(runId) {
+            var _a;
+            const runRecord = loadRun(runId);
+            if (!runRecord)
+                return null;
+            const readValue = (fieldId) => runRecord.getValue({ fieldId });
+            let status = (readValue(fields.status) || 'pending');
+            let stage = (readValue(fields.stage) || null);
+            let stagePercentComplete = Number(readValue(fields.stagePercentComplete)) || 0;
+            // Counts come from the task alone, so they are there while it is working and null once it is not.
+            let itemsProcessed = null;
+            let itemsTotal = null;
+            const errors = parseJsonField(readValue(fields.errors), []);
+            const taskId = (readValue(fields.taskId) || null);
+            // What NetSuite says about the task decides between "still working" and "died on the way".
+            if (taskId !== null && (status === 'pending' || status === 'running')) {
+                const taskStatus = checkTask(taskId);
+                if ((taskStatus === null || taskStatus === void 0 ? void 0 : taskStatus.status) === 'FAILED') {
+                    status = 'failed';
+                    errors.push({ stage: stage !== null && stage !== void 0 ? stage : 'input', message: 'NetSuite stopped the task before it finished.' });
+                }
+                else if ((taskStatus === null || taskStatus === void 0 ? void 0 : taskStatus.status) === 'COMPLETE') {
+                    // summarize writes the result before the task completes, so a complete task over a running record means it never got there.
+                    status = 'failed';
+                    errors.push({ stage: stage !== null && stage !== void 0 ? stage : 'summarize', message: 'The task finished without writing a result; see the script execution log.' });
+                }
+                else if ((taskStatus === null || taskStatus === void 0 ? void 0 : taskStatus.status) === 'PROCESSING') {
+                    status = 'running';
+                    stage = (taskStatus.stage && STAGE_BY_TASK_STAGE[taskStatus.stage]) || stage;
+                    stagePercentComplete = taskStatus.stagePercentComplete || stagePercentComplete;
+                    itemsProcessed = taskStatus.itemsProcessed;
+                    itemsTotal = taskStatus.itemsTotal;
+                }
+            }
+            const extra = {};
+            for (const [name, field] of Object.entries(extraFields))
+                extra[name] = readTypedValue(readValue(field.id), field.type);
+            const startedBy = Number(readValue(fields.startedBy));
+            return {
+                id: runId,
+                job: String((_a = readValue(fields.job)) !== null && _a !== void 0 ? _a : ''),
+                status,
+                stage,
+                stagePercentComplete,
+                itemsProcessed,
+                itemsTotal,
+                startedBy: Number.isNaN(startedBy) || startedBy === 0 ? null : startedBy,
+                startedAt: readDateField(readValue(fields.startedAt)),
+                finishedAt: readDateField(readValue(fields.finishedAt)),
+                taskId,
+                result: parseJsonField(readValue(fields.result), null),
+                errors,
+                extra: extra,
+            };
+        },
+        findRuns(runQuery = {}) {
+            var _a;
+            const conditions = [];
+            const params = [];
+            if (runQuery.job !== undefined) {
+                conditions.push(`${fields.job} = ?`);
+                params.push(runQuery.job);
+            }
+            if (runQuery.startedBy !== undefined) {
+                conditions.push(`${fields.startedBy} = ?`);
+                params.push(runQuery.startedBy);
+            }
+            if (runQuery.unfinishedOnly === true)
+                conditions.push(`(${fields.status} IS NULL OR ${fields.status} IN ('pending', 'running'))`);
+            const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+            const limit = Math.min(Math.max((_a = runQuery.limit) !== null && _a !== void 0 ? _a : 10, 1), 100);
+            const rows = query
+                .runSuiteQL({
+                query: `SELECT id, ${fields.job} AS job, ${fields.status} AS status, ${fields.stage} AS stage, ${fields.startedBy} AS startedby FROM ${recordType}${where} ORDER BY id DESC FETCH FIRST ${limit} ROWS ONLY`,
+                params,
+            })
+                .asMappedResults();
+            return rows.map((row) => {
+                var _a;
+                return ({
+                    id: String(row.id),
+                    job: String((_a = row.job) !== null && _a !== void 0 ? _a : ''),
+                    status: (row.status || 'pending'),
+                    stage: (row.stage || null),
+                    startedBy: row.startedby === null || row.startedby === undefined || row.startedby === '' ? null : Number(row.startedby),
+                });
+            });
+        },
+        findExpired(olderThanDays) {
+            const results = query
+                .runSuiteQL({ query: `SELECT id FROM ${recordType} WHERE created < SYSDATE - ?`, params: [olderThanDays] })
+                .asMappedResults();
+            return results.map((row) => String(row.id));
+        },
+        remove(runId) {
+            record.delete({ type: recordType, id: runId });
+        },
+        claimRun({ job, runId, deployment }) {
+            const claimed = runId !== null && runId !== void 0 ? runId : createRun(job, {}, undefined, null);
+            writeFields(claimed, {
+                [fields.status]: 'running',
+                [fields.stage]: 'input',
+                [fields.deployment]: deployment,
+                [fields.startedAt]: new Date(),
+            });
+            return claimed;
+        },
+        readInput(runId) {
+            const runRecord = loadRun(runId);
+            if (!runRecord)
+                return {};
+            return parseJsonField(runRecord.getValue({ fieldId: fields.input }), {});
+        },
+        findRunningRunId(job, deployment) {
+            const results = query
+                .runSuiteQL({
+                query: `SELECT id FROM ${recordType} WHERE ${fields.job} = ? AND ${fields.deployment} = ? AND ${fields.status} = 'running' ORDER BY id DESC`,
+                params: [job, deployment],
+            })
+                .asMappedResults();
+            return results.length > 0 ? String(results[0].id) : undefined;
+        },
+        finish(runId, { status, result, errors }) {
+            writeFields(runId, {
+                [fields.status]: status,
+                [fields.stage]: 'summarize',
+                [fields.stagePercentComplete]: 100,
+                [fields.result]: JSON.stringify(result !== null && result !== void 0 ? result : null),
+                [fields.errors]: JSON.stringify(errors),
+                [fields.finishedAt]: new Date(),
+            });
+        },
+        fail(runId, error) {
+            const runRecord = loadRun(runId);
+            if (!runRecord)
+                return;
+            const errors = parseJsonField(runRecord.getValue({ fieldId: fields.errors }), []);
+            errors.push(error);
+            runRecord.setValue({ fieldId: fields.status, value: 'failed' });
+            runRecord.setValue({ fieldId: fields.errors, value: JSON.stringify(errors) });
+            runRecord.setValue({ fieldId: fields.finishedAt, value: new Date() });
+            runRecord.save({ ignoreMandatoryFields: true });
+        },
+    };
+}

package/dist/server/suiteletClient.js

@@ -35,7 +35,8 @@ export function callSuiteletEndpoint(scriptRef, endpointName, request = {}) {
     }
     const envelope = parseEnvelope(scriptRef, endpointName, response.body);
     if (envelope.error !== null || envelope.status >= 400) {
-        throw new ApiError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`, { script: scriptRef.scriptId, endpoint: endpointName });
+        // The called script's details travel on, so the caller (and through it the browser) can act on them.
+        throw new ApiError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`, envelope.details !== undefined ? envelope.details : { script: scriptRef.scriptId, endpoint: endpointName });
     }
     return envelope.data;
 }

package/dist/testing/N/task.d.ts

@@ -1,7 +1,21 @@
 import { type Mock } from 'vitest';
 export declare const create: Mock;
+/** A job run reads this to tell a task still working from one NetSuite gave up on; a test decides which by returning a status here. */
 export declare const checkStatus: Mock;
 export declare const TaskType: {
     MAP_REDUCE: string;
     SCHEDULED_SCRIPT: string;
 };
+export declare const TaskStatus: {
+    PENDING: string;
+    PROCESSING: string;
+    COMPLETE: string;
+    FAILED: string;
+};
+export declare const MapReduceStage: {
+    GET_INPUT: string;
+    MAP: string;
+    SHUFFLE: string;
+    REDUCE: string;
+    SUMMARIZE: string;
+};

package/dist/testing/N/task.js

@@ -1,4 +1,7 @@
 import { vi } from 'vitest';
 export const create = vi.fn(() => ({ submit: vi.fn(() => 'TASK_ID') }));
-export const checkStatus = vi.fn();
+/** A job run reads this to tell a task still working from one NetSuite gave up on; a test decides which by returning a status here. */
+export const checkStatus = vi.fn(() => ({ status: 'PROCESSING', stage: 'MAP', getPercentageCompleted: () => 0 }));
 export const TaskType = { MAP_REDUCE: 'MAP_REDUCE', SCHEDULED_SCRIPT: 'SCHEDULED_SCRIPT' };
+export const TaskStatus = { PENDING: 'PENDING', PROCESSING: 'PROCESSING', COMPLETE: 'COMPLETE', FAILED: 'FAILED' };
+export const MapReduceStage = { GET_INPUT: 'GET_INPUT', MAP: 'MAP', SHUFFLE: 'SHUFFLE', REDUCE: 'REDUCE', SUMMARIZE: 'SUMMARIZE' };

package/dist/testing/index.d.ts

@@ -9,6 +9,9 @@
  *
  * This module runs in the vitest config, so it never imports vitest itself.
  */
+/** The Map/Reduce contexts a job's stages are called with, as plain objects: what a job test builds its calls from. */
+export { getInputDataContextFor, mapContextFor, reduceContextFor, summarizeContextFor } from './jobs.js';
+export type { CapturedJobValue, MapContextFake, ReduceContextFake } from './jobs.js';
 /** Absolute directory of the stub modules, one file per N/* module (N/ui/serverWidget included). */
 export declare const netsuiteModuleStubsDirectory: string;
 export interface ModuleAlias {

package/dist/testing/index.js

@@ -12,6 +12,8 @@ import { fileURLToPath } from 'node:url';
  *
  * This module runs in the vitest config, so it never imports vitest itself.
  */
+/** The Map/Reduce contexts a job's stages are called with, as plain objects: what a job test builds its calls from. */
+export { getInputDataContextFor, mapContextFor, reduceContextFor, summarizeContextFor } from './jobs.js';
 /** Absolute directory of the stub modules, one file per N/* module (N/ui/serverWidget included). */
 export const netsuiteModuleStubsDirectory = nodePath.join(nodePath.dirname(fileURLToPath(import.meta.url)), 'N');
 /**

package/dist/testing/jobs.d.ts

@@ -0,0 +1,50 @@
+import type { EntryPoints } from 'N/types';
+/**
+ * The contexts NetSuite hands a Map/Reduce script, as plain objects a test can build. A job's stages
+ * are called through its entry points, so a test calls the entry point with one of these and reads
+ * what it wrote: `map(mapContextFor({ value: order }))`, then `written` for what reached the next
+ * stage. Nothing here imports vitest, so it is safe in a vitest config's module graph as well.
+ */
+/** One key and value as a stage wrote it, already parsed back from the JSON the stage carried it as. */
+export interface CapturedJobValue<TValue = unknown> {
+    key: string;
+    value: TValue;
+}
+export interface MapContextFake extends EntryPoints.MapReduce.mapContext {
+    /** Everything the stage wrote, in order. */
+    written: CapturedJobValue[];
+}
+export interface ReduceContextFake extends EntryPoints.MapReduce.reduceContext {
+    written: CapturedJobValue[];
+}
+/** The getInputData context. The input itself comes from the run record, so a test stubs the store, not this. */
+export declare function getInputDataContextFor(options?: {
+    isRestarted?: boolean;
+}): EntryPoints.MapReduce.getInputDataContext;
+/** The map context for one item; `value` is given as the item itself, the way getInputData returned it. */
+export declare function mapContextFor(options: {
+    value: unknown;
+    key?: string;
+    isRestarted?: boolean;
+}): MapContextFake;
+/** The reduce context for one key; `values` are given as the values themselves, the way the map stage wrote them. */
+export declare function reduceContextFor(options: {
+    key: string;
+    values: unknown[];
+    isRestarted?: boolean;
+}): ReduceContextFake;
+/** The summarize context: what the reduce stage left, and whatever failed on the way. */
+export declare function summarizeContextFor(options?: {
+    output?: CapturedJobValue[];
+    inputError?: string;
+    mapErrors?: {
+        key: string;
+        error: string;
+    }[];
+    reduceErrors?: {
+        key: string;
+        error: string;
+    }[];
+    seconds?: number;
+    usage?: number;
+}): EntryPoints.MapReduce.summarizeContext;

package/dist/testing/jobs.js

@@ -0,0 +1,90 @@
+function emptyErrorIterator() {
+    return { iterator: () => ({ each: () => undefined }) };
+}
+function errorIterator(errors) {
+    return {
+        iterator: () => ({
+            each: (callback) => {
+                for (const entry of errors)
+                    if (!callback(entry.key, entry.error, 1))
+                        break;
+            },
+        }),
+    };
+}
+function captureWrites(written) {
+    return (keyOrOptions, value) => {
+        const pair = typeof keyOrOptions === 'string' ? { key: keyOrOptions, value } : keyOrOptions;
+        written.push({ key: String(pair.key), value: typeof pair.value === 'string' ? JSON.parse(pair.value) : pair.value });
+    };
+}
+/** The getInputData context. The input itself comes from the run record, so a test stubs the store, not this. */
+export function getInputDataContextFor(options = {}) {
+    var _a;
+    return { isRestarted: (_a = options.isRestarted) !== null && _a !== void 0 ? _a : false, ObjectRef: { id: '', type: '' } };
+}
+/** The map context for one item; `value` is given as the item itself, the way getInputData returned it. */
+export function mapContextFor(options) {
+    var _a, _b;
+    const written = [];
+    return {
+        isRestarted: (_a = options.isRestarted) !== null && _a !== void 0 ? _a : false,
+        executionNo: 1,
+        errors: emptyErrorIterator(),
+        key: (_b = options.key) !== null && _b !== void 0 ? _b : '0',
+        value: JSON.stringify(options.value),
+        write: captureWrites(written),
+        written,
+    };
+}
+/** The reduce context for one key; `values` are given as the values themselves, the way the map stage wrote them. */
+export function reduceContextFor(options) {
+    var _a;
+    const written = [];
+    return {
+        isRestarted: (_a = options.isRestarted) !== null && _a !== void 0 ? _a : false,
+        executionNo: 1,
+        errors: emptyErrorIterator(),
+        key: options.key,
+        values: options.values.map((value) => JSON.stringify(value)),
+        write: captureWrites(written),
+        written,
+    };
+}
+/** The summarize context: what the reduce stage left, and whatever failed on the way. */
+export function summarizeContextFor(options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const output = (_a = options.output) !== null && _a !== void 0 ? _a : [];
+    const stageSummary = (errors) => {
+        var _a, _b;
+        return ({
+            dateCreated: new Date(),
+            seconds: (_a = options.seconds) !== null && _a !== void 0 ? _a : 0,
+            usage: (_b = options.usage) !== null && _b !== void 0 ? _b : 0,
+            concurrency: 1,
+            yields: 0,
+            keys: { iterator: () => ({ each: () => undefined }) },
+            errors: errors.length > 0 ? errorIterator(errors) : emptyErrorIterator(),
+        });
+    };
+    return {
+        isRestarted: false,
+        dateCreated: new Date(),
+        seconds: (_b = options.seconds) !== null && _b !== void 0 ? _b : 0,
+        usage: (_c = options.usage) !== null && _c !== void 0 ? _c : 0,
+        concurrency: 1,
+        yields: 0,
+        inputSummary: { dateCreated: new Date(), error: (_d = options.inputError) !== null && _d !== void 0 ? _d : '', seconds: (_e = options.seconds) !== null && _e !== void 0 ? _e : 0, usage: (_f = options.usage) !== null && _f !== void 0 ? _f : 0 },
+        mapSummary: stageSummary((_g = options.mapErrors) !== null && _g !== void 0 ? _g : []),
+        reduceSummary: stageSummary((_h = options.reduceErrors) !== null && _h !== void 0 ? _h : []),
+        output: {
+            iterator: () => ({
+                each: (callback) => {
+                    for (const entry of output)
+                        if (!callback(entry.key, JSON.stringify(entry.value)))
+                            break;
+                },
+            }),
+        },
+    };
+}

package/dist-tooling/cli/main.js

@@ -7,7 +7,7 @@ export const CLI_USAGE = [
     'Usage: netsuite-api <command> [options]',
     '',
     'Commands:',
-    '  generate        Read the controllers and the app file; write a client module per controller, the client index, the app module and the scripts map, and delete a generated file no controller owns.',
+    '  generate        Read the controllers and the jobs; write a module per controller and per job, the client index, the jobs index and the scripts map, and delete a generated file nothing owns.',
     '  check           Exit non-zero when a generated file is missing, out of date or left over.',
     '  help            Show this message.',
     '',
@@ -26,7 +26,10 @@ function relativeTo(cwd, filePath) {
     return toPosixPath(nodePath.relative(cwd, filePath)) || filePath;
 }
 function describeControllers(plan) {
-    return plan.controllers.map((controller) => ` - ${controller.name} (${controller.kind}): ${controller.endpointCount} endpoint(s)${controller.browser ? '' : ', types only'}`);
+    return [
+        ...plan.controllers.map((controller) => ` - ${controller.name} (${controller.kind}): ${controller.endpointCount} endpoint(s)${controller.browser ? '' : ', types only'}`),
+        ...plan.jobs.map((job) => ` - ${job.name} (job): ${job.stages.join(', ')}, ${job.deploymentCount} deployment(s)`),
+    ];
 }
 /** Runs the CLI and resolves to the process exit code. Never throws for user errors. */
 export function runCli(argv, environment) {
@@ -66,7 +69,7 @@ export function runCli(argv, environment) {
         if (result.problems.length > 0)
             return failure(result);
         environment.stdout([
-            `netsuite-api: ${result.controllers.length} controller(s), ${result.writtenFiles.length} file(s) written, ${result.unchangedFiles.length} unchanged${result.deletedFiles.length > 0 ? `, ${result.deletedFiles.length} deleted` : ''}.`,
+            `netsuite-api: ${result.controllers.length} controller(s)${result.jobs.length > 0 ? `, ${result.jobs.length} job(s)` : ''}, ${result.writtenFiles.length} file(s) written, ${result.unchangedFiles.length} unchanged${result.deletedFiles.length > 0 ? `, ${result.deletedFiles.length} deleted` : ''}.`,
             ...describeControllers(result),
             ...result.writtenFiles.map((filePath) => ` - wrote ${relativeTo(environment.cwd, filePath)}`),
             ...result.deletedFiles.map((filePath) => ` - deleted ${relativeTo(environment.cwd, filePath)}`),